unity-prefab

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターでスキルを呼び出そうとしている場合は、いったん中止し、まずこのファイルを読むか、GET /skills/recommend?includeSchema=true でスキーマを取得してください。recommend/schema からパラメーター定義をすでに取得している場合は、そのまま dryRun に進めます。

トリガー

• プレハブの作成または編集
• プレハブのインスタンス化または変更の適用
• シーン内のインスタンスの検索
• プレハブのバリアントの作成
• プレハブの作成または編集、インスタンス化または変更の適用、シーン内のインスタンスの検索、プレハブのバリアントの作成

Unity プレハブスキル

バッチ優先：プレハブインスタンスを2つ以上生成する場合は prefab_instantiate_batch を使用してください。複数のアセットを編集する場合は、アセット編集の _batch API を使用してください。

動作モード

読み取り API（prefab_get_overrides、prefab_find_instances、および4つのアセットクエリ API）は SemiAuto です。書き込みは FullAuto です。コンポーネント／ノードの削除と prefab_edit_batch は、Delete／高メタデータにより NeverInSemi です。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 呼び出しを維持するには → 元のパラメーターで引き続き使用できます。
• 1つのアセットに対する編集をまとめるには → prefab_edit_batch を使用してください。1回の操作で複数のアセットを編集するには → その _batch バリアントを使用してください。
• プレハブの全インスタンスを検索するには → prefab_find_instances を使用してください（このモジュール）

アセットの直接編集

4つのクエリ API、12の単一書き込み API とそのバッチ版、および prefab_edit_batch については、ASSET_EDITING.mdを参照してください。gameObjectPath はルート相対パスです。componentType／componentIndex はコンポーネントを特定します。書き込みでは、Variant／ネストされたオーバーライドを含め、指定されたアセットのみが保存されます。

スキルの概要

単一オブジェクト	バッチ版	バッチを使う場合
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 がない場合は追加されます

*少なくとも 1 つのソース識別子が必要です。

戻り値：{success, prefabPath, name, connected}：prefabPath は保存されたアセットのパス、connected はシーンオブジェクトが現在そのプレハブのインスタンスになっているかどうかを示します。Unity が拒否した保存は成功ではなく、エラーになります。

prefab_instantiate

プレハブをシーンにインスタンス化します。

パラメーター	型	必須	デフォルト	説明
prefabPath	string	はい	-	プレハブアセットのパス
name	string	いいえ	プレハブ名	インスタンス名
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

1 回の呼び出しで複数のプレハブをインスタンス化します。

パラメーター	型	必須	説明
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 はローカル位置です。全か無かで処理されます。項目が 1 つでも失敗すると、この呼び出しで作成されたすべてのインスタンスが削除されます（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	いいえ*	オブジェクトパス

*少なくとも 1 つの識別子が必要です。

戻り値: {success, appliedTo}（appliedTo はプレハブアセットのパスです）

prefab_unpack

プレハブインスタンスを展開します（プレハブとの接続を解除します）。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ*	-	プレハブインスタンス名
instanceId	int	いいえ*	-	インスタンス ID（優先）
path	string	いいえ*	-	オブジェクトパス
completely	bool	いいえ	false	すべてのネストされたプレハブを展開するかどうか

*少なくとも 1 つの識別子が必要です。

戻り値: {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 は、これらの件数のいずれかが 0 以外の場合に 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 を指定できます。Quaternion（localRotation）は、オイラー角の度数による3つの成分（"0,90,0"）または x,y,z,w の生の値による4つの成分を受け付けます。bool は true/false/1/0/yes/no/on/off を指定できます（それ以外は拒否されます）。enum は名前、表示名、フラグを表す A,B、または component_set_serialized_property と同じ規則に従う数値（0..n-1 = メンバーのインデックス。メンバーの値が異なる場合は警告されます。未宣言のビットは拒否されます）を受け付けます。それ以外のシリアライズ型が指定されると、型名を含む SEMANTIC_INVALID が返されます。これは value の形式を変えるのではなく、assetReferencePath を使う必要があることを示します。

戻り値： { success, prefabPath, gameObject, component, property, valueSet, valueRequested?, warnings? }：component / property は解決された型名とシリアライズパスです。valueSet は保存後にアセットから読み戻された値です（シリアライズ形式：enum はインデックス、Quaternion は 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 の破損、型の不一致など）を解消してから、再試行してください。