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, valueSet, valueType} (valueSet is the string form of the actual value applied; valueType is the resolved target type name)

component_get_properties

Get all properties of a component.

Returns: {gameObject, component, fullTypeName, properties: [{name, type, fullType, value, canWrite}], fields: [{name, type, fullType, value, isSerializable}]}

component_get_serialized_properties

List Inspector serialized properties on a component via SerializedObject.

Returns: {success, gameObject, component, fullTypeName, properties}

component_set_serialized_property

Set an Inspector serialized property by propertyPath.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | No* | GameObject name | | instanceId | int | No* | Instance ID | | path | string | No* | Hierarchy path | | componentType | string | Yes | Component type | | propertyPath | string | Yes | SerializedProperty path, e.g. items.Array.data[0] | | value | string | Cond. | Primitive/vector/color/enum value | | referenceName | string | No | Scene object name for ObjectReference | | referenceInstanceId | int | No | Scene object instance ID for ObjectReference | | referencePath | string | No | Scene object path for ObjectReference | | assetPath | string | No | Project asset path for ObjectReference | | objectType | string | No | Expected object/component type for references |

Provide value for scalar properties, or a scene/project reference for ObjectReference fields.

Returns: {success, gameObject, component, propertyPath, valueSet}

Batch Skills

component_add_batch

Add components to multiple objects. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | items | json string | Yes | - | JSON array of per-item objects (see example below) |

Returns: {success, totalItems, successCount, failCount, results: [{success, gameObject, componentType, added}]}

unity_skills.call_skill("component_add_batch", items=[
    {"name": "Enemy1", "componentType": "Rigidbody"},
    {"name": "Enemy2", "componentType": "Rigidbody"},
    {"name": "Enemy3", "componentType": "Rigidbody"}
])

component_remove_batch

Remove components from multiple objects. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | items | json string | Yes | - | JSON array of per-item objects (see example below) |

Returns: {success, totalItems, successCount, failCount, results: [{success, gameObject, componentType, removed}]}

unity_skills.call_skill("component_remove_batch", items=[
    {"instanceId": 12345, "componentType": "BoxCollider"},
    {"instanceId": 12346, "componentType": "BoxCollider"}
])

component_set_property_batch

Set properties on multiple objects. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | items | json string | Yes | - | JSON array of per-item objects (see example below) |

Returns: {success, totalItems, successCount, failCount, results: [{success, gameObject, componentType, property, oldValue, newValue}]}

unity_skills.call_skill("component_set_property_batch", items=[
    {"name": "Enemy1", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Enemy2", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0}
])

component_set_serialized_property_batch

Set Inspector serialized properties on multiple components. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | items | json string | Yes | - | JSON array of per-item objects |

Item properties: name, instanceId, path, componentType, propertyPath, value, referenceName, referenceInstanceId, referencePath, assetPath, objectType

Returns: {success, totalItems, successCount, failCount, results}

Common Component Types

Physics

| Type | Description | |------|-------------| | Rigidbody | Physics simulation | | BoxCollider | Box collision | | SphereCollider | Sphere collision | | CapsuleCollider | Capsule collision | | MeshCollider | Mesh-based collision | | CharacterController | Character movement |

Rendering

| Type | Description | |------|-------------| | MeshRenderer | Render meshes | | SkinnedMeshRenderer | Animated meshes | | SpriteRenderer | 2D sprites | | LineRenderer | Draw lines | | TrailRenderer | Motion trails |

Audio

| Type | Description | |------|-------------| | AudioSource | Play sounds | | AudioListener | Receive audio |

UI

| Type | Description | |------|-------------| | Canvas | UI container | | Image | UI images | | Text | UI text (legacy) | | Button | Clickable button |

Example: Efficient Physics Setup

import unity_skills

# BAD: 6 API calls
unity_skills.call_skill("component_add", name="Box1", componentType="Rigidbody")
unity_skills.call_skill("component_add", name="Box2", componentType="Rigidbody")
unity_skills.call_skill("component_add", name="Box3", componentType="Rigidbody")
unity_skills.call_skill("component_set_property", name="Box1", componentType="Rigidbody", propertyName="mass", value=2.0)
unity_skills.call_skill("component_set_property", name="Box2", componentType="Rigidbody", propertyName="mass", value=2.0)
unity_skills.call_skill("component_set_property", name="Box3", componentType="Rigidbody", propertyName="mass", value=2.0)

# GOOD: 2 API calls
unity_skills.call_skill("component_add_batch", items=[
    {"name": "Box1", "componentType": "Rigidbody"},
    {"name": "Box2", "componentType": "Rigidbody"},
    {"name": "Box3", "componentType": "Rigidbody"}
])
unity_skills.call_skill("component_set_property_batch", items=[
    {"name": "Box1", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Box2", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Box3", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0}
])

Best Practices

Add colliders before Rigidbody for physics
Use component_list to verify additions
Check property names with component_get_properties first
Some properties are read-only (will fail to set)
Use full type names for custom scripts (e.g., "MyNamespace.MyScript")

Additional Skills

`component_copy`

Copy a component from one GameObject to another.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | sourceName | string | No* | null | Source GameObject name | | sourceInstanceId | int | No* | 0 | Source Instance ID | | sourcePath | string | No* | null | Source hierarchy path | | targetName | string | No* | null | Target GameObject name | | targetInstanceId | int | No* | 0 | Target Instance ID | | targetPath | string | No* | null | Target hierarchy path | | componentType | string | Yes | - | Component type to copy |

*At least one source identifier and one target identifier required

Returns: { success, source, target, componentType }

`component_copy_exact`

Copy a component from one GameObject to another and verify serialized Inspector fields match.

Returns: { success, source, target, componentType, verified, mismatchCount, mismatches? }

`component_set_enabled`

Enable or disable a component (Behaviour, Renderer, Collider, etc.).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | name | string | No* | null | GameObject name | | instanceId | int | No* | 0 | Instance ID | | path | string | No* | null | Hierarchy path | | componentType | string | Yes | - | Component type to enable/disable | | enabled | bool | No | true | Whether to enable or disable |