94 lines
3.9 KiB
Markdown
94 lines
3.9 KiB
Markdown
# 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](../creating-commands.md) and [Connectivity](../connectivity.md).
|