scenario-unity-expert

Unityエキスパート（テクニカルディレクターおよびエージェントプロトコル）

Unityでのエキスパート作業は、数値を基準に進めるサイクルです。予算を設定し、ステージを1つ構築し、測定して確認し、修正してから次に進みます。マウスを使えないエージェントがこれを実現するには、操作ごとに適切なチャンネルを選び、シリアライゼーションを通じて明示的に保存しながら編集し、自分の目だけを決して頼りにしないことが必要です。このスキルはそのプロトコルであり、すべての scenario-unity-* スキルがインポートする共通ツールキット（scripts/）であり、チームのマップです。対象：Unity 6000.3.21f1（6.3 LTS）、URP 17.3、macOS Apple Silicon。ここに記載された関連スキルが利用可能なスキルに見つからない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマを参照して作業を続け、不足しているスキルを明記してください。

状況（2026-09-24、ブラインド評価とリファクタリング後）： ここでは、すべてのツールキット関数がUnity 6000.3.21f1で実行されました（tests/code/unity-expert/run_all.sh --live --builds。結果はarchive/tests/unity-expert/live_results.jsonl）。リファクタリング前からの呼び出しはすべて変更されていません。

姿勢（エキスパートとしての差分）

1. プロジェクトごとにエディターは1つ。実行中のエディターを優先します。 「エディターで同じプロジェクトを開いている間は、バッチモードでプロジェクトを開くことはできません」（6.3 Manual）。エディターがプロジェクトを保持している場合は、ut_liveを使って操作し、.unity／.prefab／.assetのYAMLを直接編集しないでください。fileIDを誤る可能性があり、再インポートまで問題が見えず、間違ったシーンを操作しやすいためです（Unityのunity-cliスキル）。
2. ジョブの信頼性は、結果行の正確さで決まります。 「終了した」ことではなく、AGENT_RESULTエンベロープとログのスキャンを確認して合格と判断してください。どのアセンブリであってもコンパイルエラーがあると、「Scripts have compiler errors」により、すべてのバッチジョブが中止されます（確認済み。実行中のエディターでは同様の状態がSafe Modeで、これもcom.unity.pipelineをブロックします）。
3. ピクセルより数値を優先し、fpsではなくミリ秒で考えます。 60 fpsでは16.67 ms、30 fpsでは33.33 msです。モバイルではサーマル対策として、約65%の予算を確保します（Unity profiling e-book）。エディターのPlayモードは反復作業に使い、最終判断は対象デバイスのうち最も性能が低いもの向けの開発ビルドで行います。
4. 目で見て、確認し、キャプチャに潜む落とし穴を把握します。 すべてのフレームをut_review.image_checksに通し、開いて確認するコンタクトシートも作成してください。Epicのライティングエージェントは真っ白なフレームを承認しました（scenario-unreal-expertのソース）。ここでは、バッチキャプチャで初回フレームの白いマテリアル、カリングされた2Dライト、バインドポーズ、Overlay UIの欠落、黒い金属が確認されました（チームによる確認）。エディターのキャプチャでのみ問題が起きる場合は、まずプレイヤーで再確認してください。エージェントが構築したレベルは「90%」完成していても、ドアの前に棚が置かれていることがあります（Code Monkey、ppFshgFOgXU [00:10:52]）。
5. 起動時にプラットフォームを固定します。 バッチジョブ内でのターゲット切り替えは、何も起きないまま無視されます（6.3 Manual）。起動時に-buildTarget／-activeBuildProfileを指定し、ターゲットごとにプロセスを1つ使ってください。エディターは最後に使用したプラットフォームで再起動するため（確認済み）、固定してください。
6. evalより名前付きジョブを使います。 調査にはevalを使い、繰り返す処理には名前付きジョブを使ってください。「コマンドを書き残すことで、そのワークフローを決定的かつ再現可能なものにできます」（DgNrgZeJOxQ [00:07:41]）。汎用のrun-commandツールは挙動がぶれます（git-amend、VPjo-M6mPkE [00:03:54]）。
7. テストを契約にします。 失敗するテストと制約をセットで作業を依頼してください（「カードデータにのみ変更を限定できます」、DgNrgZeJOxQ [00:05:31]）。-runTestsを-quitと併用しないでください。
8. ビジュアルエディターの実情を正直に伝えます。 Shader Graph、VFX Graph、Animatorウィンドウ、UI Builder、Tile Paletteでのペイント、地形のスカルプトには、オーサリングAPIがありません。代替手段（HLSL、公開プロパティを持つテンプレート、AnimatorController API、UXML／USSテキスト、TerrainData）を使うか、人が行う手順を明記してください。

チャネル

チャネル	用途	コスト（ここで計測）	ルール
バッチジョブ ut_run.run_method	エディターがプロジェクトを開いていない場合のすべての処理	1 ジョブあたり 6～13 秒（エディターの起動時間を含む）	デフォルトでは -nographics を使用します。キャプチャ、ベイク、プロファイリングでは graphics=True を使用します（-nographics でベイクしないでください）。非同期ジョブでは quit=False を使用します。結果が出た後もハングするエディターは PID で終了します（grace、10 秒）
常駐ヘッドレスエディター＋AgentKit ブリッジ ut_live.start_headless, call	連続して多数の呼び出しを行う場合	起動時に 5～20 秒、その後は呼び出しごとに 0.1～0.5 秒	プロジェクトとライセンスシートを保持します。stop_headless で停止します
ユーザーの GUI エディター＋AgentKit ブリッジ ut_live.call, eval	ユーザーがプロジェクトを開いている場合	ヘッドレスと同じコードパス（テスト中は GUI ウィンドウがないため実行されません）	AgentKit をコンパイルするため、ユーザーが Unity に一度フォーカスを移す必要がある場合があります。許可を得ずにユーザーのシーンを再度開かないでください。変更内容は保存してください
Unity CLI＋com.unity.pipeline ut_live.cli_*, eval（自動）	最速のライブチャネル：151 個のコマンド、ドメインリロードなしの Roslyn eval	0.5～1.1 秒の初回呼び出し後、eval は 0.03～0.15 秒	CLI 1.0.0-beta.11（ポータブルコピー）、エディター起動前にインストールされたパッケージ 0.7.0-exp.1。セーフモード、場合によってはサンドボックスによりブロックされます
MCP	unity mcp または審査済みのコミュニティサーバーのみ		Unity の AI Assistant MCP サーバーは非推奨です（「代わりに Unity CLI を使用してください」）
テストフレームワーク ut_run.run_tests	EditMode と PlayMode の判定、コンテンツの検証	プラットフォームあたり約 14 秒	NUnit XML を解析します。テスト失敗時は終了コード 2 になります（確認済み）

ut_live.channel(P) は batch、bridge、pipeline、または blocked を選びます（ユーザーに確認してください）。「接続できません」という表示だけでは、エディターが閉じているとは限りません。まずセーフモードとサンドボックス化されたシェルを除外してください（unity-cli スキル）。

最初に確認すること

一度に、対象プラットフォームとデバイスクラス、フレーム予算（デスクトップはデフォルトで 60 fps、モバイルは 65% で 30 fps）、2D か 3D か、パイプライン（デフォルトは URP 17.3。HDRP はハイエンド PC またはコンソール専用）、品質ティア、アートスタイル、ユーザーのエディターでプロジェクトを開いているか、成果物を確認します。次に ut_env.preflight(P) と AgentJob.Echo を実行し、報告された内容（パイプラインアセット、色空間、アクティブなターゲット、品質レベル、Enter Play Mode の設定、入力ハンドラー、スクリプティングバックエンド）を計画に記載します。

ワークフロー（エキスパートループ）

1. 数値でブリーフを作成します。 プラットフォームごとの予算、解像度、スケール、スタイルを定めます。ゲート：以降のすべてのチェックで比較できる数値があること。
2. 事前確認を行います。 ライセンスの残日数、モジュール、ロック状態、コンパイルの健全性（Echo ジョブ 1 件）を確認します。ゲート：ok、コンパイルエラーがゼロ、新規の CS0618 警告がゼロ。
3. ベースラインを取得します。 AgentAudit.AuditScene／AuditAssets、固定ブックマークのキャプチャ（AgentCapture.SaveBookmark）、パフォーマンスが重要な場合は Play モードのプロファイルを取得します。ゲート：監査エラーを修正するか一覧に記載し、コンタクトシートを開いていること。
4. 小さく冪等なジョブ（references/writing-jobs.md）でステージを 1 つ構築します。取得または作成、シリアライズされた編集、明示的な保存を行います。ドメイン作業は担当者（以下を参照）に割り当てます。
5. 測定します。 監査、テスト、AgentProfile.PlayModeTimings と ut_stat.budget_check、またはビルドの概要を再実行します。ゲート：ブリーフの数値と照合すること。
6. 見た目を確認し、チェックします。 同じブックマークで ut_review.review_capture を実行し、シートを開き、ドメインスキルの批評に基づいて評価します。ゲート：空白またはマゼンタのフレームがなく、彩度が失われておらず、変更が見えること。
7. 次に進む前に修正します。 一度に変更は 1 つだけにし、ut_review.compare と ut_stat.compare_frames で同等性または改善を証明します。
8. 証拠を添えて納品します。 各ステップについて、Unity の呼び出し（references/toolkit-map.md）を記載し、その後に 検証済み（実行内容、ジョブ ID、数値またはフレーム）と 仮定（未実行のもの、[verify]、デフォルト値）を記します。数値と実際に確認したフレームなしに、シーン、シェーダー、レベル、ビルドを完了したと判断してはいけません。

数値

値	基準	出典
16.67 / 33.33 ms	60 / 30 fps のフレーム予算	プロファイリングの電子書籍
x 0.65	モバイルの持続的な予算（60 fps で 10.8 ms、30 fps で 21.7 ms）	プロファイリングとモバイルの電子書籍
6 to 13 s	このプロジェクトでの 1 回のバッチジョブ（エディターの起動を含む）	実測
about 14 s	run_tests のプラットフォーム実行 1 回（EditMode テスト 2 件、PlayMode テスト 1 件）	実測
60 s (12 s incremental), 114.7 MB	デモシーンの macOS Mono プレイヤービルド（ユニバーサル）	実測
259 s (25 s incremental), 12.2 MB	同じシーンの Web ビルド（IL2CPP、Brotli）	実測
0.1 to 0.5 s / 0.03 to 0.15 s	AgentKit ブリッジ／Pipeline eval を介したライブ呼び出し（2 回実行）	実測
30 days	Personal ライセンスのオフライン期間（license_ok() で読み取り）	実測 + Unity サポート FAQ
10 s / 120 s	ut_run が、結果を返した後に終了行を出さず無応答になったエディターを終了するまでの猶予時間	ツールキットのデフォルト

品質ゲート

• 測定可能性： エンベロープの ok に加え、compile_errors == [] であること。監査の counts.error == 0 であること。NUnit の failed == 0 かつ total > 0 であること。budget_check の判定が pass であること（warn の場合は理由が必要です）。開発プレイヤーで gc_check を実施すること。build_summary の結果が Succeeded で、サイズが予算内であること。ロック状態を記録すること。
• 視覚： すべてのキャプチャが image_checks に合格し（all_white、all_black、uniform、magenta がないこと）、実際に開いて確認済みであること。変更前後で同じブックマークを使用すること。
• 習慣（references/routing-handoffs.md のセクション 6）：すべてのステージで同じ build_target を使用すること。p95 と最悪フレームの両方を、変更前と変更後に約 200 フレームのキャプチャ 2 件ずつで測定すること（YOtDVv5-0A4 [00:17:00]）。対象デバイスのクラスで開発プレイヤーを実行して判定すること（ZkvK0mX-id4 [00:10:27]）。コードが完成する前に開発ビルドを 1 回実行すること（メインスレッド以外での Unity 呼び出しを検出できるのはこの方法だけです）。サイズは出荷する出力で測定すること。各ビルドの前にシーンのリストを確認すること。想定されるエラーは LogAssert.Expect で指定すること。

よくある間違い

間違い	発生する問題	対処
GUI エディターが使用中のプロジェクトでバッチジョブを実行する	拒否される、または Library が破損する	ut_live（ツールキットが ProjectLockedError を発生させます）
-runTests と一緒に -quit を指定する	XML が出力されず、判定も行われない	ut_run.run_tests を使います（-quit は渡しません）
-nographics を指定してキャプチャまたはベイクを行う	フレームが空になる、「no graphics device」と表示される、ライトマップが生成されない	graphics=True を指定します
ジョブ内でプラットフォームや定義を切り替える、またはビルド時だけターゲットを固定する	古いターゲットや定義が使われる。ステージごとにテクスチャが再インポートされる	すべてのステージで build_target= を指定するか、2 回に分けて呼び出します
GetComponent<T>() ?? AddComponent<T>() や Unity オブジェクトに対する ?. を使う	何も追加されず、次に MissingComponentException が発生する（偽の null によるもので、実測済みです）	明示的に == null を使うか、TryGetComponent を使います
AgentJob.List("k") ?? defaults	デフォルト値が適用されない（空のリストであり、null ではないため）	AgentJob.ListOrNull("k") ?? defaults、TryList、Has を使います
BuildReport の totalSize からビルドサイズを見積もる	IL2CPP の出荷しないフォルダーもカウントされ、数 GB になる	build_summary を使います（ディスク上の出力を対象にします）
「Access token is unavailable」をライセンスエラーだと信じる	誤報	拒否を示す行は「No valid Unity Editor license found」です
エディターを開いたままシーンの YAML を手動で編集する	変更が反映されない、または失われる	ライブジョブを実行し、その後 AgentBridge.SaveAll を使います
Unity を名前で指定して終了させる	他のエージェントのエディターまで終了する	PID のみで停止します（stop_headless の猶予タイムアウトを使用）

チームへの振り分けと引き継ぎ

担当者に応じて振り分けます：scenario-unity-architecture（コード、セーブデータ、入力）、scenario-unity-world-building （地形、ブロックアウト、ストリーミング）、scenario-unity-rendering-lighting（パイプライン、ライティング、ポスト処理）、 scenario-unity-shaders（HLSL、Shader Graph、レンダラーフィーチャー）、scenario-unity-vfx（VFX Graph、 パーティクル）、scenario-unity-animation（Animator、Timeline、Cinemachine）、scenario-unity-2d（スプライト、 タイルマップ、2D ライト）、scenario-unity-ui（uGUI、UI Toolkit）、scenario-unity-gameplay（物理演算、AI、 ネットコード、オーディオ）、scenario-unity-pipeline-automation（インポート、Addressables、CI、ビルド）、 scenario-unity-performance（プロファイリング、メモリ、バッチ処理）、scenario-unity-mobile（Android、iOS、 ストア）、scenario-unity-web（Web ビルド、サーバー、WebGPU）。キーワード一覧、ペルソナのチェーン、引き継ぎパケットの全容は references/routing-handoffs.md を参照してください。ブラインド評価で2つのスキルの境界にまたがった項目（PSO のウォームアップ、GPU Resident Drawer、VFX シェーダー、ドアを通過する NavMesh、足の滑り、UI Toolkit より uGUI、Web フォント、ストリッピング、Addressables の重複、静的状態）には、それぞれ1つの担当者と、シーム表に示された検証方法があります。ブリーフには両方を記載してください。各パケットには、プロジェクトとチャンネル、番号付きのブリーフ、Unity の呼び出しを含む実施内容、証拠（監査 JSON、フラグ付きコンタクトシート、CSV 判定、NUnit の合計、ビルド概要）、検証済みの事項、仮定、未解決の問題、境界を含めます。受け取った側は、それを基に作業を進める前に、証拠の一部を再現します。

Unity 6.3 に関する注意事項（一覧は references/unity-6.3-traps.md）

• Render Graph のみ（Compatibility Mode は削除済みで、define は 6.4 で無効になります）。_CLUSTER_LIGHT_LOOP は _FORWARD_PLUS に置き換わります。
• FindObjectsByType<T>(FindObjectsSortMode.None)、Rigidbody.linearVelocity／linearDamping、 [SerializeField] はフィールドにのみ適用、Lightmapping.TryGetLightingSettings（未割り当ての場合にゲッターが例外をスローすることを確認済み）。
• テンプレートは Input System のみを実行します。Play モードに入るとドメインがリロードされます（6.6 ではデフォルトが変更されます： SubsystemRegistration で静的状態をリセットし、ExitingPlayMode で購読を解除します）。テンプレートなしの -createProject は Built-in になります。
• 6000.3.21f1 では、Object.Destroy は階層のすべてのレベルで OnDisable をすでに呼び出します （確認済み。差分によると、6.4 より前は直接の子のみ）。OnDisable で登録を解除し、 冪等性を確保したうえで OnDestroy でも解除してください。
• Build Settings は Build Profiles に置き換わります。6.5 より前は、プロファイルを作成する公開 API はありません。 ...WithReport より IPreprocessBuildWithContext を使用してください。アクティブなプラットフォームプロファイルでの EditorUserBuildSettings の変更は、すべてのプラットフォームプロファイルに適用されます。プロファイルのテクスチャ圧縮設定は Library/ に保存されます。
• パッケージのバージョンを固定してください。manifest には Cinemachine 2.10.7 と記載されていますが、引数なしの Client.Add では 3.1.7 がインストールされました（確認済み）。IAP 4.15.1 と LevelPlay 8.10.1 はドキュメントの記載（IAP 5、LevelPlay 9）より古いバージョンです。
• Web：URP テンプレートには Manual に記載された gzip ではなく Brotli が含まれます（確認済み）。WebGPU は実験的機能です（6.6 からオプトインで本番利用可能）。Built-in RP は 6.5 から非推奨になります。

macOS 固有の注意事項

• Editor のパスは /Applications/Unity/Hub/Editor/6000.3.21f1/Unity.app/Contents/MacOS/Unity です。Hub モジュール （Web、iOS、Android）は .../6000.3.21f1/PlaybackEngines/ にあります。Xcode 26.6 は App Store の要件を満たします。
• Metal のみです。Apple Silicon では CPU ライトマッパーを利用できません（GPU ライトマッパーにはグラフィックスが必要です）。VFX Graph パネルには GPU の計測時間が表示されません。大半の Editor フレームで GPU Frame Time は 0 を示すため、プレイヤーで GPU を計測してください。
• Personal ライセンスでは、30 日ごとに Unity Hub にサインインしてください（ut_env.license_ok()）。ツールキットは、 チェックサムを検証したポータブル CLI を使用します（references/live-channels.md）。
• スペースを含むパスは機能しました。すべてのパスを引用符で囲んでください。<Product>_BurstDebugInformation_DoNotShip は絶対に出荷しないでください。自分が起動していない Editor を終了しないでください。

共有ツールキット（scripts/；正確な API は references/toolkit-map.md を参照）

import sys; sys.path.insert(0, "<scenario-unity-expert>/scripts").

• ut_env（エディター、ライセンス、base_project、install_agentkit、ロックルール、preflight）；ut_run （run_method(project, method, args=None, timeout=1800, graphics=False, quit=True, build_target=None, grace=None, result_grace=None)、 run_tests、build、scan_log）；ut_live（ブリッジ、ヘッドレスエディター、CLI、Pipeline の eval）； ut_review（image_checks、compare、contact_sheet、review_capture）；ut_stat （budget_check、summarize_csv、compare_frames、build_summary）。
• C# AgentKit（scripts/AgentKit/）：AgentJob（List／Dict は常に null 以外； キーがない場合は TryList、ListOrNull）、AgentCapture（マテリアルと 2D ライトをウォームアップ）、 AgentAudit、AgentBuild、AgentProfile、AgentBridge、AgentJson。

リファレンス

• references/toolkit-map.md：各ツールキット関数の背後で呼び出される Unity API、およびレポート形式 （Verified、Assumed）。
• references/writing-jobs.md：ドメインスキルによる AgentKit ジョブの作成方法（スケルトン、ルール、非同期ジョブ、 検出事項）。
• references/live-channels.md：ブリッジ、ヘッドレスエディター、Unity CLI と com.unity.pipeline、MCP、 サンドボックス、Safe Mode。
• references/unity-6.3-traps.md：リードとライターが確認した落とし穴、文書化された 6.3 の事実、 差分の修正、初回実行チェックリスト。
• references/routing-handoffs.md：ルーティング、境界、ペルソナチェーン、引き継ぎパケット、受け入れチェック、 検証の習慣。
• references/procedures.md：リードの 9 つの手順。それぞれにライブテストと結果が含まれます。
• references/gui-paths.md：同じタスクを実行するためのウィンドウとメニュー。
• references/sources.md：認証情報、URL、タイムスタンプを含むすべてのソース、 改訂履歴。