/component

name: unity-component
description: Manage GameObject components. 管理 GameObject 组件。

Triggers

• Attaching or removing components
• Copying components between objects
• Toggling components
• Reading/writing serialized fields
• 挂载或移除组件、在对象间复制组件、开关组件、读写序列化字段

Unity Component Skills

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

Operating Mode

• **Approval**：本模块 Mixed —— `component_list` / `component_get_properties` 标 `SkillMode.SemiAuto`，可直接执行；写类 skill (`component_add` / `component_set_property` / `component_set_enabled` / `component_copy` 等) 标 `SkillMode.FullAuto`，需 grant 单次执行返结果。
• **Auto / Bypass**：FullAuto 直接执行。
• **含 NeverInSemi 高危 skill**：`component_remove` / `component_remove_batch`（Operation.Delete）。这些在 Approval/Auto 下返 `MODE_FORBIDDEN`，仅 Bypass 或 Allowlist 命中可调。

**DO NOT** (common hallucinations):

• `component_create` / `component_get` do not exist → use `component_add` (add) and `component_get_properties` (read)
• `component_find` does not exist → use `component_list` to list components on an object
• `componentType` is case-sensitive — `Rigidbody` not `rigidbody`, `BoxCollider` not `boxcollider`
• Custom scripts need exact class name; if namespaced, use `Namespace.ClassName`

**Routing**:

• To create a C# component script → use `script` module's `script_create` first, then `component_add`
• To set multiple properties at once → use `component_set_property_batch`
• To enable/disable a component → `component_set_enabled` (not `component_set_property`)

> **Object Targeting**: All single-object skills accept `name` (string), `instanceId` (int, preferred), and `path` (string, hierarchy path). Provide at least one.

Skills Overview

| Single Object | Batch Version | Use Batch When | |---------------|---------------|----------------| | `component_add` | `component_add_batch` | Adding to 2+ objects | | `component_remove` | `component_remove_batch` | Removing from 2+ objects | | `component_set_property` | `component_set_property_batch` | Setting on 2+ objects | | `component_set_serialized_property` | `component_set_serialized_property_batch` | Setting Inspector SerializedProperty paths |

**Other Skills** (no batch):

• `component_list` - List all components on an object
• `component_get_properties` - Get component property values
• `component_set_enabled` - Enable/disable a component (Behaviour, Renderer, Collider)
• `component_copy` - Copy a component from one object to another
• `component_get_serialized_properties` - List Inspector SerializedProperty paths
• `component_copy_exact` - Copy a component and verify serialized fields match

---

Single-Object Skills

component_add

Add a component to a GameObject.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No* | GameObject name | | `instanceId` | int | No* | Instance ID (preferred) | | `path` | string | No* | Hierarchy path | | `componentType` | string | Yes | Component type name |

*At least one identifier required

**Returns**: `{success, gameObject, instanceId, component, fullTypeName}` (returns `{warning, gameObject, instanceId}` instead if a single-instance component already exists)

component_remove

Remove a component from a GameObject.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | No* | - | GameObject name | | `instanceId` | int | No* | - | Instance ID | | `path` | string | No* | - | Hierarchy path | | `componentType` | string | Yes | - | Component type to remove | | `componentIndex` | int | No | 0 | Index into the components of that type when 2+ exist on the same object |

**Returns**: `{success, gameObject, removed}` (`removed` is the requested `componentType` string)

component_list

List all components on a GameObject.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No* | GameObject name | | `instanceId` | int | No* | Instance ID |

**Returns**: `{gameObject, instanceId, path, componentCount, components: [{type, fullType, enabled, keyProperties?}]}` (`keyProperties` only present when `includeProperties=true`)

component_set_property

Set a component property value.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No* | GameObject name | | `instanceId` | int | No* | Instance ID | | `componentType` | string | Yes | Component type | | `propertyName` | string | Yes | Property to set | | `value` | any | Cond. | New value (for basic types, vectors, colors) | | `referencePath` | string | No | Scene object hierarchy path (for scene references) | | `referenceName` | string | No | Scene object name (for scene references) | | `assetPath` | string | No | Project asset path (for asset references: Material, Texture, AudioClip, ScriptableObject, Prefab, etc.) |

> Provide one of: `value` (basic types), `referencePath`/`referenceName` (scene objects), or `assetPath` (project assets).

**`value` type examples**:

# float / int / bool / string
call_skill("component_set_property", name="Obj", componentType="Rigidbody", propertyName="mass", value=2.5)
call_skill("component_set_property", name="Obj", componentType="Rigidbody", propertyName="useGravity", value=False)

# Vector3 (JSON object with x, y, z)
call_skill("component_set_property", name="Obj", componentType="Transform", propertyName="localPosition",
           value={"x": 1, "y": 2, "z": 3})

# Color (JSON object with r, g, b, a — values 0-1)
call_skill("component_set_property", name="Obj", componentType="Light", propertyName="color",
           value={"r": 1, "g": 0.5, "b": 0, "a": 1})

# Enum (use string name)
call_skill("component_set_property", name="Obj", componentType="Rigidbody", propertyName="interpolation",
           value="Interpolate")

**Returns**: `{success, gameObject, component, property, valu