/gameobject

name: unity-gameobject
description: Create and manipulate GameObjects. 创建与操控 GameObject。

Triggers

• Building or restructuring scene hierarchy
• Spawning or removing objects
• Adjusting transforms
• 搭建或调整场景层级、新建或删除物体、修改 Transform

Unity GameObject Skills

> **BATCH-FIRST**: Use `*_batch` skills when operating on 2+ objects to reduce API calls from N to 1.

Operating Mode

• **Approval**：本模块多为 `SkillMode.FullAuto`，调用需用户 grant；grant 后服务端一步执行并返结果。
• **Auto / Bypass**：直接执行。
• **含 NeverInSemi 高危 skill**：`gameobject_delete` / `gameobject_delete_batch`（标记 Operation.Delete）。这些在 Approval/Auto 下返 `MODE_FORBIDDEN`，仅 Bypass 或用户 Allowlist 命中可调。

**DO NOT** (common hallucinations):

• `gameobject_move` / `gameobject_rotate` / `gameobject_set_scale` do not exist → use `gameobject_set_transform` (handles position, rotation, and scale together)
• `gameobject_set_position` does not exist → use `gameobject_set_transform` with `posX/posY/posZ`
• `gameobject_add_component` does not exist → use `component_add` (component module)
• `gameobject_get_transform` does not exist → use `gameobject_get_info` (returns position/rotation/scale)

**Routing**:

• To add/remove components → use `component` module
• To set material/color → use `material` module
• To search objects by name/tag/component → `gameobject_find` (this module) or `scene_find_objects` (scene module, SkillMode.SemiAuto)

> **Object Targeting**: All single-object skills accept `entityId` (string, Unity 6000.4+ preferred — returned by all object skills), `name` (string), `instanceId` (int, Unity < 6000.4 preferred), and `path` (string, hierarchy path like "Parent/Child"). Provide at least one. Priority: `entityId > instanceId > path > name`. On Unity 6000.4+ use `entityId` — `instanceId` is reported as `0`. When only `name` is shown in a parameter table, `entityId`, `instanceId`, and `path` are also accepted.

Skills Overview

| Single Object | Batch Version | Use Batch When | |---------------|---------------|----------------| | `gameobject_create` | `gameobject_create_batch` | Creating 2+ objects | | `gameobject_delete` | `gameobject_delete_batch` | Deleting 2+ objects | | `gameobject_duplicate` | `gameobject_duplicate_batch` | Duplicating 2+ objects | | `gameobject_rename` | `gameobject_rename_batch` | Renaming 2+ objects | | `gameobject_set_transform` | `gameobject_set_transform_batch` | Moving 2+ objects | | `gameobject_set_active` | `gameobject_set_active_batch` | Toggling 2+ objects | | `gameobject_set_parent` | `gameobject_set_parent_batch` | Parenting 2+ objects | | - | `gameobject_set_layer_batch` | Setting layer on 2+ objects | | - | `gameobject_set_tag_batch` | Setting tag on 2+ objects |

**Query Skills** (no batch needed):

• `gameobject_find` - Find objects by name/tag/layer/component
• `gameobject_get_info` - Get detailed object information

---

Single-Object Skills

gameobject_create

Create a new GameObject (primitive or empty).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | Yes | - | Object name | | `primitiveType` | string | No | null | Cube/Sphere/Capsule/Cylinder/Plane/Quad (null=Empty) | | `x`, `y`, `z` | float | No | 0 | Local position (relative to parent if set) | | `parentEntityId` | string | No | null | Parent entityId (Unity 6000.4+, preferred) | | `parentName` | string | No | null | Parent object name | | `parentInstanceId` | int | No | 0 | Parent instance ID | | `parentPath` | string | No | null | Parent hierarchy path |

**Returns**: `{success, name, entityId, instanceId, path, parent, position}`

gameobject_delete

Delete a GameObject.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `entityId` | string | No* | Entity ID (Unity 6000.4+, preferred) | | `name` | string | No* | Object name | | `instanceId` | int | No* | Instance ID | | `path` | string | No* | Hierarchy path |

*At least one identifier required

gameobject_duplicate

Duplicate a GameObject.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `entityId` | string | No* | Entity ID (Unity 6000.4+, preferred) | | `name` | string | No* | Object name | | `instanceId` | int | No* | Instance ID | | `path` | string | No* | Hierarchy path |

**Returns**: `{originalName, copyName, copyEntityId, copyInstanceId, copyPath}`

gameobject_rename

Rename a GameObject.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `entityId` | string | No* | Entity ID (Unity 6000.4+, preferred) | | `name` | string | No* | Current object name | | `instanceId` | int | No* | Instance ID | | `newName` | string | Yes | New name |

**Returns**: `{success, oldName, newName, entityId, instanceId}`

gameobject_find

Find GameObjects matching criteria.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | No | null | Name filter | | `tag` | string | No | null | Tag filter | | `layer` | string | No | null | Layer filter | | `component` | string | No | null | Component type filter | | `useRegex` | bool | No | false | Use regex for name | | `limit` | int | No | 50 | Max results |

**Returns**: `{count, objects: [{name, entityId, instanceId, path, tag, layer, position}]}`

gameobject_get_info

Get detailed GameObject information.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `entityId` | string | No* | Entity ID (Unity 6000.4+, preferred) | | `name` | string | No* | Object name | | `instanceId` | int | No* | Instance ID | | `path` | string | No* | Hierarchy path |

**Returns**: `{name, entityId, instanceId, path, tag, layer, active, position, rotation, scale, parent, parentPath, childCount, children: [{name, entityId, instanceId, path}], components}`

gameobject_set_transform

Set position, rotation, and/or scale. Supports