godot-autopilot-scene-system
Skill1 starsChanged 17 days agoMITView on GitHub
Godot scene system operations guide: scene lifecycle, node create/delete/rename/reparent, property read/write with JSON value shapes, signal wiring, the editor undo history model and .tscn serialization details. Use when building or restructuring scenes, setting properties or connecting signals.
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-scriptingSkill
- godot-autopilot-serversSkill
- godot-autopilotSkill
- godot-autopilot-toolsSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 43
Only native node roots are supported: type names an engine class that is instantiated directly, so an inherited scene (a scene whose root …
- Very specific: line 135
Never emulate a move with hand-written remove/add (for example remove_child plus add_child inside code_execute): the manual path records no …
- Distinctive: line 162
Check what exists and what state the editor is in before modifying it:
- Distinctive: line 196
Every successful set registers with the editor undo stack so Ctrl-Z reverts it (the response reports undoable:true).
- Distinctive: line 233
Every editing tool above records exactly one action in the editor's undo/redo history, so a single Ctrl-Z reverts it.
- Very specific: line 247
Make sure a scene is open: create_editor_scene for a fresh one, open_editor_scene for an existing file.
- Very specific: line 248
Create the root — omit parent_path only while no root exists.
- Very specific: line 249
Add children with create_scene_node, passing properties for creation-time values.
- Very specific: line 252
Read back to verify what landed: get_scene_tree (optionally with include_properties) and property_get.
- Distinctive: line 265
When a script a scene depends on is updated, the editor may silently re-pack and re-instantiate the open scene and clear its undo history — …
≈ “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 Scene System
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.
godot-autopilot tools for creating, restructuring, saving and inspecting scenes in the Godot editor, plus the property read/write and signal wiring that turn a node tree into a working scene. Node paths resolve against the edited scene root; the accepted path forms and their error text are listed under Gotchas.
Deep dives live in this skill's references: references/property-json-shapes.md
(JSON value shapes, Godot 3 to 4 renames, serialization rules),
references/undo-history.md (the editor undo history model) and
references/scene-format-tokens.md (the .tscn file format).
Scene lifecycle
The editor works on one edited scene at a time; other scenes can stay open in tabs. A typical lifecycle:
create_editor_scene— start a new empty scene with a typed root- build content — nodes (below), properties and signals (below)
save_editor_sceneorsave_editor_scene_as— persist to diskopen_editor_scene/close_editor_scene— switch scenes- optionally
set_editor_main_scene— make the scene the project's launch scene
Creating a scene
create_editor_scene creates a new empty scene with a root node of the given
type (any Node subclass, default Node) and name (default NewRoot).
close_current (default false) also closes the previous scene, but only when
it has no unsaved changes. timeout_ms (default 2000, range 50-30000) caps how
long the call waits for the editor to observe the new root after adding it; on
timeout the call errors with waited_ms, timeout_ms, node_released and
editor_state (edited_root, unsaved_scenes,
file_system{scanning, progress}) diagnostics, releasing the unclaimed node
(node_released reports whether the release succeeded).
Only native node roots are supported: type names an engine class that is
instantiated directly, so an inherited scene (a scene whose root derives from
another scene) cannot be created here. To derive from an existing scene, copy
the scene file (copy_resource_file) or open it and save a copy under a new
path (save_editor_scene_as).
Replacing a scene with unsaved changes is refused:
current scene is unsaved — position: Root — expected: scene saved before close — action: call save_editor_scene first, then create_editor_scene with close_current=true
Save first, then retry. A type that is not a Node subclass fails with
<type> is not a Node subclass.
Opening, saving, closing and reloading
open_editor_sceneopens a scene file such asres://game.tscnand replaces the edited scene; it errors while the current scene has unsaved changes. The error lists the unsaved paths and suggests the recovery: save withsave_editor_scene, or discard the edits by callingreload_editor_sceneon a listed path, then retry.save_editor_scenesaves the edited scene. A scene that was never saved is written automatically tores://<root node name>.tscnand the response note explains the fallback; usesave_editor_scene_asto choose an explicit path (missing parent directories are created).save_editor_scenessaves every open scene tab at once; scenes without a file path cannot be written to disk.close_editor_scenerefuses to close a scene with unsaved changes.reload_editor_scenerestores the scene from disk, dropping all unsaved changes without confirmation (the current scene, orscene_pathif given). A target scene that is not open now errors withscene is not openinstead of reporting a fake success; on success the response is{"result": "reloaded", "scene_path": ...}(optionally withobserved: truewhen the reload was confirmed). Callsave_editor_scenefirst when the changes matter. Reloading also clears the scene's undo history.set_editor_main_scenetakes apathsuch asres://game.tscnand persists the main scene setting to project.godot.verify_scene_savedre-checks a save without writing anything: it compares the in-memory edited scene tree against its on-disk .tscn file and reports match or mismatch with the missing paths. Run it aftersave_editor_sceneorsave_editor_scene_aswhen every node must have persisted.
Creating nodes
create_scene_node parameters:
type— any Node subclass (defaultNode)name— unique among siblings (defaultNewNode)parent_path— omit it only while the scene has no root; once a root exists, pass the parent pathproperties— optional object of property values applied immediately after creation, including inline resource descriptions that create sub-resources
Creating a node while the scene already has a root and no parent_path is
given fails with scene already has a root, use parent_path to add children.
The properties object assigns values right after creation through the same
conversion chain as property_set: NodePath strings become node references,
{"path": "res://..."} values resolve to resources, and an inline resource
description such as {"type": "RectangleShape2D", "properties": {"size":
{"x": 20, "y": 28}}} creates a pathless sub-resource in one step. Any failing
property frees the new node again and reports the property name, so a failed
create leaves no half-configured node behind. Creation is one editor undo step;
the response carries the new node's path, the applied properties, the
inline_resources array for sub-resources created this way, and an undo hint
describing removal via delete_scene_node.
{
"name": "create_scene_node",
"arguments": {
"parent_path": "Root",
"name": "Player",
"type": "CharacterBody2D",
"properties": {"position": {"x": 0, "y": -10}}
}
}build_nodes_from_specbuilds a whole subtree from one declarative spec (nested type/name/props/children shapes applied through the same conversion chain asproperty_set); pass dry_run for a validate-only preview that writes nothing but runs the same conversion and validation as a real write (inline sub-resources and property families included), and any failed step rolls the whole build back with no residue.
Deleting nodes
delete_scene_node takes path and is managed by the editor undo/redo
history (action "Delete Node <name>"): the do step removes the child and frees
it at the end of the frame, undo re-adds it under the old parent with owner
and sibling index restored — effective while the deferred free has not
destroyed the node yet. The response returns deleted with undoable true
and an undo info object (name, type, parent_path).
The scene root refuses deletion: cannot delete the scene root node — use
close_editor_scene to close the scene, then create_editor_scene.
Renaming nodes
rename_scene_node takes path and new_name. / and : are rejected in
new_name, and a name already used by a sibling is refused, mirroring Godot's
uniqueness rule. The rename is one editor undo/redo step ("Rename Node <old>")
restoring the previous name on undo; the response returns renamed with
undoable true and the new relative path.
Reparenting nodes
reparent_node moves a node: pass path and new_parent_path. It refuses
the scene root, the node itself, its own descendants and its current parent.
It is one editor undo/redo step ("Reparent Node <name>") restoring the old
parent, original sibling index and owner on undo.
keep_world_position (default false) preserves the world transform when the
node and the new parent are both Node2D or both Node3D; other type
combinations ignore it. If the previous owner was the scene root, the node
stays owned by the current scene root so it is still saved with the scene.
Never emulate a move with hand-written remove/add (for example
remove_child plus add_child inside code_execute): the manual path
records no editor undo step and skips the sibling-index and owner fix-up
above, so always call reparent_node.
Instantiating packed scenes
instantiate_scene instantiates a PackedScene from path (a .tscn file)
into the edited scene. parent_path defaults to the scene root; name is
optional; owner defaults to true and sets scene ownership so the instance's
children are saved with the scene. Instances inherit the CONNECT_PERSIST
connections saved in the source scene — do not reconnect the same signal pairs.
Group management
Group names are plain strings shared across the whole scene tree and need no pre-registration. Membership added here is saved with the scene.
add_group_node(node_path,group_name) — adds the node persistently, registered with the editor undo/redo. Idempotent: an existing membership is removed first, then re-added. Returnsaddedwith the node path, the group and apersistentflag.remove_group_node— removes the node from the group, also undoable; removing a node that is not in the group is a safe no-op. Returnsremoved.has_group_node— returns true or false; errors when the node is not found.
At runtime, get_scene_tree_nodes_in_group lists member paths and
call_scene_tree_group calls a method on every member of a group.
Editing-side read-only checks
Check what exists and what state the editor is in before modifying it:
get_scene_treewalks the currently edited scene, returningname,type,pathandchildrenper node. Optionalmax_depth(default 8,-1for unlimited) andinclude_properties(true adds up to 20 filtered properties per node). Errors when no scene is open — create or open one first.get_editor_edited_scene_rootreturns the edited scene root'sname,typeandpath; null when no scene is open. Start scene workflows here.property_get_list(path, optionalonly_script_variablesandproperty_filter) — every property of a node with full metadata;only_script_variables(default false) keeps only script-declared variables (usage flag ScriptVariable, bit 4096) andproperty_filterkeeps names containing the given case-sensitive substring. See the properties section below.get_editor_selectionreports which nodes the user has selected (each withname,classandpath; an empty array means nothing is selected).set_editor_selectionfocuses subsequent operations on specific nodes.get_editor_file_system_treefetches the project file tree, optionally rooted at the given path; directory entries carry children, file entries carryname,pathandtype. Trees deeper than 12 levels are truncated and the response carries amax_depthfield. After creating or modifying files outside the editor, callscan_editor_file_system, then pollget_editor_file_system_statusuntilscanningis false.capture_editor_viewportreturns a base64 PNG of the editor 2D viewport (3D fallback) — visually verify the scene after placing nodes or changing properties. Add save=true to also write the PNG under user://godot_autopilot/captures/ and receive its path in the result; only the 20 most recent captures are kept.validate_scene_filedry-runs a.tscn/.scnfile on disk without touching the edited scene: loads it bypassing the resource cache, checks every dependency for existence, then instantiates and frees it. Returnsvalid,problems(eachkindisload_failed,missing_dependencyorinstantiate_failed),missing_dependenciesanddependency_count. Useful after bulk edits or before committing scene changes.
Properties — reading and writing
property_get(path,property) — returns the exact serialized value. Unknown nodes or properties error with candidate suggestions.property_get_list(path, optionalonly_script_variables,property_filter) — every property with its metadata: name, type, hint, hint_string, usage flags and class_name. The optional filters narrow the listing to script variables (only_script_variables) or to names containing a case-sensitive substring (property_filter). Query it first to discover valid property names and enum ordering beforeproperty_getorproperty_set.get_scene_treewithinclude_properties— a convenience snapshot of up to 20 filtered properties per node (metadata/, underscore-prefixed and Object-typed properties are skipped). Useproperty_getfor the exact full value.
property_set single form takes path, property and value; batch form
takes path plus properties as an object map instead (mutually exclusive,
max 32 entries, type_hint must be omitted). Batch applies object-typed
entries first, then the rest — the same two-pass order as create_scene_node
— and returns applied_properties, property_warnings, inline_resources,
converted_node_paths plus per-property undo entries. A failing entry
reports failed_property and the properties already applied. Property names
accept dot paths (a.b.c) into sub-resources: intermediates are fetched with
get, the leaf is type-checked and set, and failures carry the full path
plus candidates; no expression evaluation or method calls. Omit type_hint to
infer the Variant type from the property metadata. After writing, the value is
read back: a mismatch is reported either as an error (the property may be
read-only, nonexistent, or need an explicit type_hint) or as a warning when
the engine converted the value. For Object- and Array-typed properties a value
the engine does not actually apply (readback null, an emptied array, or a null
element) is an error prefixed value not applied; the tool restores the old
value when it can and says so in the error.
- Every successful set registers with the editor undo stack so Ctrl-Z reverts it (the response reports undoable:true). Exception: when the old or new value is an Object reference, no action is recorded and the response reports undoable:false with a skip reason.
- Node-typed properties — engine hint
NodeType(34), which includes C#[Export]node fields — accept a node path string; it is converted to a node reference automatically and the response reports converted_node_path. An unresolvable path is an error, not a silent ok. - Array properties convert elements one by one: node elements take a path string or
{"__node_ref__": "..."}, resource elements take ares://...ormemory://...string,{"path": "res://..."}or{"resource": "memory://..."}, andnullleaves a slot empty. Passing a non-array value for an array property is an error instead of silently clearing it, and elements the tool cannot express safely are errors too. Seereferences/property-json-shapes.md. - Dictionary properties take a JSON object; a non-object value errors instead of writing an empty dict. SpriteFrames
animationsaccepts either the engine array form or a dict mapping names to{frames, speed, loop}(frames as texture refs or{texture, duration}objects), assembled into the engine array of{name, frames, speed, loop}dicts with per-item validation; sub-resource errors name the real resource path, not the host node. Seereferences/property-json-shapes.md. - Resource-typed properties also accept an inline resource description:
{"type": "RectangleShape2D", "properties": {"size": {"x": 20, "y": 28}}}creates a pathless sub-resource in one step. It is written into the scene file as asub_resourcewhen the scene is saved, the response echoes it in inline_resources, and nesting is limited to 4 levels. Seereferences/property-json-shapes.md. - Assigning a string to an int property silently converts to 0 and reports ok. After any set with an unusual value shape, read back with
property_getto confirm what actually landed.
{"name": "property_set", "arguments": {"path": "Player", "property": "position", "value": {"x": 12.5, "y": -3.25}}}
{"name": "property_set", "arguments": {"path": "Player", "properties": {"position": {"x": 0, "y": -10}, "visible": false}}}
{"name": "property_set", "arguments": {"path": "Hero", "property": "sprite_frames.animations", "value": {"idle": {"frames": [{"texture": "res://icon.svg"}], "speed": 5.0, "loop": true}}}}JSON value shapes for all Godot types, the Godot 3 to 4 renamed-property
table, default-value serialization rules, the inline sub-resource shape and the
memory:// restriction are in references/property-json-shapes.md.
Signals
signal_connect— connects a signal onsource_pathto a method ontarget_path; requiressource_path,signal,target_pathandmethod.persistdefaults to true, which uses CONNECT_PERSIST: the connection is saved with the scene and everyinstantiate_sceneof it inherits the connection. Setpersistto false for a runtime-only connection that is not saved. Returnsconnected, or "already_connected" when the pair exists already (remove it withsignal_disconnect), plus apersistedflag.signal_disconnect— same four parameters. Idempotent: removing a pair that does not exist returns "not_connected" and is not an error. Removing a persistent connection stops it being saved with the scene.trace_signal_flow— inspects the wiring around a node:pathplus optionaldirection("outgoing", "incoming" or "both", default both) andmax_depth(default 3, cycles are cut). Each edge is{from, signal, to, method, persisted}where persisted marks connections saved in the scene file.
{
"name": "signal_connect",
"arguments": {
"source_path": "UI/StartButton",
"signal": "pressed",
"target_path": "Game",
"method": "_on_start_button_pressed"
}
}The undo history model
Every editing tool above records exactly one action in the editor's undo/redo history, so a single Ctrl-Z reverts it. The engine model behind this:
- Actions are routed by their target object: nodes of the edited scene and built-in sub-resources land in that scene's own history; everything else lands in the global history. Each open scene tab has a separate history.
- Committing an action clears the redo stacks of the other histories, and a plain Ctrl-Z picks whichever history holds the newest action by timestamp.
- An action that recorded no operations is discarded on commit. When an action is undone or redone, operations whose target object was freed meanwhile are skipped silently.
- Executing an operation on a Resource marks it dirty; undoing does not make it clean again. Per-history saved versions decide the unsaved state, and actions carry a
mark_unsavedflag that keeps a history unsaved even after the action is undone.
Routing table, redo-invalidation rules, the 800 ms merge window and its
undo-loss caveat: references/undo-history.md.
Workflow checklist
- Confirm tool names via
search_toolsandget_tool_detail— never guess (godot-autopilot-tools). - Make sure a scene is open:
create_editor_scenefor a fresh one,open_editor_scenefor an existing file; save an unsaved scene first. - Create the root — omit
parent_pathonly while no root exists. - Add children with
create_scene_node, passingpropertiesfor creation-time values. For many same-shaped nodes,batch_executeruns tool calls sequentially (stop_on_errordefaults to true). - Set remaining properties and wire signals (sections above).
- Persist with
save_editor_scenebefore playing (play_editor_current_scene) or closing. - Read back to verify what landed:
get_scene_tree(optionally withinclude_properties) andproperty_get. - Observe the result when appearance matters:
capture_editor_viewportafter placing nodes or changing properties, andvalidate_scene_filebefore committing bulk scene edits.
Gotchas
- Three accepted node path forms:
Root/Child(root-name prefixed),/root/Root/Child(absolute),Child(relative to the root). An unresolvable path fails with a node not found error whose hint names the current scene root and the legal path spellings; read the hint, fix the path and retry. create_editor_sceneandopen_editor_scenerefuse to run while the current scene has unsaved changes;open_editor_scenesuggests either saving or callingreload_editor_sceneon the listed path to discard the edits, whilecreate_editor_scenerequires saving first.- Immediately after
create_editor_sceneoropen_editor_scene,get_scene_treemay still reflect the previous scene — call it again or wait briefly for the editor to refresh. - The root node cannot be deleted; close the scene with
close_editor_sceneinstead. delete_scene_nodefrees the node at the end of the frame, so a tree read right after may still list it.- Opening or reloading a scene while the editor is in the middle of a scene change is silently skipped (no error, no effect) — if a call reports ok but the scene did not change, retry after the change settles.
- Opening a scene very early during editor startup is deferred until initialization finishes; the scene appears shortly after instead of failing.
- Opening an already-open scene only switches to its tab and does not re-read the file from disk. To pick up external changes call
reload_editor_scene, which also clears that scene's undo history. - When a script a scene depends on is updated, the editor may silently re-pack and re-instantiate the open scene and clear its undo history — undoable-only changes vanish without an error message.
- Saving re-packs the scene and silently drops: nodes whose owner is not the saved scene root, connections without CONNECT_PERSIST, properties equal to the node's computed default value unless pinned, and instanced-subscene nodes with no local property or group changes (details in
references/scene-format-tokens.md). - Saving a scene cascades to every dirty resource edited alongside it; dirty flags are cleared before writing and PackedScene resources are skipped.
- Every scene write tool (
create_scene_node,delete_scene_node,rename_scene_node,property_set,attach_script_to_node) reports scene_path and scene_unsaved in its response: scene_path is the edited scene's file path on disk, empty until the scene is saved (scene_unsaved is then true). When a scene switch silently fails — for examplecreate_editor_scenerefused because the current scene is unsaved — a following write lands in the still-open scene; read scene_path to notice the wrong target instead of a quietly misplaced node. - Property lines equal to the default value are omitted from the saved file — a missing line means "matches the default", not data loss (
references/property-json-shapes.md). - 4.7+: tree order is parent before child on enter,
_readyfires child before parent, and exit is child before parent — a node cannot rely on a sibling being ready inside_enter_tree.
See also
- godot-autopilot-resources — the
.tscn/.tresfiles behind scenes, rename/move with reference rewriting - godot-autopilot-scripting —
code_executefor programmatic scene edits - godot-autopilot-runtime — running the game and inspecting it live
- references/property-json-shapes.md — JSON value shapes and property renames
- references/undo-history.md — histories, merges and unsaved tracking
- references/scene-format-tokens.md — .tscn sections, tokens and uid resolution
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.

