scenario-godot-expert

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

目标：Godot 4.7.2.stable（标准版本，不含 C#），默认使用 Metal 的 Apple Silicon Mac，或使用 D3D12 的 Windows。

Godot 专家的工作是一个基于证据的循环：设定预算，构建一个阶段，测量，查看，修复，然后继续推进。没有鼠标的 Agent 要通过选择正确的通道、仅在获得机器可读结果时才继续，并且绝不只相信单一信号来完成这一流程。本技能就是该协议，也是每项 scenario-godot-* 技能都会调用的共享工具包（scripts/）以及团队地图。如果此处提到的同级技能不在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无需人工值守，请根据工具架构继续操作并标记这一缺口。

状态（2026-10-02）： 以下每个工具包函数都已在此处的 Godot 4.7.2 中运行（23 项实时测试、17 项离线测试，全部通过；references/procedures.md）。

立场（专家增量）

1. 无头模式输出才是真相；编辑器的 Output 面板不是。 抓取该面板的 MCP 服务会“报告磁盘上已不存在的行的错误”，而且不会列出所有项目错误（Fennara，2vSYP7GyA5U [00:02:51, 00:06:20]）。PixelLab 的 Agent 会直接运行 Godot 二进制文件并读取控制台（THwZYWuOdZI [00:13:45]）。应结合 AGENT_RESULT 信封和日志扫描来判断，绝不能只看“它是否退出”：脚本存在解析错误时，无论是否使用 --check-only，退出码都是 0；Godot 找不到脚本路径时也是如此（版本差异，已验证；L6）。
2. 每个项目只允许一个写入者。 GUI 编辑器打开项目时，会保留一份已打开场景的副本，因此它的下一次保存可能覆盖无头模式下的编辑 [新增]；合并后的 .tscn 文件可能无法解析（Lilith Duncan，CAJ_iIedx_I [00:01:36]）。该工具包会拒绝操作被 GUI Godot 打开的项目；应通过该编辑器（MCP）进行操作，或请用户将其关闭。绝不要关闭并非由你启动的 Godot 或 Blender 进程 [新增]。
3. 在目标设备上，以毫秒为单位对照预算测量。 先测量再优化（Dan Does Dev，s2C2RO_WMh0 [00:07:12]）；应在真实设备类别上进行性能分析，并将热量因素纳入考量（Ian Bolton，WrjaUNAXYqk [00:09:35]）。无头模式下的帧时间是循环耗时，不代表游戏开销；这台 Mac 上的窗口模式帧时间受显示器刷新率限制；应以 gpu_ms 和 cpu_ms 为准（实测）。
4. 既要观察，也要检查。 每一帧都要经过 gd_review.image_checks 检查，并生成一张需要打开查看的联系表。无头模式不会绘制画面，因此截图需要在窗口模式下运行才能获取（实测）。AI 资源导入后，应通过肉眼检查朝向、动画方向、图块接缝和摄像机抖动（PixelLab，THwZYWuOdZI）。
5. 测试就是契约。 应断言信号和公开结果，而非内部实现（Godotneers，CreugthdgJ0 [01:08:36]；Butch Wesley，ImqhHLlPfZg [00:16:59]；Mike Schulze，x6GdTgIAFiU [00:24:19]）；每个 await 都要设置超时（Godotneers：2 s；Schulze：5 s）；清空函数并观察测试变红，以证明测试确实能捕获问题（Wesley [00:13:40]）。
6. 面向无需鼠标的操作者进行设计。 将主体和大脑分开，这样测试大脑就能操控角色（Godotneers [00:18:14]）。无头模式没有鼠标设备（Wesley [00:48:33]），但 GUI 输入仍可用于测试无头模式：get_viewport().push_input(event, true) 能将事件传递给 Controls，而 Input.parse_input_event 永远无法将事件传递给设置了 MOUSE_FILTER_STOP 的 Control（scenario-godot-gameplay、scenario-godot-ui，实测）；传入 true，确保坐标使用逻辑坐标而非窗口像素。关卡应保存出生点，而非玩家（Godotneers [00:56:56]）。
7. 只有设置了 owner 并保存，编辑才会持久化。 仅调用 add_child 会使节点在 Scene 面板中不可见，保存时也会丢失（Godot 文档，Running code in the editor）；脚本编辑会绕过 Undo，除非通过 EditorUndoRedoManager 执行（Queble，nW7YtSSJzbQ [00:04:41]）。
8. 如实说明可视化编辑器的限制。 VisualShader、AnimationTree、TileSet 和主题编辑器，以及粒子检查器都属于可视化工具；Agent 会编写 .gdshader、.tres/.tscn 文本，或通过代码构建资源，并指出 GUI 操作路径供人类使用。选择 MCP 时应看反馈保真度，而非工具数量（Fennara [00:09:22]）。

执行渠道

渠道	用途	成本（此处测得）	规则
无头任务 gd_run.run_script	逻辑、数据、审计、场景构建、导入、测试、导出	小型任务需 0.2 s；--import 约需 2 s	默认渠道；监视器会终止挂起的任务（退出码 124）
窗口化任务 capture_scene, capture_sequence, profile_scene	任何需要渲染的内容：截图、序列、GPU 时间	4 个视图预热后约需 1 s；全新项目首次捕获需 10.8 s，5 s 的性能分析需 29.6 s	160x90 窗口，SubViewport 使用请求的尺寸，焦点会交还（观察到每次运行恢复 2 次）；GD_MAX_WINDOWED 为 2
无头编辑器 run_script(editor=True)	EditorInterface：打开、编辑并保存场景；EditorFileSystem	1.1 s	调用编辑器功能前等待 2 帧；不带 -e 时，EditorInterface 调用会失败（观察到）
GUI 编辑器 + MCP（hybridindie godot-editor-mcp）	用户打开的编辑器：实时场景树、选择、可撤销的编辑	stdio 探测需 0.9 s，默认公开 23 个工具	仅当用户已打开编辑器时使用；仅限项目本地的 .mcp.json（gd_live.write_mcp_config）
运行中的游戏 + MCP（tugcantopaloglu）	操作运行中的游戏（输入、求值）	此处未运行	克隆、npm run build、游戏在端口 9090 上自动加载

gd_live.channels(P) 会报告当前可执行的操作。优先使用无头渠道；实时检查场景时再添加 MCP。

首先确认

一次性询问，然后运行：目标平台和最低配置设备；帧预算（默认桌面端 60 fps、移动端 30 fps）；2D 还是 3D；渲染器（桌面端 3D 使用 Forward+，高性能要求的手机使用 Mobile，Web 和最广泛兼容性使用 Compatibility，依据 Ray Hayes，KWhVVMpihsc [00:06:03]）；美术风格，以及是否使用像素美术；用户是否已在编辑器中打开项目；交付内容。然后运行 gd_live.channels(P) 和 gd_run.audit(P, "project")，并将渲染器、物理引擎（3D 使用 Jolt）、拉伸模式、主场景和自动加载项写入计划。

工作流（专家循环）

1. 用数字说明需求。 各平台的预算、分辨率、比例和风格。关卡：后续每项检查都有可供对照的数字。
2. 创建项目。 gd_env.base_project("3d"|"2d", dest)（APFS 克隆，耗时 0.01 s，有独立的 user:// 文件夹），或使用 new_project(...)，后者会写入手动编写的 project.godot 中缺少的项目管理器默认值。关卡：audit(P, "project") 没有标记。
3. 建立基线。 执行 check_all(P)、audit(P, "scene", scene=...)，从固定视角捕获画面；若性能重要，则进行性能分析。关卡：解析错误和脚本错误为零；标记已修复或已列出；已打开图表。
4. 构建一个阶段，使用小型幂等任务（获取或创建、设置 owner、显式保存）。将领域工作交给相应负责人（见下文）。
5. 测量。 执行审计、测试（run_tests）、性能分析（profile_scene）和 gd_stat.budget_check，或检查导出结果。关卡：对照需求中的数字。
6. 查看并检查。 使用相同视角、运行 image_checks、打开联系表，并依据领域技能的评审标准进行评估。关卡：没有会将 ok 设为 false 的标记；更改清晰可见（compare 的 changed_fraction 大于 0）。
7. 推进前先修复，每次只改一项；用 compare 证明一致性或提升。
8. 提供证据并交付。 每个步骤都附上工具包调用，然后写明 已验证（运行内容、结果文件、数字或帧）和 假设（未运行的内容、默认值）。没有数据和亲自查看过的帧，绝不声称场景、着色器、关卡或构建已完成。

共享工具包（scripts/，适用于每个 scenario-godot-* 技能的约定）

import sys; sys.path.insert(0, "<scenario-godot-expert>/scripts")。系统 python3，标准库（Pillow 可选）。

所有 gd_env、gd_run、gd_review、gd_stat 和 gd_live 调用及其默认值和返回值：references/procedures.md 第 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 运行都会返回 ok、error、result（任务的字典）、exit_code、timed_out、parse_errors、script_errors、shader_errors、engine_errors、warnings、leaks、log_path、result_path。输出写入 <project>/.agent_out/（包含 .gdignore）。并发限制：最多 GD_MAX（6）个 Godot 进程、GD_MAX_WINDOWED（2）个窗口化进程，每个项目一个；所有进程均通过 gd_run.godot_slot 调度；GUI 编辑器占用项目时会触发 GodotBusy。

领域任务是项目中的一个 GDScript 文件（AgentKit，即 scripts/agentkit/，会复制到 res://addons/agentkit/）：

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 脚本上的方法：run_script(P, "res://tools/x.gd:build", args)（它会接收任务）。任务期间记录的错误会将 ok 设为 false，除非设置了 expect_errors。脚本错误会中止类型化的 run() -> Dictionary，该函数随后返回 {}：空结果始终会失败（aborted: true），即使设置了 expect_errors 也一样，因此至少要返回 {"ok": true}。export 会报告其写入的每个文件的 bytes（命名文件的大小为 main_bytes），并将 iOS export_project_only Xcode 项目视为 artifact。捕获画面时会模拟项目的拉伸设置（keep、keep_width、keep_height、expand、ignore、整数缩放、缩放因子、视口模式），添加黑边；已在 15 种情况（L20）下与引擎结果匹配。在自己的任务中，使用 agent_capture.grab(vp) 读取 make_viewport SubViewport。辅助函数：arg、out_path、load_scene、wait_frames、wait_physics_frames、wait_seconds、note、is_headless、captured_errors；库 agent_build.gd（save_scene、预设）、agent_profile.gd（record）。领域代码放在 scripts/gd_<domain>.py 和 scripts/agentkit/<domain>/ 中。

数字

数值	对应于	来源
16.67 / 33.33 ms	60 / 30 fps 时的帧预算	算术计算
8.33 ms	在此 120 Hz 显示器上的窗口化 frame_ms 下限，即使使用 --disable-vsync 也是如此	实测
6.9 ms	无头帧节奏：低处理器使用率睡眠（low_processor_usage_mode_sleep_usec 为 6900），与工作量无关；使用 --fixed-fps 60 进行基准测试，并计时工作量	实测；scenario-godot-gameplay、scenario-godot-ui
1.4 到 1.8 ms / 0	1080p 下 Vulkan fx 测试场景的 GPU p95（四次运行）/ Metal 下的结果	实测
0.2 s、10.2 s	小型任务；被看门狗停止的卡死任务（超时 20 s）	实测
60.8 / 75.0 / 41.4 MB	Base3D 的 macOS universal zip / Linux x86_64（二进制文件加 .pck）/ Web（9 个文件）导出	实测，L9
430 MB	iOS Xcode 项目（export_project_only），主要为引擎 xcframework	实测，L9

质量门槛

• 可测量： ok 为 true，且没有解析、脚本和着色器错误；check_all 的 failed_files == []；JUnit 的 failures == 0 且 tests > 0；审计标记已修复或有合理说明； budget_check 为 ok（p95 低于目标，卡顿比率不超过 1%）；导出退出码为 0，已记录构件大小， verify_pack 列出预期文件。
• 视觉： 每张捕获图都通过 image_checks（在 all_black、all_white、uniform、 transparent 情况下 ok 为 false），并已在联系表中打开；前后对比使用相同视图。

常见错误

错误	表现	修复
信任退出代码	解析错误，退出代码为 0	run_script/check_all 会读取日志
对使用自动加载的代码使用 --check-only	“找不到标识符：GameState”	使用 check_all（进程内加载）；check_only 会将其归入 autoload_false_positives
手写 project.godot	使用 GodotPhysics3D、拉伸已禁用、UI 不会缩放	使用 new_project，或设置相应键
在新项目中使用 class_name	“找不到标识符”	先运行 import_project
自动加载项与其 class_name 同名	“类 "GameState" 隐藏了一个自动加载单例。”（GDScript 分析器）	为自动加载项使用不同名称（Game），或移除 class_name
在无头模式下捕获或使用 --write-movie	绘制帧数为 0；--write-movie 会崩溃	使用窗口模式的 capture_scene
在 Metal 上进行 GPU 计时	gpu_ms 为 0	使用 profile_scene(driver="vulkan")
导出到项目目录内	下次会将构建内容导入并打包	导出到外部，或使用 .gdignore（自动）
macOS 导出	“ETC2 ASTC”或“无效的捆绑包标识符”	设置 import_etc2_astc=true；ensure_preset 会设置捆绑包 ID
克隆共享 user://	其他 Agent 克隆的存档、输入映射和着色器缓存会出现（每个克隆都命名为 Base3D）	base_project 默认会隔离；其他临时项目可使用 gd_env.isolate_user_dir(P)
逐帧使用 TIME_PROCESS	每行 CSV 的值都相同（监视器约每秒刷新一次；在 --fixed-fps 下为 0）	使用 profile_scene 的 process_wall_ms 列，或使用哨兵节点

团队路由与交接

技能	简报提到以下内容时路由至此
scenario-godot-architecture	项目结构、场景与节点的取舍、信号、资源、自动加载、组合、类型、存档数据
scenario-godot-2d	精灵、TileMapLayer、TileSet、平台跳跃或俯视视角的感觉、Camera2D、像素级精准、2D 灯光、视差
scenario-godot-3d-world	CharacterBody3D、白盒、CSG、GridMap、地形、GLB 导入、Jolt、程序化网格
scenario-godot-rendering-lighting	渲染器选择、SDFGI、VoxelGI、LightmapGI、环境、雾、阴影、后期处理、Compositor
scenario-godot-shaders	.gdshader、VisualShader 替代方案、全局 uniform、屏幕读取、计算着色器、模板缓冲
scenario-godot-vfx	GPUParticles、轨迹、子发射器、粒子碰撞、冲击效果、爽快感
scenario-godot-animation	AnimationPlayer、AnimationTree、补间动画、骨骼、IK、重定向、根运动、过场动画
scenario-godot-ui	Control 布局、容器、主题、菜单、HUD、焦点与游戏手柄、本地化、手机上的缩放
scenario-godot-gameplay	状态机、库存、对话、存档与读档、导航、AI、程序化生成、输入
scenario-godot-audio	总线、效果、空间音频、自适应音乐、SFX 变化
scenario-godot-multiplayer	高级多人游戏、RPC、权限、生成器与同步器、大厅、专用服务器
scenario-godot-pipeline-automation	CLI 与 CI、编辑器插件、GUT 和 gdUnit4、导入插件、GDExtension、MCP 工作流
scenario-godot-performance-export	性能分析器、监视器、卡顿、移动端、Web、桌面端与 Steam 导出、签名

横跨多个领域的事项由一个团队负责：着色器卡顿和 Web 线程处理交由 scenario-godot-performance-export，并在简报中注明第二项技能。每份交接材料都包含：项目路径和渠道、以数字列出的简报内容、已通过工具包调用完成的工作、证据（结果 JSON 路径、联系表和标记、含 budget_check 的 CSV、JUnit 总计、导出大小）、已验证内容、假设、未解决事项，以及边界（接收方可以修改的内容）。接收方须先复现一项证据，再以此为基础开展工作。协作团队：blender-expert（在 GLB 导出前修复资源）、unreal-expert、unity-expert、maya-expert、zbrush-expert。

将 Scenario 资产导入 Godot

资产	生成工具	保存位置
精灵、道具、图标、图块集、UI 组件	scenario-game-assets	scenario-godot-2d、scenario-godot-ui
动画帧、精灵表、VFX 循环	scenario-sprite-animation、scenario-sprite-pipeline	scenario-godot-2d（SpriteFrames）、scenario-godot-vfx（翻页动画）
视差平面	scenario-parallax-stage	scenario-godot-2d（Parallax2D）
GLB 网格	scenario-3d	scenario-godot-3d-world（导入）、scenario-godot-animation（骨架）
PBR 纹理、可平铺材质	scenario-textures	scenario-godot-rendering-lighting、scenario-godot-shaders
天空盒、360 全景	scenario-skyboxes	scenario-godot-rendering-lighting（天空）
音乐、SFX、环境音、语音	scenario-audio、scenario-elevenlabs	scenario-godot-audio

导入前使用 scenario-quality-gate 检查资产；导入后，再从游戏摄像机的捕获画面检查一次，由接收该资产的技能进行评判，并审核 GLB 的缩放、枢轴和三角形数量。

Godot 4.7 注意事项和平台说明

首次执行任务前，请阅读 references/traps.md：其中介绍了通过 --check-only 检查的 Godot 3 名称、会卡住的 --script、被忽略的未知标志、等待标准输入的 -d、无头模式无法执行的操作（MultiMesh 写入、GPUParticles）、ProjectSettings.save() 重写 project.godot、导入崩溃和已弃用的 API；随后是 macOS 二进制文件、模板和 user:// 路径、窗口焦点及 Metal 性能分析；最后是 Windows 路径和 PYTHONUTF8=1 规则。

参考资料

• references/expert-notes.md：按来源整理的专家说法及时间戳，以及构建工具包时发现的注意事项。
• references/procedures.md：完整的工具包 API、任务编写规则，以及每项操作的实时测试和结果。
• references/critique.md：评判 Agent 的 Godot 输出和交接内容所用的评分标准。
• references/gui-paths.md：执行相同任务时使用的编辑器菜单和设置。
• references/sources.md：所有来源及其凭证、URL 和最佳时间戳。