English

_{(Logo inspired by Daft Punk's Discovery album art)}

CLIを通じて、AIエージェントがUnityプロジェクトのコンパイル・テスト・操作を各種LLMツールから実行できるようにします。

AI駆動の開発ループを既存のUnityプロジェクト内で自律的に回し続けるために設計されています。

Note: このプロジェクトの旧名称は uLoopMCP です。

コンセプト

Unity CLI Loopは、「AIがUnityプロジェクトの実装をできるだけ人手を介さずに進められる」ことを目指して作られた Unity連携ツールです。 人間が手で行っていたコンパイル、Test Runner の実行、ログ確認、シーン編集、画面キャプチャによるUIレイアウト確認などの作業を、LLM ツールからまとめて操作できるようにします。

Unity CLI Loopのコアとなるコンセプトは次の4つです。

1. AIが自律的にビルド・テスト・ログ解析・修正を回し続ける「自律開発ループ」 — compile, run-tests, get-logs, clear-console
2. シーン構築、オブジェクト操作、メニュー実行、スクリーンショットからのUI改善など、Unity Editorの操作をAIに委任 — execute-dynamic-code, screenshot
3. PlayMode中の自動テスト — ボタンクリック、ドラッグ、キーボード入力、入力の記録・再生、ゲーム動作の検証をAIが実行 — simulate-mouse-ui, simulate-mouse-input, simulate-keyboard, record-input, replay-input, execute-dynamic-code, screenshot
4. 上記を最小限のツール数で実現する → 設計思想

https://github.com/user-attachments/assets/569a2110-7351-4cf3-8281-3a83fe181817

インストール

Unity Package Manager経由

1. Unity Editorを開く
2. Window > Package Managerを開く
3. 「+」ボタンをクリック
4. 「Add package from git URL」を選択
5. 以下のURLを入力：

https://github.com/hatayama/unity-cli-loop.git?path=/Packages/src

v1.0.0以前にgit URL でインストールされていた方へ: v1.0.0でリポジトリ名が uLoopMCP から unity-cli-loop に変更されました。manifest.json の URL を更新してください：

旧: https://github.com/hatayama/uLoopMCP.git?path=/Packages/src
新: https://github.com/hatayama/unity-cli-loop.git?path=/Packages/src

旧URLはGitHubのリダイレクトにより引き続き動作しますが、更新を推奨します。OpenUPMユーザーは影響ありません。

OpenUPM経由（推奨）

Unity Package ManagerでScoped registryを使用

1. Project Settingsウィンドウを開き、Package Managerページに移動
2. Scoped Registriesリストに以下のエントリを追加：

Name: OpenUPM
URL: https://package.openupm.com
Scope(s): io.github.hatayama.uloopmcp

3. Package Managerウィンドウを開き、My RegistriesセクションのOpenUPMを選択。Unity CLI Loopが表示されます。

クイックスタート

ステップ1: CLIのインストール

Window > Unity CLI Loop > Settingsを選択します。専用ウィンドウが開くので CLI ボタンが青くなっている事を確認します。

Install CLI ボタンを押します。

下記の表示になれば成功です。

npm install -g uloop-cli

ステップ2: Skillsのインストール

Claude CodeやCodexなど、対象を選択して Install Skills ボタンを押します。

# Claude Code のプロジェクトにインストール
uloop skills install --claude

# OpenAI Codex のプロジェクトにインストール
uloop skills install --codex

# または、グローバルにインストール
uloop skills install --claude --global

これで完了です！Skillsをインストールすると、LLMツールが以下のような指示に自動で対応できるようになります：

# 利用可能なツール一覧を取得
uloop list

# 正しいバージョンでUnityプロジェクトを起動
uloop launch

# ビルドターゲットを指定して起動（Android, iOS, StandaloneOSX など）
uloop launch -p Android

# 実行中のUnityを終了して再起動
uloop launch -r

# コンパイルを実行
uloop compile

# コンパイルしてDomain Reload完了まで待つ
uloop compile --wait-for-domain-reload true

# ログを取得
uloop get-logs --max-count 10

# テストを実行
uloop run-tests --filter-type all

# 動的コードを実行
uloop execute-dynamic-code --code 'using UnityEngine; Debug.Log("Hello from CLI!");'

# 補完スクリプトをシェル設定に追加（シェル自動検出）
uloop completion --install

# シェルを明示的に指定（Windows環境で自動検出が失敗する場合）
uloop completion --shell bash --install        # Git Bash / MINGW64
uloop completion --shell powershell --install  # PowerShell

# 補完スクリプトを確認
uloop completion

プロジェクトパス指定

--project-path を省略した場合は、カレントディレクトリの Unity プロジェクトで設定されたポートが自動選択されます。

一つのLLMツールから複数のUnityインスタンスを操作したい場合、プロジェクトパスを明示的に指定します：

# プロジェクトパスで指定（絶対パス・相対パスどちらも可）
uloop compile --project-path /Users/foo/my-unity-project
uloop compile --project-path ../other-project

CLIの代わりにMCPを使う場合

Warning

MCP接続は将来のリリースでメンテナンスが終了、または廃止される可能性があります。CLIの利用を推奨します。

MCP（Model Context Protocol）経由でも接続できます。MCPの場合、CLIやSkillsのインストールは不要です。

MCP接続の手順

1. Window > Unity CLI Loop > Settingsを選択します。専用ウィンドウが開くので MCP ボタンを押してください。

   

2. 次に、LLM Tool SettingsセクションでターゲットIDEを選択します。黄色い「Configure {LLM Tool名}」ボタンを押してIDEに自動接続してください。

   

3. IDE接続確認

• 例えばCursorの場合、設定ページのTools & MCPを確認し、uLoopMCPを見つけてください。トグルをクリックしてMCPを有効にします。

Warning

Windsurfについて プロジェクト単位の設定ができず、global設定のみとなります。

手動設定（通常は不要）

Note

通常は自動設定で十分ですが、必要に応じて、設定ファイル（mcp.jsonなど）を手動で編集できます：

{
  "mcpServers": {
    "uLoopMCP": {
      "command": "node",
      "args": [
        "[Unity Package Path]/TypeScriptServer~/dist/server.bundle.js"
      ],
      "env": {
        "UNITY_TCP_PORT": "{port}"
      }
    }
  }
}

パス例:

• Package Manager経由: "/Users/username/UnityProject/Library/PackageCache/io.github.hatayama.uloopmcp@[hash]/TypeScriptServer~/dist/server.bundle.js"

Note

Package Manager経由でインストールした場合、パッケージはハッシュ化されたディレクトリ名でLibrary/PackageCacheに配置されます。「Auto Configure Cursor」ボタンを使用すると、正しいパスが自動的に設定されます。

複数のUnityインスタンスのサポート

Note

ポート番号を変更することで複数のUnityインスタンスをサポートできます。Unity CLI Loop起動時に自動的に使われていないportが割り当てられます。

設計思想

Unity CLI Loop はツールの数を追い求めません。C#コードの動的実行（execute-dynamic-code）があれば、Unity Editor上のほとんどの操作はそれ一つで実現できます。

ツールを増やしすぎると、AIがどのツールを使うべきか適切に判断できなくなります。さらに、たとえSkill化したとしても各ツールのdescriptionはコンテキストウィンドウを消費します。必要最低限に絞ることがよい設計だと考えています。

専用ツールを設けているのは、フレームをまたぐ入力シミュレーションやスクリーンショット取得のように動的コード実行では原理的に対応できない操作と、compile・get-logsのように開発ループの中で繰り返し呼ばれる操作です。後者を専用ツール化することで、毎回C#コードを生成するトークンコストを削減しています。

主要機能

自律開発ループ系ツール

1. compile - コンパイルの実行

AssetDatabase.Refresh()をした後、コンパイルして結果を返却します。内蔵のLinterでは発見できないエラー・警告を見つける事ができます。 差分コンパイルと強制全体コンパイルを選択できます。 WaitForDomainReload=true を指定すると、ForceRecompile の値に関係なく Domain Reload完了後に結果を返せます。

→ compile実行、エラー・警告内容を解析
→ 該当ファイルを自動修正
→ 再度compileで確認

2. get-logs - UnityのConsoleと同じ内容のLogを取得します

LogTypeや検索対象の文字列で絞り込む事ができます。また、stacktraceの有無も選択できます。 これにより、コンテキストを小さく保ちながらlogを取得できます。 MaxCountの動作: 最新のログから指定数を取得します（tail的な動作）。MaxCount=10なら最新の10件のログを返します。 高度な検索機能:

• 正規表現サポート: UseRegex: trueで強力なパターンマッチングが可能
• スタックトレース検索: SearchInStackTrace: trueでスタックトレース内も検索対象

→ get-logs (LogType: Error, SearchText: "NullReference", MaxCount: 10)
→ get-logs (LogType: All, SearchText: "(?i).*error.*", UseRegex: true, MaxCount: 20)
→ get-logs (LogType: All, SearchText: "MyClass", SearchInStackTrace: true, MaxCount: 50)
→ スタックトレースから原因箇所を特定、該当コードを修正

3. run-tests - TestRunnerの実行 (PlayMode, EditMode対応)

Unity Test Runnerを実行し、テスト結果を取得します。このツールは Unity Test Framework パッケージが必要です。未導入の場合、run-tests は unsupported メッセージを返し、それ以外の Unity CLI Loop 機能は動作し続けます。FilterTypeとFilterValueで条件を設定できます。

• FilterType: all（全テスト）、exact（個別テストメソッド名）、regex（クラス名や名前空間）、assembly（アセンブリ名）
• FilterValue: フィルタータイプに応じた値（クラス名、名前空間など）
• SaveBeforeRun: 明示的に有効化した場合、未保存のロード済みScene変更と現在のPrefab Stage変更を保存してからテストを実行 テスト結果をxmlで出力する事が可能です。出力pathを返すので、それをAIに読み取ってもらう事ができます。 これもコンテキストを圧迫しないための工夫です。

→ run-tests (FilterType: exact, FilterValue: "PlayerControllerTests.TestJump")
→ run-tests (SaveBeforeRun: true)
→ 失敗したテストを確認、実装を修正してテストをパス

Unity Editor 自動化・探索ツール

4. clear-console - ログのクリーンアップ

log検索時、ノイズのとなるlogをクリアする事ができます。

→ clear-console
→ 新しいデバッグセッションを開始

5. find-game-objects - シーン内オブジェクト検索

オブジェクトを取得し、コンポーネントのパラメータを調べます。また、Unity Editorで選択中のGameObject（複数可）の情報も取得できます。

→ find-game-objects (RequiredComponents: ["Camera"])
→ Cameraコンポーネントのパラメータを調査

→ find-game-objects (SearchMode: "Selected")
→ Unity Editorで選択中のGameObjectの詳細情報を取得（複数選択対応）

6. get-hierarchy - シーン構造の解析

現在アクティブなHierarchyの情報をネストされたJSON形式で取得します。ランタイムでも動作します。 自動ファイル出力: 取得したHierarchyは常に{project_root}/.uloop/outputs/HierarchyResults/ディレクトリにJSONとして保存されます。レスポンスにはファイルパスのみが返るため、大量データでもトークン消費を最小限に抑えられます。 選択モード: UseSelection: true を指定すると、Unity Editorで選択中のGameObjectから階層を取得できます。複数選択にも対応 - 親子両方が選択されている場合、重複を避けるため親のみがルートとして使用されます。

→ GameObject間の親子関係を理解。構造的な問題を発見・修正
→ シーンの規模にかかわらず、Hierarchyデータはファイルに保存され、生のJSONの代わりにパスが返されます
→ get-hierarchy (UseSelection: true)
→ パスを手動で指定せずに、選択中のGameObjectの階層を取得

7. focus-window - Unity Editorウィンドウを前面化（macOS / Windows対応）

macOS / Windows Editor上で、Unity Editor ウィンドウを最前面に表示させます。 他アプリにフォーカスが奪われた後でも、視覚的なフィードバックをすぐ確認できます。（Linuxは未対応）

8. screenshot - EditorWindowのスクリーンショット

任意のEditorWindowのスクリーンショットをPNGとして保存します。ウィンドウ名（タイトルバーに表示されている文字列）を指定してキャプチャできます。 同じ種類のウィンドウが複数開いている場合（例：Inspectorを3つ開いている場合）、すべてのウィンドウを連番で保存します。 3つのマッチングモードをサポート: exact（デフォルト）、prefix、contains - すべて大文字小文字を区別しません。

→ screenshot (WindowName: "Console")
→ Console画面の状態をPNGで保存
→ AIに視覚的なフィードバックを提供

9. control-play-mode - Play Modeの制御

Unity EditorのPlay Modeを制御します。Play（再生開始/一時停止解除）、Stop（停止）、Pause（一時停止）の3つのアクションを実行できます。

→ control-play-mode (Action: Play)
→ Play Modeを開始してゲームの動作を確認
→ control-play-mode (Action: Pause)
→ 一時停止して状態を確認

10. execute-dynamic-code - 動的C#コード実行

Unity Editor内で動的にC#コードを実行します。

Async対応:

• スニペット内で await が利用可能です（Task / ValueTask / UniTask など awaitable 全般）
• CancellationToken をツールに渡すと、キャンセルが末端まで伝播します

セキュリティレベル対応: 2段階のセキュリティ制御を実装し、実行可能なコードを制限。ツール自体を無効化するには、MCPツール設定UIのツールon/offトグルを使用してください。

• Level 1 - Restricted（制限付き）【推奨設定】

  • 基本的に全てのUnity APIと.NET標準ライブラリが利用可能
  • ユーザー定義アセンブリ（Assembly-CSharp等）も利用可能
  • セキュリティ上危険な操作のみをピンポイントでブロック：
    • ファイル削除系: File.Delete, Directory.Delete, FileUtil.DeleteFileOrDirectory
    • ファイル書き込み系: File.WriteAllText, File.WriteAllBytes, File.Replace
    • ネットワーク通信: HttpClient, WebClient, WebRequest, Socket, TcpClient全般
    • プロセス実行: Process.Start, Process.Kill
    • 動的コード実行: Assembly.Load*, Type.InvokeMember, Activator.CreateComInstanceFrom
    • スレッド操作: Thread, Taskの直接操作
    • レジストリ操作: Microsoft.Win32名前空間全般
  • 安全な操作は許可：
    • ファイル読み取り（File.ReadAllText, File.Exists等）
    • パス操作（Path.*全般）
    • 情報取得（Assembly.GetExecutingAssembly, Type.GetType等）
  • 用途：通常のUnity開発、安全性を確保した自動化

• Level 2 - FullAccess（フルアクセス）

  • 全てのアセンブリが利用可能（制限なし）
  • ⚠️ 警告: セキュリティリスクがあるため、信頼できるコードのみで使用

→ execute-dynamic-code (Code: "GameObject cube = GameObject.CreatePrimitive(PrimitiveType.Cube); return \"Cube created\";")
→ プロトタイプの迅速な検証、バッチ処理の自動化
→ セキュリティレベルに応じてUnity APIの利用を制限

PlayMode 自動テスト系ツール

11. simulate-mouse-ui - PlayMode UI要素のマウス操作シミュレーション

PlayMode中のUI要素に対してマウスクリック・長押し・ドラッグをシミュレーションします。EventSystemとExecuteEventsを使ってポインタイベントを直接ディスパッチするため、旧Input System・新Input Systemの両方に依存せず動作します。ゲームロジックがInput Systemを直接読み取る場合（例：Mouse.current.leftButton.wasPressedThisFrame）は、simulate-mouse-input を使用してください。

6つのアクションに対応: Click、LongPress、Drag（ワンショット）、DragStart/DragMove/DragEnd（分割ドラッグ）

→ screenshot (CaptureMode: rendering, AnnotateElements: true)
→ AnnotatedElementsから要素の座標（SimX/SimY）を取得
→ simulate-mouse-ui (Action: Click, X: 400, Y: 300)
→ simulate-mouse-ui (Action: LongPress, X: 400, Y: 300, Duration: 5.0)
→ simulate-mouse-ui (Action: Drag, FromX: 100, FromY: 500, X: 400, Y: 300)
→ simulate-mouse-ui (Action: DragStart, X: 100, Y: 500)
→ simulate-mouse-ui (Action: DragMove, X: 200, Y: 400, DragSpeed: 300)
→ simulate-mouse-ui (Action: DragEnd, X: 400, Y: 300)

https://github.com/user-attachments/assets/c7ee9103-c282-4f90-8b01-64bb17400f3e

12. simulate-mouse-input - Input System経由のPlayModeマウス入力シミュレーション

Input System経由でPlayMode中のマウス入力をシミュレーションします。ボタンクリック、マウスデルタ、スクロールホイールをMouse.currentに直接注入します。EventSystemのポインタイベントを発火するsimulate-mouse-uiと異なり、Mouse.currentを直接読み取るゲームロジック向けのツールです。このツールは Input System パッケージ導入時のみ利用可能で、Player SettingsのActive Input HandlingをInput System Package (New)またはBothに設定する必要があります。

5つのアクションに対応: Click、LongPress、MoveDelta、SmoothDelta、Scroll

→ simulate-mouse-input (Action: Click, X: 400, Y: 300)
→ simulate-mouse-input (Action: Click, X: 400, Y: 300, Button: Right)
→ simulate-mouse-input (Action: LongPress, X: 400, Y: 300, Duration: 2.0)
→ simulate-mouse-input (Action: MoveDelta, DeltaX: 100, DeltaY: 0)
→ simulate-mouse-input (Action: Scroll, ScrollY: 120)
→ simulate-mouse-input (Action: SmoothDelta, DeltaX: 300, DeltaY: 0, Duration: 0.5)

13. simulate-keyboard - PlayModeでのキーボード入力シミュレーション

Input System経由でPlayMode中のキーボード入力をシミュレーションします。単発のキータップ、長押し、複数キーの同時押し（例：Shift+Wでスプリント）に対応しています。このツールは Input System パッケージ導入時のみ利用可能で、Player SettingsのActive Input Handlingを Input System Package (New) または Both に設定する必要があります。ゲームコードがInput System API（例: Keyboard.current[Key.W].isPressed）で入力を読み取っている必要があり、レガシーの Input.GetKey() には対応していません。

3つのアクションに対応: Press（ワンショットタップまたは時間指定ホールド）、KeyDown（キーを押し続ける）、KeyUp（押下中のキーを解放）

→ simulate-keyboard (Action: Press, Key: Space)
→ simulate-keyboard (Action: Press, Key: W, Duration: 2.0)
→ simulate-keyboard (Action: KeyDown, Key: LeftShift)
→ simulate-keyboard (Action: KeyDown, Key: W)
→ screenshot (CaptureMode: rendering)
→ simulate-keyboard (Action: KeyUp, Key: W)
→ simulate-keyboard (Action: KeyUp, Key: LeftShift)

14. record-input - PlayMode中の入力記録

PlayMode中のキーボード・マウス入力をフレーム単位でJSONファイルに記録します。Input Systemのデバイス状態差分によりキー押下、マウス移動、クリック、スクロールイベントをキャプチャします。このツールは Input System パッケージ導入時のみ利用可能です。

→ record-input (Action: Start)
→ record-input (Action: Start, Keys: "W,A,S,D,Space")
→ record-input (Action: Stop)
→ JSONファイルが .uloop/outputs/InputRecordings/ に保存される

15. replay-input - 記録された入力のPlayMode再生

記録されたキーボード・マウス入力をPlayMode中に再生します。JSON記録を読み込み、Input System経由でフレーム単位で入力を注入します。ループ再生と進捗モニタリングに対応しています。このツールは Input System パッケージ導入時のみ利用可能です。

→ replay-input (Action: Start)
→ replay-input (Action: Start, InputPath: "scripts/my-play.json", Loop: true)
→ replay-input (Action: Status)
→ replay-input (Action: Stop)

ツールリファレンス

全ツールの詳細仕様（パラメータ、レスポンス、使用例）については TOOL_REFERENCE_ja.md を参照してください。

Unity CLI Loop 拡張ツールの開発

Unity CLI Loopはコアパッケージへの変更を必要とせず、プロジェクト固有のツールを効率的に開発できます。 型安全な設計により、信頼性の高いカスタムツールを短時間で実装可能です。 (AIに依頼すればすぐに作ってくれるはずです✨)

開発した拡張ツールはGitHubで公開し、他のプロジェクトでも再利用できます。公開例は uLoopMCP-extensions-sample を参照してください。

using System.ComponentModel;

public class MyCustomSchema : BaseToolSchema
{
    [Description("パラメータの説明")]
    public string MyParameter { get; set; } = "default_value";

    [Description("Enumパラメータの例")]
    public MyEnum EnumParameter { get; set; } = MyEnum.Option1;
}

public enum MyEnum
{
    Option1 = 0,
    Option2 = 1,
    Option3 = 2
}

public class MyCustomResponse : BaseToolResponse
{
    public string Result { get; set; }
    public bool Success { get; set; }

    public MyCustomResponse(string result, bool success)
    {
        Result = result;
        Success = success;
    }

    // 必須のパラメータなしコンストラクタ
    public MyCustomResponse() { }
}

using System.Threading;
using System.Threading.Tasks;

[McpTool(Description = "私のカスタムツールの説明")]  // ← この属性により自動登録されます
public class MyCustomTool : AbstractUnityTool<MyCustomSchema, MyCustomResponse>
{
    public override string ToolName => "my-custom-tool";

    // メインスレッドで実行されます
    protected override Task<MyCustomResponse> ExecuteAsync(MyCustomSchema parameters, CancellationToken cancellationToken)
    {
        // 型安全なパラメータアクセス
        string param = parameters.MyParameter;
        MyEnum enumValue = parameters.EnumParameter;

        // 長時間実行される処理の前にキャンセレーションをチェック
        cancellationToken.ThrowIfCancellationRequested();

        // カスタムロジックをここに実装
        string result = ProcessCustomLogic(param, enumValue);
        bool success = !string.IsNullOrEmpty(result);

        // 長時間実行される処理では定期的にキャンセレーションをチェック
        // cancellationToken.ThrowIfCancellationRequested();

        return Task.FromResult(new MyCustomResponse(result, success));
    }

    private string ProcessCustomLogic(string input, MyEnum enumValue)
    {
        // カスタムロジックを実装
        return $"Processed '{input}' with enum '{enumValue}'";
    }
}

カスタムツール用 Skills

カスタムツールを作成した際、ツールフォルダ内に Skill/ サブフォルダを作成し、SKILL.md ファイルを配置することで、LLMツールがSkillsシステムを通じて自動的にカスタムツールを認識・使用できるようになります。

仕組み:

1. カスタムツールのフォルダ内に Skill/ サブフォルダを作成
2. Skill/ フォルダ内に SKILL.md ファイルを配置
3. uloop skills install --claude を実行（バンドル + プロジェクトのSkillsをまとめてインストール）
4. LLMツールがカスタムSkillを自動認識

ディレクトリ構造:

Assets/Editor/CustomTools/MyTool/
├── MyTool.cs           # ツール実装
└── Skill/
    ├── SKILL.md        # スキル定義（必須）
    └── references/     # 追加ファイル（オプション）
        └── usage.md

SKILL.md のフォーマット:

---
name: uloop-my-custom-tool
description: "ツールの説明と使用タイミング"
---

# uloop my-custom-tool

ツールの詳細ドキュメント...

スキャン対象（Skill/SKILL.md ファイルを検索）:

• Assets/**/Editor/<ToolFolder>/Skill/SKILL.md
• Packages/*/Editor/<ToolFolder>/Skill/SKILL.md
• Library/PackageCache/*/Editor/<ToolFolder>/Skill/SKILL.md

完全な例は HelloWorld サンプル を参照してください。

より実践的なサンプルプロジェクトは uLoopMCP-extensions-sample を参照してください。

その他

Unity CLI Loop 関連ファイル

UserSettings/UnityMcpSettings.json はユーザー個別のエディタセッション状態を保持するため、常にローカル専用です。

プロジェクトルートの .uloop/ ディレクトリには、CLIキャッシュ、ツールレジストリ、ランタイム出力が格納されます。大半はローカル専用ですが、一部のファイルはチーム共有のためにオプションでgit管理できます。

**/.uloop/*
!**/.uloop/settings.permissions.json
!**/.uloop/settings.tools.json

ライセンス

MIT License