Back to Details

scenario-godot-expert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Godot expert (technical director and agent protocol)

Godot 专家（技术总监与 Agent 协议）

Target: Godot 4.7.2.stable (standard build, no C#), macOS Apple Silicon, Metal by default.
Expert Godot work is a loop run against evidence: set the budget, build one stage, measure it, look at it, fix it, advance. An agent without a mouse gets there by picking the right channel, passing only on a machine-readable result, and never trusting one signal alone. This skill is that protocol, the shared toolkit every scenario-godot-* skill calls (
scripts/
), and the map of the team. If a sibling skill named here is missing from your available skills, ask the user to install it (
npx skills add scenario-labs/skills --skill <name>
); unattended, proceed from tool schemas and flag the gap.
Status (2026-10-02): every toolkit function below ran in Godot 4.7.2 here (23 live tests, 17 offline, all pass; 
references/procedures.md
).
目标：Godot 4.7.2.stable（standard build，无 C#），macOS Apple Silicon，默认使用 Metal。
Godot 专家工作是一套以证据为依据的循环：设定预算，构建一个阶段，测量，查看，修复，然后推进。没有鼠标的 Agent 要实现这一目标，必须选对 channel，只传递机器可读结果，并且绝不依赖单一信号。这个 skill 就是该协议、所有 scenario-godot-* skill 共同调用的共享工具包（
scripts/
），也是团队导航图。如果此处提到的某个 sibling skill 不在可用 skills 中，请让用户安装（
npx skills add scenario-labs/skills --skill <name>
）；在无人值守的情况下，则依据 tool schema 继续，并标记该缺口。
状态（2026-10-02）： 下列每项 toolkit function 均已在 Godot 4.7.2 中运行（23 个 live test、17 个 offline test，全部通过；
references/procedures.md
）。

Stance (the expert delta)

专家原则（专家的差异化能力）

  1. Headless output is the truth; the editor's Output panel is not. MCP servers that scrape it "report errors for lines no longer on disk", and it does not list every project error (Fennara, 2vSYP7GyA5U [00:02:51, 00:06:20]). PixelLab's agent runs the Godot binary itself and reads the console (THwZYWuOdZI [00:13:45]). Pass on the 
    AGENT_RESULT
    envelope plus a log scan, never on "it exited": a script with a parse error exits 0, with or without 
    --check-only
    , and so does a script path Godot cannot find (version deltas, verified; L6).
  2. One writer per project. A GUI editor holding a project keeps its own copy of the open scenes, so its next save can overwrite a headless edit [added]; merged 
    .tscn
    files can fail to parse (Lilith Duncan, CAJ_iIedx_I [00:01:36]). The toolkit refuses a project a GUI Godot has open; work through that editor (MCP) or ask the user to close it. Never close a Godot or Blender process you did not start [added].
  3. Milliseconds against a budget, on the target. Measure before optimizing (Dan Does Dev, s2C2RO_WMh0 [00:07:12]); profile on the real device class, thermals included (Ian Bolton, WrjaUNAXYqk [00:09:35]). Headless frame time is loop time, not game cost; windowed frame time on this Mac is pinned to the display refresh; judge 
    gpu_ms
    and 
    cpu_ms
    (observed).
  4. Look AND check. Every frame goes through 
    gd_review.image_checks
     and a contact sheet you open. Headless draws nothing, so captures need a windowed run (observed). After AI asset import, check facing, animation direction, tile seams and camera jitter by eye (PixelLab, THwZYWuOdZI).
  5. Tests are the contract. Assert on signals and public results, not internals (Godotneers, CreugthdgJ0 [01:08:36]; Butch Wesley, ImqhHLlPfZg [00:16:59]; Mike Schulze, x6GdTgIAFiU [00:24:19]); bound every await (2 s Godotneers, 5 s Schulze); prove the test bites by emptying the function and watching it go red (Wesley [00:13:40]).
  6. Design for a mouseless driver. Split body and brain so a test brain can steer a character (Godotneers [00:18:14]). Headless has no mouse device (Wesley [00:48:33]), yet GUI input still tests headless: 
    get_viewport().push_input(event, true)
    reaches Controls, while 
    Input.parse_input_event
    never reaches a MOUSE_FILTER_STOP Control (scenario-godot-gameplay, scenario-godot-ui, observed); pass 
    true
    so positions are logical, not window pixels. Levels hold a spawn point, not the player (Godotneers [00:56:56]).
  7. Edits persist only with 
    owner
    and a save.     
    add_child
    alone is invisible in the Scene dock and lost on save (Godot docs, Running code in the editor); script edits bypass Undo unless routed through 
    EditorUndoRedoManager
    (Queble, nW7YtSSJzbQ [00:04:41]).
  8. Be honest about visual editors. VisualShader, AnimationTree, the TileSet and theme editors, and the particle inspector are visual; the agent writes 
    .gdshader
    , 
    .tres
    /
    .tscn
    text, or builds the resource in code, and names the GUI path for a human. Pick an MCP by feedback fidelity, not tool count (Fennara [00:09:22]).
  1. Headless 输出才是真相；编辑器的 Output panel 不是。 抓取 Output panel 的 MCP server 会“报告磁盘上已不存在的行所产生的错误”，而且它不会列出所有项目错误（Fennara，2vSYP7GyA5U [00:02:51, 00:06:20]）。PixelLab 的 agent 直接运行 Godot binary 并读取 console（THwZYWuOdZI [00:13:45]）。必须传递 
    AGENT_RESULT
    envelope 加一次 log scan，绝不能只依据“它已退出”：存在 parse error 的 script 无论是否带 
    --check-only
    都会 exit 0，Godot 找不到的 script path 也一样（版本差异，已验证；L6）。
  2. 每个项目只能有一个写入者。 GUI editor 持有项目时，会保留已打开场景的独立副本，因此它下一次保存时可能覆盖 headless edit [added]；合并后的 
    .tscn
    file 可能无法解析（Lilith Duncan，CAJ_iIedx_I [00:01:36]）。toolkit 会拒绝处理被 GUI Godot 打开的项目；请通过该 editor（MCP）操作，或让用户将其关闭。绝不关闭并非由你启动的 Godot 或 Blender 进程 [added]。
  3. 在目标设备上按预算衡量毫秒数。 优化前先测量（Dan Does Dev，s2C2RO_WMh0 [00:07:12]）；在真实设备等级上做 profile，并把 thermals 纳入考虑（Ian Bolton，WrjaUNAXYqk [00:09:35]）。Headless frame time 是 loop time，而非 game cost；这台 Mac 上的 windowed frame time 被 display refresh 固定；应判断 
    gpu_ms
    和 
    cpu_ms
    （实测）。
  4. 既看画面，也做检查。 每一帧都要经过 
    gd_review.image_checks
     以及一份由你打开的 contact sheet。Headless 不会绘制任何内容，因此 capture 必须通过 windowed run（实测）。导入 AI asset 后，要用肉眼检查朝向、animation direction、tile seam 和 camera jitter（PixelLab，THwZYWuOdZI）。
  5. 测试就是契约。 对 signals 和 public results 做断言，而不是 internals（Godotneers，CreugthdgJ0 [01:08:36]；Butch Wesley，ImqhHLlPfZg [00:16:59]；Mike Schulze，x6GdTgIAFiU [00:24:19]）；为每个 await 设置上限（Godotneers 2 s，Schulze 5 s）；通过清空 function 并观察测试变红来证明测试确实能发现问题（Wesley [00:13:40]）。
  6. 为无鼠标 driver 而设计。 将 body 和 brain 分离，使 test brain 能操控 character（Godotneers [00:18:14]）。Headless 没有 mouse device（Wesley [00:48:33]），但 GUI input 仍可在 headless 下测试：
    get_viewport().push_input(event, true)
    能到达 Controls，而 
    Input.parse_input_event
    无法到达带 MOUSE_FILTER_STOP 的 Control（scenario-godot-gameplay、scenario-godot-ui，实测）；传入 
    true
    ，使 position 采用逻辑坐标，而不是 window pixel。Level 中保存的是 spawn point，而不是 player（Godotneers [00:56:56]）。
  7. 只有设置 
    owner
    并保存，编辑才会持久化。     仅调用 
    add_child
    的对象在 Scene dock 中不可见，并会在保存时丢失（Godot docs，Running code in the editor）；script edit 会绕过 Undo，除非通过 
    EditorUndoRedoManager
    路由（Queble，nW7YtSSJzbQ [00:04:41]）。
  8. 对 visual editor 保持诚实。 VisualShader、AnimationTree、TileSet 和 theme editor，以及 particle inspector 都是 visual；Agent 会写入 
    .gdshader
    、
    .tres
    /
    .tscn
    文本，或用代码构建 resource，并为人指出对应的 GUI path。选择 MCP 时依据 feedback fidelity，而不是 tool 数量（Fennara [00:09:22]）。

Execution channels

执行 channel

ChannelUse forCost (measured here)Rules
Headless job 
gd_run.run_script
logic, data, audits, scene building, imports, tests, exports0.2 s for a small job; 
--import
about 2 s		default channel; watchdog ends a hung job (exit 124)
Windowed job 
capture_scene
, 
capture_sequence
, 
profile_scene
anything that must render: screenshots, sequences, GPU timeabout 1 s for 4 views warm; first capture in a fresh project 10.8 s, a 5 s profile 29.6 s160x90 window, SubViewport at the requested size, focus handed back (2 restores per run observed); 
GD_MAX_WINDOWED
2
Headless editor 
run_script(editor=True)
EditorInterface: open, edit and save scenes; EditorFileSystem1.1 swait 2 frames before editor calls; without 
-e
EditorInterface calls fail (observed)
GUI editor + MCP (hybridindie 
godot-editor-mcp
)		the user's open editor: live tree, selection, undoable editsstdio probe 0.9 s, 23 tools exposed by defaultonly when the user has the editor open; project-local 
.mcp.json
only (
gd_live.write_mcp_config
)
Running game + MCP (tugcantopaloglu)drive a running game (input, eval)not run hereclone, 
npm run build
, a game autoload on port 9090
gd_live.channels(P)
reports what is possible now. Prefer the headless channels; add an MCP for live scene inspection.
Channel用途成本（此处实测）规则
Headless 作业 
gd_run.run_script
逻辑、数据、审计、场景构建、导入、测试、导出小型作业 0.2 s；
--import
约 2 s		默认 channel；watchdog 会终止卡住的作业（exit 124）
Windowed 作业 
capture_scene
、
capture_sequence
、
profile_scene
任何必须渲染的内容：screenshot、sequence、GPU time预热后 4 个 view 约 1 s；新项目首次 capture 10.8 s，5 s profile 29.6 s160x90 window、请求尺寸的 SubViewport、运行后归还焦点（观察到每次运行恢复 2 次）；
GD_MAX_WINDOWED
2
Headless 编辑器 
run_script(editor=True)
EditorInterface：打开、编辑和保存场景；EditorFileSystem1.1 seditor call 前等待 2 帧；不带 
-e
时 EditorInterface call 会失败（实测）
GUI 编辑器 + MCP（hybridindie 
godot-editor-mcp
）		用户已打开的 editor：实时 scene tree、selection、可撤销编辑stdio probe 0.9 s，默认暴露 23 个 tool仅在用户已打开 editor 时使用；只使用 project-local 
.mcp.json
（
gd_live.write_mcp_config
）
运行中的游戏 + MCP（tugcantopaloglu）驱动正在运行的游戏（input、eval）此处未运行clone，执行 
npm run build
，游戏 autoload 使用 port 9090
gd_live.channels(P)
会报告当前可用的 channel。优先使用 headless channel；需要 live scene inspection 时再添加 MCP。

Establish first

首先确定

Ask once, then run: target platforms and lowest device; frame budget (default 60 fps desktop, 30 fps mobile); 2D or 3D; renderer (Forward+ desktop 3D, Mobile for demanding phones, Compatibility for web and widest reach, after Ray Hayes, KWhVVMpihsc [00:06:03]); art style and pixel art or not; whether the user's editor has the project open; the deliverable. Then 
gd_live.channels(P)
and 
gd_run.audit(P, "project")
, and write the renderer, physics engine (Jolt for 3D), stretch mode, main scene and autoloads into the plan.
询问一次，然后运行：目标平台及最低规格设备；frame budget（桌面默认 60 fps，移动端 30 fps）；2D 或 3D；renderer（桌面 3D 用 Forward+，高负载手机用 Mobile，Web 和最广泛兼容用 Compatibility，参考 Ray Hayes，KWhVVMpihsc [00:06:03]）；art style 以及是否为 pixel art；用户的 editor 是否已打开项目；最终 deliverable。然后调用 
gd_live.channels(P)
和 
gd_run.audit(P, "project")
，并把 renderer、physics engine（3D 用 Jolt）、stretch mode、main scene 和 autoloads 写入 plan。

Workflow (the expert loop)

工作流（专家循环）

  1. Brief in numbers. Budgets per platform, resolution, scale, style. GATE: every later check has a number to compare with.
  2. Project. 
    gd_env.base_project("3d"|"2d", dest)
    (APFS clone, 0.01 s, its own 
    user://
    folder) or 
    new_project(...)
    , which writes the project-manager defaults a hand-written 
    project.godot
    lacks. GATE: 
    audit(P, "project")
    has no flags.
  3. Baseline. 
    check_all(P)
    , 
    audit(P, "scene", scene=...)
    , captures from fixed views, a profile if performance matters. GATE: zero parse and script errors; flags fixed or listed; sheet opened.
  4. Build one stage with small idempotent jobs (get-or-create, 
    owner
    set, explicit save). Route domain work to its owner (below).
  5. Measure. Audit, tests (
    run_tests
    ), 
    profile_scene
    plus 
    gd_stat.budget_check
    , or the export result. GATE: numbers against the brief.
  6. Look AND check. Same views, 
    image_checks
    , contact sheet opened, judged with the domain skill's critique. GATE: no flag that sets 
    ok
    false, the change visible (
    compare
    changed_fraction above 0).
  7. Fix before advancing, one change at a time; 
    compare
    proves parity or gain.
  8. Deliver with evidence. Each step with its toolkit call, then Verified (what ran, result file, number or frame) and Assumed (not run, defaults). Never call a scene, shader, level or build done without numbers and a frame you looked at.
  1. 用数字定义 brief。 各 platform 的 budget、resolution、scale、style。GATE：之后的每次 check 都必须有一个可供比较的数字。
  2. 建立项目。 
    gd_env.base_project("3d"|"2d", dest)
    （APFS clone，0.01 s，拥有自己的 
    user://
    folder），或使用 
    new_project(...)
    ；后者会写入手写 
    project.godot
    所缺少的 project-manager defaults。GATE：
    audit(P, "project")
    没有任何 flag。
  3. 建立 baseline。 
    check_all(P)
    、
    audit(P, "scene", scene=...)
    、固定 view 的 capture，以及性能相关时的 profile。GATE：parse 和 script error 均为零；flag 已修复或已列出；contact sheet 已打开。
  4. 构建一个阶段。 使用小型、幂等的作业（get-or-create、设置 
    owner
    、显式保存）。将领域工作路由给其 owner（见下文）。
  5. 测量。 Audit、tests（
    run_tests
    ）、
    profile_scene
    加 
    gd_stat.budget_check
    ，或 export result。GATE：将数字与 brief 对照。
  6. 既看画面，也做检查。 使用相同 view、
    image_checks
    、打开 contact sheet，并结合领域 skill 的 critique 进行判断。GATE：不存在令 
    ok
    为 false 的 flag，且变化可见（
    compare
    的 changed_fraction 大于 0）。
  7. 推进前先修复。 每次只做一项修改；用 
    compare
    证明结果一致或有改进。
  8. 带着证据交付。 每一步都附上 toolkit call，然后列出 Verified（运行了什么、result file、数字或 frame）和 Assumed（未运行的内容、所用默认值）。没有数字，也没有亲自查看过的 frame，绝不把 scene、shader、level 或 build 称为完成。

Shared toolkit (
scripts/
, the contract for every scenario-godot-* skill)

共享 toolkit（
scripts/
，每个 scenario-godot-* skill 的契约）

import sys; sys.path.insert(0, "<scenario-godot-expert>/scripts")
. System python3, standard library (Pillow optional).
Every 
gd_env
, 
gd_run
, 
gd_review
, 
gd_stat
and 
gd_live
call, with defaults and return values: 
references/procedures.md
 section 1. Most used: 
gd_env.new_project
, 
gd_run.run_script
, 
gd_run.capture_scene
, 
gd_run.profile_scene
, 
gd_run.export
, 
gd_review.image_checks
.
Every 
gd_run
run returns 
ok
, 
error
, 
result
(the job's dictionary), 
exit_code
, 
timed_out
, 
parse_errors
, 
script_errors
, 
shader_errors
, 
engine_errors
, 
warnings
, 
leaks
, 
log_path
, 
result_path
. Output lands in 
<project>/.agent_out/
(carries 
.gdignore
). Concurrency: 
GD_MAX
(6) Godot processes, 
GD_MAX_WINDOWED
(2), one per project, all through 
gd_run.godot_slot
; 
GodotBusy
when a GUI editor holds the project.
A domain job is a GDScript file in the project (AgentKit, 
scripts/agentkit/
, is copied to 
res://addons/agentkit/
):
gdscript
extends "res://addons/agentkit/agent_job.gd"
func run() -> Dictionary:
	var scene := await load_scene("res://main.tscn", 2)   # in the tree, 2 frames waited
	note("children", scene.get_child_count())
	return {"ok": true, "speed": arg("speed", 4.0)}       # arg() typed by its default
Or a method on any RefCounted script, 
run_script(P, "res://tools/x.gd:build", args)
(it receives the job). Errors logged during the job flip 
ok
to false unless 
expect_errors
is set. A script error aborts a typed 
run() -> Dictionary
, which then returns 
{}
: an empty result always fails (
aborted: true
), even with 
expect_errors
, so return at least 
{"ok": true}
. 
export
reports 
bytes
for every file it wrote (
main_bytes
for the named one) and treats an iOS 
export_project_only
Xcode project as the 
artifact
. Captures emulate the project stretch (keep, keep_width, keep_height, expand, ignore, integer scale, scale factor, viewport mode) with black bars, matching the engine on 15 cases (L20); in your own job read a 
make_viewport
SubViewport with 
agent_capture.grab(vp)
. Helpers: 
arg
, 
out_path
, 
load_scene
, 
wait_frames
, 
wait_physics_frames
, 
wait_seconds
, 
note
, 
is_headless
, 
captured_errors
; libraries 
agent_build.gd
 (
save_scene
, presets), 
agent_profile.gd
 (
record
). Domain code goes in 
scripts/gd_<domain>.py
and 
scripts/agentkit/<domain>/
.
import sys; sys.path.insert(0, "<scenario-godot-expert>/scripts")
。使用系统 python3 和 standard library（Pillow 可选）。
每个 
gd_env
、
gd_run
、
gd_review
、
gd_stat
和 
gd_live
call、默认值和返回值：
references/procedures.md
 section 1。最常用：
gd_env.new_project
、
gd_run.run_script
、
gd_run.capture_scene
、
gd_run.profile_scene
、
gd_run.export
、
gd_review.image_checks
。
每次 
gd_run
run 都会返回 
ok
、
error
、
result
（作业的 dictionary）、
exit_code
、
timed_out
、
parse_errors
、
script_errors
、
shader_errors
、
engine_errors
、
warnings
、
leaks
、
log_path
和 
result_path
。Output 位于 
<project>/.agent_out/
（其中包含 
.gdignore
）。并发设置：
GD_MAX
（6）个 Godot process、
GD_MAX_WINDOWED
（2）个，每个项目一个，所有 process 都通过 
gd_run.godot_slot
启动；GUI editor 持有项目时返回 
GodotBusy
。
领域作业是项目中的 GDScript file（AgentKit，
scripts/agentkit/
 会被复制到 
res://addons/agentkit/
）：
gdscript
extends "res://addons/agentkit/agent_job.gd"
func run() -> Dictionary:
	var scene := await load_scene("res://main.tscn", 2)   # in the tree, 2 frames waited
	note("children", scene.get_child_count())
	return {"ok": true, "speed": arg("speed", 4.0)}       # arg() typed by its default
也可以使用任意 RefCounted script 上的 method，即 
run_script(P, "res://tools/x.gd:build", args)
（它会收到该作业）。作业期间记录的错误会把 
ok
翻转为 false，除非设置 
expect_errors
。script error 会中止 typed 
run() -> Dictionary
，随后它返回 
{}
：empty result 永远判定为失败（
aborted: true
），即使设置了 
expect_errors
；因此至少返回 
{"ok": true}
。
export
会报告它写入的每个 file 的 
bytes
（命名 file 使用 
main_bytes
），并把 iOS 
export_project_only
Xcode project 视为 artifact。Capture 会模拟 project stretch（keep、keep_width、keep_height、expand、ignore、integer scale、scale factor、viewport mode）并添加 black bar，在 15 个 case 中与 engine 表现一致（L20）；在自己的 job 中，应读取带 
make_viewport
的 SubViewport 并使用 
agent_capture.grab(vp)
。Helper：
arg
、
out_path
、
load_scene
、
wait_frames
、
wait_physics_frames
、
wait_seconds
、
note
、
is_headless
、
captured_errors
；library：
agent_build.gd
（
save_scene
、presets）、
agent_profile.gd
（
record
）。领域代码应放在 
scripts/gd_<domain>.py
和 
scripts/agentkit/<domain>/
中。

Numbers

数值

ValueRelative toSource
16.67 / 33.33 msframe budget at 60 / 30 fpsarithmetic
8.33 mswindowed 
frame_ms
floor on this 120 Hz display, even with 
--disable-vsync
observed
6.9 msheadless frame pacing: the low-processor sleep (
low_processor_usage_mode_sleep_usec
6900), whatever the work; benchmark with 
--fixed-fps 60
and time the work		observed; scenario-godot-gameplay, scenario-godot-ui
1.4 to 1.8 ms / 0GPU p95 of the fx test scene at 1080p on Vulkan (four runs) / on Metalobserved
0.2 s, 10.2 ssmall job; a hung job stopped by the watchdog (timeout 20 s)observed
60.8 / 75.0 / 41.4 MBmacOS universal zip / Linux x86_64 (binary plus .pck) / Web (9 files) export of Base3Dobserved, L9
430 MBiOS Xcode project (
export_project_only
), mostly the engine xcframework		observed, L9
数值含义或比较基准来源
16.67 / 33.33 ms60 / 30 fps 下的 frame budget算术计算
8.33 ms此 120 Hz display 上 windowed 
frame_ms
的下限，即使使用 
--disable-vsync
实测
6.9 msHeadless frame pacing：低 processor 休眠（
low_processor_usage_mode_sleep_usec
6900），无论实际工作负载为何；使用 
--fixed-fps 60
对工作负载计时并进行 benchmark		实测；scenario-godot-gameplay、scenario-godot-ui
1.4 至 1.8 ms / 01080p 下 fx test scene 在 Vulkan 上的 GPU p95（四次运行）/ 在 Metal 上的 GPU p95实测
0.2 s / 10.2 s小型作业；watchdog 终止的卡住作业（timeout 20 s）实测
60.8 / 75.0 / 41.4 MBBase3D 的 macOS universal zip / Linux x86_64（binary 加 .pck）/ Web（9 个文件）导出实测，L9
430 MBiOS Xcode project（
export_project_only
），主要由 engine xcframework 构成		实测，L9

Quality gates

质量门禁

  • Measurable: 
    ok
    true with zero parse, script and shader errors; 
    check_all
    failed_files == []
    ; JUnit 
    failures == 0
    and 
    tests > 0
    ; audit flags fixed or justified; 
    budget_check
    ok (p95 under target, hitch ratio at most 1%); export exit 0, artifact size recorded, 
    verify_pack
    lists the expected files.
  • Visual: every capture passes 
    image_checks
    (
    ok
    false on all_black, all_white, uniform, transparent) and was opened in a contact sheet; before and after from the same views.
  • 可衡量： 
    ok
    为 true，且 parse、script 和 shader error 均为零；
    check_all
    的 
    failed_files == []
    ；JUnit 的 
    failures == 0
    且 
    tests > 0
    ；audit flag 已修复或有充分说明；
    budget_check
    通过（p95 低于目标，hitch ratio 不超过 1%）；export exit 0，记录 artifact size，并由 
    verify_pack
    列出预期文件。
  • 视觉： 每次 capture 都通过 
    image_checks
    （all_black、all_white、uniform、transparent 时 
    ok
    为 false），并在 contact sheet 中打开查看；修改前后使用相同 view。

Common mistakes

常见错误

MistakeWhat it looks likeFix
trusting exit codesparse error, exit 0
run_script
/
check_all
read the log
--check-only
on code using autoloads		"Identifier not found: GameState"
check_all
(in-process load); 
check_only
files it under 
autoload_false_positives
hand-written 
project.godot
GodotPhysics3D, stretch disabled, UI does not scale
new_project
, or set the keys
class_name
in a fresh project		"Identifier not found"
import_project
first
autoload named like its 
class_name
'Class "GameState" hides an autoload singleton.' (GDScript analyzer)name the autoload differently (
Game
) or drop 
class_name
capture or 
--write-movie
headless		0 frames drawn; 
--write-movie
crashes		windowed 
capture_scene
GPU timing on Metal
gpu_ms
0
profile_scene(driver="vulkan")
export output inside the projectbuild imported and packed next timeoutside, or 
.gdignore
(auto)
macOS export"ETC2 ASTC" or "Invalid bundle identifier"
import_etc2_astc=true
; 
ensure_preset
sets a bundle id
clones sharing 
user://
saves, input maps and the shader cache of other agents' clones show up (every clone was named Base3D)
base_project
isolates by default; 
gd_env.isolate_user_dir(P)
 for other scratch projects
per-frame 
TIME_PROCESS
the same value on every CSV row (the monitor refreshes about once per second; 0 under 
--fixed-fps
)
process_wall_ms
column of 
profile_scene
, or sentinel nodes
错误表现修复方式
信任 exit code存在 parse error，但 exit 0使用 
run_script
/
check_all
读取 log
对使用 autoload 的代码执行 
--check-only
“Identifier not found: GameState”使用 
check_all
（in-process load）；
check_only
会将其归入 
autoload_false_positives
手写 
project.godot
GodotPhysics3D、stretch 被禁用、UI 无法缩放使用 
new_project
，或手动设置相应 key
在全新项目中使用 
class_name
“Identifier not found”先执行 
import_project
autoload 与其 
class_name
同名		“Class "GameState" hides an autoload singleton.”（GDScript analyzer）使用不同名称（
Game
），或移除 
class_name
在 headless 下 capture 或使用 
--write-movie
绘制 0 帧；
--write-movie
崩溃		使用 windowed 
capture_scene
在 Metal 上进行 GPU timing
gpu_ms
为 0		使用 
profile_scene(driver="vulkan")
export output 位于项目内部下次构建时会被 import 并打包输出到项目外部，或使用 
.gdignore
（自动处理）
macOS export“ETC2 ASTC”或“Invalid bundle identifier”设置 
import_etc2_astc=true
；由 
ensure_preset
设置 bundle id
多个 clone 共享 
user://
其他 agent clone 的 save、input map 和 shader cache 相互干扰（所有 clone 都名为 Base3D）
base_project
默认提供隔离；其他临时项目使用 
gd_env.isolate_user_dir(P)
每帧使用 
TIME_PROCESS
CSV 每一行的值都相同（monitor 约每秒刷新一次；使用 
--fixed-fps
时为 0）		使用 
profile_scene
的 
process_wall_ms
column，或使用 sentinel node

Team routing and handoffs

团队路由与交接

SkillRoute here when the brief mentions
scenario-godot-architectureproject structure, scenes vs nodes, signals, Resources, autoloads, composition, typing, save data
scenario-godot-2dsprites, TileMapLayer, TileSet, platformer or top-down feel, Camera2D, pixel-perfect, 2D lights, parallax
scenario-godot-3d-worldCharacterBody3D, blockout, CSG, GridMap, terrain, GLB import, Jolt, procedural meshes
scenario-godot-rendering-lightingrenderer choice, SDFGI, VoxelGI, LightmapGI, environment, fog, shadows, post, Compositor
scenario-godot-shaders
.gdshader
, VisualShader substitutes, global uniforms, screen reading, compute, stencil
scenario-godot-vfxGPUParticles, trails, sub-emitters, particle collision, impacts, juice
scenario-godot-animationAnimationPlayer, AnimationTree, tweens, skeletons, IK, retargeting, root motion, cutscenes
scenario-godot-uiControl layout, containers, themes, menus, HUD, focus and gamepad, localization, scaling on phones
scenario-godot-gameplaystate machines, inventory, dialogue, save and load, navigation, AI, procedural generation, input
scenario-godot-audiobuses, effects, spatial audio, adaptive music, SFX variation
scenario-godot-multiplayerhigh-level multiplayer, RPCs, authority, spawner and synchronizer, lobbies, dedicated servers
scenario-godot-pipeline-automationCLI and CI, editor plugins, GUT and gdUnit4, import plugins, GDExtension, MCP workflows
scenario-godot-performance-exportprofiler, monitors, stutter, mobile, web, desktop and Steam export, signing
A cross-cutting item has one owner: shader stutter and web threading go to scenario-godot-performance-export, naming the second skill in the brief. Every handoff packet carries: project path and channel, the brief in numbers, what was done with its toolkit calls, evidence (result JSON path, contact sheet and flags, CSV with 
budget_check
, JUnit totals, export sizes), Verified, Assumed, open issues, and a fence (what the receiver may touch). The receiver reproduces one piece of evidence before building on it. Sister teams: blender-expert (asset fixes before GLB export), unreal-expert, unity-expert, maya-expert, zbrush-expert.
Skill当 brief 提到以下内容时路由到此 skill
scenario-godot-architecture项目结构、scene 与 node、signal、Resource、autoload、composition、typing、save data
scenario-godot-2dsprite、TileMapLayer、TileSet、platformer 或 top-down 手感、Camera2D、pixel-perfect、2D light、parallax
scenario-godot-3d-worldCharacterBody3D、blockout、CSG、GridMap、terrain、GLB import、Jolt、procedural mesh
scenario-godot-rendering-lightingrenderer 选择、SDFGI、VoxelGI、LightmapGI、environment、fog、shadow、post、Compositor
scenario-godot-shaders
.gdshader
、VisualShader 替代方案、global uniform、screen reading、compute、stencil
scenario-godot-vfxGPUParticles、trail、sub-emitter、particle collision、impact、juice
scenario-godot-animationAnimationPlayer、AnimationTree、tween、skeleton、IK、retargeting、root motion、cutscene
scenario-godot-uiControl layout、container、theme、menu、HUD、focus 与 gamepad、localization、手机缩放
scenario-godot-gameplaystate machine、inventory、dialogue、save 与 load、navigation、AI、procedural generation、input
scenario-godot-audiobus、effect、spatial audio、adaptive music、SFX variation
scenario-godot-multiplayer高层 multiplayer、RPC、authority、spawner 与 synchronizer、lobby、dedicated server
scenario-godot-pipeline-automationCLI 与 CI、editor plugin、GUT 与 gdUnit4、import plugin、GDExtension、MCP workflow
scenario-godot-performance-exportprofiler、monitor、stutter、mobile、web、desktop 与 Steam export、signing
跨领域事项只能有一个 owner：shader stutter 和 web threading 归 scenario-godot-performance-export，并在 brief 中注明第二个 skill。每次 handoff packet 都必须包含：project path 与 channel、以数字表达的 brief、通过 toolkit call 完成的工作、证据（result JSON path、contact sheet 与 flag、带 
budget_check
的 CSV、JUnit 总数、export size）、Verified、Assumed、open issue，以及 fence（接收方可以修改的范围）。接收方在基于现有结果继续工作前，必须先复现其中一项证据。姐妹团队：blender-expert（GLB export 前修复 asset）、unreal-expert、unity-expert、maya-expert、zbrush-expert。

Scenario assets into Godot

将场景资产接入 Godot

AssetGenerated withLands in
sprites, props, icons, tilesets, UI piecesscenario-game-assetsscenario-godot-2d, scenario-godot-ui
animation frames, sprite sheets, VFX loopsscenario-sprite-animation, scenario-sprite-pipelinescenario-godot-2d (SpriteFrames), scenario-godot-vfx (flipbooks)
parallax planesscenario-parallax-stagescenario-godot-2d (Parallax2D)
GLB meshesscenario-3dscenario-godot-3d-world (import), scenario-godot-animation (rigs)
PBR textures, tileable materialsscenario-texturesscenario-godot-rendering-lighting, scenario-godot-shaders
skyboxes, 360 panoramasscenario-skyboxesscenario-godot-rendering-lighting (sky)
music, SFX, ambience, voicescenario-audio, scenario-elevenlabsscenario-godot-audio
Check the asset before import (scenario-quality-gate) and again after it, in a capture from the game camera judged by the receiving skill, which also audits GLB scale, pivot and triangle count.
资产生成方式接收 skill
sprite、prop、icon、tileset、UI 组件scenario-game-assetsscenario-godot-2d、scenario-godot-ui
animation frame、sprite sheet、VFX loopscenario-sprite-animation、scenario-sprite-pipelinescenario-godot-2d（SpriteFrames）、scenario-godot-vfx（flipbook）
parallax planescenario-parallax-stagescenario-godot-2d（Parallax2D）
GLB meshscenario-3dscenario-godot-3d-world（import）、scenario-godot-animation（rig）
PBR texture、可平铺 materialscenario-texturesscenario-godot-rendering-lighting、scenario-godot-shaders
skybox、360 panoramascenario-skyboxesscenario-godot-rendering-lighting（sky）
music、SFX、ambience、voicescenario-audio、scenario-elevenlabsscenario-godot-audio
Import 前通过 scenario-quality-gate 检查资产，import 后再从游戏相机 capture 并由接收 skill 进行判断；接收 skill 还应审计 GLB scale、pivot 和 triangle count。

Godot 4.7 traps and macOS notes

Godot 4.7 陷阱与 macOS 注意事项

Read 
references/traps.md
 before the first job: Godot 3 names that pass 
--check-only
, 
--script
hangs, unknown flags ignored, 
-d
waiting on stdin, what headless cannot do (MultiMesh writes, GPUParticles), 
ProjectSettings.save()
rewriting 
project.godot
, import crashes, deprecated APIs; then the macOS binary, template and 
user://
paths, window focus, and Metal profiling.
首次作业前阅读 
references/traps.md
：会通过 
--check-only
的 Godot 3 名称、会卡住的 
--script
、被忽略的未知 flag、等待 stdin 的 
-d
、headless 无法完成的工作（MultiMesh 写入、GPUParticles）、重写 
project.godot
的 
ProjectSettings.save()
、import 崩溃、已弃用的 API；以及 macOS binary、template 和 
user://
path、window focus 与 Metal profiling。

References

参考资料

  • references/expert-notes.md
    : expert claims by source with timestamps, and traps observed while building the toolkit.
  • references/procedures.md
    : the toolkit API in full, job-writing rules, and each procedure with its live test and result.
  • references/critique.md
    : the rubric for judging an agent's Godot output and a handoff.
  • references/gui-paths.md
    : editor menus and settings for the same tasks.
  • references/sources.md
    : every source with credentials, URLs and best timestamps.
  • references/expert-notes.md
    ：按来源列出的专家结论与时间戳，以及构建 toolkit 时观察到的陷阱。
  • references/procedures.md
    ：完整的 toolkit API、作业编写规则，以及每项 procedure 的 live test 和结果。
  • references/critique.md
    ：用于评判 Agent Godot 输出与完成交接的 rubric。
  • references/gui-paths.md
    ：执行同类任务时对应的 editor menu 和 setting。
  • references/sources.md
    ：所有来源、凭据、URL 和最佳时间戳。