unity-scene

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

トリガー

• シーンを開く、または保存する
• 加算読み込み
• アクティブシーンの切り替え
• シーン内容の照会
• シーンを開く、または保存する、加算読み込み、アクティブシーンの切り替え、シーン内容の照会

Unity シーンスキル

Unity シーンを操作します。シーンは、すべての GameObject を保持するコンテナーです。

動作モード

• Approval：このモジュールは Mixed です。scene_get_info / scene_get_hierarchy / scene_get_loaded / scene_find_objects は SkillMode.SemiAuto が設定されており、直接実行できます。scene_screenshot / scene_unload / scene_set_active は Mode フィールドが設定されていないため（デフォルトは FullAuto）、Approval モードでは grant が必要です。
• Auto / Bypass：FullAuto はそのまま実行されます。
• NeverInSemi を含む高リスクスキル：scene_create / scene_load / scene_save（シーンファイル全体の切り替え／上書きは影響範囲が非常に大きいため、RiskLevel="high" が設定されています）。これらは Approval/Auto では MODE_FORBIDDEN を返し、Bypass または Allowlist に一致する場合にのみ呼び出せます。

よくある誤りに注意してください：

• scene_delete / scene_rename は存在しません。シーンファイルの削除には asset_delete、名前の変更には asset_move を使用してください。
• scene_list は存在しません。読み込み済みシーンには scene_get_loaded、すべてのシーンアセットには asset_find と t:Scene を使用してください。
• scene_find_objects は、名前／タグ／コンポーネントによる簡易フィルターです。正規表現／レイヤー／パスによる検索には gameobject_find を使用してください（SkillMode.SemiAuto、読み取り専用、どのモードでも直接呼び出せます）。

ルーティング：

• 詳細なヒエラルキーツリーには、perception モジュールの hierarchy_describe を使用してください。
• シーンの統計情報には、perception モジュールの scene_summarize を使用してください。
• スクリーンショットには scene_screenshot（このモジュール）を使用してください。Game View の最終合成画像（すべてのカメラと UI を含む。Play モードではライブ実行フレーム）をキャプチャします。camera_screenshot（camera モジュール、SkillMode.FullAuto）は、単一の Game Camera をオフスクリーンでレンダリングします。

スキル概要

スキル	説明
scene_create	新しいシーンを作成
scene_load	シーンを読み込む
scene_save	現在のシーンを保存
scene_get_info	シーン情報を取得
scene_get_hierarchy	ヒエラルキーツリーを取得
scene_screenshot	スクリーンショットをキャプチャ
scene_get_loaded	読み込み済みのすべてのシーンを取得
scene_unload	加算読み込みされたシーンをアンロード
scene_set_active	アクティブシーンを設定
scene_find_objects	名前／タグ／コンポーネントでオブジェクトを検索

---

スキル

scene_create

新しいシーンを作成します。

パラメーター	型	必須	説明
scenePath	string	はい	新しいシーンのパス（例："Assets/Scenes/MyScene.unity"）

scene_load

シーンを読み込みます。

パラメーター	型	必須	デフォルト	説明
scenePath	string	はい	-	シーンアセットのパス
additive	bool	いいえ	false	加算読み込み（現在のシーンを保持）

scene_save

現在のシーンを保存します。

パラメーター	型	必須	説明
scenePath	string	いいえ	保存先パス（null = 現在のシーンを保存）

scene_get_info

現在のシーン情報を取得します。

パラメーターはありません。

戻り値：{sceneName, scenePath, isDirty, rootObjectCount, rootObjects: [{name, entityId, instanceId, childCount}]} — ルートエントリーには childCount が含まれるため、ヒエラルキー取得を呼び出す前に、どのルートを詳しく調べる価値があるか判断できます。

scene_get_hierarchy

深さを制限して、シーンの階層ツリーを取得します。

Parameter	Type	Required	Default	Description
maxDepth	int	No	3	展開する階層の最大深度

Returns: {sceneName, hierarchy: [node, ...]}。各ノードは {name, scene, entityId, instanceId, components: [type, ...], childCount, children} です。scene はノードが属するシーン名です。

DontDestroyOnLoad：Play モードでは、DontDestroyOnLoad 疑似シーンのルートがアクティブシーンのノードの後に追加され、scene: "DontDestroyOnLoad" として示されます。ルートがある場合、scene_get_loaded にも {name: "DontDestroyOnLoad", isPseudoScene: true} として表示されます。これらのオブジェクトは他のオブジェクトと同様に gameobject_find で検索できますが、シーン自体をアンロードまたはアクティブ化することはできません。

childCount と children の違い — 末端ノードと省略されたノードの見分け方。 childCount は maxDepth に関係なく、ノードの実際の子の数を常に示します。深度制限に達すると、children は null になります。つまり、次のとおりです。

childCount	children	意味
0	null	実際の末端ノード — これより下にノードはありません。
> 0	null	maxDepth によって省略されています — 表示されていない子があります。
> 0	array	この階層レベルまで完全に展開されています。

children: null を「空」と解釈しないでください。childCount > 0 かつ children: null で、その下の階層が必要な場合は、maxDepth を大きくして再度呼び出してください。デフォルトは 3 にすぎないため、深い階層はデフォルトで省略されます。または、該当するサブツリーを直接クエリしてください（perception モジュールの gameobject_find、hierarchy_describe）。

scene_screenshot

Game View のスクリーンショットを撮影します。すべてのカメラと UI を合成した最終フレームです。Play モードでは、実行時のライブ画像であり、Scene／エディターのビューではありません。単一の Game Camera のレンダリングを取得するには、代わりに camera_screenshot を使用してください。

Parameter	Type	Required	Default	Description
filename	string	No	"screenshot.png"	ファイル名のみ（パス区切り文字なし）。Assets/Screenshots/ に保存されます
width	int	No	1920	画像の幅
height	int	No	1080	画像の高さ
returnImage	bool	No	false	ファイルシステムにアクセスできないクライアント向けに、レスポンスで PNG を base64 としても返します（imageBase64）
maxDimension	int	No	1280	returnImage=true の場合のみ使用されます。返される画像を縮小し、長辺がこの値以下になるようにします（保存ファイルには適用されません）。256～4096 の範囲に制限されます

Returns: {success, path, width, height, isPlaying, note}。isPlaying は、フレームが実行時のライブ画像（Play モード）か、静的な Edit モードのフレームかを示します。returnImage=true の場合は {imageBase64, imageWidth, imageHeight, imageBytes} も追加されます。base64 ペイロードが 8MB を超える場合、スキルは maxDimension を小さくするよう求めるエラーを返しますが、path のファイルは保存されます。

非同期処理：ScreenCapture.CaptureScreenshot は約 1 フレーム後に PNG を書き込みます。path をすぐに読み取れない場合は、約 200ms 待ってから再試行してください。returnImage は、まだ書き込まれていないそのファイルを読み戻しません。代わりに、Game View の現在のバックバッファを別途同期キャプチャします（ScreenCapture.CaptureScreenshotAsTexture）。そのため、返される画像は、最終的に path に書き込まれるファイルより少し古い場合があります。

**returnImage の使用上のヒント：**ファイルを読み取れるローカルエージェント（ローカルの Unity Editor に接続する Claude Code など）は、通常 returnImage を省略し、path の PNG が書き込まれた後に読み取ることをおすすめします。トークンの消費を抑えられます。Unity プロジェクトのファイルシステムにアクセスできないリモートの MCP クライアントでは、returnImage=true を使用してください。

scene_get_loaded

現在ロードされているすべてのシーンの一覧を取得します。

パラメーターはありません。

戻り値：{success, count, scenes: [{name, path, isLoaded, isDirty, isActive, rootCount, isPseudoScene}]}。Play Mode でルートオブジェクトがある場合は、DontDestroyOnLoad の疑似シーン（isPseudoScene:true、path は空）が追加されます。

scene_unload

ロード済みのシーンをアンロードします（アディティブ）。

パラメーター	型	必須	説明
sceneName	string	はい	アンロードするシーン名

scene_set_active

アクティブシーンを設定します（複数シーンの編集用）。

パラメーター	型	必須	説明
sceneName	string	はい	アクティブに設定するシーン名

scene_find_objects

名前のパターン、タグ、またはコンポーネント型で GameObject を検索します。正規表現、レイヤー、パスによる高度な検索には gameobject_find を使用してください。

パラメーター	型	必須	デフォルト	説明
namePattern	string	いいえ	-	一致させる名前の部分文字列（大文字と小文字を区別しません）
tag	string	いいえ	-	タグで絞り込みます。Tags & Layers で定義されていないタグは拒否されます
componentType	string	いいえ	-	コンポーネント型名で絞り込みます。不明な型は拒否されます
limit	int	いいえ	50	返す結果の最大数

戻り値：{success, count, objects: [{name, path, instanceId, active, tag}]}

---

使用例

import unity_skills

# Create a new scene
unity_skills.call_skill("scene_create", scenePath="Assets/Scenes/Level1.unity")

# Load an existing scene
unity_skills.call_skill("scene_load", scenePath="Assets/Scenes/MainMenu.unity")

# Load scene additively (multi-scene)
unity_skills.call_skill("scene_load", scenePath="Assets/Scenes/UI.unity", additive=True)

# Get current scene info
info = unity_skills.call_skill("scene_get_info")
print(f"Scene: {info['name']}, Objects: {info['rootObjectCount']}")

# Get full hierarchy (useful for understanding scene structure)
hierarchy = unity_skills.call_skill("scene_get_hierarchy", maxDepth=5)

# Save scene
unity_skills.call_skill("scene_save")

# Take screenshot
unity_skills.call_skill("scene_screenshot", filename="preview.png", width=1920, height=1080)

ベストプラクティス

1. 新しいシーンをロードする前に、必ず保存してください
2. UI オーバーレイにはアディティブロードを使用してください
3. 空の親オブジェクトを使ってシーン階層を整理してください
4. scene_get_info を使用してシーンの状態を確認してください
5. スクリーンショットは Assets/Screenshots/ に保存されます（ファイル名は名前のみで、パス区切り文字はすべて取り除かれます）

正確なシグネチャ

正確な名前、パラメーター、デフォルト値、戻り値はこのファイルではなく、GET /skills/schema または unity_skills.get_skill_schema() で定義されています。

よくあるエラー

トランスポートレベルのすべてのコード（COMPILING/RATE_LIMIT など）については、../../references/protocol-error-codes.md を参照してください。

エラー	発生条件	対処方法
TARGET_NOT_FOUND	指定されたシーンが見つからない、または現在ロードされていません（例：Scene not found、Scene is not loaded）。	asset_find でシーンパスを確認するか、scene_get_loaded でロード済みシーンを一覧表示してから、再試行してください。
MISSING_PARAM	scene_create の scenePath など、必須パラメーターが不足しているか、現在のシーンに保存先パスがありません。	scenePath を指定するか、操作の前にシーンを一度保存してください。
SEMANTIC_INVALID	無効なタグまたはコンポーネント型が scene_find_objects に渡されました。	有効なタグまたはコンポーネント型名を使用し、より複雑な条件で絞り込む場合は gameobject_find の使用を検討してください。
SKILL_ERROR	ロード済みの唯一のシーンをアンロードしようとした場合など、状態の制約によって操作がブロックされました。	有効なエディター状態になるようリクエストを調整してください（例：少なくとも 1 つのシーンをロードしたままにする）。