agentleFS
jesspigjesspig/Godot-Autopilot/skills/godot-autopilot-scripting/SKILL.md

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.

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
  1. Distinctive:

    All four execute arbitrary GDScript and are treated as highest-risk side effects.

    line 43
  2. Very specific:

    Write func with a trailing space: func followed by a tab or ( does not select multi-function mode and is rejected inside single-function …

    line 74

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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_script compiles before saving: compilation errors abort the call with parser output, so a success means the file on disk parses. overwrite defaults 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 parallel create_script calls 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, read get_debugger_log to confirm the editor process logged no parser or runtime errors.
  • attach_script_to_node and detach_script_from_node operate on the edited scene and are registered with the editor undo/redo. script_path accepts any resource that ResourceLoader resolves as a Script, not only .gd files. Replacing an existing script does not migrate or clean up the old script's exported properties: stored references such as node_paths may be lost and have to be re-wired by hand. A script without @tool cannot be instantiated in the editor, so its methods only run once the game runs - call_script_node reports the same restriction.
  • reload_script reloads 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_list lists a script's declared variables with name, type and usage flags.
  • get_script_property reads a value: with script_path it returns the declared default; with node_path the node's current value. Pass exactly one of the two.
  • set_script_property writes a node property directly - no undo entry, no type or read-only validation. It is the lightweight channel for quick in-memory tweaks; use property_set when undo support and validation matter.
  • patch_script patches one anchored spot in an existing script file (first occurrence of the anchor text, replace or insert mode) instead of rewriting the whole file; like create_script it 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 @tool is 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_property with script_path keeps returning the declared defaults; editor-side mutations you expected from the script never appear; call_script_node is rejected for non-@tool scripts.
  • Fix: add @tool as the first line, then reload_script - or run the game and use the game channel.

Details in references/execution-gotchas.md.

Four execution channels

ChannelRuns where@tool neededTimeoutSweet spot
execute_scripteditor process, synchronousnonone - long code blocks the editoreditor automation with SceneRoot access
call_script_nodean existing node instance in the edited sceneyesdefault tool timeoutcalling one method with real instance state
execute_game_scriptthe running game processnotimeout_ms default 5000, cap 25000game-state queries and mutations
code_executeeditor process, wrapped temporary nodewrapped for youtimeout_ms, default 5000, cap reported by the schemaloops, bulk edits, computed results

All four execute arbitrary GDScript and are treated as highest-risk side effects.

  • execute_script auto-returns a single expression's value; multi-line code needs an explicit return. Bare statements (no top-level func) are auto-wrapped into extends Node + func _run() — the same wrapper the game channel applies; a complete script must define func _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 exposes SceneRoot (the edited scene root); reach scene nodes via SceneRoot.get_node(...).
  • call_script_node runs inside the existing node instance, so its state is real, not reconstructed. Its parameters are node_path, function (the method name — not method) and optional args. Non-@tool scripts error - run the game instead for those.
  • execute_game_script runs inside the running game. Its action script accepts either a complete GDScript defining func _run() (used as-is; required for a persistent entry point) or bare statements, auto-wrapped into extends Node + func _run() exactly like the editor channels — a value needs an explicit return, and wrapped calls report wrapped: 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 func line 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 func line found): the whole source is preserved verbatim; pick the entry point with function_name (default _run; a missing entry is stubbed with func <name>(): pass):
func build_report():
    var lines = []
    for child in SceneRoot.get_children():
        lines.append(child.name)
    return lines

Pass function_name set to build_report to select it.

  • Write func with a trailing space: func followed 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_ms defaults to 5000 and is clamped to the maximum the code_execute schema 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. Use close_editor_scene to close scenes.
  • SceneRoot is 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_init runs after every successful script reload, not once per session: side effects placed there (building caches, registering helpers) re-execute on each reload_script.
  • self is unavailable inside _static_init - it executes in a static context with no instance.
  • Static variables survive a hot reload only when reload_script runs with keep_state=true; a plain reload re-initializes them (and re-runs _static_init on 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 _ready sees 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 (@tool required).
  • 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 status
  • godot-autopilot-scene-system - node CRUD, property JSON shapes and undo semantics
  • godot-autopilot-tools - discovery protocol and the error watermark

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.