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 GODOTPATH and GODOTCONSOLE_PATH environment variables.

Expert Automation Mindset

• Headless Isolation via XDG: When running multiple concurrent Godot instances, always override XDGDATAHOME and XDGCONFIGHOME 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 duplicatedeep(Resource.DEEPDUPLICATE_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.callonrender_thread().
• NEVER enable the Shader Baker for Dedicated Server builds; the headless backend ignores it.
• NEVER call ResourceUID.setid() without calling hasid() first; it causes a fatal CLI crash.
• NEVER skip RenderingServer.canvasitemresetphysicsinterpolation() 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 (launcheditor.py, runproject.py, stopproject.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: [gltfprocessor.py](scripts/gltfprocessor.py) → [collisiongenerator.py](scripts/collisiongenerator.py) → [savescene.py](scripts/savescene.py). Then run godot -e --headless --import (or [importautomator.py](scripts/importautomator.py)) — do not invent alternate flag orders.
• Sequence: gltfprocessor.py -> collisiongenerator.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 [updateprojectuids.py](scripts/updateprojectuids.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 gettree().quit(); kill the PID via [stopproject.py](scripts/stopproject.py) and retry with XDG* isolation. - Collision mesh empty / wrong: Source glTF had no mesh arrays or wrong node paths. Fallback: inspect [gltfprocessor.py](scripts/gltfprocessor.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: [csgoptimizer.py](scripts/csgoptimizer.py) → [navmeshbaker.py](scripts/navmeshbaker.py). Apply duplicatedeep(Resource.DEEPDUPLICATE_ALL) between bake steps — do not use duplicate(true).
• Sequence: csgoptimizer.py -> duplicatedeep(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 [navmeshbaker.py](scripts/navmeshbaker.py). - Material/state bleed across chunks: Used shallow duplicate. Fallback: re-bake with DEEPDUPLICATEALL per instance. - Headless bake hang: Missing quit() after bake. Fallback: add explicit quit; isolate via XDGDATAHOME / XDGCONFIGHOME.

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: [testrunner.py](scripts/testrunner.py) → [profilegenerator.py](scripts/profilegenerator.py) → [ciexportprepper.gd](scripts/ciexportprepper.gd) → [ciexporter.py](scripts/ciexporter.py).
• Sequence: rm -rf .godot/imported -> testrunner.py -> profilegenerator.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: exportpresets.cfg not mutated for the target. Fallback: run [ciexportprepper.gd](scripts/ciexportprepper.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 [updateprojectuids.py](scripts/updateproject_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.

Scene & Asset Pipelines

• gltf_processor.py: Headlessly converts raw .glb/.gltf assets into Godot Scenes.
• collision_generator.py: Generates ConcavePolygonShape3D physics from mesh data.
• save_scene.py: Safely packs and persists the current node tree to disk (set owner first).
• csg_optimizer.py: Bakes procedural CSG boolean operations into static meshes.
• navmesh_baker.py: Executes asynchronous headless NavMesh pathfinding baking.
• tilemap_generator.py: Procedurally builds TileMapLayer grids from JSON data.
• ui_assembler.py: Constructs complex GUI layouts from standardized JSON structures.
• createscene.py / addnode.py / load_sprite.py: Programmatic scene tree builders.
• exportmeshlibrary.py: Converts 3D scenes into .meshlib resources for GridMaps.
• orphanassetscanner.gd: Recursive dependency tracer for identifying unused resources.

CI / Import / Export Pipelines

• ci_exporter.py: Orchestrates multi-platform release exports headlessly.
• ciexportprepper.gd: Headless versioning script for export_presets.cfg.
• profile_generator.py: Generates feature profiles for module-stripping optimization.
• test_runner.py: Executes headless unit and integration tests (GUT/doctest).
• importautomator.py / assetreimport_utility.gd: Batch import enforcement.
• updateprojectuids.py / get_uid.py: UID sync after headless saves.
• config_compiler.py: Compiles JSON/CSV data into optimized .cfg config files.

Appendix: Thin Process Wrappers (Do NOT preload)

Convenience CLI only — not expert pipeline prose. Load when you need that exact process action.

• launcheditor.py / runproject.py / stop_project.py: Editor/game process lifecycle.
• getdebugoutput.py / getgodotversion.py / getprojectinfo.py / list_projects.py: Read-only project/process introspection.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Command line tutorial — --headless, --path, -s/--script, --import, and --export-* flags that every builder wrapper invokes.
• Exporting projects — Export presets, CLI release/debug export flow, and why CI must mutate exportpresets.cfg before --export-release.
• Feature tags — Custom/feature-profile tags used when stripping modules or gating CI smoke paths with OS.hasfeature.
• Exporting for dedicated servers — Headless/server export constraints (no GPU bake assumptions) that pair with CI isolation via XDG vars.
• Import process — .import + .godot/imported lifecycle; why deleting imported cache forces project-wide revalidation.
• Importing 3D scenes — glTF→scene pipeline entry before GLTFDocument/ResourceSaver automation.
• Available 3D formats — glTF/GLB expectations for headless converters and collision generation.
• Using CSG tools — Why procedural CSG must bake to static meshes before shipping or NavMesh baking.
• Using NavigationMeshes — Headless NavMesh bake ownership and region setup after CSG/static geometry lands.
• ResourceUID — Safe hasid/set_id/uid:// sync after headless saves (UIDs are not serialized by ResourceSaver headless).
• ResourceSaver — Pack/save API for programmatic .tscn writes; ownership must be set before PackedScene.pack.
• EditorFileSystem — reimportfiles() for batch import enforcement from @tool EditorScripts.

Related Skills

Prerequisites

• godot-project-foundations — Feature folders, project.godot metadata, and VCS ignores must exist before CLI launch/import/export automation.
• godot-gdscript-mastery — Headless SceneTree workers, typed Resources, and quit() lifecycle patterns used by every -s script.
• godot-resource-data-patterns — PackedScene, UID paths, and deep-duplicate rules that prevent procedural state-bleed across builder runs.

Complements

• godot-version-migration — CI / headless target engine bumps: hop-by-hop via the migration hub before baking against new APIs.
• godot-export-builds — Platform templates, codesign/keystore, and filter rules that sit on top of ci_exporter.py orchestration.
• godot-3d-world-building — CSG/GridMap/MeshLibrary authoring that this skill bakes and exports headlessly.
• godot-navigation-pathfinding — Runtime agents and layer costs that consume NavMeshes produced by navmesh_baker.py.
• godot-tilemap-mastery — TileSet/TileMapLayer conventions for scenes generated by tilemap_generator.py.
• godot-ui-containers — Container layout rules that ui_assembler.py should emit instead of absolute Control positions.
• godot-physics-3d — Collision layers/shapes for trimesh bodies created by collision_generator.py.

Downstream / consumers

• godot-testing-patterns — GUT/integration suites launched through test_runner.py in CI after import/export steps.
• godot-performance-optimization — Escalate when orphan scans, import compression, or export size still miss budgets.
• godot-monte-carlo-balancer — Headless test_runner calibration loops for balance sims after builder CI smoke passes.
• godot-debugging-profiling — Consume getdebugoutput.py logs when headless imports/exports fail without a GUI.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting build/automation concern.