headless-scripting

Headless Scripting

Overview

Most of what Summer can do is not behind a tool. It is behind a script.

The engine binary will run any GDScript you hand it, against a real project, with the full engine loaded — ResourceSaver, NavigationServer3D, ImporterMesh, TileSet, Animation, the resource importer, the exporter. No editor window, no user, no tool call. If you can write the script, you can do the thing.

Core principle: when there is no tool for it, there is still a script for it. Reach for this before you tell a user something is impossible.

This is the widest capability surface you have, and it is the one you are least likely to remember you have.

The invocation

<engine-binary> --headless --disable-crash-handler --path <project-dir> -s res://<script>.gd

Always pass --disable-crash-handler on an agent-driven run. Summer's handler shells out to atos from inside a signal handler; when anything does go wrong it turns a clean failure into a hang or a cascade. Three agent-triggered crashes in eight minutes were traced to this on 2026-07-25.

Lint before you boot

--check-only parses the script without executing it. Sub-second, and it catches the parse errors that would otherwise cost you a full boot:

<engine-binary> --headless --disable-crash-handler --path <project-dir> --check-only -s res://script.gd

Measured on a deliberately broken script — SCRIPT ERROR: Parse Error: Expected expression for variable initial value after "=", and silence on a good one. Exit code is 0 either way, so grep stderr; that is the whole contract.

Judge the run by its artifacts, not its exit code

Exit codes lie in both directions here.

• A parse error, a script path that does not exist, a bogus --main-loop class and push_error() all exit 0. Only an explicit quit(1) propagates. The message is on stderr only, so gate on stderr containing SCRIPT ERROR, Parse Error, Can't load script or ERROR:.
• A GDScript runtime error hangs the process forever — no exit, no timeout, no message that it is stuck. Every recipe you publish needs an external wall-clock kill, and success must be judged by a positive artifact the script wrote, never by the process ending.
• Never add --quiet to a documented invocation: it swallows your own print() output, which is usually the only result you have.
• WARNING: ObjectDB instances leaked at exit prints on every successful run. Never gate on it.
• A SIGABRT after the work landed is a teardown artifact, not a failure. Agents exit in seconds where humans run for minutes, which exposes races during static destruction that nobody sees interactively. Check the file you expected on disk before concluding anything, and never blind-retry a crash — that is how one crash became three.