unity-prefab

调用此模块中的任何技能之前： 如果你打算根据技能名称或描述猜测参数后调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，可以直接进行 dryRun。

触发条件

• 创建或编辑预制体
• 实例化预制体或应用预制体改动
• 在场景中查找实例
• 创建预制体变体
• 创建或编辑预制体、实例化或应用预制体改动、在场景中查找实例、创建预制体变体

Unity 预制体技能

优先批量处理：生成 2 个或更多预制体实例时，使用 prefab_instantiate_batch；进行多项资源编辑时，使用资源编辑 _batch API。

操作模式

读取 API（prefab_get_overrides、prefab_find_instances 和四个资源查询 API）为 SemiAuto。写入操作为 FullAuto。删除组件/节点和 prefab_edit_batch 属于 NeverInSemi，因其具有 Delete/高风险元数据。Auto / Bypass 会直接执行；Approval 使用框架授权/许可列表。有关目标定位、批处理和 Undo 语义，请参阅资源编辑。

不要（常见幻觉）：

• prefab_create_from_object 不存在 → 使用 prefab_create（接受场景对象名称/instanceId 和 savePath）
• prefab_spawn 不存在 → 使用 prefab_instantiate
• prefab_edit / prefab_modify 不存在 → 使用 prefab_edit_batch 按顺序直接编辑资源。
• prefab_save 不存在 → 使用 prefab_apply（将实例改动应用到源预制体）

路由：

• 要修改场景中预制体实例上的组件 → 使用 component 模块技能，然后使用 prefab_apply
• 要直接编辑预制体资源 → 使用 ASSET_EDITING.md 中的资源查询/组件/节点 API；从 prefab_get_hierarchy / prefab_list_components 开始，然后使用 prefab_add_component / prefab_set_serialized_property。
• 要保留现有的 prefab_set_property 调用 → 该调用仍受支持，且参数保持不变。
• 要组合对单个资源的编辑 → 使用 prefab_edit_batch；要通过一次操作编辑多个资源 → 使用其 _batch 变体。
• 要查找某个预制体的所有实例 → 使用 prefab_find_instances（本模块）

直接编辑资源

有关四个查询 API、十二个单项写入 API 及其批量版本，以及 prefab_edit_batch，请参阅 ASSET_EDITING.md。gameObjectPath 相对于根节点；componentType/componentIndex 用于标识组件。写入操作只保存指定的资源，包括变体/嵌套覆盖项。

技能概览

单个对象	批处理版本	适合使用批处理的情况
prefab_instantiate	prefab_instantiate_batch	生成 2 个或更多实例

无需批处理：

• prefab_create - 从场景对象创建预制件
• prefab_apply - 将实例更改应用到预制件
• prefab_unpack - 解包预制件实例
• prefab_get_overrides - 获取实例覆盖项
• prefab_revert_overrides - 还原为预制件值
• prefab_apply_overrides - 将覆盖项应用到预制件
• prefab_create_variant - 创建预制件变体
• prefab_find_instances - 在场景中查找预制件的所有实例
• prefab_set_property - 设置 Prefab 资源内部组件的属性（支持基本类型、向量、颜色和资源引用）

资源编辑（参数和返回值见 ASSET_EDITING.md）：

单个操作	批处理
prefab_add_component	prefab_add_component_batch
prefab_remove_component	prefab_remove_component_batch
prefab_set_component_enabled	prefab_set_component_enabled_batch
prefab_set_serialized_property	prefab_set_serialized_property_batch
prefab_create_gameobject	prefab_create_gameobject_batch
prefab_delete_gameobject	prefab_delete_gameobject_batch
prefab_duplicate_gameobject	prefab_duplicate_gameobject_batch
prefab_rename_gameobject	prefab_rename_gameobject_batch
prefab_set_transform	prefab_set_transform_batch
prefab_set_parent	prefab_set_parent_batch
prefab_set_active	prefab_set_active_batch
prefab_set_sibling_index	prefab_set_sibling_index_batch

只读，无批处理版本：prefab_get_info、prefab_get_hierarchy、prefab_list_components、prefab_get_serialized_properties。对单个资源执行一次有序的全有或全无事务：prefab_edit_batch。

---

技能

prefab_create

从场景 GameObject 创建预制件。

参数	类型	必填	描述
name	string	否*	源对象名称
instanceId	int	否*	实例 ID（首选）
path	string	否*	对象路径
savePath	string	是	预制件保存路径；缺少 .prefab 时会自动追加

*必须至少提供一个源标识符。

返回值：{success, prefabPath, name, connected}：prefabPath 是已保存资源的路径，connected 表示场景对象现在是否为该预制件的实例。若 Unity 拒绝保存，则会报错，而非返回成功。

prefab_instantiate

将预制件实例化到场景中。

参数	类型	必填	默认值	描述
prefabPath	string	是	-	预制件资源路径
name	string	否	prefab name	实例名称
x、y、z	float	否	0	局部位置（若设置了父级，则相对于父级）
parentEntityId	string	否	null	父实体 ID（Unity 6000.4+，首选）
parentName	string	否	null	父对象名称
parentInstanceId	int	否	0	父实例 ID
parentPath	string	否	null	父级层级路径

返回值：{success, name, entityId, instanceId, path}

prefab_instantiate_batch

通过一次调用实例化多个预制件。

参数	类型	必填	描述
items	jsonstring	是	实例化配置数组

条目属性：prefabPath、name、x、y、z（局部位置；若设置了父级，则相对于父级）、rotX、rotY、rotZ、scaleX、scaleY、scaleZ、parentEntityId、parentName、parentInstanceId、parentPath

返回值：{success, totalItems, successCount, failCount, results: [{success, name, entityId, instanceId, position, localPosition}]}：position 是读回的世界位置，localPosition 是局部位置。全有或全无：若有一个条目失败，本次调用创建的所有实例都会被移除（rolledBack: true）。

unity_skills.call_skill("prefab_instantiate_batch", items=[
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "x": 0, "z": 0, "name": "Enemy_01"},
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "x": 2, "z": 0, "name": "Enemy_02"},
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "x": 4, "z": 0, "name": "Enemy_03"}
])

prefab_apply

将实例更改应用回预制件资源。

参数	类型	必填	描述
name	string	否*	预制件实例名称
instanceId	int	否*	实例 ID（优先使用）
path	string	否*	对象路径

*至少需要一个标识符。

返回：{success, appliedTo}（appliedTo 为预制件资源路径）

prefab_unpack

解包预制件实例（断开预制件连接）。

参数	类型	必填	默认值	描述
name	string	否*	-	预制件实例名称
instanceId	int	否*	-	实例 ID（优先使用）
path	string	否*	-	对象路径
completely	bool	否	false	解包所有嵌套预制件

*至少需要一个标识符。

返回：{success, unpacked}（unpacked 为实例的 GameObject 名称）

prefab_get_overrides

获取预制件实例属性覆盖的摘要（仅计数，不包含各项覆盖列表）。

参数	类型	必填	描述
name	string	否*	预制件实例名称
instanceId	int	否*	实例 ID

返回：{success, prefabPath, propertyOverrides, addedComponents, removedComponents, addedGameObjects, hasOverrides}——propertyOverrides/addedComponents/removedComponents/addedGameObjects 是计数（int），不是数组；当这些计数中任一项非零时，hasOverrides 为 true。

prefab_revert_overrides

将预制件实例上的所有覆盖还原为预制件值。

参数	类型	必填	描述
name	string	否*	预制件实例名称
instanceId	int	否*	实例 ID

返回：{success, reverted}（reverted 为预制件根对象的 GameObject 名称）

prefab_apply_overrides

将实例上的所有覆盖应用到源预制件资源。

参数	类型	必填	描述
name	string	否*	预制件实例名称
instanceId	int	否*	实例 ID

返回：{success, appliedTo}（appliedTo 为预制件资源路径）

prefab_create_variant

从现有预制件创建预制件变体。

参数	类型	必填	默认值	描述
sourcePrefabPath	string	是	-	源预制件资源的路径
variantPath	string	是	-	新变体的保存路径

返回：{ success, sourcePath, variantPath, name, isVariant }：variantPath 是已保存资源的路径（缺少时会追加 .prefab），isVariant 表示 Unity 是否将其存储为源预制件的变体。

prefab_find_instances

查找当前场景中某个预制件的所有实例。

参数	类型	必填	默认值	描述
prefabPath	string	是	-	要搜索的预制件资源路径
limit	int	否	50	返回的实例最大数量

返回：{ success, prefabPath, count, instances: [{ name, path, entityId, instanceId }] }

prefab_set_property

在 Prefab 资源文件中的组件上设置属性（无需实例化）。支持基本类型、向量、颜色、枚举和资源引用。

参数	类型	必填	默认值	描述
prefabPath	string	是	-	Prefab 资源的路径
componentType	string	是	-	组件类型名称
propertyName	string	是	-	序列化属性名称
value	string	条件必填	null	基本类型（int/float/bool/string/enum/vector/color/quaternion）的值
assetReferencePath	string	条件必填	null	Object 引用字段（Material、Texture、AudioClip、ScriptableObject 等）的资源路径
gameObjectName	string	否	null	Prefab 内部子对象的名称（默认为根对象）

请提供 value（基本类型）或 assetReferencePath（资源引用）之一。

value 支持 Integer、Float、Boolean、String、Enum、Color、Vector2/3/4、Vector2Int/3Int、Quaternion、Rect、Bounds 和 LayerMask。四元数（localRotation）接受 3 个分量作为欧拉角度（"0,90,0"），或 4 个分量作为原始 x,y,z,w 值。bool 的取值为 true/false/1/0/yes/no/on/off（其他值都会被拒绝）。枚举接受名称、显示名称、用于标志的 A,B，或遵循与 component_set_serialized_property 相同规则的数字（0..n-1 = 成员索引；当成员值不同时会发出警告；未声明的位会被拒绝）。其他任何序列化类型都会返回 SEMANTIC_INVALID 并指出类型名称——这是应使用 assetReferencePath 而非重新格式化 value 的信号。

返回： { success, prefabPath, gameObject, component, property, valueSet, valueRequested?, warnings? }：component / property 是解析后的类型名称和序列化路径；valueSet 是保存后从资源中读回的值（序列化形式：枚举读取为其索引，四元数读取为 x,y,z,w；对于 assetReferencePath，则为所引用资源的路径）；仅当存储的值与写入的值不同时（被组件限制，或类型不匹配的引用未被存储），才会出现 valueRequested。

# Set a float property on prefab root
unity_skills.call_skill("prefab_set_property",
    prefabPath="Assets/Prefabs/Enemy.prefab",
    componentType="EnemyStats",
    propertyName="maxHealth",
    value="100"
)

# Assign an asset reference to a prefab component
unity_skills.call_skill("prefab_set_property",
    prefabPath="Assets/Prefabs/Enemy.prefab",
    componentType="AudioSource",
    propertyName="m_audioClip",
    assetReferencePath="Assets/Audio/hit.wav"
)

# Edit a child object inside a prefab
unity_skills.call_skill("prefab_set_property",
    prefabPath="Assets/Prefabs/Player.prefab",
    componentType="MeshRenderer",
    propertyName="m_Materials.Array.data[0]",
    assetReferencePath="Assets/Materials/PlayerSkin.mat",
    gameObjectName="Body"
)

---

示例：高效生成敌人

import unity_skills

# BAD: 10 API calls for 10 enemies
for i in range(10):
    unity_skills.call_skill("prefab_instantiate",
        prefabPath="Assets/Prefabs/Enemy.prefab",
        name=f"Enemy_{i}",
        x=i * 2
    )

# GOOD: 1 API call for 10 enemies
unity_skills.call_skill("prefab_instantiate_batch", items=[
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "name": f"Enemy_{i}", "x": i * 2}
    for i in range(10)
])

最佳实践

1. 将 Prefab 整理到专用文件夹中
2. 对重复对象使用 Prefab
3. 应用更改以更新所有实例
4. 仅在需要进行独特修改时才取消嵌套
5. 使用批量实例化生成关卡

---

精确签名

确切的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。

常见错误

完整的传输层错误代码（COMPILING/RATE_LIMIT 等）→ ../../references/protocol-error-codes.md

错误	触发条件	修复方法
TARGET_NOT_FOUND	找不到 Prefab 资源、源 Prefab、Prefab 内的子 GameObject、组件或资源引用。	使用 asset_find / prefab_find_instances 确认 Prefab 路径，检查子对象/组件名称，并使用准确标识符重试。
MISSING_PARAM	缺少必需参数，例如 savePath、prefabPath、sourcePrefabPath、componentType 或 propertyName。	提供缺少的参数；使用 mode=dryRun 查看完整架构。
SEMANTIC_INVALID	目标不是 Prefab 实例、属性不是 Object 引用字段，或无法解析序列化值。	确保对象是 Prefab 实例（可通过 prefab_get_overrides 验证），匹配属性类型，并使用有效值重试。
SKILL_ERROR	底层操作失败，例如 Failed to instantiate prefab 或 Failed to set value ... (type: ...)。	解决消息中指出的根本原因（例如 Prefab 损坏、类型不匹配），然后重试。