AIC-Project/Client/PackageLocal/com.unity.pipeline@0.4.0-exp.1/Documentation~/commands/gameobjects-and-components.md

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 and Connectivity.