用途
该技能用于让 Godot 4.2+ 的无头（headless）开发变得可复现，避免环境漂移和特定环境下的失败。适用范围为 Godot 4.2+，Godot 3.x 不在范围内。
主要能力与强制规则
以下规则优先级最高：
-
始终使用
--headless --path <PROJECT_DIR>，以消除对当前工作目录（cwd）的依赖。 -
始终将日志捕获到项目目录下。对于自行终止的命令，使用
2>&1 | tee <PROJECT_DIR>/logs/<name>.log，并从${PIPESTATUS[0]}获取 Godot 的状态。当 timeout 是唯一的终止机制时，直接使用> <PROJECT_DIR>/logs/<name>.log 2>&1重定向，并显式捕获 timeout 的状态；不要将该次运行通过 tee 管道。 -
对任何脚本化的 Godot 运行，始终设置项目本地的
XDG_DATA_HOME、XDG_CONFIG_HOME和XDG_CACHE_HOME。三者必须一起设置——Godot 会写入这三类目录，部分重定向仍会命中未设置项对应的不可写默认路径。这是避免 CI/沙箱写入失败（如Can't open file for writing: ~/.config/godot/...）所必需的；在开发者机器上无害，唯一效果是每个项目的元数据/缓存位于<PROJECT_DIR>/.godot-xdg/而非用户全局目录。需将.godot-xdg/加入.gitignore。注意：这些导出会影响同一 shell 中启动的每个进程，而不仅是 godot。如果同一 shell 会话还运行遵循 XDG 变量的非 Godot 工具（例如用于 Web 导出测试的 Node/Playwright 浏览器自动化步骤），该工具自身的缓存/数据查找也会静默移动到
<PROJECT_DIR>/.godot-xdg/下，可能找不到它安装在别处的东西（已观察到：Playwright 报告缺少浏览器可执行文件）。因此应仅在调用 godot 的特定命令/子 shell 中导出这三个变量，或在同一 shell 中运行无关工具前显式 unset/恢复它们。 -
绝不以纯文本方式编辑
.tscn，编辑必须通过--headless --script完成。 -
对于重复的验证命令，将其标准化为
tools/*.sh；手动调整后，通过相同的脚本重新运行。 -
如果缺少
res://tools/godot_apply_patch.gd，在运行 patch 命令前，将相对于本 SKILL.md 解析的tools/godot_apply_patch.gd复制到<PROJECT_DIR>/tools/godot_apply_patch.gd。 -
将启动冒烟测试与逻辑测试分开：冒烟测试启动
run/main_scene；run_tests.gd保存项目特定的逻辑检查。
使用方式
最小冒烟包装模板
对于重复的启动验证，标准化为 <PROJECT_DIR>/tools/smoke.sh。其他重复调用（run_tests.sh、export_web.sh 等）遵循相同形态——仅 godot 参数和日志文件名不同。
#!/usr/bin/env bash
set -euo pipefail
PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
# Project-local XDG (always; see Required rules above).
export XDG_DATA_HOME="$PROJECT_DIR/.godot-xdg/data"
export XDG_CONFIG_HOME="$PROJECT_DIR/.godot-xdg/config"
export XDG_CACHE_HOME="$PROJECT_DIR/.godot-xdg/cache"
mkdir -p "$XDG_DATA_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$PROJECT_DIR/logs"
# Smoke = launch run/main_scene headlessly, quit after a few frames.
# --quit-after <N> bounds the run by frame count.
godot --headless --path "$PROJECT_DIR" --quit-after 60 \
2>&1 | tee "$PROJECT_DIR/logs/smoke.log"
echo "godot_exit=${PIPESTATUS[0]}"
冒烟测试通过标准
- 捕获的退出码（
${PIPESTATUS[0]}）为 0。 logs/smoke.log中不包含项目已知警告白名单之外的ERROR、SCRIPT ERROR、Failed to load或Parse Error行（参见references/headless_cli.md）。- 存在启动可见的标记（例如主场景
_ready中的print()，或没有出现 "Main scene can't be loaded"）。
遇到困难时需提供
- 完整命令行和
logs/*.log godot --version输出- 导出时
export_presets.cfg是否存在
详细参考文件
需要细节时，阅读以下文件（相对于本技能的基础目录）：
references/headless_cli.md— CLI 约定、XDG 设置、已知警告references/export_and_import.md— 导出/导入规则references/scene_editing_via_godot.md— 安全的 .tscn 编辑、patch JSON schema 与操作references/testing_headless.md— 无头测试策略
官方文档
如果不确定 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
适用场景
- 在命令行或 CI 环境中运行 Godot 4.2+ 项目
- 执行 Godot CLI 命令、导出项目
- 通过脚本编辑
.tscn场景文件 - 运行无头测试与启动冒烟验证
限制
以下内容不在范围内：
- 超出项目本地 XDG 包装的 GUI/操作系统特定设置
- 关卡设计、渲染验证、性能调优
- 游戏特定的计分、胜负规则、控制与模拟策略