85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
# Prefab commands
|
||
|
||
Commands covering the prefab lifecycle an agent needs to build content procedurally: saving a configured GameObject as a prefab asset, instantiating it into a scene, deriving a variant, applying/reverting instance overrides, unpacking, and editing prefab contents through the prefab stage. Asset paths are sandboxed to the authoring root; scene-side mutations are Undo-able, but prefab asset writes are AssetDatabase operations and are not part of Unity's Undo system.
|
||
|
||
### `create_prefab`
|
||
Save a GameObject as a prefab asset at a project path; the source becomes a connected instance.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `source` | yes | – | Reference to the source GameObject to save as a prefab (globalId/path/guid/instanceId/hierarchyPath). |
|
||
| `path` | yes | – | Prefab asset path relative to the authoring root (the Assets/ prefix is optional and the .prefab extension is added if missing). e.g. Prefabs/Enemy or Prefabs/Enemy.prefab |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Scene-side effects are Undo-able; the prefab asset write is not undoable.
|
||
|
||
### `instantiate_prefab`
|
||
Instantiate a prefab asset into a loaded scene and return the created instance.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `prefab` | yes | – | Reference to the prefab asset to instantiate (path/guid/globalId). |
|
||
| `scene_path` | no | `–` | Optional path of a loaded scene to instantiate into; defaults to the active scene. |
|
||
| `name` | no | `–` | Optional name for the created instance; defaults to the prefab name. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able.
|
||
|
||
### `create_prefab_variant`
|
||
Create a prefab variant asset that inherits from a base prefab.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `base` | yes | – | Reference to the base prefab asset (path/guid/globalId). |
|
||
| `path` | yes | – | Variant prefab asset path relative to the authoring root (.prefab added if missing). |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Prefab asset write is not undoable.
|
||
|
||
### `apply_prefab_overrides`
|
||
Apply a prefab instance's overrides back to its source prefab asset.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `instance` | yes | – | Reference to a prefab instance GameObject in a scene (instanceId/hierarchyPath/globalId). |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Scene-side effects are Undo-able; the asset write is not. The instance's source prefab asset must live under the authoring root.
|
||
|
||
### `revert_prefab_overrides`
|
||
Revert a prefab instance's overrides so it matches its source prefab asset.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `instance` | yes | – | Reference to a prefab instance GameObject in a scene (instanceId/hierarchyPath/globalId). |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able.
|
||
|
||
### `unpack_prefab`
|
||
Unpack a prefab instance into plain GameObjects (outermost level or completely).
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `instance` | yes | – | Reference to a prefab instance GameObject in a scene (instanceId/hierarchyPath/globalId). |
|
||
| `completely` | no | `false` | If true, unpack all nested prefab levels (Completely); if false, only the outermost level (OutermostRoot). |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able.
|
||
|
||
### `save_prefab_contents`
|
||
Open a prefab asset in an isolated prefab stage, apply a declarative edit, and save it back (nested-prefab safe).
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `prefab` | yes | – | Reference to the prefab asset to edit (path/guid/globalId). |
|
||
| `rename_child` | no | `–` | Optional child name (relative path under the root, e.g. 'Body/Head') to rename. |
|
||
| `new_name` | no | `–` | New name for the child identified by rename_child. |
|
||
| `set_active_child` | no | `–` | Optional child name (relative path under the root) whose active state to set. |
|
||
| `active` | no | `true` | Active state to apply when set_active_child is provided. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Prefab asset write (prefab-stage save) is not part of Unity's Undo system. The prefab asset must live under the authoring root.
|
||
|
||
See [Creating commands](../creating-commands.md) and [Connectivity](../connectivity.md).
|