Godotwright

Godotwright

为 Claude Code、Codex 和任何编码 Agent 提供更强 Godot 4 能力的 MCP 服务和 CLI。
离线 Godot 4.7 API、项目地图、无头检查、GDScript 的 AAA 评审，以及通过代码构建、查看和检查 3D 模型。

网站 · 3D 模型库 · 快速入门 · MCP 设置 · 基准测试 · 路线图

编码 Agent 从多年来的 Godot 3 教程中学习 Godot。它们会写出 yield、 export var 和 KinematicBody2D，编造方法，还会把信号连接到场景中不存在的节点。 Godotwright 为 Agent 提供真实的 Godot 4.7 API、精简的项目地图、真实的 Godot 检查和固定的 AAA 评审， 可作为 MCP 工具使用，也可通过 CLI 使用。

状态：第 1 层（工具包和 MCP 服务）已完成；请参阅 ROADMAP.md。

它还能构建 3D 模型

编码 Agent 还可以在无需 Blender 的情况下为 Godot 制作、查看和检查 3D 模型：model identify 会说明物体是什么（部件、尺寸、枢轴），model build 可从 53 种现成类型（车辆、飞机、船舶、建筑、植物、 带湖泊和河流的地形）或你自己的 JSON 规范中生成干净的 .glb，model view 会以文本形式展示模型，而 model lint 会为其评分。 它也针对小型、低成本模型进行了优化：我们的测试和经验。

快速入门

npx -y godotwright review ~/games/my-game

你会获得 api、性能、质量和结构各项 0 到 100 的评分，每项发现都会以 res://file.gd:12: error [rule] message 的形式列出，并附上 Godot 4 中的修正方法。 然后将它连接到你的 Agent。

为什么选择 Godotwright？

• 不再写 Godot 3 代码。 评审会标记 Godot 3 语法和名称，并提供 Godot 4 中的替代写法。
• 不再编造 API。 每个类、方法、属性和信号都会与官方 Godot 4.7 类参考核对，该参考已打包在本地，无需联网（共 1078 个类）。
• 在按下 F5 前发现错误。 缺失的 $Node 路径、连接到不存在方法的场景信号、未知输入操作，以及失效的 preload() 路径。
• 降低模型开销。 输出精简且稳定，并提供 cheap 配置，按小步引导小型模型完成检查。
• 本地运行，保护隐私。 scan、api 和 review 无需安装 Godot，也无需联网。

命令

godotwright scan [path]               # compact project map, cheap to read
godotwright scan [path] --detail full # node trees, signatures, line numbers
godotwright scan [path] --json        # the full map as JSON
godotwright check [path]              # run Godot headless, report errors as file:line
godotwright check [path] --run        # also run the main scene for 120 frames and show what it printed
godotwright check --scene res://scenes/Test.tscn   # run one scene instead: put print() in the code and read it back here
godotwright api Node2D.look_at        # offline Godot 4.7 API: classes, methods, signals
godotwright api --search "is on floor"
godotwright review [path]             # AAA review with a score per category
godotwright usages take_damage       # every place a name or res:// path is used: code, scenes, connections, groups, settings
godotwright rename take_damage apply_damage --write   # rename everywhere (code, scenes, connections, node paths); dry run without --write
godotwright rename res://a.tscn res://scenes/a.tscn --write   # move a file with its .uid and .import, and every reference
godotwright migrate --write         # port Godot 3 scripts to Godot 4 where that is mechanical; lists what is left
godotwright review --sarif > review.sarif   # for GitHub code scanning: findings inline on pull requests
godotwright review --only-new       # in a fix loop: only what changed since the last review, the rest as one line each
godotwright review [path] --detail full --min-score 90
godotwright model car.glb             # what is in a 3D model: nodes, triangles, textures, size
godotwright model lint car.glb        # model review with a score per category
godotwright model contract car.glb    # write a model.contract.json: node names, size, budget
godotwright model contract --archetype car   # the same, from what a car usually is (no model yet)
godotwright model lint car.glb --archetype car   # also check it is what it should be
godotwright model lint car.glb --contract model.contract.json
godotwright model brief "a tractor"    # one page before you build: kind to start from, parts, size, rules, order of work (for small models)
godotwright model identify "a tractor" # what it is: parts, size, variants, what to anticipate
godotwright model archetypes          # the family tree of things Godotwright knows
godotwright model kinds               # what `model build` can make, with parameters
godotwright model view car.glb       # see a model as text: front, side and top views, the parts, what does not touch
godotwright model recipes             # the ready-made recipes and the archetype each one is checked against
godotwright model recipes tractor     # print one recipe as a spec to edit
godotwright model build house -o house.glb --set floors=3 --set roof=hip
godotwright model build house -o house.glb --collision trimesh   # Godot adds collision shapes on import (-col / -convcol names)
godotwright learn                     # what Godotwright learned on this machine

scan 会在不启动 Godot 的情况下读取 project.godot、场景、资源和脚本。 它会列出场景及其节点树、脚本及其信号、函数和导出变量、 自动加载项、输入动作和关键设置，并警告存在损坏的引用 （缺失文件、缺少主场景或自动加载项、错误的 preload() 路径）。

check 需要 Godot 4.7：使用 --godot <path>、$GODOT、PATH 中的 godot，或使用它自动找到的 Godot 4 下载版本 （Program Files、Steam、Scoop、Downloads、Desktop）。它会导入 项目，加载并实例化每个脚本和场景，还可以运行主场景。 每个问题只会返回一次，格式为 res://path/file.gd:12: error: ...。 存在错误时，退出代码为 1。

api 根据离线捆绑的 Godot 4.7 官方类参考文档（共 1078 个类）回答问题。 它接受 Class、Class.member、Class.Enum.VALUE、@annotation 或全局函数，会沿继承关系查找，并解释 Godot 3 中的名称 （KinematicBody2D 在 Godot 4 中是 CharacterBody2D）。请参阅 data/README.md。

review 不需要安装 Godot。它会对四个类别按 0 到 100 评分，并将每项发现列为 res://file.gd:12: error [rule] message：

类别	检查内容
api	Godot 3 代码、未知类、函数、成员和信号、参数数量错误、Input Map 中缺少的输入动作
performance	节点查找、load()、逐帧回调中的打印和物理调用、空回调、投射阴影的灯光
quality	静态类型覆盖率、过长或嵌套过深的函数、从未发出的信号、基于字符串的信号、命名、TODO
structure	损坏的引用、场景连接到缺失的方法或信号、场景中缺失的 $Node 路径、未知组、文件命名

这些检查遵循 Godot 自身的规则（继承、更具体节点上的脚本、 继承的场景、内置脚本、通过 has_method() 实现的鸭子类型），并在官方演示项目上进行调优， 以报告实际问题，而非无关提示。 存在错误时，或者分数低于 --min-score 时，退出代码为 1。

model 无需 Godot 即可读取 .glb 或 .gltf 文件。单独运行 model 会显示节点树、 三角形数量、材质、纹理（含纹理内存估算值）、尺寸和最低点。model lint 会对四个类别按 0 到 100 评分：

类别	检查内容
geometry	朝向与自身法线相反的三角形（粉色背面、光照错误）、单面表面上的开放边、由两个以上三角形共享的边、无面积的三角形、负缩放、几乎但并非完全左右对称的模型
materials	缺少法线、UV 或切线、超出 0..1 范围的 UV、尺寸过大或非 2 的幂次方的纹理
performance	三角形预算（--max-triangles）、纹理内存预算（--max-texture-mb）、材质过多
rig	同级节点同名、未命名节点、模型未位于 y = 0 上、文件为空

发现项按节点分组，其严重性取决于受影响表面的面积，因此一个偏离的三角形属于信息提示，翻转的面板则属于错误。 模型契约（model.contract.json）会固定模型必须保持的内容，从而发现节点重命名或船体宽度增加 3 cm 等变更。model contract 会根据模型当前状态生成契约； 请检查契约，为每个尺寸添加 source，并将其与模型放在一起。对于尚不存在的模型，model contract --archetype car 会从某类物体的典型特征开始（按名称区分的独立部件、典型尺寸的中间值、三角形预算）。使用 --contract 时，model lint 会报告 contract-missing-node、contract-order、contract-extra-node、contract-size、 contract-ground 和 contract-triangles。尺寸默认容差为 1%，也可以用米为单位设置 tolerance。 存在错误时，或者分数低于 --min-score 时，退出代码为 1。 model build 可直接根据代码生成模型，无需 Blender 或其他工具：生成的 .glb 结构干净，包含 UV 和切线，部件命名清晰、枢轴位置合理，底部位于 y = 0，且相同参数每次都会生成相同的字节。生成结果可直接通过 model lint，--contract-out 会为其写入 model.contract.json。model kinds 会列出各种类型及其参数、范围和默认值；使用 --set name=value 或 --spec file.json 设置参数。这些都是干净的参数化基础模型，旨在后续精修，而非手工雕刻的艺术作品。目前支持的类型有：house、开放世界类型 terrain（由种子噪声生成的高度图地块，其相邻地块会精确衔接，并可选包含湖泊和开凿出的河流）和 sea（位于 y = 0、经过细分且带有海底的水面），以及配方。配方是 data/recipes/ 中现成的规格，包括：car、tractor、helicopter、airliner、ship、tree、conifer、wind-turbine、shipping-container、truck、bus、motorcycle、bicycle、train、tank、light-aircraft、fighter、drone、boat、sailboat、piston-engine、jet-engine、barn、tower、church、windmill、apartment、bridge、road、railway-track、street-lamp、fence、power-pylon、palm、bush、grass、flower、crate、barrel、chair 和 table。每个配方都会指定其原型，因此 model build 会在构建时检查；每个配方也都经过测试，确保各参数取最低值和最高值时仍保持干净。

小型、低成本模型可以盲用：参见 docs/cheap-models.md，了解相关测试，以及 model view 和浮动部件检查对此的处理方式。

model identify 会在你构建之前，根据事物的英文或荷兰语名称（包括拼写错误、复数形式和“vrachtauto”这类荷兰语复合词），或根据描述（“带轮子和发动机的东西”），指出事物是什么。它会回答该事物所属的类别、其模型所需的部件（哪些部件会移动、绕哪个轴移动，以及枢轴的位置）、典型尺寸范围及其来源和置信度类别、变体（汽车可以是轿车、掀背车或皮卡）、Godot 约定（+Y 朝上，正面朝 +Z）、需要预先考虑的事项（碰撞、LOD、灯光）以及常见错误。若一个词有多种含义（荷兰语“windmolen”就是如此），结果会标记为有歧义；对于无法识别的事物，则会标记为通用类别，并给出最接近的类别，而不是编造答案。该库的数据位于 data/archetypes/，并会随着 pull request 不断扩充。它也了解开放世界的组成部分：地形地块、山脉、岛屿、海岸、海洋、湖泊、河流、生物群系和聚居地，以及它们各自的规则（地块共享边界高度、y = 0 作为海平面、碰撞由相同高度生成、细节层级、实例化散布，以及用于超大型世界的浮动原点）。

model lint --archetype <what>（或在规格中设置 "archetype": "vehicle.wheeled.car"，也可以使用任何内置类型）会根据 identify 对该事物的判断来检查模型，作为第五个类别 archetype，占总分的五分之一：

规则	检查内容
archetype/missing-part	没有车轮的汽车、没有旋翼的直升机（通过英文或荷兰语节点名称识别部件）
archetype/part-count	汽车只有两个车轮、自行车有五个车轮
archetype/pivot	车轮未绕轮毂旋转、门未绕铰链线转动、炮塔未安装在底座上
archetype/wheel-axis	车轮朝向错误
archetype/size	模型尺寸大了或小了约 10 倍，这几乎总是单位设置错误（只有差异超过 3 倍才会标记，因为这些范围是典型值，并非精确值）
archetype/orientation	汽车朝侧面，而非沿 z 轴朝向
archetype/optional-part	通常应有但实际缺失的部件（信息）
其他内容均由模型规格构建：一个由命名部件（box、cylinder、ellipsoid、
lathe、loft、extrude、roof）组成的 JSON 树，支持 at、rotate、mirror、repeat、变量和算术
表达式（"$width / 2 - 0.1"，绝不会作为代码执行）。model spec 介绍了这种格式，并以一辆
小汽车为例；model build --spec car.json --set width=1.9 则会构建它。每个可动部件都是
自己的节点，枢轴位于节点原点（车轮的枢轴位于轮毂处）；规格有误时，会显示包含路径的提示
（nodes[0].children[2].size[1]: unknown variable $x）。

将 Godot 3 脚本移植到 Godot 4

godotwright migrate                 # shows every change it would make, and what still needs a hand
godotwright migrate --write         # applies them
godotwright review                  # what is still wrong, with line numbers

migrate 会改写移植过程中的机械性部分：将 export、onready 和 tool 转换为注解（提示信息明确时， 也会使用 @export_range、@export_enum、@export_file 和类型化数组）；将重命名的类、函数、属性和 常量替换为 Godot 4 中的名称（仅当旧名称在 Godot 4 中已不存在且未在脚本中定义时）；将 yield(x, "sig") 转换为 await x.sig，将 connect("sig", target, "method", [binds]) 转换为 sig.connect(target.method.bind(...))，将 emit_signal 和 funcref 转换为信号和可调用对象，并将已移至 其他类的成员（OS.get_ticks_msec()）移到新类中。字符串、注释和节点路径保持不变。它无法安全处理的内容 会列出并附上行号：setget、move_and_slide(velocity)、remote func，以及它不认识的导出提示。 场景和项目设置不会被修改；这些由 Godot 自带的 --convert-3to4 处理。请先提交更改；再次运行不会带来 更多改动。

更省时的修复循环：只看改动之处

godotwright review --only-new

每次审查都会将发现记录在 .godot/godotwright/review-last.json 中（Godot 项目会在 git 中忽略 .godot/）。使用 --only-new（MCP：only_new: true）时，下一次审查会完整显示自上次以来的新发现，将你 已经看过的发现各用一行简短内容显示（file:line [rule]），并显示已修复的数量。即使发现所在的 行发生移动，其身份仍会保留。修复长列表的 Agent 只需读取一次列表，无需每次编辑后都重新查看。

在 GitHub Actions 中进行审查

将此内容保存为游戏仓库中的 .github/workflows/godot-review.yml。它会在每次推送和拉取请求时 审查项目；如果存在错误或总分低于 80，则任务失败。静态审查只需要 Node.js 22.12+ （下方使用 Node 24），无需安装 Godot，也无需模型或 API 密钥。

name: Review Godot project
on: [push, pull_request]
permissions:
  contents: read
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 24
      - run: npx --yes github:laaielichter/godotwright#0dd9ce885df21fafefc09f8ddd6e92745d5ae303 review . --min-score 80

工具包固定在某个修订版本；需要更新到较新版本时，请有意更新该修订版本。如果游戏位于子目录中，请在 审查步骤上设置 working-directory，指向包含 project.godot 的文件夹。

若要在拉取请求中内联查看发现，请将审查结果作为 SARIF 上传到 GitHub 代码扫描（这需要 security-events: write，并且仓库已启用代码扫描）：

permissions:
  contents: read
  security-events: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 24
      - run: npx --yes godotwright review . --sarif > godotwright.sarif || true
      - uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: godotwright.sarif

游戏上的模组和补丁

模组或补丁通常会使用游戏中的脚本、场景和模型，而非模组文件夹中的内容。将 Godotwright 指向游戏， 即可将这些文件视为已存在：

godotwright review mod/ --base game/                       # the game's source folder
godotwright review mod/ --base-files game/pck-manifest.json # files the shipped .pck holds

或者将其写入模组根目录下的 godotwright.json（路径相对于该根目录）：

{ "base": ["../game"], "baseFiles": ["../manifests/pck-files.json"] }

这样就能识别游戏的类、自动加载项、输入映射和场景；如果路径相同，则优先使用模组自身的文件， 并且只审查模组的文件。文件列表可以是每行一个路径的文本，也可以是 JSON（字符串，或带有 path、resource 或 file 键的对象）；x.glb.import 和 x.gdc 等导出名称会映射回其源文件。

用于 Claude Code、Codex 和其他编码 Agent（MCP）

godotwright mcp 通过标准输入输出运行 MCP 服务，提供十四个工具：

工具	功能
godot_scan	映射项目：场景和节点树、脚本、信号、自动加载、输入映射
godot_api	精确查询 Godot 4.7：签名、继承关系、Godot 3 名称
godot_api_search	搜索 Godot 4.7 类参考
godot_review	进行 AAA 评审并给出评分；也可评审未保存的代码（code + file）
godot_check	以无头模式运行 Godot，并按 文件:行 报告错误
godot_checklist	列出每条 AAA 规则及其修复方法
godot_feedback	将评审发现标记为错误或正确，让后续评审能够从中学习
godot_model_brief	开始制作前的一页指南，适用于小型模型：可作为起点的类型、部件、尺寸、规则、工具使用顺序和简短的规格速查表
godot_model_identify	识别物体：部件、枢轴、尺寸及其来源、变体、需要预期的情况（英语或荷兰语）
godot_model_spec	模型规格格式、示例和现成类型
godot_model_build	根据类型或规格（在项目内编写）构建干净的 .glb，并对其进行 lint 检查
godot_model_lint	为 .glb 评分；提供 archetype 时也会检查模型是否符合预期
godot_model_view	以文本形式查看 .glb：正面、侧面和顶面视图、各部件的尺寸，以及未与其他部分接触的部件
godot_model_inspect	查看 .glb 的内容：节点、三角形、纹理、尺寸

使用 --tier 选择配置：

• cheap（默认）：简短输出，以及引导模型分小步完成并进行检查的服务指令（扫描、查询、保存前评审、每次编辑后评审）。
• premium：完整详情，以及所有发现和修复方法。

Claude Code

claude mcp add godotwright -- npx -y godotwright mcp --tier premium

Codex

codex mcp add godotwright -- npx -y godotwright mcp --tier premium

或在 ~/.codex/config.toml 中：

[mcp_servers.godotwright]
command = "npx"
args = ["-y", "godotwright", "mcp", "--tier", "premium"]
startup_timeout_sec = 30 # the first npx run downloads the package

从 Godot 项目文件夹运行 Agent（或传入 --project <path>）。 每次推送时，CI 都会将 Claude Code 和 Codex 连接到该服务。

学习

Godotwright 会在你的机器上从每次使用中学习：

• Godot 一直否定的规则。 每次 check 后，它都会将评审结果与 Godot 实际报告的内容进行比较。如果某条错误规则在这里被否定 3 次且从未得到确认，其相关发现就会降为警告，并标记为提示。
• 误报。 godotwright learn feedback wrong "<finding line>"（或 godot_feedback MCP 工具）会在后续评审中隐藏该发现。
• API 查询。 如果一次查询没有找到结果，而下一次查询找到了，那么之后对同一名称查询失败时，会说明它通常代表什么。

除非你明确同意，否则不会有任何内容离开你的机器。学习文件（运行 godotwright learn 可查看其位置）保存计数器、规则名称、API 名称和消息模板，不包含名称或路径；标记为错误的发现则以哈希形式保存。

godotwright learn          # status: what was learned, where the file is
godotwright learn off      # stop learning (or set GODOTWRIGHT_LEARN=0)
godotwright learn on
godotwright learn reset    # forget everything
godotwright learn preview  # the exact report sharing would send
godotwright learn share on # opt in: send anonymous counts once a day

共享有助于所有用户：许多安装实例学到的内容会随后续版本一同发布。此功能默认关闭，不会发送代码、文件名、路径或项目名称，并遵循 DO_NOT_TRACK。请参阅 PRIVACY.md。 设置 GODOTWRIGHT_HOME 可将文件保存在其他位置。

Godotwright 还会免费从公开项目中学习：每周，Learn 工作流都会检查官方 Godot 示例项目，以及为 Godot 3 编写的相同示例项目，用实际的 Godot 进行检查，并记录 Godot 确认或否定了哪些规则。这些数据，加上选择加入的安装实例所共享的内容，会发布在 data/learned.json 中：常见拼写错误的 API 提示，以及 Godot 一直否定的规则。 你自己的机器上观察到的结果优先：只要 Godot 确认过一次，某条规则就仍会被视为错误。

对于维护者，godotwright collector serve 会接收报告（再次检查，并且不存储 IP 地址）；godotwright collector aggregate <dir> --out data/learned.json 会汇总这些报告，只保留至少有 3 个安装实例报告的内容。 godotwright collector projects <dirs...> 会从公开项目中学习。

基准测试

bench/ 使用固定的 Godot 任务运行编码 Agent，并对比是否使用 Godotwright；随后由真实的 Godot 4.7.2 针对每项任务通过行为测试评判结果。 第一轮共运行 168 次（Claude Haiku、Sonnet 和 Opus 5.5，12 项任务）：所有运行均通过，无论是否使用 Godotwright，因此这些任务无法区分两种设置在正确性方面的差异。 使用 Godotwright 时，所有代码都完全采用了静态类型（84 次运行中有 84 次；未使用时为 84 次中的 71 次）。详情和限制：bench/RESULTS.md。

对比

	Godotwright	Agent 独立运行	Godot 编辑器
Godot 4.7 API	内置类参考，支持离线使用	来自训练数据	内置
修复后标记出 Godot 3 代码	是	有时	仅解析错误
Agent 可自行使用	MCP + CLI	不适用	需要人工操作
性能和结构审查	按类别评分	无	仅警告
是否需要安装 Godot	仅 check 需要	否	是
不会	编写你的游戏、取代游戏测试、审查 C#	运行 Godot	与 Agent 对话

常见问题

需要安装 Godot 吗？ scan、api 和 review 不需要。只有 check 会运行 Godot 4.7 无头模式。

支持哪些 Agent？ 任何通过标准输入/输出使用 MCP 通信的 Agent。CI 会在每次推送时连接 Claude Code 和 Codex。CLI 可在任何 shell 中运行。

它会把我的代码发送到其他地方吗？ 不会。请参阅学习和 PRIVACY.md。

支持较旧的 Godot 4 版本吗？ 大多数发现适用于所有 Godot 4 版本，但 API 查询针对 4.7。

贡献

报告错误的审查结果和新规则建议最有帮助。 请参阅 CONTRIBUTING.md。

要求

• Node.js 22.12 或更新版本
• 目标引擎：Godot 4.7.x

开发

npm ci
npm run check
node dist/cli.js --help

请参阅 AGENTS.md 了解项目约定。

许可证

MIT