# ツールとRQL — Unity · AI Game Developer Wiki

Unity MCPでAIエージェントがUnity Editor内でできること - RQLクエリとミューテーション、スクリーンショット、C#スクリプト、テスト、パッケージ、プロファイリング。

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/unity/tools-and-rql)。

このページでは、Unity MCPが接続された後、AIエージェントがUnityプロジェクト内で何をできるかを説明します。エージェントが見えるツール、RQLでEditor内のほぼすべてを読み取り・変更する方法、インストール済みだが非表示のツールについて扱います。パラメータ付きの検索可能な完全な一覧は[Unityツールカタログ](https://ai-game.dev/docs/tools/unity)に、クエリ言語は[RQLリファレンス](https://ai-game.dev/docs/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` | すべてのツールと、エージェントに表示されるかどうかを一覧表示します。 |

短いリストはトークン消費が少なく、モデルが推論に使える余地を増やします。他のツールもインストールされています。[非表示のツール](https://ai-game.dev/ja/docs/wiki/unity/tools-and-rql#hidden-tools)を参照してください。

## RQL: Editor全体のための単一言語

RQLはEditorのライブデータに対するクエリ言語です。クエリは**ソース**から始まり、`|`で区切られたステージ（`where`、`select`、`get`、`set`、`call`など）を通して結果を渡します。アクションごとに1つのツール（以前の`gameobject-create`、`scene-save`、`console-get-logs`など多数）を使う代わりに、エージェントは1つのクエリを記述します。

開いているシーンの階層全体を読み取る:

```text
roots | recurse children | select name active
```

プレイヤーを検索する:

```text
objects | where name == "Player" | select path name active
```

地面プレーンを作成する:

```text
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
```

コンポーネントを追加して保存する:

```text
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()
```

Consoleからエラーのみを読み取る:

```text
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")`で検索します。インストールされた各[拡張機能](https://ai-game.dev/ja/docs/wiki/unity/extensions)は、たとえば`tilemap`や`cinemachine`など、独自のソースと型を追加します。

RQLはリフレクションを通じて動作するため、Unity組み込みのコンポーネントだけでなく、独自コンポーネントのメンバーも読み取り・設定できます。[カスタムアダプター](https://ai-game.dev/docs/rql/custom-adapters)を使って、独自の型をRQLに教えることができます。

## スクリプトとC#実行

`script-execute`はC#スニペットをRoslynでコンパイルし、Editor内で実行します。コードに加えて、任意の`className`、`methodName`、追加の`usings`、`include`するヘルパーファイルを指定できます。RQLではカバーできない処理のための抜け道です。ターミナルからは、`unity-mcp-cli exec`が同じツールを呼び出します:

```bash
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 ログを含めるかどうかを制御でき、出力を小さく保てます。

```bash
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` ツールで、あるいは次のコマンドで表示できます:

```bash
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 ツールカタログ](https://ai-game.dev/docs/tools/unity)と [RQL リファレンス](https://ai-game.dev/docs/rql)。
- 独自のツールを追加するには [カスタムツール](https://ai-game.dev/ja/docs/wiki/unity/custom-tools)。
- プロンプト作成のヒントは [Unity ベストプラクティス](https://ai-game.dev/docs/best-practices/unity)。

---

Source (HTML): https://ai-game.dev/ja/docs/wiki/unity/tools-and-rql

Machine-translated (ja) from the English page: https://ai-game.dev/docs/wiki/unity/tools-and-rql