godot-builder

Godot 构建器技能

godot-builder 技能为使用 Godot 4.7-stable CLI 进行程序化游戏开发和无头自动化提供专家级基础。可通过 GODOT_PATH 和 GODOT_CONSOLE_PATH 环境变量覆盖路径。

专家级自动化思维

• 通过 XDG 实现无头隔离：同时运行多个 Godot 实例时，务必覆盖 XDG_DATA_HOME 和 XDG_CONFIG_HOME，以防实例间缓存损坏。
• 缓存失效（强制导入）：以编程方式删除 .godot/imported/ 目录，强制引擎重新评估已修改的全局导入设置。
• 明确所有权：场景节点必须将其 owner 属性设为场景根节点，否则序列化时会被丢弃。
• 对延迟敏感的多线程：GPU 交互（纹理、图像数据）必须留在主线程，以避免管线停顿和死锁。

严格禁止的反模式（绝不允许）

• 绝不要在无头模式下保存运行时生成的 UID；ResourceSaver.save() 在无头模式下不会序列化 UID。请在后处理中调用 godot -e --headless --import。
• 绝不要在 Godot 4.4+ 中使用 Resource.duplicate(true)；请使用 duplicate_deep(Resource.DEEP_DUPLICATE_ALL)，以防止程序化状态泄漏。
• 绝不要硬编码 .tscn 或 .tres 扩展名；始终通过 uid:// 或不带扩展名的路径加载，以避免导出的二进制构建失败。
• 绝不要在辅助线程上执行受 GPU 限制的调用。请使用 RenderingServer.call_on_render_thread()。
• 绝不要为专用服务器构建启用 Shader Baker；无头后端会忽略它。
• 绝不要在调用 has_id() 之前调用 ResourceUID.set_id()；这会导致 CLI 致命崩溃。
• 绝不要在首帧以编程方式移动底层 CanvasItems 时跳过 RenderingServer.canvas_item_reset_physics_interpolation()；否则会导致渲染系统与物理系统之间出现视觉不同步。

专家级自动化工作流

不要加载单项任务所需的完整脚本目录。只加载当前工作流中列出的必需脚本。轻量级流程封装脚本（launch_editor.py、run_project.py、stop_project.py、get_*、list_projects.py）位于附录中——除非确实需要执行对应的 CLI 操作，否则不要预加载。

工作流 #1：严格的 3D 资源管线

用途：将原始 3D 资源自动导入生产就绪的场景，并生成精确的物理碰撞。

• 必需——尝试 CLI 标志前先阅读：gltf_processor.py → collision_generator.py → save_scene.py。然后运行 godot -e --headless --import（或 import_automator.py）——不要自行设计其他标志顺序。
• 顺序：gltf_processor.py -> collision_generator.py -> save_scene.py -> 无头 --import。
• 专家级防护：为每个节点明确设置 owner。强制执行最终的无头导入，以修复 UID 未序列化的问题。
• 故障模式 / 回退方案：
  • 无头保存后缺少 UID：这是预期情况——ResourceSaver 不会在无头模式下序列化 UID。回退方案：重新运行 --import；如果仍缺少 UID，则在导入完成后运行 update_project_uids.py。
  • 导入卡住 / 始终无法退出：脚本遗漏了 quit()，或编辑器导入正在等待 GPU。回退方案：确保后处理脚本调用 get_tree().quit()；通过 stop_project.py 结束 PID，并在隔离的 XDG_* 环境下重试。
  • 碰撞网格为空 / 错误：源 glTF 没有网格数组，或节点路径错误。回退方案：检查 gltf_processor.py 的输出场景，然后重新生成碰撞。

工作流 #2：程序化关卡优化与 4.4+ 扩展

用途：生成经过优化的程序化关卡区块，避免实例之间的共享资源状态损坏。

• 必须在自行尝试前阅读：csg_optimizer.py → navmesh_baker.py。在烘焙步骤之间应用 duplicate_deep(Resource.DEEP_DUPLICATE_ALL)，不要使用 duplicate(true)。
• 顺序：csg_optimizer.py -> duplicate_deep(ALL) -> navmesh_baker.py。
• 专家防护：使用 duplicate_deep 隔离材质和资源。在触发 NavMesh 寻路前，将 CSG 烘焙为静态几何体。
• 故障模式 / 后备方案：
  • 在实时 CSG 上烘焙 NavMesh：出现寻路空洞 / 空白区域。后备方案：确认 CSG→静态网格烘焙已完成，再运行 navmesh_baker.py。
  • 区块之间的材质 / 状态相互污染：使用了浅复制。后备方案：对每个实例使用 DEEP_DUPLICATE_ALL 重新烘焙。
  • 无头烘焙卡住：烘焙后缺少 quit()。后备方案：添加显式退出；通过 XDG_DATA_HOME / XDG_CONFIG_HOME 隔离。

工作流 #3：生产环境 CI/CD 与强制导入验证

用途：验证跨平台构建，并确保严格应用全局项目设置（VRAM 压缩）。

• 必须在自行尝试导出标记前阅读：test_runner.py → profile_generator.py → ci_export_prepper.gd → ci_exporter.py。
• 顺序：rm -rf .godot/imported -> test_runner.py -> profile_generator.py -> ci_exporter.py。
• 专家防护：强制完整重新导入以验证资源压缩。通过 XDG 变量隔离 CI 运行。通过环境变量注入安全的密钥库路径。
• 故障模式 / 后备方案：
  • 缺少导出预设 / 平台错误：未针对目标平台修改 export_presets.cfg。后备方案：在无头模式下运行 ci_export_prepper.gd，然后再运行 --export-release；确认预设名称与 CI 矩阵一致。
  • 无头 CI 卡住（未退出）：脚本未调用 quit()。后备方案：始终以 quit() 结束 -s 脚本；对于非零退出的卡住情况，先终止，再通过 XDG 隔离重试。
  • 清除缓存后 UID / 导入验证失败：重新导入未完成。后备方案：重新运行 --import，然后运行 update_project_uids.py；导入未顺利完成前不要导出。

---

自动化与 CI/CD 流水线（Godot 4.7）

专业的 Godot 构建要求对资源和二进制导出采用“零接触”理念。

1. 以编程方式重新导入资源

• 绝不要手动选择 500 个纹理来更改其压缩设置。
• 使用 ConfigFile 修改 .import 文件，并使用 EditorFileSystem.reimport_files() 在主线程上安全地触发批量更新。

2. 孤立资源检测（冗余扫描）

• 绝不要认为 res:// 中没有冗余内容。随着时间推移，被删除的场景会留下孤立的纹理和声音，使最终构建膨胀。
• 使用 ResourceLoader.get_dependencies() 递归追踪与你的“主场景”关联的所有资源，并将其他资源标记为冗余。

3. 无头 CI/CD 环境

• 在运行最终的 --export-release 之前，使用 --headless --script 执行版本管理任务（修改 export_presets.cfg）。
• 提示：务必在无头脚本末尾调用 quit()，否则 CI 运行器会无限期卡住。

---

专家流水线脚本（按需加载）

主要自动化脚本——仅在匹配的工作流需要时打开。

场景与资源管线

• gltf_processor.py：在无头模式下将原始 .glb/.gltf 资源转换为 Godot 场景。
• collision_generator.py：根据网格数据生成 ConcavePolygonShape3D 物理形状。
• save_scene.py：将当前节点树安全地打包并保存到磁盘（请先设置 owner）。
• csg_optimizer.py：将程序化 CSG 布尔运算烘焙为静态网格。
• navmesh_baker.py：异步执行无头 NavMesh 寻路烘焙。
• tilemap_generator.py：根据 JSON 数据以程序化方式构建 TileMapLayer 网格。
• ui_assembler.py：根据标准化 JSON 结构构建复杂 GUI 布局。
• create_scene.py / add_node.py / load_sprite.py：以编程方式构建场景树。
• export_mesh_library.py：将 3D 场景转换为供 GridMap 使用的 .meshlib 资源。
• orphan_asset_scanner.gd：递归追踪依赖项，以识别未使用的资源。

CI / 导入 / 导出管线

• ci_exporter.py：在无头模式下编排多平台发行版导出。
• ci_export_prepper.gd：用于 export_presets.cfg 的无头版本管理脚本。
• profile_generator.py：生成特性配置文件，以优化模块剥离。
• test_runner.py：在无头模式下执行单元测试和集成测试（GUT/doctest）。
• import_automator.py / asset_reimport_utility.gd：强制执行批量导入。
• update_project_uids.py / get_uid.py：无头保存后同步 UID。
• config_compiler.py：将 JSON/CSV 数据编译为经过优化的 .cfg 配置文件。

附录：轻量级进程包装器（不要预加载）

仅用于便捷的 CLI 操作，并非专家级管线说明。仅在需要执行对应的进程操作时加载。

• launch_editor.py / run_project.py / stop_project.py：编辑器/游戏进程生命周期管理。
• get_debug_output.py / get_godot_version.py / get_project_info.py / list_projects.py：只读的项目/进程检查。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在路由到相关领域时加载相关技能——不要预加载整个技能网络。

官方文档

• 命令行教程 — 每个构建器封装都会调用的 --headless、--path、-s/--script、--import 和 --export-* 标志。
• 导出项目 — 导出预设、CLI 发布版/调试版导出流程，以及 CI 为什么必须在 --export-release 之前修改 export_presets.cfg。
• 功能标签 — 剥离模块时使用的自定义标签/功能配置标签，或通过 OS.has_feature 控制 CI 烟雾测试路径时使用的标签。
• 为专用服务器导出 — 无头/服务器导出限制（不能假设有 GPU 烘焙），适用于配合 XDG 变量隔离 CI。
• 导入流程 — .import + .godot/imported 生命周期；删除导入缓存为何会强制重新验证整个项目。
• 导入 3D 场景 — 在使用 GLTFDocument/ResourceSaver 自动化之前的 glTF→场景流水线入口。
• 可用的 3D 格式 — 无头转换器和碰撞体生成对 glTF/GLB 的要求。
• 使用 CSG 工具 — 程序化 CSG 为何必须在发布或烘焙 NavMesh 之前烘焙为静态网格。
• 使用 NavigationMeshes — CSG/静态几何体就位后的无头 NavMesh 烘焙职责划分和区域设置。
• ResourceUID — 无头保存后安全地同步 has_id/set_id/uid://（无头模式下 ResourceSaver 不会序列化 UID）。
• ResourceSaver — 用于以编程方式写入 .tscn 的打包/保存 API；必须在 PackedScene.pack 之前设置所有权。
• EditorFileSystem — 使用 @tool EditorScript 强制批量导入的 reimport_files()。

相关技能

前置条件

• godot-project-foundations — 启动 CLI、自动执行导入/导出之前，必须先准备好功能文件夹、project.godot 元数据和 VCS 忽略规则。
• godot-gdscript-mastery — 每个 -s 脚本都会用到的无头 SceneTree worker、类型化 Resources 和 quit() 生命周期模式。
• godot-resource-data-patterns — 可防止构建器运行之间程序化状态泄漏的 PackedScene、UID 路径和深度复制规则。

补充

• godot-version-migration — CI / 无头目标引擎升级：通过迁移中心逐步升级，然后再基于新 API 构建。
• godot-export-builds — ci_exporter.py 编排之外的平台模板、代码签名 / 密钥库和筛选规则。
• godot-3d-world-building — CSG/GridMap/MeshLibrary 创作，此技能会以无头模式烘焙并导出。
• godot-navigation-pathfinding — 使用 navmesh_baker.py 生成的 NavMesh 的运行时 Agent 和图层成本。
• godot-tilemap-mastery — tilemap_generator.py 生成场景所遵循的 TileSet/TileMapLayer 约定。
• godot-ui-containers — ui_assembler.py 应输出的容器布局规则，而不是绝对 Control 位置。
• godot-physics-3d — collision_generator.py 创建的三角网格刚体的碰撞层 / 形状。

下游 / 使用方

• godot-testing-patterns — 导入 / 导出步骤后，在 CI 中通过 test_runner.py 启动的 GUT / 集成测试套件。
• godot-performance-optimization — 当孤立项扫描、导入压缩或导出大小仍未达到预算时升级处理。
• godot-monte-carlo-balancer — 构建器 CI 冒烟测试通过后，用于平衡模拟的无头 test_runner 校准循环。
• godot-debugging-profiling — 无头导入 / 导出在没有 GUI 的情况下失败时，使用 get_debug_output.py 日志。

主索引

• godot-master — 库路由器和镜像模块入口；需要确定哪个领域技能负责跨领域构建 / 自动化事项时，请打开此项。