scenario-unreal-expert

Unreal のエキスパート（テクニカルディレクターとエージェントプロトコル）

Unreal のエキスパートとしての作業は、数値に基づいて繰り返すループです。予算を設定し、1つのステージを構築し、測定して確認し、修正してから次へ進みます。マウスを使えないエージェントは、各操作に適切なチャネルを選び、Details パネルのように作業する（1つのトランザクションを実行し、明示的に保存する）ことで目的を達成します。また、自分の目だけを決して信頼してはいけません。このスキルは、プロトコル、scripts/ にある共有ツールキット、そしてチームとの連携方法を示すものです。対象：macOS Apple Silicon 上の UE 5.8。ここに記載された兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で作業する場合は、ツールのスキーマをもとに続行し、不足している点を明示してください。

ステータス（2026-09-24）： UE 5.8 はインストールされていません。scripts/ と references/ にあるエンジン内の呼び出しは、まだ Unreal で実行されていません。純粋な Python 部分はオフラインで実行し、合格しています（テストファイル8件、Python 3.14 で314件、3.9で311件のチェック）。エンジンのインストール後に最初に実行する操作： UE_TEST_PROJECT にスクラッチプロジェクトを設定して tests/code/unreal-expert/run_all.sh --live を実行し、その後 references/ue-5.8-traps.md のセクション7を確認してください。

1. 実行チャネル

チャネル	用途	ルール
Epic Unreal MCP（プラグイン ModelContextProtocol、実験的）、.mcp.json 経由の MCP クライアント	提供済みのツールセット（アクター、シーン、マテリアルインスタンス、Sequencer、PCG、UMG、アニメーション）で対応する構造化編集、エディターを開いた状態で使用	Unreal MCP と All Toolsets を有効にします。「接続済みなのに何もできない」場合は、Epic のウェビナーによるとドキュメントに記載されていない Editor Toolset を追加します（Sam Deiter、k0tgmrBuIJc [00:18:13]）。-ModelContextProtocolStartServer -ModelContextProtocolPort=8000 または ModelContextProtocol.StartServer で起動します。ModelContextProtocol.GenerateClientConfig ClaudeCode は .mcp.json を書き込みます。エディターを先に、エージェントを後に起動します。呼び出しはゲームスレッド上で逐次実行されます。決して重ねて実行しないでください。今必要なツールセットに限って describe_toolset を使います。Niagara のものは「ほぼ25万件」です（k0tgmrBuIJc [00:46:04]）。ループバック接続で、認証はありません。
実行中のエディター内の Python（ue_remote.PythonRemote、または MCP サーバー上のカスタム Python ツールセット）	ループ、監査、ツールセットにないあらゆる処理、スクリーンショット	Python Remote Execution を有効にします（Project Settings > Plugins > Python）。完全な unreal API が使えます。エディターは呼び出しの合間にティックします。1回の呼び出しは、実行内容を報告する名前付きトランザクション1つに相当します。
ヘッドレスコマンドレット（ue_run.run_python、UnrealEditor-Cmd <uproject> -run=pythonscript）	監査、インポート、一括編集、検証、CI、プロジェクトを開いたエディターがない場合	レベルは読み込まれません（map= を指定すると読み込みます）。モジュールは少なく、レンダリングもありません。起動時にアセットレジストリの準備を待ちます（get_asset_registry().wait_for_completion()、5.8 の一括処理の例）。ジョブの成功は、起動時のジョブ ID に対応する UE_RESULT 行でのみ判定します。終了コードでは判定しません。保存するコマンドレットで、エディターが開いているプロジェクトに触れてはいけません。エディターが書き込みロックを保持しているためです（Jamie Dale、0guOMTiwmhk [01:17:18]）。
フルエディター、一度だけ実行（mode="editor"：-ExecutePythonScript、mode="latent"：終了するまでティックする起動）	フルモジュールが必要なジョブ。latent：エディターを起動せずにスクリーンショットやレンダリングを行う	-ExecutePythonScript はスクリプト直後に終了するため、ティックは発生しません。ue_run は -ScriptErrorsAreFatal（5.5）を追加するため、スクリプトが失敗するとプロセスも失敗します。Latent ジョブはジェネレーターです。yield は1ティックを意味します。
Remote Control API（ue_remote.RemoteControl、127.0.0.1:30010）	既知のオブジェクトへのプロパティの一括書き込み、ライブプリセット、-game ビルド	WebControl.StartServer を実行するまで無効です。5.8 では許可リストにより、リモート UFUNCTION 呼び出しがデフォルトで無効になっています（5.8 のリリースノート）。C++ 名、Undo 用の WRITE_TRANSACTION_ACCESS、公開された EditAnywhere プロパティのみを使用します。
コンソールと cvar	統計、ビューモード、品質設定、HighResShot	Python からは unreal.SystemLibrary.execute_console_command(world, cmd) を使います［要確認］。起動時には -DPCVars= を使います（初期化前に指定し、読み取り専用 cvar を上書きします。Profiling with Purpose、C-AjCqjKRSs [00:14:13]）。-ExecCmds は使いません。変更した設定は元に戻します。
コマンドレットと UAT（ue_run.run_commandlet、run_uat）	DataValidation、ResavePackages -fixupredirects、WorldPartitionBuilderCommandlet、BuildCookRun	ヘッドレスで実行します。ログを解析します（ue_run.scan_log）。
機能マトリックス（5.8 のドキュメントと講演に基づくものです。tests/code/unreal-expert/jobs/job_00_probe.py
で各行を確認、または訂正しています）。

アクション	MCP	Python、エディター実行中	ヘッドレスコマンドレット	Remote Control
アクター、アセット、プロパティの読み取りと編集	ツールセット	はい	はい（先にレベルを読み込みます）	公開 EditAnywhere プロパティ
マテリアルインスタンスとパラメーター	MaterialInstanceTools	はい	はい	プロパティのみ
マテリアルグラフ	ツールセット（大規模なスキーマ）	MaterialEditingLibrary、一部のみ：公開されていないピンがあります（Matt Oztalay、m6mJ9r7ytks [00:13:39]）	同様	いいえ
Blueprint グラフ、AnimGraph［要確認］	Blueprint ツールセット［対象範囲を要確認］	5.8 の BlueprintGraphEditor［対象範囲を要確認］	同様	いいえ
Niagara エミッターとモジュール	ツールセット、非常に大規模なスキーマ	エミッターやモジュールの編集は不可	不可	ユーザーパラメーター
PCG グラフ	PCG ツールセット、プリミティブ、ファイア・アンド・フォーゲットの呼び出し	グラフ API［要確認］	はい	いいえ
スクリーンショット、MRG 静止画、PIE	Python ツールセット経由	はい	不可（mode="latent" または -game レンダリング CLI を使用）	いいえ
ランドスケープのスカルプト、フォリッジのペイント、Fracture Mode	なし	不可	不可	いいえ
クック、パッケージ化、検証	なし	クックは不可（エディター内クックは 5.9 で削除）	はい、UAT	いいえ

グラフエディターとビューポートツールの代替手段： Blueprint：ロジックは C++（コードプロジェクト、Xcode）で実装し、 データのみの Blueprint を使用します。テンプレート Blueprint を複製してデフォルト値を設定します。150 個の Delay ノードや、正当な理由のない Event Tick は決して使用しません（k0tgmrBuIJc [00:56:45]、[00:57:19]）。マテリアル： 承認済みのマスターのインスタンスを使用します。ノードグラフを使い、必要な場合を除き、HLSL 全体を含む Custom ノードは使いません（k0tgmrBuIJc [00:39:27]）。Niagara：テンプレートシステムを複製し、ユーザーパラメーターを設定します。PCG：Epic の プリミティブとサンプルグラフを組み合わせます（lDf_y-YPELo [00:05:20]）。Control Rig：その「Copy Python Script」。 スカルプト、ペイント、破砕：高さマップのインポート、PCG、Dataflow グラフ、または人手による手順を使うことを、明確に伝えます。 書き込みロックとソース管理： ue_run は、プロジェクトを使用中の UnrealEditor プロセスを一覧表示します （ps）。保存するジョブには lock_check="refuse" を渡してください。5.8 の PythonScript コマンドレットはスクリプトの前にソース管理を有効にするため、保存時にチェックアウトを確認できます［Perforce で確認］。ResavePackages には -autocheckout が必要です（リダイレクターのドキュメント）。編集が必要なファイルがチェックアウトされていない場合は、そこで作業を止めてください（Bardoux、MjjkWH0eT3U [00:55:27]）。OFPA のチェンジリストはエディター内から送信します。一部だけ送信すると参照が宙に浮いた状態になります（World Partition のドキュメント）。PCG パーティションアクターなど、ビルダーが再生成するコンテンツはチェンジリストに含めないでください（TbNZ4GKaTow [00:26:23]）。

2. エキスパートのループ

すべてのツールキット呼び出しの背後にあるエンジン呼び出しを、計画でも報告でも明記してください。 scripts/ を持たない読者が各手順を確認できるようにします。 ue_review.screenshot(p, 1920, 1080) （AutomationLibrary.take_high_res_screenshot、フォールバックは HighResShot 1920x1080）、CVar、コンソールコマンドは文字どおり記載し、最後に Verified（実行した内容と、それを証明する数値、ログ行またはフレーム）および Assumed（Unreal で実行していない項目、［確認］が必要な名称、採用したデフォルト値）を記載してください。 対応関係とテンプレート：references/toolkit-map.md。

1. 数値で概要を定めます。 プラットフォームとデバイスクラス、スレッドごとおよび GPU のフレーム予算（60 fps では 16.67 ms、30 fps では 33.3 ms。Ari Arnbjörnsson、GuIav71867E [00:03:53]）、出力解像度とアップスケーラー、規模（ワールドサイズ、アクター、NPC）、ゲームプレイかシネマティックか、参考資料を明記します。指定がない場合は、ドメインスキルのデフォルトを採用して記録してください。
2. 事前確認。 ue_env.preflight()（チップ、macOS、Xcode）、ue_env.find_project()（プラグイン、パスに空白がある場合）、および計画に影響するプロジェクト設定を確認します。 r.Substrate、Lumen、VSM、Nanite、ハードウェアレイトレーシングを確認してください（ue_env.read_ini_value またはプローブを使用）。アップグレードしたプロジェクトでは、以前のレンダラー設定が引き継がれています［追加］。
3. 小さく冪等なスクリプトでステージを1つ構築します。パスを指定して取得または作成し、作成したものに印を付け、論理操作ごとにトランザクションを1つ使い、明示的に保存します。
4. 計測します。 コンテンツには ue_audit.verdict を使用し、stat unit で分類します（Frame、Game、Draw、GPU、RHIT）。続いて Insights を使います（「予算内か」を確認するには軽量キャプチャ、「原因」を調べるには -statnamedevents を使った詳細キャプチャを使用します。オーバーヘッドは約 20％です。C-AjCqjKRSs [00:11:27]）。 CSV プロファイラーまたは TraceQuery JSONL には ue_stat.budget_check を使用します。ターゲットのハードウェアで、クック済みの Development または Test ビルドをプロファイルしてください。この Mac はコンソールの代用です。書き換える前に計測してください（VMZftEVDuCE [00:16:33]）。Insights でヒッチの原因を説明できない場合は、サンプリングプロファイラーを追加してください（C-AjCqjKRSs [00:17:30]）。
5. 見て、さらに確認します。 固定カメラのブックマークまたは MRG の静止画からスクリーンショットを撮り、画像リーダーで開いたうえで、ue_review.image_checks を実行します。Epic のライティングエージェントは、全面が白いフレームを承認しました（lDf_y-YPELo [00:17:29]）。review_images を使うと、1回の呼び出しでフラグとコンタクトシートが得られます。ドメインスキルの references/critique.md に従って評価してください。レンダリング後は、5.8 の画面上の露出範囲警告を確認します。MRG のフレームがビューポートと異なる場合は、まず Game Overrides を疑ってください（fVg5ihB8Wdc [00:03:33]）。
6. 先に進む前に修正します。 一度に1つの変更を加え、同じビューで変更前後の整合性を確認するには ue_review.compare を使用します。
7. 証拠を添えて納品します。 この形式で、保存済みのアセットとレベル、監査および stat の JSON、確認したフレームとそのチェック結果、Verified と Assumed のリストを提示します。

数値と実際に確認したフレームなしに、レベル、マテリアル、ショット、ビルドを完了したと報告してはいけません。

3. ペルソナ別パイプライン

概要	チェーン	成果物
オープンワールドまたはレベル	scenario-unreal-world-building, scenario-unreal-materials（ランドスケープ、RVT）、scenario-unreal-lighting-rendering、scenario-unreal-performance	ストリーミング対応レベル、HLOD、予算レポート
マテリアルキット	scenario-unreal-materials、その後 scenario-unreal-lighting-rendering（テストベンチ）、scenario-unreal-performance（シェーダーコスト）	マスター、インスタンス、パーミュテーション監査
ライティング済みの屋内シーンまたはヒーロー静止画	scenario-unreal-lighting-rendering（エミッシブには scenario-unreal-materials）、MRG 出力には scenario-unreal-cinematics	予算内のゲームプレイ用ライティング、EXR 静止画
ゲームプレイのプロトタイプ	scenario-unreal-gameplay、scenario-unreal-animation、アビリティには scenario-unreal-vfx、scenario-unreal-performance	プレイ可能なマップ、自動テスト
Maya のキャラクター	scenario-unreal-pipeline-automation（インポート）、scenario-unreal-animation、scenario-unreal-gameplay	リターゲット済み、ロコモーション対応キャラクター
トレーラー	scenario-unreal-cinematics（scenario-unreal-animation、scenario-unreal-lighting-rendering）	Sequencer ショット、レビュー済みレンダー
VFX または破壊表現	scenario-unreal-vfx、scenario-unreal-performance	予算内のシステム
一括インポートとビルド	scenario-unreal-pipeline-automation、scenario-unreal-performance（パッケージ化）	レポート、検証済みパッケージ
フレームレートの改善	scenario-unreal-performance、担当者への修正依頼	証拠となるキャプチャ、同等性を示すフレーム

引き継ぎの取り決め： 名前を付けたフォルダーに保存したアセット、受け取り側のプロファイル向けでエラーのない ue_audit.verdict、パフォーマンスが重要な場合は stat または trace の数値、送信側が確認した image_checks のフレーム、各ツールキット呼び出しに対応するエンジン呼び出し、および Verified と Assumed のリスト。単位はセンチメートル、Z-up [追加済み] です。連携チーム：scenario-maya-expert（1 unit = 1 cm、Maya では Y-up）、scenario-zbrush-expert、scenario-blender-expert（scenario-blender-export 経由の FBX）；生成メッシュを仕上げる scenario-3d。

4. 共有ツールキット（scripts/、Unreal で未実行のエンジン内部分）

インポート：import sys; sys.path.insert(0, "<this skill>/scripts")。PythonRemote.call は、エディターでの各呼び出し時にこのフォルダーを追加します。

• ue_env.py：find_engine(version=None)（エディター、editor_cmd、uat、バージョン、UE_ROOT による上書き）、 find_project(path)、preflight()、plan_plugins / enable_plugins（タイムスタンプ付きバックアップ）、 read_ini_value、xcode_status。
• ue_run.py： run_python(uproject, script, args=None, map=None, timeout=1800, mode="commandlet"|"editor"|"latent", strict=False, lock_check="warn") は、ログスキャンとwarningsを含むUE_RESULTエンベロープを返します。ジョブ側の関数はresult(obj)、args()、 in_commandlet()、to_jsonable()、wait_for_registry()です。また、run_commandlet(uproject, name, args)、 run_uat、build_buildcookrun、launch_editor(mcp_port=)、stop_editor、editor_processes、 scan_log、parse_ue_resultもあります。
• ue_remote.py： RemoteControl(host, port).info/describe/get_property/set_property/call/batch/search_assets/console。 エラーには修正のヒントが含まれます。PythonRemote().open/exec/call/close、McpHttp().health()（到達可能性、 ツール検索）、loopback_only(port)、pie_path、cdo_path、python_cdo_pathもあります。
• ue_review.py：エディター内のset_camera、screenshot、wait_screenshot、screenshot_views、 camera_views_from_actors、render_still（MRG または MRQ プリセット、専用キュー）、wait_render。 オフラインのimage_checks（ヒストグラム、白飛び、黒つぶれ、EV 類似値、中央と周辺の比較、全白、全黒、 均一性、アルファ）、image_verdict、compare、contact_sheet、review_images、wait_for_file、 build_render_commandもあります。
• ue_audit.py：エディター内のaudit_assets(paths, rules, profile)、collect_facts。任意の場所で使える evaluate、build_report、verdict(report, "game"|"cinematic"|"mobile"|"prototype")。Epic の プレフィックス、テクスチャサイズと圧縮、Nanite、コリジョン、LOD、スロット、インスタンスの親、 Custom HLSL、After-DOF の半透明、リダイレクターを扱います。
• ue_stat.py：parse_stat_unit、parse_csv_profile とcsv_frames、parse_jsonl と sniff_schema、trace_frames、timer_totals、budget_check(frames, target_ms)、bound_by、 summarize。

ドメイン別スキルでは scripts/ue_<domain>.pyを追加します。これらのツールキットを複製することはありません。 各関数の背後にあるエンジン呼び出しについては、references/toolkit-map.mdを参照してください。

5. 上位 5.8 の落とし穴（全一覧：references/ue-5.8-traps.md）

• EditorLevelLibrary と EditorAssetLibrary は旧 API です：unreal.get_editor_subsystem経由で EditorActorSubsystem、LevelEditorSubsystem、UnrealEditorSubsystem、EditorAssetSubsystemを使います。 Epic の 5.8 のサンプルでも、依然として旧名称が使われています。load_levelは未保存の変更を破棄し、 delete_assetは強制削除を行って元に戻す操作を消去することがあります。Interchange ではdestination_nameは 無視されます。
• Substrate のデフォルト設定はプロジェクトの作成時期によって異なります：5.7 以降で作成したプロジェクトでは 有効ですが、アップグレードしたプロジェクトではオプトインするまでレガシー設定のままです。無効にすると Substrate マテリアルは黒くレンダリングされます。Metallic ピンはありません。Mac は既知の問題ありとして 記載されています。作成前にr.Substrateを確認してください。
• Mac の機能サポート：Apple Silicon のみです。Nanite と VSM は M2 以降でベータ版、Lumen HWRT と MegaLights は M2 以降で実験的機能です。パストレーシングは Metal 経由で、macOS 26.4 以降が必要です。Xcode については、 Epic は最小バージョンを 26.0、推奨バージョンを 26.1.1 とし、26.4 は非対応としています。この Mac の 26.6 は一覧にないため、C++ ビルドで確認してください。
• MRG の名称変更：Movie Render Graph は本番環境対応となりました。新機能はグラフ専用で、MRQ プリセットは レガシーです。キューのデフォルトは「Basic」です。MoviePipelinePrimaryConfig（Master ではありません）を使い、 グラフジョブにはset_graph_preset()を使います。終了フレームは排他的です。H.264 ノードは Windows のみです。
• Remote Control のデフォルト設定：サーバーは起動するまで無効です。5.8 ではリモート UFUNCTION 呼び出しは デフォルトで拒否され、127.0.0.1 のみにバインドされます。DefaultBindAddressを LAN に開放すると、 認証なしの MCP サーバーも公開される可能性があります［推測を追記］。

6. macOS 固有の事項

• ランチャーのインストール先は /Users/Shared/Epic Games/UE_5.8/ です。エディターは Engine/Binaries/Mac/UnrealEditor.app/Contents/MacOS/UnrealEditor にあります。-Cmd の場所は [要確認] であり、find_engine は -run= を付けてエディターにフォールバックします。UAT は RunUAT.sh、クック プラットフォームは Mac です。
• Unreal プロジェクトはスペースを含まないパスに置いてください（Allar スタイルガイド）[影響を要確認]。ツールキットは いずれにしても、スペースを含まないフォルダーにジョブをステージングします。
• Metal のみです。DX11、DX12、Vulkan に関するヒントは該当しません。RenderDoc は Metal をサポートしていないため、Xcode の Metal デバッガーを使用してください[追加]。Metal System Trace では、キャプチャを無効にするシェーダーのコンパイルと熱によるスロットリングを確認できます（ufPtQEtk-RQ [00:14:06]、[00:18:17]）。Insights のメモリコールスタックは Mac では 表示されません。Insights 以外では、Mac のサンプリングプロファイラーとして Instruments Time Profiler を使用します[追加]。
• ドキュメントに Ctrl ショートカットと Windows のパスが記載されている場合は、Cmd [要確認] と POSIX パスに読み替えてください。MacBook にはテンキーがありません。Gameplay Debugger のテンキーカテゴリーキーを再割り当てしてください（tranek GAS ガイド 6.2。バージョン差分に記載）。
• 自分が起動していないエディターを終了させないでください。自分が起動したエディターを停止する前には保存してください。

参考資料

• references/ue-5.8-traps.md：覚えているコードや古いチュートリアルを動作不能にする 5.8 の変更点を、出典と初回実行チェックリストとともにすべて記載しています。記憶を頼りにコードを書く前に読み込んでください。
• references/toolkit-map.md：各ツールキット関数の背後にあるエンジン呼び出し、コマンド、または cvar と、レポート形式（各手順のエンジン呼び出し、Verified と Assumed）を記載しています。
• references/python-reliability.md：unreal モジュールのイディオムと手順（サブシステム、パス、トランザクション、保存、get-or-create、作成したものへのマーク付け、書き込みロックとソース管理、遅延処理、インポート、未加工スクリーンショットのループ）。
• references/sources.md：各出典と、認証情報、URL、最適なタイムスタンプを記載しています。