unity-component

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity Component Skills

Unity 组件技能

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

优先批量操作：当操作2个及以上对象时，使用
*_batch
技能，可将API调用次数从N次减少到1次。

Guardrails

约束规则

Mode: Full-Auto required

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.

模式：需设置为全自动模式

禁止操作（常见错误）：

不存在

component_create

component_get

→ 使用

component_add

（添加）和

component_get_properties

（读取）

不存在
```
component_find
```
→ 使用
```
component_list
```
列出对象上的所有组件

componentType

区分大小写 — 需写

Rigidbody

而非

rigidbody

，

BoxCollider

而非

boxcollider

自定义脚本需使用精确类名；若包含命名空间，使用
```
Namespace.ClassName
```
格式

路由指引：

若要创建C#组件脚本 → 先使用
```
script
```
模块的
```
script_create
```
，再调用
```
component_add
```
若要一次性设置多个属性 → 使用
```
component_set_property_batch
```
若要启用/禁用组件 → 使用
```
component_set_enabled
```
（而非
```
component_set_property
```
）

对象定位：所有单对象技能支持
name
（字符串）、
instanceId
（整数，推荐使用）和
path
（字符串，层级路径）作为参数。至少需提供其中一个。

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

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_add`	`component_add_batch`	给2个及以上对象添加组件时
`component_remove`	`component_remove_batch`	从2个及以上对象移除组件时
`component_set_property`	`component_set_property_batch`	给2个及以上对象设置属性时

其他技能（无批量版本）：

```
component_list
```
- 列出对象上的所有组件
```
component_get_properties
```
- 获取组件的属性值
```
component_set_enabled
```
- 启用/禁用组件（Behaviour、Renderer、Collider类型）
```
component_copy
```
- 将组件从一个对象复制到另一个对象

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, componentType, added}

给GameObject添加组件。

参数	类型	是否必填	描述
`name`	string	否*	GameObject名称
`instanceId`	int	否*	实例ID（推荐使用）
`path`	string	否*	层级路径
`componentType`	string	是	组件类型名称

*至少需提供一个标识符

返回值：

{success, gameObject, componentType, added}

component_remove

Remove a component from a GameObject.

Parameter	Type	Required	Description
`name`	string	No*	GameObject name
`instanceId`	int	No*	Instance ID
`componentType`	string	Yes	Component type to remove

Returns:

{success, gameObject, componentType, removed}

从GameObject移除组件。

参数	类型	是否必填	描述
`name`	string	否*	GameObject名称
`instanceId`	int	否*	实例ID
`componentType`	string	是	要移除的组件类型

返回值：

{success, gameObject, componentType, removed}

component_list

List all components on a GameObject.

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

Returns:

{success, gameObject, instanceId, components: [string]}

列出GameObject上的所有组件。

参数	类型	是否必填	描述
`name`	string	否*	GameObject名称
`instanceId`	int	否*	实例ID

返回值：

{success, gameObject, instanceId, components: [string]}

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:

python

undefined

设置组件的属性值。

参数	类型	是否必填	描述
`name`	string	否*	GameObject名称
`instanceId`	int	否*	实例ID
`componentType`	string	是	组件类型
`propertyName`	string	是	要设置的属性名称
`value`	any	可选	新值（支持基本类型、向量、颜色）
`referencePath`	string	否	场景对象层级路径（用于场景引用）
`referenceName`	string	否	场景对象名称（用于场景引用）
`assetPath`	string	否	项目资源路径（用于资源引用：Material、Texture、AudioClip、ScriptableObject、Prefab等）

需提供以下其中一种：
value
（基本类型）、
referencePath
/
referenceName
（场景对象）、
assetPath
（项目资源）。

value
类型示例：

python

undefined

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)

Vector3（包含x、y、z的JSON对象）

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)

Color（包含r、g、b、a的JSON对象，值范围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, componentType, property, oldValue, newValue}`

call_skill("component_set_property", name="Obj", componentType="Rigidbody", propertyName="interpolation", value="Interpolate")


**返回值**：`{success, gameObject, componentType, property, oldValue, newValue}`

component_get_properties

Get all properties of a component.

Parameter	Type	Required	Description
`name`	string	No*	GameObject name
`instanceId`	int	No*	Instance ID
`componentType`	string	Yes	Component type

Returns:

{success, gameObject, componentType, properties: {name: value}}

获取组件的所有属性。

参数	类型	是否必填	描述
`name`	string	否*	GameObject名称
`instanceId`	int	否*	实例ID
`componentType`	string	是	组件类型

返回值：

{success, gameObject, componentType, properties: {name: value}}

Batch Skills

批量技能

component_add_batch

Add components to multiple objects.

Returns:

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

python

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

给多个对象添加组件。

返回值：

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

python

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.

Returns:

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

python

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

从多个对象移除组件。

返回值：

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

python

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.

Returns:

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

python

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}
])

给多个对象设置属性。

返回值：

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

python

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}
])

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

类型	描述
`Rigidbody`	物理模拟
`BoxCollider`	盒型碰撞体
`SphereCollider`	球形碰撞体
`CapsuleCollider`	胶囊型碰撞体
`MeshCollider`	基于网格的碰撞体
`CharacterController`	角色移动控制

Rendering

渲染类

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

类型	描述
`MeshRenderer`	渲染网格
`SkinnedMeshRenderer`	渲染带动画的网格
`SpriteRenderer`	渲染2D精灵
`LineRenderer`	绘制线条
`TrailRenderer`	绘制运动轨迹

Audio

音频类

Type	Description
`AudioSource`	Play sounds
`AudioListener`	Receive audio

类型	描述
`AudioSource`	播放声音
`AudioListener`	接收音频

UI

UI类

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

类型	描述
`Canvas`	UI容器
`Image`	UI图片
`Text`	UI文本（旧版）
`Button`	可点击按钮

Example: Efficient Physics Setup

示例：高效物理设置

python

import unity_skills

python

import unity_skills

BAD: 6 API calls

不推荐：6次API调用

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

推荐：2次API调用

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} ])

undefined

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} ])

undefined

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")

为物理组件添加碰撞体时，先添加Collider再添加Rigidbody
使用
```
component_list
```
验证组件是否添加成功
设置属性前，先用
```
component_get_properties
```
确认属性名称
部分属性为只读（设置会失败）
自定义脚本需使用完整类型名（例如："MyNamespace.MyScript"）

Additional Skills

额外技能

component_copy

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 }

将组件从一个GameObject复制到另一个GameObject。

参数	类型	是否必填	默认值	描述
`sourceName`	string	否*	null	源GameObject名称
`sourceInstanceId`	int	否*	0	源实例ID
`sourcePath`	string	否*	null	源层级路径
`targetName`	string	否*	null	目标GameObject名称
`targetInstanceId`	int	否*	0	目标实例ID
`targetPath`	string	否*	null	目标层级路径
`componentType`	string	是	-	要复制的组件类型

*至少需提供一个源标识符和一个目标标识符

返回值：

{ success, source, target, componentType }

component_set_enabled

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

*At least one identifier required

Returns:

{ success, gameObject, componentType, enabled }

启用或禁用组件（Behaviour、Renderer、Collider等类型）。

参数	类型	是否必填	默认值	描述
`name`	string	否*	null	GameObject名称
`instanceId`	int	否*	0	实例ID
`path`	string	否*	null	层级路径
`componentType`	string	是	-	要启用/禁用的组件类型
`enabled`	bool	否	true	是否启用组件

*至少需提供一个标识符

返回值：

{ success, gameObject, componentType, enabled }

Exact Signatures

精确签名

Exact names, parameters, defaults, and returns are defined by

GET /skills/schema

unity_skills.get_skill_schema()

, not by this file.

精确的名称、参数、默认值和返回值由

GET /skills/schema

或

unity_skills.get_skill_schema()

定义，而非本文档。