170 lines
8.2 KiB
Markdown
170 lines
8.2 KiB
Markdown
# GameObject & component commands
|
||
|
||
Commands for creating GameObjects, querying the scene hierarchy, mutating the core GameObject/Transform surface, and adding/removing components and editing their serialized properties. Scene mutations are wrapped in Unity's Undo system (so a multi-step action reverts as one collapsible step) and are blocked during Play mode. Objects are referenced by an `ObjectRef` handle (globalId/path/guid/instanceId/hierarchyPath), and results come back as `AuthoringResult` identities you can chain into a follow-up call.
|
||
|
||
### `create_gameobject`
|
||
Create an empty GameObject or a built-in primitive (cube/sphere/capsule/cylinder/plane/quad) in the active scene.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `name` | no | `–` | Name for the new GameObject. Defaults to 'GameObject' (or the primitive name). |
|
||
| `primitive` | no | `–` | Optional primitive type: cube, sphere, capsule, cylinder, plane, quad. Omit for an empty GameObject. |
|
||
| `parent` | no | `–` | Optional parent handle (globalId/path/guid/instanceId/hierarchyPath). The new object becomes a child of it. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `create_gameobjects`
|
||
Batch-create N empty GameObjects or primitives in one call. Optional positions/rotations/scales are arrays of [x,y,z] (length must equal count). Returns the created identities.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `name` | no | `–` | Base name. With count>1 and no explicit names, objects are suffixed Name1..NameN. |
|
||
| `primitive` | no | `–` | Optional primitive type: cube, sphere, capsule, cylinder, plane, quad. Omit for empty GameObjects. |
|
||
| `parent` | no | `–` | Optional parent handle. Every created object becomes a child of it. |
|
||
| `count` | no | `1` | How many GameObjects to create. Default 1. |
|
||
| `positions` | no | `–` | Local positions, one [x,y,z] per object. Length must equal count when supplied. |
|
||
| `rotations` | no | `–` | Local Euler rotations (degrees), one [x,y,z] per object. Length must equal count when supplied. |
|
||
| `scales` | no | `–` | Local scales, one [x,y,z] per object. Length must equal count when supplied. |
|
||
|
||
**Returns:** `CreateGameObjectsResult`
|
||
**Notes:** Undo-able (the whole batch reverts as one step); blocked during Play mode.
|
||
|
||
### `find_gameobjects`
|
||
Find GameObjects in loaded scenes by name, tag, component type, and/or hierarchy path (filters are combined). Returns structured identities.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `name` | no | `–` | Exact name to match. |
|
||
| `tag` | no | `–` | Tag to match (e.g. 'Player'). |
|
||
| `type` | no | `–` | Component type name to match (e.g. 'Rigidbody', 'UnityEngine.Camera'). |
|
||
| `hierarchy_path` | no | `–` | Exact hierarchy path to match (e.g. '/Root/Child'). |
|
||
| `include_inactive` | no | `true` | Include inactive GameObjects. Default true. |
|
||
|
||
**Returns:** `FindGameObjectsResult`
|
||
|
||
### `set_transform`
|
||
Set a GameObject's local position/rotation(euler)/scale. Omitted channels are left unchanged.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject to modify. |
|
||
| `position` | no | `–` | Local position as [x,y,z]. |
|
||
| `rotation` | no | `–` | Local rotation as Euler angles [x,y,z] in degrees. |
|
||
| `scale` | no | `–` | Local scale as [x,y,z]. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `set_parent`
|
||
Reparent a GameObject under a new parent, or detach it to scene root when no parent is given.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject to reparent. |
|
||
| `parent` | no | `–` | Handle of the new parent. Omit (or empty) to move the object to the scene root. |
|
||
| `world_position_stays` | no | `true` | Keep the object's world position when reparenting. Default true. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `set_active`
|
||
Set a GameObject's active self-state (activeSelf).
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject. |
|
||
| `active` | yes | – | Desired active state. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `set_tag`
|
||
Set a GameObject's tag (the tag must already exist in the project).
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject. |
|
||
| `tag` | yes | – | Tag to assign (must exist in the Tag Manager). |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `set_layer`
|
||
Set a GameObject's layer by name or numeric index (0-31).
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject. |
|
||
| `layer` | yes | – | Layer name (e.g. 'UI') or numeric index 0-31. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `rename_gameobject`
|
||
Rename a GameObject.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject. |
|
||
| `name` | yes | – | New name. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `delete_gameobject`
|
||
Delete a GameObject from the scene (reversible via Undo).
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject to delete. |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode. The result describes the object's identity captured before destruction.
|
||
|
||
### `add_component`
|
||
Add a component (by type name) to a GameObject.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the GameObject. |
|
||
| `type` | yes | – | Component type name (e.g. 'Rigidbody' or 'UnityEngine.Camera'). |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `remove_component`
|
||
Remove a component from a GameObject. Provide either a component handle (target) or a GameObject handle (target) plus a type name.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the component to remove, OR of the GameObject when 'type' is given. |
|
||
| `type` | no | `–` | Component type name to remove from the target GameObject (omit when 'target' already points at a component). |
|
||
|
||
**Returns:** `AuthoringResult`
|
||
**Notes:** Undo-able; blocked during Play mode.
|
||
|
||
### `get_component_properties`
|
||
Get a component's serialized properties as a JSON map. Address the component by handle, or by GameObject handle + type.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the component, OR of the GameObject when 'type' is given. |
|
||
| `type` | no | `–` | Component type name on the target GameObject (omit when 'target' is a component handle). |
|
||
|
||
**Returns:** `ComponentPropertiesResult`
|
||
|
||
### `set_component_properties`
|
||
Set serialized properties on a component (one Undo step). 'properties' maps property name -> value; object references accept an ObjectRef handle.
|
||
|
||
| Parameter | Required | Default | Description |
|
||
|-----------|----------|---------|-------------|
|
||
| `target` | yes | – | Handle of the component, OR of the GameObject when 'type' is given. |
|
||
| `properties` | yes | – | Map of serialized property name to value. Vectors/colors are arrays; object refs are handle objects. |
|
||
| `type` | no | `–` | Component type name on the target GameObject (omit when 'target' is a component handle). |
|
||
|
||
**Returns:** `ComponentPropertiesResult`
|
||
**Notes:** Undo-able (one Undo step); blocked during Play mode. An unknown property name fails the whole batch (no partial apply).
|
||
|
||
See [Creating commands](../creating-commands.md) and [Connectivity](../connectivity.md).
|