3.9 KiB
Scene commands
Commands for creating, opening, saving and inspecting scenes, controlling the active scene, snapshotting a scene's hierarchy, and managing the Build Settings scene list. Mutating scene operations are blocked while the editor is entering or in play mode (they fail with a recoverable error before touching any state); read-only commands are safe in play mode.
create_scene
Create a new scene and save it to the given path under the authoring root.
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
yes | – | Scene path relative to the authoring root (default Assets/); the Assets/ prefix and the .unity extension are optional. e.g. Scenes/Level1 |
additive |
no | false |
Open the new scene additively alongside currently open scenes instead of replacing them. |
template |
no | empty |
Initial contents: 'empty' (default) for a blank scene, or 'default' to seed a Main Camera + Directional Light matching Unity's built-in 3D template. |
Returns: AuthoringResult
Notes: Blocked during Play mode.
open_scene
Open an existing scene from the given path.
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
yes | – | Scene path relative to the authoring root (default Assets/); the Assets/ prefix and the .unity extension are optional. |
additive |
no | false |
Open additively alongside currently open scenes instead of replacing them. |
Returns: AuthoringResult
Notes: Blocked during Play mode.
save_scene
Save an open scene. Saves the active scene when no path is given.
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
no | – |
Path of the open scene to save (authoring-root relative; Assets/ prefix and .unity optional). Omit to save the active scene. |
Returns: AuthoringResult
Notes: Blocked during Play mode.
save_all
Save all open scenes that have unsaved changes.
No parameters.
Returns: object
Notes: Blocked during Play mode.
list_open_scenes
List all currently open scenes with their load/active/dirty state.
No parameters.
Returns: object
set_active_scene
Set which open scene is the active scene (new objects are created in the active scene).
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
yes | – | Path of an already-open scene to make active (authoring-root relative; Assets/ prefix and .unity optional). |
Returns: AuthoringResult
Notes: Blocked during Play mode.
get_scene_hierarchy
Return the GameObject tree of an open scene (or the active scene). Each node carries instanceId + hierarchyPath usable by GameObject commands.
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
no | – |
Path of the open scene to snapshot (authoring-root relative; Assets/ prefix and .unity optional). Omit for the active scene. |
Returns: SceneHierarchy
add_scene_to_build
Add a scene to the Build Settings scene list (idempotent). Optionally enable it.
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
yes | – | Scene path to add (authoring-root relative; Assets/ prefix and .unity optional). |
enabled |
no | true |
Whether the scene is enabled in the build list. |
Returns: object
Notes: Blocked during Play mode.
remove_scene_from_build
Remove a scene from the Build Settings scene list (idempotent).
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
yes | – | Scene path to remove (authoring-root relative; Assets/ prefix and .unity optional). |
Returns: object
Notes: Blocked during Play mode.
See Creating commands and Connectivity.