Node Manipulation

Add, remove, and modify nodes in a Godot scene.

Operations

`node_add`

Add a new node to a scene.

json

{
  "op": "node_add",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "parent_path": "Level/Platforms",
  "node_type": "StaticBody3D",
  "node_name": "Platform_5"
}

Parameter	Type	Required	Description
`node_name`	`string`	required	Name for the new node.
`node_type`	`string`	required	The Godot class name for the new node (e.g., "Sprite2D", "CollisionShape2D").
`parent_path`	`string`	optional default: `"."`	Path to the parent node within the scene tree (e.g., "." for root, "Player" for a child named Player). Default: root node (".").
`project_path`	`string`	required	Absolute path to the Godot project directory.
`properties`	`object`	optional
`scene_path`	`string`	required	Path to the scene file relative to the project root.

Response:

json

{
  "op": "node_add",
  "node_name": "Platform_5",
  "node_type": "StaticBody3D",
  "path": "Level/Platforms/Platform_5",
  "result": "ok"
}

The path in the response is the full scene-relative path to the newly created node.

`node_remove`

Remove a node and all its children.

json

{
  "op": "node_remove",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "node_path": "Level/Platforms/Platform_Old"
}

Parameter	Type	Required	Description
`node_path`	`string`	required	Path to the node to remove within the scene tree. All children of this node are also removed.
`project_path`	`string`	required	Absolute path to the Godot project directory.
`scene_path`	`string`	required	Path to the scene file relative to the project root.

Response:

json

{
  "op": "node_remove",
  "node_path": "Level/Platforms/Platform_Old",
  "result": "ok"
}

`node_set_properties`

Set one or more properties on a node.

json

{
  "op": "node_set_properties",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "node_path": "Level/Enemy_0",
  "properties": {
    "collision_layer": 2
  }
}

Parameter	Type	Required	Description
`node_path`	`string`	required	Path to the target node within the scene tree (e.g., "Player/Sprite2D").
`project_path`	`string`	required	Absolute path to the Godot project directory.
`properties`	`object`	required	Properties to set. Keys are property names, values are JSON representations. Type conversion is automatic: Vector2 from {"x":1,"y":2}, Color from "#ff0000" or {"r":1,"g":0,"b":0}, NodePath from string, resources from "res://" paths.
`scene_path`	`string`	required	Path to the scene file relative to the project root.

To set multiple properties at once, pass more keys in properties:

json

{
  "op": "node_set_properties",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/enemy.tscn",
  "node_path": "Enemy",
  "properties": {
    "collision_layer": 2,
    "collision_mask": 1,
    "motion_mode": "grounded",
    "floor_snap_length": 0.1
  }
}

Response:

json

{
  "op": "node_set_properties",
  "node_path": "Level/Enemy_0",
  "properties_set": ["collision_layer"],
  "result": "ok"
}

`node_reparent`

Change a node's parent or rename it in place.

json

{
  "op": "node_reparent",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "node_path": "Level/Pickups/Coin_0",
  "new_parent_path": "Level/Room2/Pickups"
}

Parameter	Type	Required	Description
`new_name`	`string`	optional
`new_parent_path`	`string`	required	Path to the new parent node within the scene tree.
`node_path`	`string`	required	Path to the node to move within the scene tree.
`project_path`	`string`	required	Absolute path to the Godot project directory.
`scene_path`	`string`	required	Path to the scene file relative to the project root.

Response:

json

{
  "op": "node_reparent",
  "node_path": "Level/Pickups/Coin_0",
  "new_path": "Level/Room2/Pickups/Coin_0",
  "result": "ok"
}

`node_find`

Search nodes by class, group, name pattern, or property value.

json

{
  "op": "node_find",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "class_name": "CharacterBody3D",
  "group": "enemies",
  "name_pattern": "Enemy_*",
  "limit": 50
}

Parameter	Type	Required	Description
`class_name`	`string`	optional
`group`	`string`	optional
`limit`	`number`	optional default: `100`	Maximum number of results to return (default: 100).
`name_pattern`	`string`	optional
`project_path`	`string`	required	Absolute path to the Godot project directory.
`property`	`string`	optional
`property_value`	`any`	optional	Filter: property must equal this value (requires `property` to also be set).
`scene_path`	`string`	required	Path to the scene file relative to the project root.

Response:

json

{
  "op": "node_find",
  "nodes": [
    { "name": "Enemy_0", "class": "CharacterBody3D", "path": "Level/Enemies/Enemy_0" },
    { "name": "Enemy_1", "class": "CharacterBody3D", "path": "Level/Enemies/Enemy_1" }
  ],
  "result": "ok"
}

`node_set_groups`

Add or remove a node from groups.

json

{
  "op": "node_set_groups",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "node_path": "Level/Enemy_0",
  "add": ["enemies", "patrol_units"],
  "remove": ["idle"]
}

Parameter	Type	Required	Description
`add`	`array`	optional
`node_path`	`string`	required	Path to the target node within the scene tree.
`project_path`	`string`	required	Absolute path to the Godot project directory.
`remove`	`array`	optional
`scene_path`	`string`	required	Path to the scene file relative to the project root.

`node_set_script`

Attach a GDScript to a node. Omit script_path to detach the current script.

json

{
  "op": "node_set_script",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "node_path": "Level/Enemy_0",
  "script_path": "scripts/enemy_ai.gd"
}

Parameter	Type	Required	Description
`node_path`	`string`	required	Path to the target node within the scene tree.
`project_path`	`string`	required	Absolute path to the Godot project directory.
`scene_path`	`string`	required	Path to the scene file relative to the project root.
`script_path`	`string`	optional

`node_set_meta`

Set metadata on a node.

json

{
  "op": "node_set_meta",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "node_path": "Level/Enemy_0",
  "meta": {
    "spawn_group": "wave_1",
    "difficulty": 2
  }
}

Parameter	Type	Required	Description
`meta`	`object`	required	Metadata entries to set. Keys are metadata names, values are the data. Set a value to null to remove that metadata key.
`node_path`	`string`	required	Path to the target node within the scene tree.
`project_path`	`string`	required	Absolute path to the Godot project directory.
`scene_path`	`string`	required	Path to the scene file relative to the project root.

Property types

Director maps JSON types to Godot property types automatically:

JSON type	Godot type
`number` (integer)	`int`
`number` (float)	`float`
`boolean`	`bool`
`string`	`String`, `NodePath`, `StringName`
`[x, y]` (2-element array)	`Vector2`
`[x, y, z]` (3-element array)	`Vector3`
`[x, y, z, w]` (4-element array)	`Vector4`, `Quaternion`, `Color`
`[[r,g,b,a]]`	`Color` (if property expects Color)
`object`	`Dictionary`
`array`	`Array`

For ambiguous cases (e.g., a 4-element array that could be a Quaternion or Color), Director uses the property's declared type from Godot's class database to disambiguate.

Example conversations

Building a collision shape

Add a BoxShape3D collision to the Platform_5 node. Make it 4m wide, 0.5m tall, 4m deep.

Done. CollisionShape3D added under Platform_5 with a BoxShape3D (4×0.5×4m).

Fixing collision layers on multiple nodes

Set collision_layer=2 and collision_mask=1 on Enemy_0, Enemy_1, and Enemy_2.

All three enemies updated. collision_layer=2, collision_mask=1 applied to Enemy_0, Enemy_1, and Enemy_2.

Tips

Use node_set_properties for related property changes. One call validates the submitted property collection before mutation and keeps the result together. See Batch Operations for sequential multi-operation work.

Node paths are relative to the scene root. The root node itself is ".". A child named Player is "Player". A grandchild is "Player/Camera3D". Use scene_read to confirm paths.

Check persistence after node_remove. Against an open scene, removal creates a native undo entry and remains unsaved until scene_save. Against a detached headless scene, the target file is saved. Read the persistence result rather than assuming either outcome.

Node Manipulation ​

Operations ​

node_add ​

node_remove ​

node_set_properties ​

node_reparent ​

node_find ​

node_set_groups ​

node_set_script ​

node_set_meta ​

Property types ​

Example conversations ​

Building a collision shape ​

Fixing collision layers on multiple nodes ​

Tips ​

Node Manipulation

Operations

`node_add`

`node_remove`

`node_set_properties`

`node_reparent`

`node_find`

`node_set_groups`

`node_set_script`

`node_set_meta`

Property types

Example conversations

Building a collision shape

Fixing collision layers on multiple nodes

Tips