Scenario Godot Pipeline Automation

Godot pipeline automation (tools and build engineer)

Target: Godot 4.7.2.stable, macOS Apple Silicon, gdUnit4 6.2.1.

Expert level here means every step a human would click is a command that CI can run twice with the same result, and every result is checked by a test that has been seen failing. The tools engineer owns the path from an art drop or a commit to a tested export: ingest, import, editor tooling, tests, CI, native extensions and agent channels. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-godot-expert (channels, gd_run and gd_env, the review loop, 4.7 traps). This skill adds scripts/gd_pipeline.py and the AgentKit module scripts/agentkit/pipeline/; it never starts Godot itself, every run goes through gd_run.

Status (2026-10-02): 43 live checks in 9 test files, the round-2 checks (procedures 15) and 8 offline tests, all pass, on a 200-GLB art drop that includes 12 real image-to-3D files (references/procedures.md). Not run: the workflow on GitHub runners, godot-cpp and Rust builds (no scons or cargo here).

Stance (the expert delta)

1. Write the import settings before the first import. A .glb.import sidecar holding only [remap] importer="scene" and [params] is honored by headless --import, and Godot adds the uid [added, verified M2]. Ingest therefore decides scale, pivot, collision and texture mode per file, then imports once. Rewriting .import files after the fact doubles the import time and dirties the repo.
2. Pass data to the importer, not code paths. An EditorScenePostImportPlugin declares per-file options (pipeline/fit_height, pipeline/unit_scale, pipeline/fix_pivot, pipeline/collision) that sit in each sidecar, appear in the Import dock, and run under headless --import once the plugin is listed in project.godot [added, verified M6, M10]. One plugin serves the whole project; files without pipeline/prop_id are untouched.
3. AI image-to-3D files are not DCC files. The 12 real files here call themselves "Khronos glTF Blender I/O", so a generator check cannot find them; only the manifest can. They arrived at arbitrary scale (a toy robot 1.96 m tall) with 2 to 35 materials; 8 of 12 use clearcoat, transmission, ior or specular, which 4.7.2 drops without a warning [added, verified M8]. Fit them to a manifest height; keep DCC props at authored size after a unit fix.
4. Parse bytes, not paths. Dinoleaf's rule for import code: parse(bytes: PackedByteArray) with the source injected, so the same parser serves res://, user://, zips and tests with literal bytes (sSurjCgebjw [00:04:46]). The GLB probe here works this way, and its tests build GLBs in memory.
5. A test counts only once you have seen it fail. Butch Wesley, author of GUT: watch red, then green; break the function body to retrofit (ImqhHLlPfZg [00:13:40]). Every suite here has a planted failure that must exit 100.
6. Judge an export by its artifact, not its exit code. Headless --export-pack crashed at shutdown with signal 11 after "[ DONE ] savezip" in 4 of 5 runs while gdUnit4 was in the pack, and the pack was complete [added, observation]. Check the file, its size and its contents; exclude dev folders from every preset.
7. Headless output is the truth for agents (Fennara, 2vSYP7GyA5U [00:02:51]). Output-panel scrapers report errors for lines no longer on disk, and the panel does not list every project error [00:06:20]: re-run headless before believing either. MCP servers add scene edits and screenshots, never error truth; call only their headless tools on a shared machine [added].
8. Test behavior through signals, with bounded waits. Godotneers and Mike Schulze (gdUnit4's author) assert on signals and public results, never private state; call monitor_signals() before the action, since a signal emitted earlier is missed (CreugthdgJ0 [00:36:34]); every wait has a timeout. Headless has no input device, so GUI-input tests are skipped in CI (Butch Wesley [00:48:33]; gdUnit4 6.2.1 prints the same warning).

Establish first

Workflow

1. Probe and decide (no import). prop_ingest.gd:ingest reads every file as bytes, probes it (glb_probe.gd: header, chunks, triangles, materials, images with their glTF role, extensions, world bounds), applies prop_rules.gd, copies accepted files to res://props/<category>/<id>/<id>.glb with a sidecar, and writes props_manifest.json. Writes happen only when content changes. Put an empty .gdignore in a raw drop inside the project, or the editor imports it too (verified, procedures 15). Collision naming uses Godot's node suffixes, stripped on import (verified, procedures 15): -col keeps the mesh and adds a StaticBody3D with a trimesh shape, -convcol a convex one, -colonly keeps only the body, -noimp drops the node. GATE: counts add up (accepted + warned + rejected + duplicates = files), every reject has a reason, zero engine errors.

2. Import. gd_run.import_project(P). GATE: no ERROR: lines except the exit noise 4.7.2 prints after the work is done (ERROR: N resources still in use at exit, WARNING: N ObjectDB instances were leaked at exit, WARNING: N RIDs of type ... were leaked; filter these three, procedures 15); every accepted prop has a .scn in .godot/imported.

3. Texture pass (extract mode). prop_textures.gd:fix sets VRAM compression, mipmaps, the normal-map flag by glTF role and the size limit by category in each extracted texture's .import, then import again. Headless never draws a frame, so detect_3d never flips and extracted textures stay lossless without this pass [added, verified M7]. GATE: every extracted texture lands as .s3tc.ctex (plus ETC2/ASTC when mobile is a target).

4. Audit and test. prop_audit.gd:audit loads every prop and checks meta version, root name, pivot, fitted height, height range, triangles against three times the budget, the Collision body, no AnimationPlayer, VRAM textures. The same check_prop() runs inside one gdUnit4 case over all props. GATE: 0 failures, JUnit parsed, the planted failure exits 100.

5. Look. prop_thumbs.gd:thumbs (windowed, 160x90 main window, SubViewport renders) frames each prop at three-quarter view next to a red 1 m post; gd_review.contact_sheet builds sheets of 100 at 1500 px. Open them. GATE: no black or missing prop, sizes plausible against the post, nothing floating or sunk.

6. Rerun and change one file. Run ingest and import again: 0 copies, 0 sidecars, nothing reimported. Change one source: only that prop and its textures reimport. GATE: both.

7. Export. Templates: the .tpz holds everything under templates/ (35 files) plus version.txt reading 4.7.2.stable, the folder name; move the contents into export_templates/4.7.2.stable/ under the data dir (~/.local/share/godot on Linux; Voylin AbMESM0UEHk [00:11:34]). C# projects run --build-solutions first (listed in the 4.7.2 --help, implies --editor). Then gd_run.ensure_preset, gp.exclude_from_export(P, preset) (test frameworks, tests, agent tooling, editor-only plugins), gd_run.export. GATE: artifact exists and non-empty, no dev files in the pack listing, verify_pack loads a prop.

8. CI. gp.write_workflow(root, "game", presets=(...)) writes .github/workflows/godot-ci.yml and tools/ci/godot_ci.sh. Run the script locally first, plant a failing test, lint with gp.lint_workflow, HEAD-check the URLs with gp.check_urls. GATE: local run exit 0, planted failure exit 11, actionlint clean, URLs 200.

9. Editor tooling. An EditorScript's _run() is a plain method: a gd_run.run_script(..., editor=True) job opens the scene (EditorInterface.open_scene_from_path), waits a few frames, calls _run(), saves with EditorInterface.save_scene(). Route changes through EditorInterface.get_editor_undo_redo() so Ctrl+Z works later (Queble, nW7YtSSJzbQ [00:04:41]); set owner on new nodes or they vanish on save (docs). Call an @export_tool_button Callable and _get_configuration_warnings() directly. GATE: undo and redo restore the child count, the saved .tscn contains the new nodes, warnings match good and bad inputs.

GridMap. A GridMap level wants a MeshLibrary: create_item(id), set_item_mesh(id, mi.mesh) per imported mesh, saved as .res (verified, procedures 15).

10. Custom formats. An EditorImportPlugin registered by an enabled plugin runs under headless --import; a parse error returns ERR_PARSE_ERROR, leaves valid=false in the sidecar and logs the bad line. GATE: good files load as their resource type, bad files fail with a readable message, a format-version bump reimports through reimport_files().

11. Native code. Only for a profiled hotspot or a native library (Snopek, 4R0uoBJ5XSk [00:03:16]). Smoke-test the chain: dump gdextension_interface.h, build, write the .gdextension, --import, then ClassDB.class_exists and one bound call. Production uses godot-cpp with a renamed entry_symbol (Snopek [00:13:22]); not yet run (no scons here). GATE: class registered, method answers, no load errors.

12. Agent channels. For live scene inspection, clone and build one MCP server in the project's tooling folder, pass GODOT_PATH in its environment only, and call it through gp.mcp_stdio(..., hold_project=P) (shares the GD_MAX lock). Never call tools that launch the editor or game on a shared machine. GATE: tools listed, one headless edit verified by loading the result through gd_run.