gda — Godot Automation for AI Agents
Read this in: · ·
接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令? 两种安装方式的区别
Build and verify Godot projects with AI coding agents, shell scripts, and CI.
gda provides Godot automation with headless validation as well as live runtime
inspection and control through a CLI, a bundled Agent Skill, or an MCP server,
returning structured results agents can act on.
Two complementary modes cover this build-and-verify workflow:
Just tell your AI agent:
Install the gda CLI with
uv tool install gda(orpipx install gda), and install its Agent Skill withnpx skills add aigengame/godot-agent --skill gda -g. Then read the skill, follow it to set up gda for my Godot project, and check the setup withgda info --json.
gda?--json, each command emits
exactly one result object on stdout. Typed input and output models also power
--schema and the generated MCP tool surface.gda uses a single
Godot-aligned operation model and vocabulary, giving agents consistent terms for
project content and runtime state.These capabilities were refined while building a real game, with the work documented in a public dogfooding record.
Requirements: Python 3.13+ and a Godot binary — 4.4+ for Headless operations, 4.6+ for Live operations (see the platform support table).
Install gda, the Godot CLI for AI agents, from PyPI onto your PATH:
uv tool install gda # or: pipx install gda
gda --help
Into an existing environment:
pip install gda
From source (for development or unreleased changes):
git clone https://github.com/aigengame/godot-agent.git
cd godot-agent
uv sync # create the environment + install dependencies
uv run gda --help
Point gda at your Godot binary, then ask the engine its version — no project needed:
export GDA_GODOT="/path/to/Godot" # or pass --godot to any command; Windows: use *_console.exe
gda info --json
# {"major":4,"minor":6,"patch":3,"status":"stable","string":"4.6.3-stable (official)",…}
With --json, stdout is clean JSON you can pipe; all engine and script diagnostics go to stderr:
gda info --json | jq .major # → 4
No project yet? gda still runs projectless on plain filesystem paths (relative to your
current directory); only res:// resolution needs a project. See Configuration.
To create one, use a destination that is new or empty (entries such as .git do not count).
gda writes one file, a project.godot that sets only the name:
gda project create ./my-game --name "My Game" --json
# {"path":"/home/me/my-game","name":"My Game","created_dirs":["/home/me/my-game"],"project_file":"/home/me/my-game/project.godot"}
Build a scene headlessly. Point gda at a Godot project (a directory with project.godot)
once; relative paths then resolve inside it, and nodes are addressed by their path relative to
the scene root:
export GDA_PROJECT="/path/to/your/godot-project" # or pass --project to any command
gda scene create scenes/main.tscn --root-type Node2D --json
gda node add scenes/main.tscn --type Sprite2D --name Hero --json
gda node set scenes/main.tscn --node Hero --property position --value 10,20 --json
gda scene validate scenes/main.tscn --json
gda scene get scenes/main.tscn --json
# {"path":"scenes/main.tscn","root":{"name":"main","type":"Node2D","children":[{"name":"Hero",…}]}}
Inspect and drive the running game with Live operations. These operations run the
project's main scene, so point it at the one you just built via Godot's
application/run/main_scene project setting (the editor's Application → Run → Main Scene),
then start the daemon (Godot 4.6+):
gda project set application/run/main_scene --value res://scenes/main.tscn --json # a Godot project setting key
gda daemon start # start the daemon for $GDA_PROJECT (installs the in-game harness)
gda game tree --json # the runtime scene tree, after _ready
gda perf monitors --json # live engine counters: fps, memory, node count
gda daemon stop
(gda screen capture works live too, but needs a windowed session — start the daemon
with gda daemon start --windowed.)
gda provides one operation surface through three complementary access paths. Use the CLI,
the Agent Skill, the MCP server, or a combination that fits your workflow. The underlying
operations and structured results stay the same.
Not sure which path fits your workflow? See Godot MCP vs CLI vs Agent Skill.
gda ships an Agent Skill that teaches an AI agent when and how to drive Godot from the
CLI. Use it when your coding agent supports Agent Skills and you want reusable guidance without
registering a server. Install it with the Skills CLI,
which asks which agents to install it for (name them with -a):
npx skills add aigengame/godot-agent --skill gda # this project
npx skills add aigengame/godot-agent --skill gda -g # all your projects
This copy tracks the repository's main branch. For guidance that matches your installed gda
version, use gda skill instead. It prints the same file from the package, or installs it:
gda skill # print SKILL.md (redirect it anywhere)
gda skill --install --provider claude --scope user # resolve a known agent's skills dir
gda skill --install --dir ~/.claude/skills/gda # …or give the directory yourself
Either way you still install gda, since the Agent Skill drives it. The
Agent Skill recipes list each agent's skills directory.
gda-mcp is the bundled Godot MCP server for compatible clients. It implements the
Model Context Protocol over stdio and is available through
the [mcp] extra. Run it through uvx without a permanent install:
uvx --from "gda[mcp]" gda-mcp
The server resolves two pieces of context — which Godot project to drive and which Godot binary to run (MCP can't pass per-call flags):
GDA_PROJECT. Without it, gda-mcp uses the workspace roots the client
sends (the folder you have open) — but the MCP 2026-07-28 revision deprecates roots, so pinning
GDA_PROJECT is the setup that keeps working. See Configuration.GDA_GODOT to your Godot binary, e.g. "GDA_GODOT": "/path/to/Godot".gda-mcp accepts both protocol eras — the pre-2026 MCP protocol and the 2026-07-28 revision —
but not with the same project resolution: a pre-2026 client still sends roots, a client on the new
revision does not, so it resolves from GDA_PROJECT or the server's cwd. Pin GDA_PROJECT before
your client moves. On the new revision gda-mcp also marks tools/list cacheable (1-hour TTL).
Project scope, .mcp.json at the repo root (auto-detects the project via roots):
{
"mcpServers": {
"gda-mcp": {
"command": "uvx",
"args": ["--from", "gda[mcp]", "gda-mcp"]
}
}
}
User scope (every project) — the CLI, which writes ~/.claude.json:
claude mcp add --scope user gda-mcp -- uvx --from "gda[mcp]" gda-mcp
Project scope, .codex/config.toml at the repo root (the project must be trusted):
[mcp_servers.gda-mcp]
command = "uvx"
args = ["--from", "gda[mcp]", "gda-mcp"]
[mcp_servers.gda-mcp.env]
GDA_PROJECT = "/absolute/path/to/your/godot/project"
User scope (available everywhere, but pinned to one project) — the same table in
~/.codex/config.toml, or add it with the CLI. Codex has no workspace variable, so
GDA_PROJECT is an absolute path; use project scope if you work across several projects:
codex mcp add gda-mcp --env GDA_PROJECT=/absolute/path/to/your/godot/project -- \
uvx --from "gda[mcp]" gda-mcp
Project scope, .cursor/mcp.json at the repo root (${workspaceFolder}
tracks the open project):
{
"mcpServers": {
"gda-mcp": {
"type": "stdio",
"command": "/path/to/uvx",
"args": ["--from", "gda[mcp]", "gda-mcp"],
"env": {
"GDA_PROJECT": "${workspaceFolder}"
}
}
}
}
User scope (available everywhere, but pinned to one project) — the same config in
~/.cursor/mcp.json with GDA_PROJECT set to an absolute path (${workspaceFolder} only
works in project scope; use project scope for several projects). Cursor has no mcp add
command — register via the JSON above or the Settings → MCP UI.
Cursor is GUI-launched with a minimal
PATH, so a bareuvxmay not resolve — hence the absolutecommandabove; fill it with the output ofwhich uvx. Full recipes — PATH injection, Claude Desktop, user vs project scope, per-agent project pinning — are in the registration recipes.
gda is one Godot automation toolchain with three components and two complementary
operation modes:
gda-daemon launches it, injects an inert
in-game harness, and brokers requests over local IPC (runtime tree, input,
frame capture, performance, diagnostics).Headless validation confirms project readiness; Live operations return runtime evidence about actual behavior.
The in-game harness gda-daemon injects is dev-only: gda export run strips it from the
artifact entirely, and built any other way (editor GUI, raw godot --export) it still
self-disables in the exported game — so a shipped game never runs anything daemon-related
(and via gda export run, doesn't even carry it).
Platform & version support:
¹ Headless is cross-platform by design (one-shot processes, no platform-specific
dependency) — Windows keeps the full headless surface, and the nightly CI exercises
it on a Windows runner too.
² A windowed session, which screen capture and screen frames need, requires a
display: an on-console GUI session on macOS, $DISPLAY or $WAYLAND_DISPLAY
on Linux (Xvfb on a headless host), or an accessible interactive desktop on
Windows. Each command's --schema constraints state its supported platforms.
gda commands are grouped by Godot domain object and use a small, consistent verb
vocabulary, so the same verb means the same thing in every group:
Every command supports --json and --schema. Commands that read or mutate a res:// path
resolve a project context. Run gda <group> <command> --help for full
flags — gda --help is the authoritative list of what is installed.
New here? A good first path: gda info → gda scene create → gda node add →
gda script validate → gda export run; then go live with gda daemon start → gda game tree.
Meta — about gda / the engine itself
scene — scene files (.tscn)
Run both — scene get reads a scene with its script missing as healthy, only validate
names the file, and only preflight catches a first-frame failure.
node — nodes within a scene file
script — GDScript files (.gd)
project — the project as a whole (settings, autoloads, static analysis)
resource — resource files (.tres) and the project's imported assets
export — export presets and artifacts
export smoke takes a macOS .app or a directly host-runnable file. End-to-end evidence covers macOS and Windows Desktop; Linux is not measured and not promised.
shader — shader files (.gdshader)
theme — theme resources (.tres)
gda-daemon; Godot 4.6+daemon — the live runtime lifecycle
game — the running game's runtime scene graph
game call reads what game get cannot: state your project exposes as a method.
game set --property position follows the same Control rule as node set.
game get refuses a Control's position, size, global_position and global_rect;
game rect is the read for them.
diag — runtime diagnostics
logger — structured runtime log
perf — performance monitoring
input — input simulation
Read injected mouse coordinates from event.position — in a daemon session
get_mouse_position() / get_global_mouse_position() can stay stale.
In a windowed session, a loss of OS focus after input action releases the held
state: the engine releases every pressed input, an injected action state included,
when another application or a second windowed session takes the focus, and
regaining the focus does not restore it. Press again after such a loss.
screen — viewport capture
A capture's receipt carries two frame counters: engine_frame is the boundary the read
was taken at, render_frame the drawn frame the pixels are.
Each screen frames item includes a receipt; --summary keeps only the first and last receipts.
gda finds the Godot binary from the --godot <path> flag, otherwise the
GDA_GODOT environment variable — set one of these so gda can locate your engine.
Domain commands resolve a Godot project so that res:// paths resolve. A named
directory must be a project, or gda reports an error; when nothing resolves, gda runs
projectless — plain filesystem paths work, res:// does not.
Pointing gda at a project runs some of that project's own code — by design, since the
project is trusted (ADR-0009):
--project operation that boots the game-facing engine,
read-only ones included (a cached resource import boots nothing)._init runs wherever a scene is instantiated: every mutating node
command and node get; scene get / scene list / node list read without instantiating.script run executes the named script in full; scene preflight boots the scene
and runs its _ready.resource import on a cache miss and the native export of export run boot the
editor instead: the engine's importers and the project's import plugins run, with every
@tool autoload and the enabled editor plugins; plain autoloads do not. export run also
runs the export plugins those editor plugins register, after it reads the preset in an
ordinary operation that starts the autoloads.game call runs the one method the node's GDA_CALLABLE declaration names; nothing
undeclared is ever called.Headless Godot interleaves its banner, warnings, and print() output into stdout. gda
solves this with a sentinel contract
(ADR-0002):
The GDScript payload emits exactly one result, wrapped in unique sentinels on stdout:
<<<GDA:RESULT>>>{ …json… }<<<GDA:END>>>
It routes all of its own diagnostics to stderr; stdout carries nothing but the contract.
gda extracts and parses only the bytes between the sentinels, ignoring the surrounding
engine noise, and surfaces stderr for inspection.
This is what makes gda's output safe to consume programmatically, and it generalizes to
the per-message protocol the daemon uses for live operations.
Exit codes (the CLI ABI). A failed gda run exits with a small, stable code so a shell
or agent can branch on the failure category without parsing the JSON error:
These values are the public ABI; their authoritative source is
src/gda/exit_codes.py. The {"error": {category, code, …}}
envelope carries a finer code within each category (e.g. path_not_found,
already_exists, node_not_found all sit under operation / exit 4). The full
registry lives in
ADR-0002's GdaError.code table.
uv sync # set up the environment
uv run pytest # run the full suite (includes e2e tests against a real Godot)
uv run pytest -m "not e2e" # unit tests only (no Godot binary required)
uv run pytest -m e2e # only the end-to-end tests (needs Godot 4.4+ on this machine)
uv run pytest -n 0 # any tier above serially (the default also goes serial under --pdb)
uv run pytest -n 2 # any tier above on two workers, e.g. beside another e2e run
uv run pytest -m e2e --splits 3 --group 2 --splitting-algorithm least_duration # one third of the e2e tier, as one CI shard runs it
uv run ruff check . # lint
uv run ruff format . # auto-format (append --check to verify without writing)
uv run pyright # type-check (src/ + tests/, basic mode)
The e2e tier runs by default with uv run pytest, and fails loudly — saying how to
fix it — when GDA_GODOT does not name a Godot binary, rather than skipping.
Deselect the whole tier with -m "not e2e" (CI's per-PR job uses exactly this).
Every tier runs on 4 xdist workers by default, capped at the CPU count, with
--dist loadgroup keeping the tests that open a window on one worker. That policy is
pyproject.toml's addopts and the default is in tests/conftest.py; CI runs the same
entry with no flags. PYTEST_XDIST_AUTO_NUM_WORKERS=<n> changes the default for one run
(CI maps the repository variable PYTEST_WORKERS to it), and an explicit -n wins over
both. Adjust the count to your machine's core count: too many workers contend for CPU
time. CI's e2e job shards the tier across runners with the same --splits/--group
flags; the e2e-shards dispatch input or the repository variable E2E_SHARDS sets
the count (default 4; 1 runs the tier as one job). The e2e-select dispatch input, a
pytest -k expression, narrows the main e2e step to the tests it selects, as one job per
operating system; the Linux rendered step on Xvfb still runs its whole set.
Linting and formatting are enforced by ruff — one tool in
place of flake8 + black + isort, configured under [tool.ruff] in pyproject.toml and
pinned via uv.lock so local and CI agree. CI's lint job runs ruff check . and
ruff format --check . on every PR; run uv run ruff format . before committing to stay
green.
Types are checked by pyright in basic mode, covering
src/ and tests/ and configured under [tool.pyright] in pyproject.toml (also pinned via
uv.lock). CI's type-check job runs uv run --frozen pyright on every PR.
src/gda/
cli.py # composition root (Typer): mounts every command group
exit_codes.py # the exit-status table (public ABI)
commands/ # one module per command group: its models, renderers, commands
surface/ # the command surface: the per-command descriptor (one
# HeadlessCommand per command), the shared options, the CLI dispatch
# tails + the runner seams the groups call, the `gda schema` manifest
core/ # the library the daemon, the surface and the groups build on
project/ # the project on disk: project.godot, file tree, import cache, paths
engine/ # one Godot process: binary resolution (flag > $GDA_GODOT),
# the one-shot headless spawn seam, user data, the sentinel wire
contract/ # the shared typed I/O core (Pydantic) backing --json and --schema,
# and the shared human-readable (non-JSON) render helpers
failure/ # failure classification + the error-code registry
steps/ # the shared steps: the engine import pass and the completed run
ops/operations.gd # the headless GDScript payload, dispatched by operation name
daemon/ # gda-daemon: server, session supervision, IPC protocol, discovery,
# and the live-operation client that talks to it
harness/ # the inert in-game `gda` autoload injected into a live session
mcp/ # gda-mcp: the schema → MCP-tool server
tests/ # unit + e2e tests against a real engine (shared fixtures in conftest.py)
docs/adr/ # architecture decision records
CONTEXT.md # the project's shared domain language
gda has two external boundaries, each behind a seam fast tests inject through: spawning a
one-shot headless process (core/engine/launch.py) and talking to a running game via the
daemon (daemon/client.py). The e2e suite drives a real engine across both.
Contributions are welcome. Read CONTEXT.md to align with the project's
shared language, and review the relevant ADRs for the area you're touching.
Issues and PRDs live as GitHub issues.
Commits follow the Conventional Commits specification.
Python code is linted and formatted with ruff and type-checked
with pyright, both enforced in CI — run
uv run ruff format . and uv run pyright before committing (see Development above).
Working with an AI coding agent? This project is built to be agent-navigable —
AGENTS.mdis the entry point for coding agents, wiring in the project's rules, domain docs, and skills.
Released under the MIT License. Copyright (c) 2026 aigengame.
Godot automation for AI agents to build and verify projects through a CLI, Agent Skill, or MCP server, with structured results, headless operations, and live runtime control.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Godot Agent 通过 stdio 在本地运行。
上次检查时间:2026-10-28。 Godot automation for AI agents to build and verify projects through a CLI, Agent Skill, or MCP server, with structured results, headless operations, and live runtime control.