unity-pipeline

Unity Pipeline（エージェント制御）

unity command <name> [args] でコマンドを実行します。名前を指定せずに unity command を実行すると、インスタンスが公開している機能の一覧が表示されます。サーバーは 2 つあります。Editor（7800-7849。エディターとともに自動起動）と Runtime（7900-7949。dev Player ビルドの場合のみ）。unity command --query <term> を使うと、名前、説明、タグで一覧を絞り込めます。

1. インストールと確認

unity pipeline install            # install into current project (or --project-path)
unity pipeline list               # confirm the editor instance + server are reachable
unity status --until-ready        # wait until the editor server is ready
unity command editor_status       # confirm the editor server answers

すでに開いているエディターでは、通常はウィンドウにフォーカスが戻ったときなど、次の更新時にパッケージが読み込まれます。それまでは unity status が STATUS_PIPELINE_LOAD_PENDING を報告します。この状態が続く場合は、ユーザーに Unity Editor ウィンドウへ切り替えてもらってから、unity status --until-ready を再実行してください。

2. 自律編集ループ（Editor）

これがエージェントの基本的なワークフローです。エディターを起動したままにして、コードを変更し、再コンパイルしてテストします。

# 1. Keep the editor ticking even when unfocused/minimized. REQUIRED before headless work —
#    Unity otherwise throttles or stalls update/compile when it isn't the active app.
unity command set_autotick --enable true

# 2. Edit C# source files on disk normally.

# 3. Recompile (async: triggers a domain reload, then poll until done).
unity command recompile
unity command recompile_status    # repeat until "completed" or "up_to_date"
#   Tolerate connection errors while the domain reload is in flight — that is expected.
#   If recompile_status reports failed=true, read its "errors" array and fix before testing.

# 4. (Optional) List available tests without running them.
unity command list_tests --mode editor            # mode: all | editor | playmode

# 5. Run tests (filter to keep it fast).
unity command run_tests --mode editor --filter MyFixture.MyTest

run_tests のモード：all | editor | playmode。filter_type：testName | assembly | category。実行時間が長い場合は --async_tests true を指定し、unity command test_status をポーリングしてください（中止するには unity command cancel_tests を実行します）。

既知の注意点： 選択したテストが 1 つでも 失敗 すると、run_tests は失敗の詳細ではなく、不透明な結果を返す場合があります。より狭い --filter で再実行するか、エディターの Test Runner／ログを調べて実際の失敗内容を確認してください。

終了コードの確認。 終了コードは「呼び出し方を修正する」場合と「Editor で失敗が発生した」場合を区別します。この区別が、このループの前提となります。

終了コード	意味	対処方法
2	引数が不正です。フラグの誤記、型の誤り、位置引数の過剰などが該当します。何も実行されていません。	コマンドラインを修正して再試行してください。エラーには問題点が記載され、多くの場合は正しいフラグも示されます。
6	コマンドの実行に失敗したか、接続可能な Editor がありません。	エラーを確認してください。Pipeline インスタンスが見つからないという内容の場合は、Editor に接続できていません。unity status --until-ready で待機するか（または unity pipeline list で Safe Mode になっていないか確認して）、再試行してください。それ以外の場合、同じ呼び出しを再試行しても解決しません。

終了コードが 2 の場合、変更せずに再試行してはいけません。終了コードが 6 の場合、コマンドラインを書き換えてはいけません。

3. Runtime メソッドのリロード

ドメインリロードなしで、実行中のゲームのゲームプレイコードを変更できます。ゲームは実行中である必要があります。Editor の Play Mode に入る（unity command editor_play）か、dev Player を実行してください。Runtime Pipeline ドライバー（Project Settings > Pipeline > Runtime で有効化）は、Awake 時にタグ付きメソッドを自動検出します（手動登録は不要）。Mono のみが対象です。Editor の Play Mode と Mono のデスクトップ dev ビルドで使用でき、IL2CPP は対象外です。ローカルリクエストにはトークンが自動で挿入されます。

reload_file

メソッド本体を直接編集します。別ファイルや定型コードは不要です。

1. Play Mode に入る前に、MonoBehaviour のメソッドに [MethodReload] を付けて再コンパイルしてください。リロードフックはメソッドにコンパイルされるため、ゲームの実行中にタグを付けても効果はありません。Play Mode を終了して再コンパイルし、もう一度入ってください。
2. ゲームの実行中に、ディスク上のメソッド本体を編集します。
3. 変更を適用します（反復する場合は再実行します）。

   unity command reload_file --filename Assets/Spinner.cs
   

   デバッグ可能にするには --pdb を追加します。ソースに対応付けられたポータブル PDB が出力され、元のファイルに設定したブレークポイントが有効になります（IDE をアタッチして Editor Attaching を有効にしてください。最適化なしでコンパイルされます）。

   unity command reload_file --filename Assets/Spinner.cs --pdb
   

制約：void のインスタンスメソッドのみ。public メンバーのみ。デバッグには --pdb が必要です（デフォルトではシンボルは出力されません）。

unity command methodreload_status で有効なオーバーライドを確認できます。reload_file のオプション：--timeout <ms>（デフォルトは 30000）、--assemblyDir <dir>（DLL をメモリ内ではなく保存）。cleanup_methodreload --assemblyDir <dir> で古い DLL を削除します。

CLI は --timeout を秒単位で独自に処理します。パッケージの --timeout を渡すには、コマンドの引数を -- の後に指定してください。

unity command reload_file -- --filename Assets/Spinner.cs --timeout 60000

4. 一括構築：run_script（ビルダーパターン）

大量の作業（多数のオブジェクトの作成、フィールドの接続、コンテンツの生成など）では、コードを バージョン管理されたプロジェクトスクリプトに記述し、run_scriptで名前付きの静的エントリーポイントを実行します。ドメインのリロードは不要で、プロトコル経由でコードを渡す必要もありません。反復にかかるのはメモリ内コンパイル（約2秒未満）だけで、15～20秒の再コンパイルは発生しません。

# 1. Write the builder OUTSIDE Assets/ (so the write triggers no asset import / domain reload),
#    e.g. AgentScripts/Build.cs:  public static class Build { public static int All() { ... } }
# 2. Run it — relative paths resolve against the project root (the parent of Assets/):
unity command run_script --file AgentScripts/Build.cs --entry Build.All
# 3. Iterate: edit the file, re-run. Useful extras:
unity command run_script --file AgentScripts/Build.cs --dry_run true   # compile-only check: diagnostics, nothing loaded or executed
unity command run_script --file AgentScripts/Build.cs --entry Build.All --args '[3, "Green"]'

基本的な指針：

• コードはrun_scriptを使ってディスク上のファイルに記述し、evalは本当にその場限りの1行コードに使います。 複数行のエスケープ済みC#文字列をeval経由で渡してはいけません。ファイルに書き込み、エントリーポイントを実行してください。
• コンパイルでは、プロジェクトの有効なエディター定義（UNITY_EDITOR、バージョン／プラットフォームのシンボル）が参照されます。 --definesは追加のシンボルを上乗せします。
• エントリーポイントではasync Task／Task<T>を使用できます。非同期で待機され（エディターは処理を継続するため、Unityのコンテキストで再開するawaitは自然に動作します）、Task<T>.Resultが返されます。 待機時間はtimeout_msで制限されます。タイムアウトすると、タスクは切り離されて実行を続けます。
• 実行時の例外は、ソースに対応付けられたfile:lineとともに返されます（実行時にはソースマップ付きPDBが常に出力され、最適化なしでコンパイルされます）。
• --mode hotpatchは、代わりに[MethodReload]によるインプレースのメソッド置換を適用します（reload_fileに委譲します）。この場合、entry／args／dry_runは拒否され、references／definesは適用されません。

5. C#をすばやく評価する（エディターまたは開発用Player）

本当にその場限りの1行コードにのみ使用してください。それより長いコードは、run_scriptで実行するファイルに記述します。 evalはデフォルトでエディターを対象とします。開発用Playerで実行するには、--runtime <process name>を追加します。

unity command eval "return 2 + 2;"
unity command eval "return UnityEngine.Time.timeScale;" --runtime MyGame
# Or evaluate a .cs file on disk. Keep it outside Assets/, where Unity would compile it as project source:
unity command eval_file AgentScripts/Scratch.cs

6. プロジェクト監査（エディター）

Project Auditorを使用した静的解析スキャンを実行し、修正が必要な問題をCSVに出力します。開始、状態の確認、読み取りの順に行います。

unity command audit                              # optional: --categories Code,ProjectSetting --output my.csv
unity command audit_status                       # repeat until terminal status

audit_statusは、completed（csvPathとissueCountを含む）、failed、unavailable、interrupted（ドメインのリロードによってスキャンが終了した状態。auditを再実行してください）のいずれかで終端状態になります。Codeカテゴリーのスキャンがアセンブリをコンパイルしてメインスレッドを占有している間も、ポーリングは応答します。同時に実行できるスキャンは1つだけです。2つ目のauditはbusyを返します。キャンセル機能はありません。スキャンを中断するにはポーリングを停止してください。

CSVの列：Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation （診断結果のみなので、すべての行が修正対象です。Recommendationに修正方法が記載されています）。

Project Auditorとそのルールが必要です。 unavailableは、エディターにProject Auditorがないか、解析ルールがないことを意味します。組み込みモジュールのエディターでは、ルールは別の com.unity.project-auditor-rulesパッケージにあります（unity command package_add --identifier com.unity.project-auditor-rules --confirm true）。messageフィールドを確認してください。クリーンなプロジェクトと誤認される可能性のある、空のcompletedスキャンをコマンドが報告することはありません。

注意事項

• 最初にset_autotickを実行してください。 これを設定しないと、エディターがフォーカスを失ったときに再コンパイルやテストが停止する場合があります。パッケージのウォッチドッグは、ティックループが稼働し続けることを前提としています。
• コマンドが停止しているように見えても、ハングではなくモーダルダイアログが開いている可能性があります。 ダイアログが閉じられるまでメインスレッドがブロックされます。コマンドの実行に時間がかかる場合は、unity command editor_statusを確認してください（ブロック中でも即座に応答します）。status: "blocked_by_dialog"の場合は、再試行せず、何がブロックしているか（dialog.title／message／buttons）を人に伝えてください。CLIからクリックすることはできません。
• メソッドのリロードにはゲームの実行が必要です。 reload_fileは実行中の ゲームに適用されます。まずエディターのPlay Modeに入り（unity command editor_play）、または開発用Playerを実行してください。
• Player専用コマンドには開発用Playerが必要です。 log、set_timescale、runtime_statusなどはRuntimeサーバーに接続します。このサーバーはエディター内では実行されません。
• 非同期コマンドはポーリングしてください。 recompileの後はrecompile_status、run_tests --async_testsの後は test_statusを実行します。トリガー呼び出しの応答だけで完了したと判断しないでください。
• 複数のインスタンスが実行中の場合は、対象を特定してください。--project-path <path>はエディターを選択し、--runtime <process name>または--runtime-path <port file>は開発用Playerを選択します。