godot-autopilot-scripting
Skill1 starsChanged 17 days agoMITView on GitHub
Godot GDScript guide: script lifecycle, the four execution channels (execute_script, call_script_node, execute_game_script, code_execute), @tool semantics, static initializers and the editor-vs-game process boundary. Use when writing, attaching or running GDScript.
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-serversSkill
- godot-autopilotSkill
- godot-autopilot-toolsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 43
All four execute arbitrary GDScript and are treated as highest-risk side effects.
- Very specific: line 74
Write func with a trailing space: func followed by a tab or ( does not select multi-function mode and is rejected inside single-function …
≈ “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
GDScript Workflows
Invocation: use the native MCP tools first; when that channel is down, follow the calling ladder in the godot-autopilot-tools skill (the gda CLI, via bunx, a global install, or the standalone gda binary); with no CLI available, work through its references/manual-fallback.md.
Creating, attaching, editing and reloading GDScript through godot-autopilot, and the safety differences between the four execution channels plus the code_execute meta tool. Engine-level execution gotchas (placeholder instances, static initializers, editor-vs-game semantics, frame ordering) are summarized here and covered in depth in references/execution-gotchas.md.
Script lifecycle
create_scriptcompiles before saving: compilation errors abort the call with parser output, so a success means the file on disk parses.overwritedefaults to false. The saved content is read back from disk and verified; a locked file surfaces as verified=false instead of silent success. Never issue parallelcreate_scriptcalls for the same path - serial writes to one file are not synchronized. A passing compile only proves the file parses, not that the code runs correctly: after any script edit, readget_debugger_logto confirm the editor process logged no parser or runtime errors.attach_script_to_nodeanddetach_script_from_nodeoperate on the edited scene and are registered with the editor undo/redo.script_pathaccepts any resource thatResourceLoaderresolves as aScript, not only .gd files. Replacing an existing script does not migrate or clean up the old script's exported properties: stored references such asnode_pathsmay be lost and have to be re-wired by hand. A script without@toolcannot be instantiated in the editor, so its methods only run once the game runs -call_script_nodereports the same restriction.reload_scriptreloads from disk after an external edit;keep_state(default false) preserves instance state across the reload. Static variables follow their own rule - see "Static initializers" below.get_script_property_listlists a script's declared variables with name, type and usage flags.get_script_propertyreads a value: withscript_pathit returns the declared default; withnode_paththe node's current value. Pass exactly one of the two.set_script_propertywrites a node property directly - no undo entry, no type or read-only validation. It is the lightweight channel for quick in-memory tweaks; useproperty_setwhen undo support and validation matter.patch_scriptpatches one anchored spot in an existing script file (first occurrence of the anchor text, replace or insert mode) instead of rewriting the whole file; likecreate_scriptit compiles before writing and proves the write with a disk-readback hash. Preview with dry_run first for a no-write diff.
Gotcha: non-@tool scripts never execute in the editor
The single most common cause of "my script did nothing" reports:
- A script without
@toolis never instantiated in the editor process. A node holding such a script in the edited scene carries a placeholder instance (PlaceHolderScriptInstance) that exposes only the exported property defaults. - Zero code runs: no
_init, no_ready, no_process, no tool-time callbacks - and nothing errors or warns. The scene looks perfectly healthy while the script is inert. - The gate is
can_instantiate = valid && !abstract && (tool || scripting_enabled): only scripts marked@tool(or failing compilation or abstract-ness checks) are instantiable in the editor. - Symptoms:
get_script_propertywithscript_pathkeeps returning the declared defaults; editor-side mutations you expected from the script never appear;call_script_nodeis rejected for non-@toolscripts. - Fix: add
@toolas the first line, thenreload_script- or run the game and use the game channel.
Details in references/execution-gotchas.md.
Four execution channels
| Channel | Runs where | @tool needed | Timeout | Sweet spot |
execute_script | editor process, synchronous | no | none - long code blocks the editor | editor automation with SceneRoot access |
call_script_node | an existing node instance in the edited scene | yes | default tool timeout | calling one method with real instance state |
execute_game_script | the running game process | no | timeout_ms default 5000, cap 25000 | game-state queries and mutations |
code_execute | editor process, wrapped temporary node | wrapped for you | timeout_ms, default 5000, cap reported by the schema | loops, bulk edits, computed results |
All four execute arbitrary GDScript and are treated as highest-risk side effects.
execute_scriptauto-returns a single expression's value; multi-line code needs an explicit return. Bare statements (no top-levelfunc) are auto-wrapped intoextends Node+func _run()— the same wrapper the game channel applies; a complete script must definefunc _run()and is used as-is. Compile errors are line-mapped back to your source. print() output lands in the output field, errors in the errors field. The environment exposesSceneRoot(the edited scene root); reach scene nodes via SceneRoot.get_node(...).call_script_noderuns inside the existing node instance, so its state is real, not reconstructed. Its parameters arenode_path,function(the method name — notmethod) and optionalargs. Non-@toolscripts error - run the game instead for those.execute_game_scriptruns inside the running game. Itsactionscriptaccepts either a complete GDScript definingfunc _run()(used as-is; required for a persistent entry point) or bare statements, auto-wrapped intoextends Node+func _run()exactly like the editor channels — a value needs an explicitreturn, and wrapped calls reportwrapped: true. Unlike the code_execute sandbox, temporary nodes it creates can persist in the game after the call returns. Game-channel prerequisites are covered by the godot-autopilot-runtime skill.
The code_execute meta tool
code_execute wraps your source into a @tool extends Node script, runs it on a temporary editor node, then cleans the node up. Bare-statement wrapping is shared with execute_script and the game channel — all three channels wrap, reindent and line-map through one implementation. Which wrapper you get is decided by a line scan: leading spaces/tabs stripped, blank and #/// comment lines skipped - a line starting with func (trailing space, even indented; static func too) selects multi-function mode, anything else is inlined into the entry function (func-like lines such as func( are rejected in single-function mode).
- Single-function mode (no
funcline found): your code is indented into an implicit entry function. Write straight-line code ending in return:
var total = 0
for child in SceneRoot.get_children():
total += 1
return total- Multi-function mode (a
funcline found): the whole source is preserved verbatim; pick the entry point withfunction_name(default_run; a missing entry is stubbed withfunc <name>(): pass):
func build_report():
var lines = []
for child in SceneRoot.get_children():
lines.append(child.name)
return linesPass function_name set to build_report to select it.
- Write
funcwith a trailing space:funcfollowed by a tab or(does not select multi-function mode and is rejected inside single-function mode. - Indentation (tabs or spaces) is auto-detected per source; mixing both aborts with an error.
timeout_msdefaults to 5000 and is clamped to the maximum thecode_executeschema reports - 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. The deadline is injected into the script and checked while it runs, so a long loop is interrupted once the deadline passes.- A source calling
close_scene(is rejected outright - it would destroy the node executing the code and crash the editor. Useclose_editor_sceneto close scenes. SceneRootis injected as the edited scene root; the wrapper node itself lives under /root, so scene nodes are reachable only through SceneRoot.get_node(...).- Node cleanup: with
auto_owner=true, nodes created during execution get their owner assigned recursively and survive (reported in auto_owner_set); with false, newly created ownerless children are deleted after the run. - Results: the return value is serialized into result, alongside execution_time_ms, output (capped at 8192 bytes) and wrapped_source; compile errors arrive with line-mapped messages and the wrapped source. When the result is a Resource it is auto-registered and returned through registered_resource.
Bulk data through code_execute
Anything touching many objects - filling tile cells, rewriting hundreds of properties, computing over large arrays - belongs in one code_execute loop instead of hundreds of individual tool calls. It avoids oversized JSON payloads (responses cap at 4 MiB) and runs far faster.
Static initializers
_static_initruns after every successful script reload, not once per session: side effects placed there (building caches, registering helpers) re-execute on eachreload_script.selfis unavailable inside_static_init- it executes in a static context with no instance.- Static variables survive a hot reload only when
reload_scriptruns withkeep_state=true; a plain reload re-initializes them (and re-runs_static_initon top).
Editor vs game process semantics
is_editor_hint() is true for the whole editor process - including @tool scripts and editor plugins - and false for the entire F5-launched game subprocess. Two frequent knock-on effects: Input.set_custom_mouse_cursor() is a no-op when called in the editor process, and editor-only (API_EDITOR) classes error when instantiated in the running game. Branch on is_editor_hint() early in @tool code that must behave differently per process. Full cross-process details: references/execution-gotchas.md.
Tree entry and exit order
For any subtree added to or removed from the scene tree, callbacks fire in a fixed three-phase order:
_enter_tree: parents before children._ready: children before parents - a parent's_readysees all descendants fully initialized._exit_tree: children before parents.
The tree_exited signal fires once after the whole branch has been cut from the tree, not per node during removal. In a @tool script the same order applies to editor-side tree changes.
Assembly recipe (stage required children before the parent enters the tree, or get_node_or_null guards): references/execution-gotchas.md.
C# limitations
C#-specific workflows — build_csharp_assembly, the lack of in-editor .NET assembly hot-reload, and how C# properties appear to GDScript — live in the godot-autopilot-csharp skill; the GDScript channels are unaffected by .NET assembly state.
Hot reload in the running game
reload_game_scripts reloads GDScript files inside the running game without restarting it. Use it after editing scripts mid-session, then re-run your verification calls. Remember the static-variable rule above applies to editor reloads; in-game reload behavior is covered by the godot-autopilot-runtime skill.
Choosing a channel
- Editor-side inspection or one-shot automation:
execute_script. - One method on one node with real instance state:
call_script_node(@toolrequired). - Anything inside the running game:
execute_game_script. - Loops, bulk edits, computed results, anything wanting a timeout guard:
code_execute.
See also
godot-autopilot-runtime- the game channel, input injection, pause semantics and statusgodot-autopilot-scene-system- node CRUD, property JSON shapes and undo semanticsgodot-autopilot-tools- discovery protocol and the error watermark
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.

