aigengame/godot-agent/gda

gda

gda is an agent-facing CLI for Godot. Use headless operations to create and inspect scenes, nodes, scripts, resources, shaders, themes, and project settings; validate or run scripts and scenes; and export artifacts. Use live operations to inspect a running game, inject input, capture the viewport, and read diagnostics or performance data. Live operations use gda-daemon. Both kinds support Godot 4.6+ on macOS, Linux and Windows; check a command's --schema constraints for its supported platforms.

Configure and discover

• Set GDA_GODOT to the Godot executable, or pass --godot PATH after the

command. If a command reports binary_not_found, find the Godot executable or ask the user for its path, then use it as above. On Windows, use Godot's *_console.exe.

• Pass --project DIR, set GDA_PROJECT, or run inside the project directory.

The project must contain project.godot. Use an explicit project when a script or asset depends on res:// or project autoloads.

• Keep the same engine and project for the related calls of one workflow.
• Use gda --version --json to identify the installed CLI and its source in a

long session. Use gda info --json to check the Godot engine.

• Use gda --help for command groups, gda <group> --help for a group's

commands, and gda <group> <command> --help for usage. Use gda <group> <command> --schema for that command's arguments, JSON result, and errors. gda schema describes the full installed surface. Consult these sources for exact options and fields instead of assuming this skill is a command catalog.

The CLI reads stdin and writes stdout and stderr as UTF-8 on every platform, including Windows. Encode JSON stdin and decode captured CLI output as UTF-8.

Pass --json on operations, for example gda scene validate res://main.tscn --project game --json. Read the one JSON object on stdout; engine output goes to stderr. On failure, branch on the structured error.code and inspect any evidence; do not parse error.message. An exit code of zero does not always mean the requested check passed:

For precision-sensitive values, inspect the result or read-back. Godot can change a decimal value while parsing it; gda refuses values that the parser would destroy. Consult the relevant command schema for accepted value forms and limits.

Headless workflow

With no project yet, run gda project create DIR --name NAME --json first. DIR must be a new directory in an existing parent, or an empty directory; dot-prefixed entries such as .git do not count. The new project.godot sets only the name, so set the main scene and other settings with project set. Then use DIR as the project.

Run gda project scan --json on a fresh checkout or a project the editor never opened, and after you add, rename or delete a class_name script: the engine finds a project class_name only through the index a scan writes, and gda does not check whether that index is current.

1. Create or edit a scene with scene, node, script, and resource

commands. Use script attach to bind a script to a node; generic node set --property script is refused. Create assets used by preload("res://...") before you attach the script. Supply a res:// Resource path when assigning a Resource-typed property.

1. Run scene validate and script validate for the changed files. Check

their valid verdicts. scene validate checks dependencies and scripts, but does not prove that the target scene starts.

1. Run scene preflight to boot the target scene for a bounded interval.

Check its startup verdict and diagnostics. Use script run for a project test script; inspect the child status even when gda succeeds.

1. Use export list to select a preset. Optionally inspect it with

export get, then run export run. If needed, use export smoke on the built artifact. A smoke run proves only what that bounded process observed; it does not prove that the game completed its intended task.

When scene create uses a Control-derived root from --root-type, it writes zero anchors and zero offsets. A root with no intrinsic minimum size renders as a zero-size rect; a root with an intrinsic minimum size renders at that minimum instead, not at viewport size. Set anchor_right and anchor_bottom to 1 with node set, then confirm the layout with game rect in an Engine session. For a Control inside a Container, change minimum size, size flags, or the container layout instead of offsets. A root from --inherits keeps the base's anchors and offsets.

For a variant of a base scene, use scene create PATH --inherits BASE, not node add --instance: the new scene's root is the base's root. In the variant, override inherited nodes with node set and add its own nodes; edit or remove inherited nodes in the base. scene get and node list show the variant's composed tree and mark inherited nodes with inherited_from; an inherited instance whose scene is missing carries no mark.

export run checks the export templates itself before it exports, and refuses with export_templates_missing when they are not available. --mode pack needs no templates. export get is optional inspection. Give it the same engine, project, preset, and data root (--user-data-root) as export run:

• templates_installed: false means that the templates_version directory

is missing under templates_root. Then a non-null templates_root_host means that the host has these templates but the data root hides them; a null value means that they are not installed.

• templates_installed: true means only that the version directory exists.

It does not prove that the preset's platform can export.

To recover, put matching templates, including the files for the preset's platform, under templates_root. With a data root, you can instead select another data root, or run without one where the environment permits. Template readiness does not prove that an export succeeds or that the Export artifact runs.

Data root in restricted environments

A headless run sends the engine log to a private temporary file. Godot can still write to its data directory during engine initialization, including for a validation. If that directory is not writable, select a writable data root. The global option comes before the command group:

gda --user-data-root /writable/gda-data scene validate res://main.tscn --project game --json

The data root moves the engine data directory (user:// and the export templates) and the engine log. The editor configuration and cache locations depend on the platform and can stay in place; on Linux they do not move. project scan, and resource import when it starts an engine, move the platform's configuration and cache locations under the data root too; without a data root, they use a private directory. Judge the impact from the operation verdict and the engine diagnostics. A directory warning does not by itself make a successful operation invalid. script run reports engine_data_path and log_file; inspect them before you treat a failed user:// save as a game defect.

• Use one data root for the engine-launching headless operations of one

restricted workflow.

• Use a separate data root for each invocation that runs at the same time.

Each launch truncates the one engine log under a data root.

• Do not set the data root (GDA_USER_DATA_ROOT) for unrelated commands.
• Do not give export smoke a data root unless it refuses with

user_data_unwritable. Without one, each smoke run creates a private data root, so no user:// state carries from one smoke run to the next.

• --user-data-root does not reconfigure an Engine session that the daemon

manages.

• A successful validation under a data root does not prove that the export

templates are available there.

Advanced Godot usages

Scene inheritance. One base scene holds the tree and its scripts. A variant made with scene create PATH --inherits BASE keeps that tree and stores only what it changes: overrides on the base's nodes, and nodes of its own. Keep the logic in the base and specialize the visuals and values in each variant. The commands and the rules are in the variant paragraph above.

Resource-based components. A class_name script that extends Resource holds a behavior's data and logic, decoupled from the scene tree: the behavior lives in a file that any node can hold and call, not in a node at a path, so the agent defines and tunes it without a scene edit, and swaps it without changing the node tree. project scan registers the class, resource create writes the .tres, and node set --value res://….tres links it to a node export typed with that class.

A shared component is the default: the .tres stays linked in every scene file, and an edit of the .tres reaches all of them. For a per-instance copy, choose one of two options:

• Local to scene (`resource set --property resource_local_to_scene

--value true): the engine gives each scene instance its own copy when it instantiates the scene, before any _ready; the nodes of one instance share that copy, and a nested resource that is local to scene is copied too. On that copy get_local_scene() returns the scene root and the engine calls _setup_local_to_scene; a duplicate() copy gets neither. The risk: when the node that holds the component is one an inherited scene takes from its base, or the root of an instanced child, a re-save of that scene by any gda write or by the editor stores the copy in its file as an embedded sub_resource. The link to the .tres is lost in that file, a later edit of the .tres` does not reach it, and nothing reports it.

• `duplicate()` in the owner's script, for example in _ready: the

.tres stays linked in every scene file, and the script makes the copy at runtime. The script then owns what the engine owned: a child's _ready runs before its parent's and sees the shared .tres; two nodes of one instance that duplicate separately do not share. duplicate(true) copies an embedded sub-resource but keeps a nested .tres shared, and duplicate_deep(Resource.DEEP_DUPLICATE_ALL) copies the nested .tres too.

Rule of thumb: use duplicate() for a component on a node that the re-save above can reach, and local to scene for a resource the engine must set up per scene. The copy semantics above are the engine's, not a gda guarantee.

Live workflow

A live run needs a main scene. Set application/run/main_scene or pass a valid --scene res://... to daemon start. An explicit res:// scene also bypasses an unresolved uid:// main scene.