/component

name: unity-component
description: Manage GameObject components

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

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 | | `path` | string | No* | Hierarchy path | | `componentType` | string | Yes | Component type | | `propertyName` | string | Yes | C# property/field name — see the serialized-name note below | | `value` | string | Cond. | New value (basic types, vectors, colors, enums) — wire format below | | `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.) |

**Which of the four value parameters to use** — exactly one carries the payload, and they are checked in this order: `assetPath` first, then `referencePath` / `referenceName`, and `value` only if neither reference form was supplied. So a `value` sent alongside an `assetPath` is silently ignored; never send two.

| Use | When the target field is | Example | |---|---|---| | `value` | a primitive, vector, colour, enum, `LayerMask`, `Rect`, `Bounds`, `Quaternion` | `value="2.5"`, `value="Interpolate"` | | `referencePath` | a scene object, addressed by hierarchy path (unambiguous) | `referencePath