godot-builder

name

godot-builder

description

Expert-level toolkit for modular Godot 4.x CLI automation and headless build orchestration. Use this skill when you need to: (1) Build complex scene trees or UI layouts programmatically, (2) Automate expert 3D asset pipelines (glTF -> Collision), (3) Optimize procedural geometry headlessly (CSG -> Static Mesh), or (4) Engineer production-grade CI/CD pipelines with engine module stripping and delta patching.

Godot Builder Skill

The godot-builder skill provides an expert-grade foundation for programmatic game development and headless automation using the Godot 4.6.1-stable CLI.

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

Workflow #1: The Hardened 3D Asset Pipeline

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

• Sequence: gltf_processor.py -> collision_generator.py -> save_scene.py.
• Expert Defense: Sets explicit owner for every node. Forces a final headless import to fix the missing UID serialization.

Workflow #2: Procedural Level Optimization & 4.4+ Scaling

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

• 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.

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

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

• 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.

---

Automation & CI/CD Pipelines (Godot 4.6)

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.

---

Full Modular Skill Index (25 Scripts)

Project & Process Management

1. launch_editor.py: Opens the Godot visual editor for the project.
2. run_project.py: Launches the game project in debug or release mode.
3. get_debug_output.py: Captures and redirects engine logs to the terminal.
4. stop_project.py: Safely terminates a running Godot instance via its PID.
5. get_godot_version.py: Retrieves the specific engine version and build info.
6. list_projects.py: Recursively scans directories to identify Godot project roots.
7. get_project_info.py: Parses project.godot to retrieve metadata (display, features).
8. ci_exporter.py: Orchestrates multi-platform release exports headlessly.
9. ci_export_prepper.gd: Headless versioning script for export_presets.cfg.
10. profile_generator.py: Generates feature profiles for module-stripping optimization.

Scene & Dynamic Building

11. create_scene.py: Programmatically creates new .tscn resource files.
12. add_node.py: Instantiates and appends nodes to an existing scene tree.
13. load_sprite.py: Dynamically assigns and configures textures for Sprite2D nodes.
14. save_scene.py: Safely packs and persists the current node tree to disk.
15. gltf_processor.py: Headlessly converts raw .glb/.gltf assets into Godot Scenes.
16. csg_optimizer.py: Bakes procedural CSG boolean operations into static meshes.
17. tilemap_generator.py: Procedurally builds TileMapLayer grids from JSON data.
18. ui_assembler.py: Constructs complex GUI layouts from standardized JSON structures.
19. navmesh_baker.py: Executes asynchronous headless NavMesh pathfinding baking.
20. collision_generator.py: Generates ConcavePolygonShape3D physics from mesh data.
21. orphan_asset_scanner.gd: Recursive dependency tracer for identifying unused resources.

Automation & Utilities

22. get_uid.py: Retrieves the uid:// identifier for a specific resource path.
23. update_project_uids.py: Re-scans and synchronizes all project resource UIDs.
24. config_compiler.py: Compiles JSON/CSV data into optimized .cfg config files.
25. import_automator.py: Programmatically configures import settings for directory batches.
26. asset_reimport_utility.gd: Expert batch re-importer for enforcing project-wide settings.
27. test_runner.py: Executes headless unit and integration tests (GUT/doctest).
28. export_mesh_library.py: Converts 3D scenes into .meshlib resources for GridMaps.