Scene Operations

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

Operations

`scene_create`

Create a new empty scene with a root node.

json

{
  "op": "scene_create",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/player.tscn",
  "root_type": "CharacterBody3D"
}

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:

json

{
  "op": "scene_create",
  "scene_path": "scenes/player.tscn",
  "root_type": "CharacterBody3D",
  "result": "ok"
}

`scene_read`

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

json

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

Parameter	Type	Required	Description
`depth`	`number`	optional	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:

json

{
  "op": "scene_read",
  "scene_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).

json

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

Parameter	Type	Required	Description
`directory`	`string`	optional	Subdirectory to list (relative to project root). Lists entire project if omitted.
`pattern`	`string`	optional	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:

json

{
  "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.

json

{
  "op": "scene_add_instance",
  "project_path": "/home/user/my-game",
  "scene_path": "scenes/level_01.tscn",
  "instance_scene": "scenes/enemies/basic_enemy.tscn",
  "parent_path": "Level/Enemies",
  "node_name": "Enemy_4"
}

Parameter	Type	Required	Description
`instance_scene`	`string`	required	Scene to instance (relative to project, e.g. "scenes/player.tscn").
`node_name`	`string`	optional	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:

json

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

`scene_diff`

Compare two scenes and return a list of differences. Supports git refs.

json

{
  "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:

json

{
  "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.

json

{
  "op": "uid_get",
  "project_path": "/home/user/my-game",
  "file_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:

json

{
  "op": "uid_get",
  "file_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.

json

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

Parameter	Type	Required	Description
`directory`	`string`	optional	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.

json

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

Parameter	Type	Required	Description
`items`	`string[]`	optional	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).

Project settings

These operations modify project.godot directly through Godot's ConfigFile API. Use them instead of hand-editing the file — they guarantee correct INI formatting and work in headless mode.

`autoload_add`

Register an autoload singleton so it is globally accessible by name in all GDScript files (e.g. EventBus, GameState). Call this after creating the script file and after project_reload.

json

{
  "op": "autoload_add",
  "project_path": "/home/user/my-game",
  "name": "EventBus",
  "script_path": "autoload/event_bus.gd"
}

Parameter	Type	Required	Description
`enabled`	`boolean`	optional default: `true`	Whether the autoload is active. Default: true.
`name`	`string`	required	Autoload singleton name as it will appear in code (e.g. "EventBus", "GameState").
`project_path`	`string`	required	Absolute path to the Godot project directory (must contain project.godot).
`script_path`	`string`	required	Script path relative to the project root (e.g. "autoload/event_bus.gd").

Response:

json

{ "name": "EventBus", "script_path": "autoload/event_bus.gd", "enabled": true }

`autoload_remove`

Remove an autoload registration. The script file itself is not deleted.

json

{
  "op": "autoload_remove",
  "project_path": "/home/user/my-game",
  "name": "EventBus"
}

Parameter	Type	Required	Description
`name`	`string`	required	Autoload singleton name to remove.
`project_path`	`string`	required	Absolute path to the Godot project directory (must contain project.godot).

`project_settings_set`

Set one or more project settings. Keys use "section/key" format matching project.godot. Set a value to null to erase the key.

json

{
  "op": "project_settings_set",
  "project_path": "/home/user/my-game",
  "settings": {
    "application/run/main_scene": "res://scenes/main/main.tscn",
    "application/config/name": "My Game",
    "display/window/size/viewport_width": 1920,
    "display/window/size/viewport_height": 1080
  }
}

Parameter	Type	Required	Description
`project_path`	`string`	required	Absolute path to the Godot project directory (must contain project.godot).
`settings`	`object`	required	Map of setting keys to values. Keys use the format "section/key" matching the project.godot file structure, e.g.: - "application/run/main_scene" → sets the main scene path - "application/config/name" → sets the project display name - "display/window/size/viewport_width" → sets window width Set a value to null to erase the key.

`project_reload`

Reload the project and validate all scripts. Call this after writing .gd files with the Write tool. Returns structured diagnostics (parse errors, missing identifiers, broken references) so you can fix issues before they cause failures in scene operations. Also restarts the daemon so the next operation sees new GDScript class names.

json

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

Parameter	Type	Required	Description
`project_path`	`string`	required	Absolute path to the Godot project directory (must contain project.godot).

Response:

json

{
  "result": "ok",
  "scripts_checked": 12,
  "autoloads": { "EventBus": "autoload/event_bus.gd" },
  "errors": [],
  "warnings": []
}

Typical workflow when creating scripts:

Write tool: write autoload/event_bus.gd
→ project_reload           (daemon restarts fresh, validates scripts)
→ autoload_add             (registers EventBus in project.godot)
→ scene_create + node_set_script  (safe to reference the script)

`editor_status`

Get a snapshot of the Godot editor's current state. Returns which scenes are open, which is active, whether the game is running, registered autoloads, and recent log output from godot.log (errors, warnings, print statements). Works in headless mode too — returns autoloads and log with editor_connected: false.

json

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

Parameter	Type	Required	Description
`project_path`	`string`	required	Absolute path to the Godot project directory (must contain project.godot).

Response (editor running):

json

{
  "editor_connected": true,
  "active_scene": "scenes/player.tscn",
  "open_scenes": ["scenes/main.tscn", "scenes/player.tscn"],
  "game_running": false,
  "autoloads": { "EventBus": "autoload/event_bus.gd" },
  "recent_log": [
    "Godot Engine v4.6.1.stable.official",
    "[Director] Editor plugin listening on port 6551",
    "ERROR: res://debug/test_grid.gd:20 - Parse Error: Identifier \"EventBus\" not declared"
  ],
  "errors": [
    { "file": "debug/test_grid.gd", "line": 20, "severity": "error",
      "message": "Parse Error: Identifier \"EventBus\" not declared in the current scope." }
  ],
  "warnings": []
}

Response (headless / editor not running):

json

{
  "editor_connected": false,
  "active_scene": "",
  "open_scenes": [],
  "game_running": false,
  "autoloads": { "EventBus": "autoload/event_bus.gd" },
  "recent_log": ["..."],
  "errors": [],
  "warnings": []
}

Use editor_status to orient yourself before making changes, to check whether the editor is connected, or to see what errors currently exist in the 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.

Scene Operations ​

Operations ​

scene_create ​

scene_read ​

scene_list ​

scene_add_instance ​

scene_diff ​

uid_get ​

uid_update_project ​

export_mesh_library ​

Project settings ​

autoload_add ​

autoload_remove ​

project_settings_set ​

project_reload ​

editor_status ​

Example conversation ​

Tips ​

Scene Operations

Operations

`scene_create`

`scene_read`

`scene_list`

`scene_add_instance`

`scene_diff`

`uid_get`

`uid_update_project`

`export_mesh_library`

Project settings

`autoload_add`

`autoload_remove`

`project_settings_set`

`project_reload`

`editor_status`

Example conversation

Tips