godot-autopilot-tools
Skill1 starsChanged 17 days agoMITView on GitHub
Calling the GDA (godot-autopilot) plugin: the invocation ladder (native MCP tools, the gda CLI, the plain-HTTP REST face, manual fallback), what to do when the plugin is installed but no MCP client is configured, search-first tool discovery, meta-tool semantics including batch_execute/code_execute and the three-tier capability gates, the error protocol and error watermark, limits, the full domain tool catalog, dynamic user tools, and the manual fallback guide for machines without a usable CLI. Load this skill whenever MCP tools are missing or you need calling-protocol facts.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- cpp-registrationSkill
- domain-tool-authoringSkill
- gda-demo-e2eSkill
- gda-e2e-analysisSkill
- skill-proposerSkill
- thread-security-gateSkill
- wiki-maintainerSkill
- godot-autopilot-contentSkill
- godot-autopilot-csharpSkill
- godot-autopilot-resourcesSkill
- godot-autopilot-runtimeSkill
- godot-autopilot-scene-systemSkill
- godot-autopilot-scriptingSkill
- godot-autopilot-serversSkill
- godot-autopilotSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 53
Search by the object first, then by the operation: "tilemap cell" finds the cell tools, "animation track" finds the track tools.
- Very specific: line 57
Read get_tool_detail for the candidate schema and side-effect marker before the first write.
- Very specific: line 58
When a query still comes back empty, browse the tool catalog reference in the godot-autopilot volume (every domain tool grouped by source …
- Very specific: line 75
Every tool failure is returned as a JSON object with an error key.
- Very specific: line 81
After every write call (property_set, create_scene_node, write_file, save_resource, scene, script or config edit), read the watermark …
- Distinctive: line 89
Wait at least the suggested interval, then retry the same call.
- Distinctive: line 109
Use the watermark as the closing step of every fix instead of assuming a fix worked:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Godot Autopilot Tools
This volume is the cross-domain calling knowledge for the godot-autopilot plugin: the channel ladder, the discovery protocol, meta-tool semantics, the error protocol and the limits. The MCP server is the product; skills and scripts are the experience layer on top of it. Whichever channel you use, the same rules hold: discover every tool name with search_tools and never guess one; call every domain tool through call_tool; read the new_errors_since_last_call watermark after every call.
This volume carries no domain knowledge. Scene and property work, resources and files, GDScript, runtime and debugging, server RID tools, content pipelines and C# each have their own volume (see See also). Come here to learn how to reach any of them; go there to learn what to do once you arrive.
Channel ladder
Four channels, in preference order. Drop to the next only when the current one is unavailable.
When to enter the ladder. Either of these:
- The plugin is installed but no MCP client is configured. The Godot project contains
addons/godot-autopilotand the server may already be listening on loopback, yet your harness lists no GDA tools. Nothing is broken — you simply have no native channel, so start at rung 2. - The client lost its tools. The list went empty or calls fail right after an editor restart, and reconnecting did not help.
Probe before choosing a rung: bun --version, then node --version. Take the first rung whose precondition holds, and never jump to the manual guide while a shell still works.
- Native MCP tools. Whenever the client harness lists the MCP tools, use them directly:
ping,search_tools,list_categories,get_tool_detail,call_tool,batch_execute,code_execute. This is the primary channel with full schemas, structured errors and image content. - GDA CLI. When the MCP channel is down, drive the server from a shell with the
gdacommand. It is the only scripted channel: it speaks the same MCP protocol, accepts the same subcommands and shares the same exit codes as the native channel. Pick the first distribution that works on the machine:- bunx (Bun present, nothing installed): run
bunx --no-install "github:jesspig/Godot-Autopilot#0.3.0" <cmd>first (instant when the bunx cache is warm; a fast failure otherwise); if not cached,bunx "github:jesspig/Godot-Autopilot#0.3.0" <cmd>downloads once. Quotes are required on PowerShell because#starts a comment. - global install (Bun, used repeatedly):
bun install -gonce, then run plaingda <cmd>. - standalone binary (no JavaScript runtime at all): download the
gdarelease asset for the user's OS and CPU, verify it against the release'ssha256sums.txt, and run it exactly like the CLI. No runtime needed; one download per version. Asset names, checksum verification and per-platform caveats (macOS quarantine, musl, SmartScreen) are in references/cli-access.md. Calling commands: ping/status/categories/search/describe/call; lifecycle: list/start/stop/restart/logs; control plane: serve (loopback-only proxy that routes to one or several instances); REST family: api list/api describe/api call/endpoints. Run<prefix> --helpfor the full reference; stdout is compact JSON, diagnostics go to stderr. Note on the pinned ref: as of0.3.0the tree does ship the CLI (rootpackage.jsonexposes thegdabin,cli/is in the tree), so the pinnedbunxcommand resolves once that tag is published — until then it is not fetchable and usebunx "github:jesspig/Godot-Autopilot#develop" <cmd>instead (that branch does ship the CLI, but it is an unreleased moving target, not a pinned version), or the standalonegdarelease asset once a release ships it (asset names and checksum verification in references/cli-access.md), or drop to rung 3.
- bunx (Bun present, nothing installed): run
- REST face. The plugin serves a plain-HTTP API on the same port as the MCP endpoint, under the
/apiprefix. It needs no MCP handshake and no session, so a client that can only send ordinary HTTP can still reach every registered tool. It is not a scripted channel: it is the interface for an HTTP-only client. Its endpoints areGET /api(service and endpoint list),GET /api/tools(filtered, paged tool list),GET /api/tools/<tool>(one tool's schema),POST /api/tools/<tool>(call one tool — the request body is the argument object itself),POST /api/batch(ordered operations),GET /api/health(the only endpoint that needs no token) andGET /api/openapi.json. Every endpoint except the health probe requires anAuthorization: Bearer <token>header; the token is in the plugin's instance registry and thegda apisubcommands read it for you. Read references/rest-api.md for the endpoint contract, the token sources, the status-code table and two minimal snippets (Python and JavaScript). Prefer rung 2 whenever a shell exists — the CLI resolves the port and the token for you. - Manual guide. When there is neither a working MCP client nor any usable CLI nor an HTTP-capable client, hand the user step-by-step editor instructions per references/manual-fallback.md.
Never hand-write HTTP requests against the MCP endpoint in any channel: no raw requests, no ad-hoc scripts against /mcp. Every MCP call goes through the harness MCP tools or the gda CLI. The one sanctioned exception is the REST face in rung 3, which has its own reference and its own examples.
Discovery protocol — search first, never guess
Tool names are snake_case with the verb first, but segment counts vary, so guessing is unreliable. Always discover:
pingto confirm the server responds.search_toolswith aquery(optionally filtered bycategoryortags), orlist_categoriesto browse by domain.get_tool_detailwith the exactnameto read the input schema, description and side-effect marker before calling anything that writes files or config.call_toolwithnameandargumentsto execute. The seven meta tools are called directly at the MCP layer; every domain tool goes throughcall_tool.
Calling call_tool with an unknown name fails with a message telling you to use search_tools. Use it instead of improvising similar names.
{"name": "create_scene_node", "arguments": {"type": "Node2D", "name": "Player", "parent_path": "Root/Actors"}}Search techniques
search_tools ranks candidates over tool names, descriptions, categories and tags, so the words you send shape the order you get back:
- Search by the object first, then by the operation: "tilemap cell" finds the cell tools, "animation track" finds the track tools. Add a verb only when the object query is too broad.
- Describe, do not name. While you do not know the real tool name, describe the outcome ("connect a signal from a button") instead of guessing a plausible-looking name.
- Rerun with synonyms before concluding a tool is missing: tile/cell, sprite/texture, log/output, delete/remove/erase, create/add/new.
- Narrow with filters: pass
categoryfor a single domain ortagsfor required tags, and browselist_categorieswhen you only know the domain. - Read
get_tool_detailfor the candidate schema and side-effect marker before the first write. - When a query still comes back empty, browse the tool catalog reference in the godot-autopilot volume (every domain tool grouped by source module) before inventing anything. The exact tool set is whatever
search_toolsreturns — never assert a count from memory.
Meta-tool semantics
call_toolexecutes one tool: pass the domain tool name asnameand its inputs asarguments. Meta tools themselves (ping,search_tools,list_categories,get_tool_detail,batch_execute,code_execute) are called directly, not throughcall_tool. Server status is a domain tool: reachsystem_statusthroughcall_tool.batch_executeorchestrates existing tools: an orderedoperationslist (at most 256 items) run in sequence, withstop_on_error(default true) and optionalrollback_on_error. Each operation takes onlytool(required) andargs(optional object, defaults to{}); thecall_tool-stylename/argumentskeys are not accepted there. Result counts:total= executed operations (succeeded+failed+pending),skipped= operations never run after an early stop, andtotal+skippedalways equals the length ofoperations; failed items carry their message undererror. Choose it for deterministic sequences such as "set these five properties, then save". Async game tools inside a plain batch are refused with status error (the pending record is released, sopendingcounts 0) — call those tools one at a time viacall_toolwhen you need their response, or passawait_async: trueand invokebatch_executedirectly.code_executeruns GDScript in the editor: the source is wrapped in a script extending Node, and the edited scene root is exposed as SceneRoot. Without a line-startfuncdefinition the code is inlined inside a single entry-function body — write straight-line code ending in return. When any non-comment line starts withfunc(leading whitespace stripped, comment lines ignored) the whole source is preserved verbatim andfunction_name(default_run) selects the entry point. The detector needsfuncwith a trailing space.timeout_msdefaults to 5000 and is capped at the maximum the server reports in thecode_executeschema - that ceiling follows the host's long-blocking dispatch budget and can be lowered per deployment, so read it from the schema rather than assuming a fixed number;auto_ownerdefaults to true so created nodes are saved with the scene. The timeout is enforced while the script runs, not only before it — a long loop is interrupted when the deadline passes, and the call comes back as an exec_timeout failure instead of freezing the editor. Details in the gotchas reference.side_effectis the risk markerget_tool_detailreports, and it is never empty: a tool that only reads reportsnone. The classes arenone,writes_file,writes_config,shows_alert,modifies_window,process,code_execute,game_runtime,destructiveandwrites_scene. The two script-running meta tools,code_executeandbatch_execute, both reportcode_execute. The authorization gate is derived from that marker alone — the server keeps no per-tool-name exception list — so a tool can start requiring a capability because its class changed, not because its name is special.- Decision rule: expressible as a handful of existing tool calls — use
batch_execute. Needs loops, math or conditions (laying out hundreds of tiles, bulk renames, computed values) — usecode_execute. Very large payloads also favorcode_executeto avoid huge JSON arguments. - Authorization gates, checked on every call, in three tiers. The gate follows the tool's
side_effectclass. Read tools (classnone) are allowed by default. Write tools (writes_file,writes_config,shows_alert,modifies_window,writes_scene) are denied by default and need thewritecapability. Danger tools are denied by default and need their own capability:process,code_execute,game_runtime,destructive.user_toolsis a seventh capability, independent of the class, guarding user-registered dynamic tools. The full capability list isread,write,process,code_execute,game_runtime,destructiveanduser_tools.- Concretely:
code_executeandexecute_scriptneed thecode_executecapability, and so doesbatch_execute— a batch is gated as a whole, so a client that enabled onlyprocessorgame_runtimecan no longer run a batch of ordinary domain tools and gets an authorization_required error instead. The tools that reach the running game (execute_game_script,queue_game_input,wait_game_input,sequence_game_inputs,reload_game_scripts) need thegame_runtimecapability. User-registered dynamic tools (see References and extension points) need theuser_toolscapability. Scene-writing tools — node/property/signal/animation/tilemap/gridmap/theme write tools — reportwrites_sceneand need the samewritecapability. - A write-class tool now needs
write. Before this change a write-class tool needed no capability at all. If your calls start failing with an authorization error on a file or config write, that is the cause: addwriteto the allow list. Do not work around it by switching to a different tool. Destructive tools — the ones that irreversibly destroy an object that already exists inside the editor host, such asdelete_scene_node,delete_display_window,remove_animation,remove_animation_track,remove_audio_bus_effectandremove_debug_custom_monitor— need thedestructivecapability and are denied by default too. Deleting a file or a directory on disk stays in the write class, because project content is usually recoverable from version control. - Compatibility mode for pre-0.3.0 setups. The plugin also has an authorization mode switch.
strict(the default) denies write-class tools untilwriteis allowed.legacyallows the whole write class with no allow-list entry — the pre-0.3.0 behavior — while danger and destructive tools still need their own capability. SetGODOT_AUTOPILOT_AUTH_MODE=legacy(orstrict) in the environment, put"auth_mode": "legacy"in the plugin config, or pick "Compatibility" in the MCP Config dock's "Authorization mode" dropdown; the dock takes effect on the next tool call with no restart, and the environment variable wins over the config. An invalid value falls back tostrictand logs a warning. Every denial carries anauthorization_modefield, so a client can tell which mode produced it. Preferstrictplus an explicitwriteallow-list entry whenever the caller can set one up. - Enable a capability either by setting the
GODOT_AUTOPILOT_ALLOWenvironment variable to the capability name (orall) and restarting the engine, or by ticking the matching checkbox ("Allow code_execute", "Allow game_runtime", "Allow user tools", "Allow write", "Allow destructive") in the plugin MCP Config dock, which saves to the plugin config and takes effect on the next tool call with no restart. Un-ticking a box removes only that one capability and leaves the others alone, even when the allow list wasall.processhas no dock checkbox — it needs the environment variable and a restart. WhenGODOT_AUTOPILOT_ALLOWis set it wins over the config, so do not rely on the dock checkbox while the variable is present.
- Concretely:
Error protocol
Every tool failure is returned as a JSON object with an error key. For call_tool and code_execute, a top-level error also sets the MCP-level error flag on the response.
In addition, every meta-tool response carries a top-level integer watermark field counting new errors recorded since your previous call, including errors the call itself just produced. A failed call reports at least its own error. The semantics:
- It is one-shot: the value is consumed when you read it and the counter resets. Never skip reading it, even when the call succeeded.
- Errors printed by a running game are recorded too.
- After every write call (
property_set,create_scene_node,write_file,save_resource, scene, script or config edit), read the watermark before issuing the next call. A non-zero value means new errors were recorded — stop, pull the real log lines, fix or explain them, then continue.
Soft (retryable) errors: while the editor is importing or scanning resources, affected calls return a structured error with a retryable flag set to true and a suggested retry_after_ms wait:
{"error": "editor is currently importing/scanning resources; retry shortly", "retryable": true, "retry_after_ms": 500}Wait at least the suggested interval, then retry the same call.
Export lockout: while the editor is exporting the project, all tool calls are rejected with an "editor is exporting" error. Wait for the export to finish instead of retrying in a tight loop. That rejection carries a machine-readable code as well as the message, so branch on the code when you can.
Error codes
Some failures carry a machine-readable code field next to the error text. Branch on the code, not on the message: the messages are prose and get reworded, the codes are stable. The codes you can receive:
| Code | Raised when | Retry? |
| exec_timeout | a code_execute script outran its timeout_ms | no — the script was interrupted; split the work or raise timeout_ms |
| eval_timeout | a game-side eval script outlived the 25000 ms host wait, or the editor gave up waiting for the eval answer | not immediately — the game may still be running that script |
| eval_cancelled | the eval request was torn down by a cancel handle | no — re-issue it if the result is still needed |
| main_thread_timeout | the editor main thread did not process the tool inside its dispatch budget | no — the call was cancelled and the side effect may still land; read the editor state first |
| queue_unavailable | the editor main-thread queue was full or already closed | yes, later — the editor may be shutting down |
The two eval codes arrive nested under a structured_error object inside the tool payload; the other three come back as the top-level result of the call. The dispatch codes carry a retryable flag: it is false for main_thread_timeout and true for queue_unavailable, while exec_timeout also carries it false and the eval codes carry no flag at all — treat a missing flag as "do not retry immediately". A main-thread timeout means the call was abandoned: the editor may still run the work afterwards, so read the state back before repeating it. main_thread_timeout also reports how long it waited, and on the dispatch path the queue depth and the age of the oldest pending call; exec_timeout reports the measured execution time next to the timeout_ms it exceeded. A failure with no code is a plain tool error: read its error text.
Confirming a fix with the error watermark
Use the watermark as the closing step of every fix instead of assuming a fix worked:
- A call fails, or the watermark reports new errors.
- Diagnose and fix the cause.
- Re-run the failing call. A success with the watermark at 0 confirms the fix produced no new errors.
- A non-zero value means new errors were recorded since your previous call — errors printed by the running game count too. Read them with
get_debugger_errorsorget_debugger_log, fix again, then make any meta-tool call (evenping) until the watermark comes back 0.
Observing while working
Never chain write operations blind. After a write, confirm with a read-back (property_get, get_scene_tree, get_resource_property), a screenshot (capture_editor_viewport, capture_game_viewport) or output (get_debugger_log; with a running game get_debugger_errors and get_debugger_output, on-disk fallback get_game_log_entries). When the problem is inside the plugin itself (authorization denials, timeouts, dropped responses), read get_plugin_log. Prefer observed output over assuming a call did what its name suggests; ok only means the call went through.
Limits
- Default operation timeout is 5000 ms. The maximum accepted timeout is the value the tool schema reports as its maximum: for editor-only operations it follows the host's long-blocking dispatch budget and can be lowered per deployment, so read it from the schema instead of assuming a fixed number. Game operations cap
timeout_msat 25000 ms, keeping the host wait plus a grace interval below the transport limit. - Editor-side calls are handed to the editor main thread under a wait budget with three tiers: 27000 ms for ordinary tools, 5000 ms for the health probes (
pingandsystem_status), and 29000 ms for the long-blocking meta tools (code_executeandbatch_execute). The long-blocking tier used to wait forever; it is bounded now, so a long task can still end with a main_thread_timeout instead of hanging forever, but it will end. The three tiers can be overridden with theGODOT_AUTOPILOT_DISPATCH_TIMEOUT_MS,GODOT_AUTOPILOT_HEALTH_TIMEOUT_MSandGODOT_AUTOPILOT_LONG_BLOCKING_TIMEOUT_MSenvironment variables, each clamped to 1000-29000 ms. - JSON responses are capped at 4 MiB. Large results are truncated with detectable fields (such as a truncated flag) rather than silently dropped — check them before trusting completeness.
batch_executeaccepts at most 256 operations per call.- At most 8 concurrent in-flight requests. Exceeding the limit fails fast — reduce parallelism instead of retrying blindly.
- On the REST face the tool list is paged (500 per page by default, 2000 maximum), a batch accepts at most 256 operations, a tool name is at most 128 characters, and a request body over 4 MiB is refused with 413 before it reaches the tool.
References and extension points
- references/cli-access.md — the GDA CLI, the only scripted channel: which distribution to pick when no MCP client is configured, every command and global option (including the REST family
api list/api describe/api call/endpoints), the seven-step port and target resolution chain, engine resolution forstart, exit codes, the output contract, image handling, release asset names, checksum verification and per-platform caveats. Read it before runninggdaor downloading a binary. - references/rest-api.md — the plain-HTTP face on the same port, for a client that cannot do an MCP handshake: the endpoint list, the request and response shapes, where the bearer token comes from, the status-code table, and minimal Python and JavaScript snippets. Read it only when the MCP channel and the CLI are both unavailable and the client can still send HTTP requests.
- references/manual-fallback.md — the manual guide: trigger criteria, hard rules, the handoff template and recovery steps. Read it when neither the MCP channel nor any CLI is available.
- The tool catalog, tool gotchas and development-workflow references live in the godot-autopilot volume; this volume does not duplicate them. When a
search_toolsquery comes back empty, browse the catalog there; when a call behaves surprisingly, check the gotchas there. - User-defined dynamic tools (the
user_toolsmechanism): project scripts can register extra domain tools that then surface through the same discovery protocol and the samecall_toolpath, marked as dynamic. Registration and calls both sit behind theuser_toolscapability (environment variable wins over config; "Allow user tools" dock checkbox; see Meta-tool semantics). The directory-scan convention defaults to res://addons/godot-autopilot-tools, and the plugin ships samples under its user-tools sample directory. For writing or debugging such tools, load the godot-autopilot-scripting volume.
See also
- godot-autopilot — connection prerequisites, usage overview and the shared references (tool catalog, gotchas, development workflow)
- godot-autopilot-scene-system — scene lifecycle, nodes, properties, signals
- godot-autopilot-resources — resource and file operations, rename and move
- godot-autopilot-scripting — GDScript execution channels and user-defined tools
- godot-autopilot-runtime — running the game, input injection, debugging
- godot-autopilot-servers — RenderingServer, PhysicsServer and NavigationServer RID tools
- godot-autopilot-content — tilemap, animation, audio, UI theming
- godot-autopilot-csharp — C#/.NET projects, assembly build loop and script interop
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

