Scene Operations

Director can create, read, list, instance, and compare Godot scenes.

Operations

scene_create

Create a new empty scene with a root node.

{
  "op": "scene_create",
  "project_path": "/home/user/my-game",
  "path": "scenes/player.tscn",
  "root_class": "CharacterBody3D",
  "root_name": "Player"
}

Parameter	Type	Required	Description
project_path	string	required	Absolute path to the Godot project directory (must contain project.godot).
root_type	string	required	The Godot class name for the root node (e.g., "Node2D", "Node3D", "Control").
scene_path	string	required	Path to the scene file relative to the project root (e.g., "scenes/player.tscn").

Response:

{
  "op": "scene_create",
  "path": "scenes/player.tscn",
  "root_name": "Player",
  "root_class": "CharacterBody3D",
  "result": "ok"
}

scene_read

Read the structure of an existing scene — all nodes, their classes, properties, and hierarchy.

{
  "op": "scene_read",
  "project_path": "/home/user/my-game",
  "path": "scenes/player.tscn",
  "max_depth": 4
}

Parameter	Type	Required	Description
depth	number	optional default: null	Maximum tree depth to include (default: unlimited).
project_path	string	required	Absolute path to the Godot project directory (must contain project.godot).
properties	boolean	optional default: true	Whether to include node properties in the output (default: true).
scene_path	string	required	Path to the scene file relative to the project root (e.g., "scenes/player.tscn").

Response:

{
  "op": "scene_read",
  "path": "scenes/player.tscn",
  "nodes": [
    {
      "name": "Player",
      "class": "CharacterBody3D",
      "path": ".",
      "properties": {
        "collision_layer": 1,
        "collision_mask": 3,
        "motion_mode": "grounded"
      },
      "children": ["CollisionShape3D", "MeshInstance3D", "Camera3D", "AnimationPlayer"]
    }
  ]
}

scene_list

List all .tscn files in the project (or a subdirectory).

{
  "op": "scene_list",
  "project_path": "/home/user/my-game",
  "directory": "scenes/enemies"
}

Parameter	Type	Required	Description
directory	string	optional default: null	Subdirectory to list (relative to project root). Lists entire project if omitted.
pattern	string	optional default: null	Glob pattern to filter scene paths (e.g., "scenes/**/*.tscn"). Uses Godot's String.match() which supports * and ? wildcards. Omitting returns all scenes (backward-compatible).
project_path	string	required	Absolute path to the Godot project directory (must contain project.godot).

Response:

{
  "scenes": [
    { "path": "scenes/enemies/basic_enemy.tscn", "root_class": "CharacterBody3D" },
    { "path": "scenes/enemies/boss.tscn", "root_class": "CharacterBody3D" }
  ]
}

scene_add_instance

Add an instance of another scene as a child node.

{
  "op": "scene_add_instance",
  "project_path": "/home/user/my-game",
  "scene": "scenes/level_01.tscn",
  "parent": "Level/Enemies",
  "source_scene": "scenes/enemies/basic_enemy.tscn",
  "name": "Enemy_4",
  "position": [10.0, 0.0, -5.0]
}

Parameter	Type	Required	Description
instance_scene	string	required	Scene to instance (relative to project, e.g. "scenes/player.tscn").
node_name	string	optional default: null	Override the instance root's name. Uses the instanced scene's root name if omitted.
parent_path	string	optional default: "."	Parent node path within the target scene (default: root ".").
project_path	string	required	Absolute path to the Godot project directory.
scene_path	string	required	Scene file to modify (relative to project, e.g. "scenes/level.tscn").

Response:

{
  "op": "scene_add_instance",
  "name": "Enemy_4",
  "source_scene": "scenes/enemies/basic_enemy.tscn",
  "result": "ok"
}

scene_diff

Compare two scenes and return a list of differences.

{
  "op": "scene_diff",
  "project_path": "/home/user/my-game",
  "scene_a": "scenes/level_01.tscn",
  "scene_b": "scenes/level_01_backup.tscn"
}

Parameter	Type	Required	Description
project_path	string	required	Absolute path to the Godot project directory.
scene_a	string	required	Path to the first scene (relative to project, e.g. "scenes/player.tscn"). Supports git ref syntax (e.g. "HEAD:scenes/player.tscn") to compare against previous versions.
scene_b	string	required	Path to the second scene (relative to project). Supports git ref syntax (e.g. "HEAD:scenes/player.tscn").

Response:

{
  "differences": [
    {
      "type": "node_added",
      "path": "Level/Platform_5",
      "class": "StaticBody3D",
      "in": "scene_a"
    },
    {
      "type": "property_changed",
      "path": "Level/Enemy_0",
      "property": "position",
      "value_a": [5.0, 0.0, -3.0],
      "value_b": [3.0, 0.0, -3.0]
    }
  ]
}

uid_get

Look up the UID for a resource path.

{
  "op": "uid_get",
  "project_path": "/home/user/my-game",
  "path": "scenes/enemies/basic_enemy.tscn"
}

Parameter	Type	Required	Description
file_path	string	required	File path relative to project (e.g. "scenes/player.tscn").
project_path	string	required	Absolute path to the Godot project directory.

Response:

{
  "op": "uid_get",
  "path": "scenes/enemies/basic_enemy.tscn",
  "uid": "uid://abc123xyz"
}

uid_update_project

Rescan all resources and rebuild the project UID cache. Run after adding or moving resource files outside of the editor.

{
  "op": "uid_update_project",
  "project_path": "/home/user/my-game"
}

Parameter	Type	Required	Description
directory	string	optional default: null	Subdirectory to scan (relative to project). Default: scan entire project.
project_path	string	required	Absolute path to the Godot project directory.

export_mesh_library

Export meshes from a scene into a MeshLibrary resource for use with GridMap.

{
  "op": "export_mesh_library",
  "project_path": "/home/user/my-game",
  "scene": "scenes/dungeon_tiles.tscn",
  "save_path": "assets/dungeon_tiles.meshlib"
}

Parameter	Type	Required	Description
items	string[]	optional default: null	Optional list of MeshInstance3D node names to include. If omitted, all MeshInstance3D children of the scene root are included.
output_path	string	required	Output path for the MeshLibrary .tres file (relative to project).
project_path	string	required	Absolute path to the Godot project directory.
scene_path	string	required	Source scene containing MeshInstance3D nodes (relative to project).

Example conversation

Create a new player scene with a CharacterBody3D root, and add a CapsuleShape3D collision shape.

Player scene created at scenes/player.tscn. Now adding the collision shape.

Done. Player scene has a CapsuleShape3D collision with radius 0.4 and height 1.8. Open scenes/player.tscn in the editor to verify.

Tips

Use scene_read before modifying. Know the existing structure before adding nodes. This prevents duplicate additions or wrong parent paths.

Use scene_list to find existing scenes. Before creating a new enemy scene, check if one already exists. scene_list with a directory filter is fast.

scene_add_instance vs node_add. Use scene_add_instance when you want to place a pre-built scene (like an enemy prefab) into a level. Use node_add when building node hierarchy from scratch.

scene_diff for auditing AI changes. After a batch of Director operations, diff the modified scene against its last git version to see exactly what changed.