Godot Builder

Godot Builder Skill

The godot-builder skill provides an expert-grade foundation for programmatic game development and headless automation using the Godot 4.7-stable CLI. Override paths via GODOT_PATH and GODOT_CONSOLE_PATH environment variables.

Expert Automation Mindset

• Headless Isolation via XDG: When running multiple concurrent Godot instances, always override XDG_DATA_HOME and XDG_CONFIG_HOME to prevent cache corruption between instances.
• Cache Invalidation (Force Import): Programmatically delete the .godot/imported/ directory to force the engine to re-evaluate modified global import settings.
• Explicit Ownership: Scene nodes MUST have their owner property set to the scene root, or they will be discarded during serialization.
• Latency-Sensitive Multi-threading: GPU interactions (textures, image data) must stay on the main thread to avoid pipeline stalls and deadlocks.

Hardened Anti-Patterns (NEVER List)

• NEVER save runtime-generated UIDs headlessly; ResourceSaver.save() does NOT serialize UIDs in headless mode. Invoke godot -e --headless --import as a post-process.
• NEVER use Resource.duplicate(true) in Godot 4.4+; use duplicate_deep(Resource.DEEP_DUPLICATE_ALL) to prevent procedural state-bleed.
• NEVER hardcode .tscn or .tres extensions; always load via uid:// or without extensions to avoid failures in exported binary builds.
• NEVER execute GPU-bound calls on secondary threads. Use RenderingServer.call_on_render_thread().
• NEVER enable the Shader Baker for Dedicated Server builds; the headless backend ignores it.
• NEVER call ResourceUID.set_id() without calling has_id() first; it causes a fatal CLI crash.
• NEVER skip RenderingServer.canvas_item_reset_physics_interpolation() when programmatically moving low-level CanvasItems on their first frame; failure causes visual desync between rendering and physics systems.

Expert Automation Workflows

Do NOT Load the full script catalog for a single task. Load only the MANDATORY scripts named in the active workflow. Thin process wrappers (launch_editor.py, run_project.py, stop_project.py, get_*, list_projects.py) live in the appendix — do not preload them unless that exact CLI action is required.

Workflow #1: The Hardened 3D Asset Pipeline

Purpose: Automates the ingestion of raw 3D assets into production-ready scenes with accurate physics collisions.

• MANDATORY — read before improvising CLI flags: gltf_processor.py → collision_generator.py → save_scene.py. Then run godot -e --headless --import (or import_automator.py) — do not invent alternate flag orders.
• Sequence: gltf_processor.py -> collision_generator.py -> save_scene.py -> headless --import.
• Expert Defense: Sets explicit owner for every node. Forces a final headless import to fix the missing UID serialization.
• Failure modes / fallbacks:
  • UID missing after headless save: Expected — ResourceSaver does not serialize UIDs headless. Fallback: re-run --import; if UIDs still missing, run update_project_uids.py after import completes.
  • Import hangs / never exits: Script omitted quit() or editor import is waiting on GPU. Fallback: ensure the post-process script calls get_tree().quit(); kill the PID via stop_project.py and retry with XDG_* isolation.
  • Collision mesh empty / wrong: Source glTF had no mesh arrays or wrong node paths. Fallback: inspect gltf_processor.py output scene before regenerating collisions.

Workflow #2: Procedural Level Optimization & 4.4+ Scaling

Purpose: Generates optimized procedural level chunks without shared resource state corruption between instances.

• MANDATORY — read before improvising: csg_optimizer.py → navmesh_baker.py. Apply duplicate_deep(Resource.DEEP_DUPLICATE_ALL) between bake steps — do not use duplicate(true).
• Sequence: csg_optimizer.py -> duplicate_deep(ALL) -> navmesh_baker.py.
• Expert Defense: Uses duplicate_deep to isolate materials/resources. Bakes CSG to static geometry before triggering NavMesh pathfinding.
• Failure modes / fallbacks:
  • NavMesh bake on live CSG: Pathfinding holes / empty regions. Fallback: confirm CSG→static mesh bake finished before navmesh_baker.py.
  • Material/state bleed across chunks: Used shallow duplicate. Fallback: re-bake with DEEP_DUPLICATE_ALL per instance.
  • Headless bake hang: Missing quit() after bake. Fallback: add explicit quit; isolate via XDG_DATA_HOME / XDG_CONFIG_HOME.

Workflow #3: Production CI/CD & Force-Import Validation

Purpose: Validates cross-platform builds and ensures global project settings (VRAM compression) are strictly applied.

• MANDATORY — read before improvising export flags: test_runner.py → profile_generator.py → ci_export_prepper.gd → ci_exporter.py.
• Sequence: rm -rf .godot/imported -> test_runner.py -> profile_generator.py -> ci_exporter.py.
• Expert Defense: Forces full re-import to validate asset compression. Isolates CI runs via XDG variables. Injects secure keystore paths from environment variables.
• Failure modes / fallbacks:
  • Export preset missing / wrong platform: export_presets.cfg not mutated for the target. Fallback: run ci_export_prepper.gd headlessly before --export-release; verify preset name matches CI matrix.
  • Hung headless CI (no exit): Script never called quit(). Fallback: always end -s scripts with quit(); treat non-zero hang as kill + retry with XDG isolation.
  • UID / import validation fail after cache wipe: Re-import incomplete. Fallback: re-run --import, then update_project_uids.py; do not export until import finishes cleanly.

---

Automation & CI/CD Pipelines (Godot 4.7)

Professional Godot building requires a "Zero-Touch" philosophy for assets and binary exports.

1. Programmatic Asset Re-import

• NEVER manually select 500 textures to change their compression.
• Use ConfigFile to mutate .import files and EditorFileSystem.reimport_files() to trigger a batch update on the main thread safely.

2. Orphan Asset Detection (Slop Scan)

• NEVER trust res:// is clean. Over time, deleted scenes leave behind orphaned textures and sounds that bloat the final build.
• Use ResourceLoader.get_dependencies() to recursively trace exactly which assets are linked to your "Main Scene" and flag anything else as slop.

3. Headless CI/CD Context

• Use --headless --script for versioning tasks (mutating export_presets.cfg) before running the final --export-release.
• Tip: Always call quit() at the end of a headless script, or your CI runner will hang indefinitely.

---

Expert Pipeline Scripts (load on demand)

Primary automation scripts — open only when the matching workflow requires them.