ツールとRQL
Unity MCPでAIエージェントがUnity Editor内でできること - RQLクエリとミューテーション、スクリーンショット、C#スクリプト、テスト、パッケージ、プロファイリング。
このページでは、Unity MCPが接続された後、AIエージェントがUnityプロジェクト内で何をできるかを説明します。エージェントが見えるツール、RQLでEditor内のほぼすべてを読み取り・変更する方法、インストール済みだが非表示のツールについて扱います。パラメータ付きの検索可能な完全な一覧はUnityツールカタログに、クエリ言語はRQLリファレンスに記載されています。
エージェントがデフォルトで見るツール
バージョン1.0.0以降、プラグインはエージェントのツールリストを短く保ちます。インストール後に表示されるのは次の7つのツールです。
| ツール | できること |
|---|---|
rql-query | RQLクエリでEditorデータを読み取ります: シーン、GameObject、コンポーネント、アセット、Console、設定、テスト、プロファイラ。 |
rql-mutate | RQLでEditorデータを変更したりEditor操作を呼び出したりします: オブジェクトやアセットの作成、変更、移動、削除、シーンのオープンと保存。 |
rql-schema | RQLで使用できるソース、型、メンバー、呼び出しを説明し、トピックガイドを出力します。エージェントは不明なときにここから始めます。 |
script-execute | RoslynでC#コードをコンパイルしてEditor内で実行し、結果を返します。 |
screenshot-isolated | 選択した角度から1つのGameObjectを分離してレンダリングします。任意で2x2の合成画像として出力でき、モデルがそれを確認できます。 |
tests-run | EditModeまたはPlayModeのテストを実行し、テストごとの結果を返します。 |
unity-tool-list | すべてのツールと、エージェントに表示されるかどうかを一覧表示します。 |
短いリストはトークン消費が少なく、モデルが推論に使える余地を増やします。他のツールもインストールされています。非表示のツールを参照してください。
RQL: Editor全体のための単一言語
RQLはEditorのライブデータに対するクエリ言語です。クエリはソースから始まり、|で区切られたステージ（where、select、get、set、callなど）を通して結果を渡します。アクションごとに1つのツール（以前のgameobject-create、scene-save、console-get-logsなど多数）を使う代わりに、エージェントは1つのクエリを記述します。
開いているシーンの階層全体を読み取る:
roots | recurse children | select name activeプレイヤーを検索する:
objects | where name == "Player" | select path name active地面プレーンを作成する:
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})コンポーネントを追加して保存する:
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()Consoleからエラーのみを読み取る:
console | where logType == "Error"各rql-mutate呼び出しは1つのUndoグループなので、Ctrl+Zで元に戻せます。また、変更されたアセット、シーン、開いているプレハブはミューテーション後に保存されます。rql-mutateはdry_runで変更内容をプレビューでき、max_targetsで1回のミューテーションが触れるオブジェクト数の上限を指定できます。
UnityにおけるRQLソース
| ソース | 内容 |
|---|---|
scenes, roots, objects | 読み込まれたシーン、そのルートGameObject、およびそれらに含まれるすべてのGameObject。 |
selection | 現在のEditorの選択。 |
prefab | プレハブモードで開いているプレハブ。 |
editor | Editor操作: GameObject、マテリアル、フォルダ、シーンの作成、シーンとプレハブのオープンと保存、アセットのコピー、移動、削除、メニュー項目の実行、再生モードの状態。 |
settings | プロジェクト設定。 |
console | キャプチャされたEditorログエントリ。 |
shaders, componentTypes | 利用可能なシェーダーとコンポーネント型。 |
tests, testResults | テストツリーと最後の結果。 |
profiler | メモリ、レンダリング、スクリプト、フレームのデータ。キャプチャの開始、停止、保存、読み込み。 |
lighting | アクティブなシーンの環境（アンビエント、フォグ、スカイボックス、サン、リフレクション）、Lighting Settings、ベイク。 |
アセットはunity.asset("Assets/…")でパス指定するか、unity.assets("t:Material")で検索します。インストールされた各拡張機能は、たとえばtilemapやcinemachineなど、独自のソースと型を追加します。
RQLはリフレクションを通じて動作するため、Unity組み込みのコンポーネントだけでなく、独自コンポーネントのメンバーも読み取り・設定できます。カスタムアダプターを使って、独自の型をRQLに教えることができます。
スクリプトとC#実行
script-executeはC#スニペットをRoslynでコンパイルし、Editor内で実行します。コードに加えて、任意のclassName、methodName、追加のusings、includeするヘルパーファイルを指定できます。RQLではカバーできない処理のための抜け道です。ターミナルからは、unity-mcp-cli execが同じツールを呼び出します:
unity-mcp-cli exec 'Application.unityVersion'コードを実行する代わりにファイルを書き込むには、非表示のツールscript-read、script-update-or-create、script-deleteでプロジェクト内の.csファイルを管理します。変更後はUnityが再コンパイルします。ドメインリロード中は接続が一時的に切れますが、自動的に復帰します。
テスト
tests-run は EditMode または PlayMode のテストを実行します（testMode、デフォルトは EditMode）。アセンブリ、名前空間、クラス、メソッドでフィルタするか、tests ソースに対して RQL の選択を渡すことで、選んだテストだけを 1 回の実行として走らせられます。結果は testResults に対する RQL でフィルタできます。オプションで、成功したテスト、メッセージ、スタックトレース、Console ログを含めるかどうかを制御でき、出力を小さく保てます。
unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'スクリーンショット
screenshot-isolated はデフォルトで表示されます。さらに 3 つが非表示です: screenshot-scene-view、screenshot-game-view、screenshot-camera。画像は MCP の転送に収まるよう、最長辺が 3840 ピクセルに制限されます。スクリーンショットにはグラフィックスデバイスが必要です: -nographics で起動した Editor は、空白の画像ではなくエラーを返します。
非表示のツール
これらはインストールされていますが、エージェントの一覧には表示されません。非表示のツールも、名前で呼び出せば実行されます。
- スクリーンショット:
screenshot-scene-view、screenshot-game-view、screenshot-camera。 - スクリプト:
script-read、script-update-or-create、script-delete。 - パッケージ: Unity Package Manager 用の
package-list、package-search、package-add、package-remove。 - ツール管理:
tool-set-visibility、および非推奨のエイリアスtool-set-enabled-state。
AI Game Developer ウィンドウ（Tools > Open）で表示するか、tool-set-visibility ツールで、あるいは次のコマンドで表示できます:
unity-mcp-cli configure ./MyUnityProject --enable-tools package-add,package-listプロンプトとスキル
このプラグインには 46 個の MCP プロンプト（setup-basic-scene や add-event-system といったスラッシュコマンドのテンプレート）も同梱されており、スクリプティング、GameObject とコンポーネント、シーン、デバッグとテスト、アセット管理、アニメーションとタイムラインの 6 グループに分かれています。デフォルトでは非表示で、使いたいものを Prompts > Open で有効にします。
Skills はプラグインがエージェントのスキルフォルダに生成する Markdown ファイルです。Unity とインストール済みのすべての拡張機能向けの RQL 構文をまとめた unity-rql ガイドや、セットアップと CLI のメモが含まれます。ウィンドウの Skills > Auto-generate で有効にするか、unity-mcp-cli setup-skills <agent> を実行してください。
古いチュートリアルのツール名
バージョン 1.0.0 で、1 アクション 1 ツールのツール群は削除されました。チュートリアルでそれらの名前を見かけた場合は、代わりに RQL を使ってください:
gameobject-create、gameobject-find、gameobject-modify、gameobject-destroy、gameobject-component-*:setとcallを使ったobjects、roots、selectionに対する RQL。scene-create、scene-open、scene-save:editor | call NewScene(…)、OpenScene(…)、SaveScenes()。assets-*、assets-prefab-*、assets-material-create:unity.asset(…)、unity.assets(…)、およびCreateMaterial、CopyAsset、InstantiatePrefabなどのeditor呼び出し。console-get-logs、console-clear-logs:consoleソースとeditor | call ClearConsole()。editor-application-*、editor-selection-*:isPlayingやselectionなどのeditorメンバー。reflection-method-find、reflection-method-call、type-get-json-schema: RQL のcallとrql-schema。profiler-*:profilerソース。
関連ページ
- Unity ツールカタログと RQL リファレンス。
- 独自のツールを追加するには カスタムツール。
- プロンプト作成のヒントは Unity ベストプラクティス。