scenario-unreal-pipeline-automation

Unreal パイプラインの自動化（パイプラインおよびツールの TD）

Unreal のエキスパート向けパイプライン作業では、ポリシーをデータとして扱い、その証拠を示します。インポートポリシーはバージョン管理されたパイプラインアセットとし、名前は計画に基づいて決め、重要なルールはすべて、人による編集も防ぐバリデーターにします。また、致命的な検証エラーなしにクックされ、起動した時点でビルドは合格とみなします。一括処理はヘッドレスで実行し、視覚的な確認が必要なものは、実際に人が確認するスクリーンショットを用意します。ここに記載されている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマに基づいて作業し、不足している点を明示してください。

必須の背景知識： scenario-unreal-expert（チャネル、レビューループ、5.8 の落とし穴）。

ステータス（2026-09-24）： ここに記載されている Unreal の呼び出しは、すべてまだ Unreal では実行されていません。scripts/ue_pipeline.py の純粋なレイヤーと両方のジョブは、オフラインで実行済みです（ユニットテスト、および偽の unreal に対する制御フロー）。5.8 をインストールしたら、最初に次を実行してください： tests/code/unreal-pipeline-automation/in_engine/run_in_unreal.py

スタンス（エキスパートとして特に重視する点）

• インポートポリシーは渡すアセットであり、ダイアログの記憶ではありません。ポリシーはアセットに紐づきます。 スクリプトによるインポートでは、ダイアログが最後に記憶した設定ではなく、パイプラインのデフォルトが使われます（Interchange PM、Oq6KbrqkGnw [00:39:28]；Jamie Dale、0guOMTiwmhk [01:26:38]）。汎用アセットパイプラインをプロジェクトに複製し、すべてのオプションを設定して、override_pipelines で渡します。スタックの順序は実行順です。デフォルトパイプラインより上に調整用パイプラインを置くと、ファクトリーノードが見えなくなります [00:20:22]。Factory Dependencies に従い、ファクトリーノードのレベルでフィルタリングして、孤立したマテリアルが作成されないようにします [00:31:33]。スタックに Graph Inspector を残すと、バッチ処理の途中でポップアップが表示されます [00:40:00]。アセットにはスタックが保持され、再インポート時にはそれが再利用されます（Interchange doc）。そのため、ポリシーの変更を既存のアセットに適用するには、新しいプリセットを渡して再インポートする必要があります（plan_imports(..., policy=)）。
• 名前はインポーターではなく、プランから取得します。 Interchange は AssetImportTask.destination_name を無視します（5.8 API reference）。各ファイルを目標の名前でステージングし、フォールバックとしてのみ名前を変更します。名前を変更するとリダイレクターが残り（naming doc）、Zen ローダーはコアリダイレクトを無視します。既存のアセットと同じ名前に変更すると失敗するため、再実行時に重複が残ります。代わりに再インポートしてください（I03）。ドラッグ＆ドロップは使いません。他のツールがパスに依存しているためです（Bardoux、MjjkWH0eT3U [00:09:14]）。
• 三角形数ではなく、適性で Nanite を有効にします。 Nanite 対応ターゲット上の不透明またはマスク付きのスタティックメッシュは、ローポリも含めて Nanite を有効にします。Nanite 以外のジオメトリは「VSM への描画コストがはるかに高くなる」ためです（VSM doc）。半透明マテリアル（Nanite はデフォルトマテリアルを描画します）、モーフターゲット、Nanite 非対応ターゲットでは無効にします。「すべてが Nanite に対応するわけではありません」（Oztalay、S2olUc9zcB8 [00:34:33]）。すべての Nanite メッシュでフォールバック設定を行います（DxBKmQ-0kfw [00:37:15]）。シンプルなコリジョンも引き続き必要です。
• 検証は作成時点で行うコードであり、赤は新しい問題を意味する必要があります。 バグの約30～40％は、アセットバリデーターで検出できる問題に起因します（Fray、KuIWCzujtag [00:35:40]）。CanValidateAsset は軽量に保ち [00:31:47]、5.8 のバリデーターごとのクック統計（DataValidation.ReportCookValidationStats）で各バリデーターのコストを確認します。従来のエラーは許可リストに登録します [00:38:07]。まずフィクスチャで各チェックが失敗することを確認します [01:46:04]。Python バリデーターはセッションごとに登録され、-run=DataValidation では C++ のルールのみが実行されます。また、-ValidationErrorsAreFatal を指定しないクック時検証では、エラーが警告に変わります。
• 一括処理にはヘッドレスを、開いているエディターが保持するものにはエディターを使い、終了コードは信用しません。 コマンドレットはレベルを読み込まず（Python doc）、アセットレジストリのスキャンが続いている場合があります。クエリの前に wait_for_completion() を実行します（5.8 batch example）。-ScriptErrorsAreFatal を指定しない限り、Python の失敗はエラーをログに出すだけです（5.5）。判定にはジョブ独自の結果行（P.job_verdict）を使います。エディターは読み込まれたアセットの書き込みロックを保持します（Jamie Dale [01:17:18]）。MCP または Python リモート実行を使って、エディター内で実行してください。set_editor_property は Details パネルと同様に動作しますが、通常の属性への書き込みでは何も再構築されません [00:21:25]。Perforce を使う場合、5.8 の PythonScript コマンドレットは先にソース管理を有効にします。保存するものをチェックアウトし、チェックアウトに失敗したら中止してください（Bardoux [00:55:27]）。インポートは取り消せません。先にスナップショットを取ってください。
• 一覧表示、確認、実行を行い、メッシュごとに一度で処理します。 解決済みの対象を表示してから実行します（Sam Deiter、k0tgmrBuIJc [00:52:23]）。Nanite、LOD、コリジョンを一度の処理で設定し、チャンクごとに一度だけ保存します。LOD グループを設定しても、LOD が自動で生成されるとは限りません［確認が必要］。設定後に数を数え、足りなければチェーンを明示的に構築し、画面サイズが減少していることを確認します（L02）。ファイルに問題があっても、バッチ全体は停止しません。
• ビルドは、起動して検証する再現可能なコマンドラインです。 Project Launcher のプロファイルから BuildCookRun の行を一度生成し、自分のものと差分を比較します（UAT doc；P.buildcookrun_diff）。Cook はステージングを行いません。-skipcook は -cook を省略する指定ではありません（Josh Adams、uxdEt9XXKb8 [00:19:14]、[00:20:20]）。Xcode で誰も編集していなくても、Xcode は .app を組み立てます [00:03:33]（コンテンツのみのプロジェクトに完全な Xcode が必要という点は、検証が必要な推論です）。ローカルと CI で同じコマンドを使い（Hamilton、3ftOkc-cA7U [00:25:15]）、その後起動して（Gauntlet UE.BootTest）、起動を見届けます（Ari、102O0FOEzNY [00:39:07]）。パフォーマンスの数値は推移を見るためのものであり、合否判定には使いません（Fray [01:29:38]）。

まず確認する項目

入力	変更内容	指示がない場合のデフォルト
タスク	ステージ	新規バッチ：すべて；変更されたソース：previous= を指定して 2～10（P11）；ルールを採用する既存プロジェクト：許可リストを指定して 6；ビルドのみ：10；アーティストのボタン：P12
ソースとサイドカー	単位、法線	Maya の summary.json と <file>.settings.json、なければスキャン；法線はサイドカーに opengl と記載がない限り DirectX
対象プラットフォーム	Nanite、LOD	PC とコンソール；この Mac（M5 Max）は、Nanite と VSM の M2 基準をクリアしています
命名	バリデーターのプレフィックス	Epic の表（SM_、T_、MI_）；プロジェクトで使用している場合に限り Allar
レイアウト	保存先	/Game/<Project>/Art/<Kind>/<Category>/<Base>、タイプ別フォルダーなし（Allar 2.6）
マスター マテリアル	インスタンス、頂点カラー	scenario-unreal-materials を参照；なし：インスタンスを作成せず、その旨を報告
アセットクラス	コリジョン、LOD	サイドカーの asset_class、なければカテゴリーマップ、なければサイズ（150 cm［追加済み］）
エディターは起動中？	チャンネル	はい：エディター内；いいえ：ヘッドレス
ソース管理	チェックアウト	Perforce：require_checkout、再保存時は -autocheckout
ビルド	プラットフォーム、構成	Mac、Development、アーカイブはプロジェクト外に保存

ワークフロー

1. 事前確認。 ue_env.preflight()（チップ、Xcode ウィンドウ）、P.project_path_problems、プラグイン （Python Editor Script、Editor Scripting Utilities、Interchange、Data Validation、 PythonAutomationTest）、プロジェクトを開いているエディター、p4 opened。ゲート：エラー行がないこと、チャンネルが選択されていること（P0）。

2. オフラインで計画とステージング。 P.scan_sources、P.read_dcc_manifest、 P.plan_imports(..., previous=manifest, policy="PL_Props@3")、P.stage_plan。ゲート：項目数と 却下数の合計がソース数と一致すること、D01〜D07 を読み込んでいること、 ソースがバイト単位で同一であること（P1）。

3. インポートポリシー。 ジョブの describe の後、ルートを指定して preset を実行します：post_import（デフォルト：マテリアルはオフ、インスタンスは明示的なパラメーターマップを使ってインポート後に作成）または interchange_mi（Material Import = Import as Material Instance、Parent Material = マスター。Interchange が名前で認識するパラメーターのみを設定）。マスターが頂点カラーを読み取る場合を除き、Vertex Color Import Option は Ignore にします。Lumen では Generate Lightmap UVs をオフにします。ゲート：failed が空であること、P.pipeline_stack_problems(stack) に問題がないこと（P2）。

4. 試行。 make_fixtures.py と実際のファイル 5〜10 個を使います。ゲート：壊れた各フィクスチャに問題 ID が表示されること、ファイルごとの所要秒数が分かっていること。

5. インポート。 ヘッドレスの場合：ue_run.run_python 経由でジョブの import を実行します。エディターが開いている場合：MCP または ue_remote.PythonRemote 経由で P.run_import_plan を実行します。エンジン呼び出しは P3b で実行します。25 個単位で処理し、 unreal.collect_garbage() を実行します。ゲート：すべてのファイルが処理対象として記録されていること、P.job_verdict の終了コードが 0 であること（P3、P4）。

   ステップ	ヘッドレス	レンダリングエディターが必要
   インポート、インスタンス、Nanite、コリジョン、LOD、バリデーター、レポート	はい（書き込みロック：開いているエディターを使用）	いいえ
   スクリーンショット、コリジョンと Nanite のビュー	いいえ	はい（mode="latent"）
   マスターグラフ、Blueprint パイプライン、Graph Inspector	いいえ	scenario-unreal-materials または人手

6. 検証。 レポートには独自の問題、engine_validate、ue_audit が含まれます。C++ ルールには -run=DataValidation を使い、P.new_issues(records, allow) で CI の判定を行います。ゲート：新しいエラーが 0 件であること、バリデーターの所要時間が分かっていること（P5）。

7. 外観確認。 ue_contact_sheet_job.py（潜在スクリーンショットループの実例は P7 にそのまま掲載）を実行し、続いて ue_review.review_images を実行します。シートを開き、サンプルのコリジョンビューを確認します。ゲート：空白のフレームがないこと、フラグが付いたアセットごとにメモがあること。

8. リダイレクターとチェックイン。 redirectors_found（レジストリ由来）が 0 より大きい場合： エディターを閉じて P.resave_command(uproject, autocheckout=...) を実行します。ゲート：0 件であること（P8）。

9. テスト。 P.automation_command 経由で Python テスト（test_*.py）を実行し、 P.parse_automation_report で読み取ります。ティアは push、build、weekend です（Fray [01:31:46]）。ゲート：すべて合格すること、新しいテストがそれぞれ一度は失敗することを確認済みであること（P6）。

10. クック、パッケージ化、起動。 P.cook_command（クックのみ）または package_command(..., incremental=True)（-cookincremental、Beta、Zen）を使ってコンテンツを反復処理します。リリース時： P.zen_ci_patch、P.package_command、P.buildcookrun_problems、ランチャーの行を基準とした P.buildcookrun_diff、ue_run.run_uat、P.parse_uat_log、P.gauntlet_command。ゲート：終了コードが 0 であること、.app がアーカイブされていること、BootTest に合格すること（P9）。

数値

値	対象	出典
1 uu = 1 cm、FBX 2020.2	DCC エクスポート	Epic；scenario-maya-pipeline-scripting
UCX_ UBX_ UCP_ USP_ + メッシュ名	DCC コリジョン	Interchange doc
最大 8192、UI を除き 2 の累乗	テクスチャ	Allar 7.1、7.3
それぞれ 1 秒未満	Epic の Smoke フラグ	automation doc
安定待ち 0.5～1 秒	Smoke チェック	KuIWCzujtag [01:03:07]
予想 3 秒、上限 4 秒	機能テストの時間制限	3ftOkc-cA7U [00:26:46]
20～30 分；約 60 分	プッシュ後の滞在時間	Ari [00:39:07]；Fray [01:56:41]
26.0 min、26.1.1 推奨、26.4 非互換	5.8 用の Xcode	macOS doc（ここでは 26.6：未記載）
チャンクあたり 25 ファイル；小道具は 150 cm	保存と GC；クラス分割	[追加]
クラスごとに LOD は 3 または 4；段階的に半減	LOD の最小数；明示的なフォールバック	[追加] プロジェクトのデフォルト

品質ゲート

測定可能な項目： 項目数と却下数の合計がソース数と一致すること；summary["ok"]；新たなエラーがゼロであること；バリデーターが登録され、engine_validation.ok が真であること；ue_audit が pass であること；redirectors_found が空であること；DataValidation に問題がないこと；automation の failed が 0 であること；-ValidationErrorsAreFatal を指定して cook すること；ジョブごとに P.job_verdict の終了コードが 0 であること；ランチャーの差分がレビュー済みであること；UAT の終了コードが 0 であること；.app が存在すること；BootTest に合格すること。評価基準： references/critique.md。

視覚的な項目： コンタクトシート（マネキンの横にスケールを配置、ピボット、法線の緑チャンネル、テクスチャスロット、r.ForceLOD で LOD の切り替わりを確認）、サンプルのコリジョン表示、Nanite の可視化、scenario-unreal-lighting-rendering のリグを使ったルックデブ。

よくある間違い

間違い	どのように見えるか	修正方法
明示的なパイプラインを指定せずにスクリプトでインポートする	ダイアログから実行した場合と異なる	override_pipelines にプリセットを設定する
プリセットを変更したのに、アセットを再インポートしない	古いアセットに古い設定が残る	プランで policy= を指定する：プリセットを使って再インポートする
再インポートではなく、もう一度インポートする	計画したアセットの隣に重複ができる	previous= マニフェストを使う。I03 がこれを防止する
Interchange の下に destination_name を指定する	ファイル名がアセット名になる	ターゲット名でステージングする
デフォルトのパイプラインより上に調整パイプラインを置く	変更が通知なく失われる	後ろに配置する
インポート後に不要なメッシュを削除する	孤立したマテリアルができる	ファクトリーノードと依存関係を無効にする
三角形の数を基準に Nanite を使う、または半透明マテリアルに使う	影のコストが高くなる。デフォルトのマテリアルになる	P.nanite_decision
Python バリデーターが実行されない	CI は成功と表示され、エディターでは何も起きない	init_unreal.py と各ジョブで add_validator を使う。名前には k2_ を使用する
合格または不合格の判定がないバリデーターパス	「未チェック」と表示される	クリーンな場合は asset_passes を使う
コマンドレットの終了コードを信頼する	実行は成功と表示されても、ジョブがクラッシュしている	結果行、-ScriptErrorsAreFatal、P.job_verdict を使う
ヘッドレス起動時にレジストリを照会する	リストにアセットが表示されない	先に wait_for_completion() を呼び出す
EditorAssetLibrary、EditorStaticMeshLibrary、ScriptingCollisionShapeType を使う	非推奨の警告、型エラー	サブシステムと ScriptCollisionShapeType を使う
LOD グループを設定するが、LOD 数を数えない	レポートに LOD が 1 つしか表示されない	数を数えてから set_lods を呼び出す
エディターを開いたまま保存する	ファイルがロックされる	エディター内チャネルを使う
数百個のファイルを 1 つのループで処理する	メモリ使用量が増え続ける	チャンクに分割して collect_garbage を呼び出す。数千個の場合はバッチプロセッサーを使う
スクリーンショットに Automation RunTests と -nullrhi を使う	テストが 1 つも実行されない。画像が真っ黒になる	Automation RunTest とレンダリングエディターを使う
BuildCookRun を手入力する。最初のビルドに Shipping を使う	-stage または -package がなく、アプリもなく、ログもない	ランチャーの行、P.buildcookrun_problems を使う。最初は Development を使う

引き継ぎ

受け取るもの： scenario-maya-pipeline-scripting から、アセットごとの cm 単位の FBX、UCX_<mesh>_NN、 <file>.settings.json、sha1 を含む summary.json。scenario-zbrush-retopology-export から、cm 単位の OBJ、 原点が足元にあるもの、マップ。Blender から、DirectX 法線または opengl フラグ付きの FBX または glTF （scenario-blender-uv-baking）。scenario-unreal-materials から、マスターのパス、パラメーターマップ、マスターが頂点カラーを読み取るかどうか。scenario-unreal-lighting-rendering から、ルックデブレベル。

引き渡すもの： アセットと、report.json、report.csv、manifest.json（ソースごとの sha1 とポリシー）、および未検証リスト。スケルタルアイテムは scenario-unreal-animation へ、M04 の不足分は scenario-unreal-materials へ、プロップは scenario-unreal-world-building へ送ります。問題は ID で差し戻します（D01、D02、 S01 は scenario-maya-pipeline-scripting へ、T01 はテクスチャ担当者へ）。ビルドは、アーカイブパス、UAT の判定、BootTest の結果、チェンジリストとともに QA および scenario-unreal-performance へ送ります。

UE 5.8 に関する注意事項

• Interchange は FBX を処理します（5.5 以降、本番運用可能）。5.8 ではダイアログのオプション名が変更され、uFBX （実験的）が追加され、USD アセットのインポートが本番運用可能になりました。InterchangeManager.import_asset と reimport_asset は、オブジェクトまたは None を返します（5.8 API）。
• AssetImportTask.result は非推奨です（get_objects() を使用）。バリデーターのオーバーライドは k2_can_validate_asset と k2_validate_loaded_asset です。create_asset には overwrite_existing が追加されました。
• バッチプロセッサー：BatchProcessLibrary.run_batch。フォークボムを防ぐため、init_unreal.py からインポートされるスクリプトは __main__ でガードしてください。
• Zen のクック済み出力ストアはデフォルトで有効です。CI では LimitProcessLifetime=false にしてください。エディター内でのクックは 5.9 で削除されます。
• Remote Control は、リモートからの UFUNCTION 呼び出しをデフォルトでブロックします。Python のリモート実行または MCP を通じてインポートを実行してください。
• SupportedClasses が空のアクションユーティリティは検証に失敗します。Interchange ページには FBX cvar が引き続き「実験的」と表示されます。インストール時に確認してください（ジョブの flags）。
• Python 3.11.8。

参考資料

• references/procedures.md：P0 から P14、および P3b（エンジンの生の呼び出し）。それぞれにテストパスとステータスが記載されています。
• references/expert-notes.md：ソースごとの判断、意見の相違、決定条件。
• references/critique.md：実行、バリデーター、テスト、ビルドの評価基準。
• references/gui-paths.md：同じ手順のメニュー。
• references/sources.md：ソース、認証情報、タイムスタンプ、改訂履歴。
• scripts/ue_pipeline.py、scripts/ue_pipeline_job.py、 scripts/ue_contact_sheet_job.py。