Unity AI Bridge

英語 | 中国語

Unity AI Bridge

あらゆる AI IDE から Unity Editor をリモート操作できます。ポートも依存関係も不要で、すぐに使えます。

https://github.com/user-attachments/assets/4e8b3f85-b209-406f-a96e-f8b8eddc9160

---

Unity AI Bridge を選ぶ理由

多くの AI コーディングアシスタントはファイルの読み書きができますが、Unity Editor の中は見えません。シーンの確認やマテリアルの調整、テストの実行、パフォーマンスのプロファイリングができないのです。Unity AI Bridge を使えば、AI がエディターにフルアクセスできます。

主な利点

• 65 個のツール、15 のカテゴリ — Scene、GameObject、Assets、Prefab、Script、Profiler、LightProbe、Screenshot、Runtime、Tests などに対応。ファイルの入出力だけでなく、エディターのワークフロー全体をカバーします。
• WebSocket ではなくファイルベースの IPC — ポートの開放やファイアウォールの問題、接続切断がありません。再コンパイル、プレイモードへの切り替え、エディターの再起動にも適切に対応します。
• 外部依存関係ゼロ — Python 標準ライブラリのみを使う自己完結型の CLI／MCP サーバーと、自己完結型の C# Unity パッケージです。pip のインストールも npm も Node.js ランタイムも不要です。
• 主要な AI IDE に対応 — Claude Code（Skill モード）、Cursor、GitHub Copilot、Windsurf、Claude Desktop（MCP モード）。Unity プラグインは 1 つで、すべての IDE に対応します。
• 5 行で拡張可能 — [BridgeTool] 属性を使ってカスタムツールを追加できます。自動検出、自動シリアライズ、自動ドキュメント生成に対応しており、登録コードは不要です。
• 実運用で検証済み — 大規模なオープンワールド Unity ゲーム（開発者 50 人以上、C# コード 200 万行以上）向けに開発され、実戦で検証されています。

Unity 6 AI Gateway との比較

Unity 6.2 では、MCP に対応する公式の AI Gateway が導入されました。どちらのプロジェクトも、MCP を介して AI エージェントにエディターへのアクセスを提供することを目指していますが、重要な違いがあります。

	Unity AI Bridge	Unity 6 AI Gateway
Unity のバージョン	2022.3 LTS 以降	6.2 以降のみ
ツールの対応範囲	15 カテゴリにわたる 65 個のツール	汎用（Scene、Assets、Script、Console）
高度なツール	Profiler（スナップショット、ホットパス、ストリーム）、LightProbe、Reflection、Package Manager	未対応
IPC の方式	ファイルポーリング（約 100 ms）	Unix Socket／Named Pipe
拡張性	[BridgeTool] 属性 — 5 行	未定

実際には、AI エージェントの思考時間が各ラウンドトリップの大部分を占めるため、約 100 ms のファイルポーリングによる遅延はほとんど感じられません。ファイル IPC ならプロセス間のデバッグも簡単です。ディスク上の JSON ファイルを確認するだけです。

---

クイックスタート

AI ネイティブなプロジェクト — 以下のプロンプトをコピーして、AI コーディングアシスタントに送信してください。セットアップガイド は AI が手順に沿って進められるように書かれているため、自分でコマンドを実行する必要はありません。

このガイドに従って Unity AI Bridge をインストールしてください。
https://github.com/butterlatte-zhang/unity-ai-bridge/blob/main/docs/SETUP.md

手動でセットアップする場合：

1. Unity パッケージ — Unity で Window > Package Manager > + > Add package from git URL を選択します。

   https://github.com/butterlatte-zhang/unity-ai-bridge.git?path=Packages/com.aibridge.unity
   

   または、このリポジトリの Packages/com.aibridge.unity をプロジェクトの Packages/ ディレクトリに手動でコピーします。

2. IDE 連携 — .claude/ をプロジェクトのルートにコピーしてから、docs/SETUP.md に従って IDE を設定します。

対応：Claude Code（Skill モード）、Cursor、GitHub Copilot、Windsurf、Claude Desktop（MCP モード）。

---

ツールのカテゴリ

15 個のカテゴリに整理された 65 個のツール：

カテゴリ	数	ツール
シーン	7	scene-open, scene-save, scene-create, scene-list-opened, scene-get-data, scene-set-active, scene-unload
ゲームオブジェクト	11	gameobject-find, gameobject-create, gameobject-destroy, gameobject-modify, gameobject-duplicate, gameobject-set-parent, gameobject-component-add, gameobject-component-destroy, gameobject-component-get, gameobject-component-list-all, gameobject-component-modify
アセット	11	assets-find, assets-find-built-in, assets-get-data, assets-modify, assets-move, assets-copy, assets-delete, assets-create-folder, assets-refresh, assets-material-create, assets-shader-list-all
プレハブ	5	assets-prefab-create, assets-prefab-open, assets-prefab-save, assets-prefab-close, assets-prefab-instantiate
スクリプト	4	script-read, script-update-or-create, script-delete, script-execute
オブジェクト	2	object-get-data, object-modify
エディター	4	editor-application-get-state, editor-application-set-state, editor-selection-get, editor-selection-set
リフレクション	2	reflection-method-find, reflection-method-call
スクリーンショット	1	screenshot-capture
ランタイム	2	runtime-query, runtime-invoke
コンソール	1	console-get-logs
プロファイラー	5	profiler-snapshot, profiler-stream, profiler-frame-hierarchy, profiler-hotpath, profiler-gc-alloc
パッケージ	4	package-list, package-search, package-add, package-remove
ライトプローブ	5	lightprobe-generate-grid, lightprobe-analyze, lightprobe-bake, lightprobe-clear, lightprobe-configure-lights
テスト	1	tests-run

---

アーキテクチャ

┌──────────────────────────────────────────────────┐
│                   AI IDE                         │
│  (Claude Code / Cursor / Copilot / Windsurf)     │
└──────────┬────────────────────┬──────────────────┘
           │                    │
     Skill mode            MCP mode
           │                    │
           ▼                    ▼
    ┌─────────────┐    ┌──────────────┐
    │  bridge.py  │    │ mcp_server.py│
    │  (Python)   │    │  (Python)    │
    └──────┬──────┘    └──────┬───────┘
           │                  │
           └────────┬─────────┘
                    │
              File-based IPC
            (request / response)
                    │
                    ▼
    ┌───────────────────────────────┐
    │     Unity Editor Plugin      │
    │   (com.aibridge.unity)       │
    │                              │
    │  BridgePlugin ← polls files  │
    │  BridgeToolRegistry          │
    │  BridgeToolRunner            │
    │  [BridgeTool] methods        │
    └───────────────────────────────┘

デュアルチャネル設計：同じ Unity プラグインが、スキルモード（直接 CLI）と MCP モード（プロトコルサーバー）の両方に対応します。どちらのチャネルも、ファイルベースの同じ IPC（ディスク上のリクエストファイルとレスポンスファイルのペア）を介して通信します。ネットワークソケットやポートの競合、ファイアウォールのルールは不要です。

ファイル IPC を採用する理由：Unity のメインスレッドはシングルスレッドであり、ドメインの再読み込み中はブロックされます。ファイルポーリングは、メッセージを失うことなく、再コンパイル、プレイモードの切り替え、エディターの再起動を乗り切る最も信頼できる方法です。

---

編集の先へ — ゲームテスターとしての AI

多くの Unity AI ツールはファイル編集で終わります。Unity AI Bridge はその先へ進み、Claude Code（または任意の AI IDE）をゲームテストハーネスに変えます。

機能	従来の AI	Unity AI Bridge の場合
C# コードを記述する	:white_check_mark:	:white_check_mark:
コンパイルエラーを確認する	:x:	:white_check_mark: console-get-logs
プレイモードに入る／終了する	:x:	:white_check_mark: editor-application-set-state
ゲーム内のアクションを実行する	:x:	:white_check_mark: runtime-invoke
ランタイムのゲーム状態を読み取る	:x:	:white_check_mark: runtime-query
スクリーンショットを撮る	:x:	:white_check_mark: screenshot-capture
完全なクローズドループ：記述 → テスト → 修正 → 繰り返し	:x:	:white_check_mark:

AI プレイテストループ

AI writes code → compiles → enters Play Mode → observes state → judges → fixes → repeats
     ↑                                                                         │
     └─────────────────── fully automated loop ────────────────────────────────┘

パターンは 実行 → 待機 → 観察 → 判定 → 繰り返し です。

• 実行：runtime-invoke が静的メソッドを呼び出し、ゲーム内のアクションを実行します
• 待機：wait_playmode.py ／ wait_compile.py がタイミングを処理します
• 観察：runtime-query で MonoBehaviour のフィールドを読み取り、screenshot-capture で画面を確認します
• 判定：AI が状態やスクリーンショットを分析し、PASS／FAIL を判断します

自動プレイテストの例 | AI クローズドループガイド | プレイテストツールリファレンス

---

独自のツールを追加する

属性を 1 つ付けるだけで、任意の静的メソッドを AI に公開できます。

using UnityAiBridge;

[BridgeToolType]
public static partial class CustomTools
{
    [BridgeTool("custom-greet")]
    [System.ComponentModel.Description("Say hello")]
    public static string Greet(string name = "World")
    {
        return $"Hello, {name}!";
    }
}

ブリッジはリフレクションを使用して、エディターの起動時にツールを検出します。登録コードも設定ファイルも不要です。パラメーターは、AI が呼び出せるよう JSON Schema に自動的にマッピングされます。

---

セキュリティ

Unity AI Bridge はすべてローカルマシン上で実行されます。ファイル IPC チャネルはユーザーの一時ディレクトリ内に限定されており、ネットワークリスナーは開きません。

詳しくは SECURITY.md をご覧ください。

---

互換性

Unity バージョン	レンダーパイプライン	状態
2022.3 LTS+	Built-in	対応
2022.3 LTS+	URP	対応
2022.3 LTS+	HDRP	対応
6000.x (Unity 6)	すべて	対応

プラットフォーム：Windows、macOS

---

コントリビューション

コントリビューションを歓迎します！ガイドラインについては CONTRIBUTING.md をご覧ください。

• バグの報告や機能のリクエストは GitHub Issues からお寄せください
• main ブランチに対してプルリクエストを送信してください
• 上記の [BridgeTool] パターンに従って、新しいツールを追加してください

---

謝辞

Unity AI Bridge は、Ivan Murzak による Unity-MCP を基にしています（Apache License 2.0）。詳しくは THIRD_PARTY_NOTICES.md をご覧ください。

ライセンス

Apache License 2.0