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
`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
`pattern`	`string`	optional
`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
`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
`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`	`array`	optional
`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.7.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. Its project path and process identifier establish which editor or headless process answered. Its recent log is editor context, not a run-scoped diagnostic stream.

Save an open scene

Use scene_save after an editor-backed scene mutation when the change should reach disk. It serializes only the selected scene, retains native undo, and does not save unrelated external resources. Godot's native dirty marker may remain. Read the returned persistence data, then reopen or diff when saved content matters.

Run a selected saved scene

Use editor_run with start, stop, restart, or status. Start and restart require a scene path and a verified open editor. Launch does not implicitly save open work or fall back to a headless run. A successful response reports Godot's native play state only. Use Stage runtime_status to establish the actual run, current scene, and readiness.

On Windows, start and restart may set presentation to automated, deferred, or interactive. Automated is for agent visual work, deferred prepares an ordinary window for the user to focus after the agent reports readiness, and interactive permits a requested visible review. Omission is legacy behavior. Automated and deferred are unsupported outside Windows. If their best-effort window protection degrades after launch, stop the reported run before fallback.

Inspect the installed engine API

Use engine_api when a class member, property type, signal, method, enum, or default is uncertain. Start with a class summary, then narrow to one category or member. The response identifies the selected engine version and bounds large member sets. Some defaults are text-only or unavailable rather than authoring-ready JSON.

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 ​

Save an open scene ​

Run a selected saved scene ​

Inspect the installed engine API ​

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`

Save an open scene

Run a selected saved scene

Inspect the installed engine API

Example conversation

Tips