headless-godot

用途

Headless Godot 是一套开发规则集，目标是让 Godot 4.2+ 的无头（headless）开发过程可复现，避免配置漂移和因环境差异导致的失败。它适用于需要在命令行、沙箱或 CI 环境中运行 Godot 的场景。

适用范围

• 支持 Godot 4.2+。
• Godot 3.x 不在范围内。

主要能力与强制规则

以下为最高优先级的必需规则：

1. 始终使用 --headless --path <PROJECT_DIR>，以消除对当前工作目录（cwd）的依赖。
2. 始终捕获日志：2>&1 | tee logs/<name>.log。
3. 在沙箱/CI 中，或在 user:// / XDG 写入失败后，使用项目本地的 XDG_DATA_HOME、XDG_CONFIG_HOME 和 XDG_CACHE_HOME。
4. 绝不以纯文本方式编辑 .tscn，编辑必须通过 --headless --script 进行。
5. 对于重复的验证命令，将其标准化为 tools/*.sh；手动调整后，通过同一脚本重新运行。
6. 如果缺少 res://tools/godot_apply_patch.gd，在运行补丁命令前，先将 .agents/skills/headless-godot/tools/godot_apply_patch.gd 复制到 <PROJECT_DIR>/tools/godot_apply_patch.gd。
7. 将启动冒烟测试与逻辑测试分开：冒烟测试启动 run/main_scene；run_tests.gd 保存项目特定的逻辑检查。

使用方式

当需要细节时，阅读以下文件（相对于该技能的基础目录）：

• skills/headless_cli.md — CLI 约定、XDG 设置、已知警告
• skills/export_and_import.md — 导出/导入规则
• skills/scene_editing_via_godot.md — 安全的 .tscn 编辑、补丁 JSON schema 与操作
• skills/testing_headless.md — 无头测试策略

如果遇到问题，需提供：

• 完整命令行和 logs/*.log
• godot --version 输出
• 导出时 export_presets.cfg 是否存在

适用场景

• 在命令行、沙箱或 CI 中运行 Godot CLI 命令。
• 通过脚本编辑 .tscn 场景文件。
• 执行无头导出、导入与测试。

限制

以下内容不在范围内：

• 超出项目本地 XDG 包装器的 GUI/操作系统特定设置。
• 关卡设计、渲染验证、性能调优。
• 游戏特定的计分、胜负规则、控制与模拟策略。

参考

如果对 Godot CLI 或功能不确定，可查阅：

• https://docs.godotengine.org/en/4.4/tutorials/editor/command_line_tutorial.html
• https://docs.godotengine.org/en/4.4/tutorials/export/exporting_for_dedicated_servers.html
• https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html