scenario-maya-pipeline-scripting

Maya パイプラインスクリプティング（パイプライン TD）

熟練したパイプライン作業に必要なのは、契約と証明です。Maya から出るすべてのファイルには、生成された名前、明示的なエクスポート設定、再インポートによる確認を適用します。また、1 つの Maya プロセスで 200 個のファイルを処理するバッチに依存しません。パイプライン TD は生成できるものを手入力せず、デフォルトを信頼せず、出力を読み戻して検証します。ここで名前が挙がっている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼します（npx skills add scenario-labs/skills --skill <name>）。無人で実行する場合は、ツールのスキーマに基づいて作業を進め、欠落している点を明示してください。

必須の前提知識： scenario-maya-expert（実行チャネル、レビューループ、2027 年版の落とし穴）。

ステータス（2026-09-24）： ここに記載されている Maya の呼び出しは、すべてまだ Maya 上で実行されていません（未インストール）。scripts/mx_pipeline.py はオフラインで実行済みで、Maya レイヤーはフェイクを使ってテストしています。Maya をインストールしたら最初に実行するのは tests/code/maya-pipeline-scripting/run_all.sh です。

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

• 生成できるものを手入力しない（Guignolle、Borderlands、lfWkJrkhd2U [00:04:58]）：名前、ネームスペース、パス、クリップ範囲はマニフェストから取得します。検証は実行時点で行います（承認済みショットの警告、シーンの内訳、パブリッシュ差分の緑・青・赤 [00:22:11]～[00:24:57]）。
• 出力を読み戻して証明する（dcc-mcp の「主張ではなく数値」という基準。Maya Help のテストでは、FBX を再インポートしたときに法線、スケール、軸、長さが一致すること）：クリーンなシーンに再インポートし、メッシュ、三角形、ジョイント、メッシュごとの境界ボックス、法線の方向、単位、上方向の軸を比較します。FBXRead でテイクを読み込み、pxr で USD を開き直し、ソースのハッシュを取得します。ファイルごとに mayapy を 1 つ使用します。FBX の設定と optionVars は file(new=True) の後も保持されます。
• 状況が見えないまま実行しない（chadrik、maya-mcp-server：「stdout と stderr がなければ、エージェントは状況を把握できない」。FBX ドキュメント：バッチではログだけが問題のあるファイルに関するフィードバック）：FBXExportGenerateLog を有効にして各子プロセスのログを読み込みます。子プロセスは MAYA_DISABLE_ADP=1 と Maya の stderr の warning 設定で実行します（デバッグ時は maya_log="all"）。ブリッジ呼び出しのたびに stdout、stderr、maya_messages を読み込みます。
• FBX はグローバル状態です（Maya 2027 Help、FBX MEL コマンド）：設定を退避し、リセットし、すべてのオプションを設定し、テイクの蓄積をクリアし、設定を照会してログに記録してファイルの隣に保存し、最後に復元します。Bake の開始と終了はプリセットに保存しません。接線をエクスポートできるのは、すべて三角形で構成されたメッシュだけです。非直交行列は破棄されます。制御したエッジで Maya 上で三角形化します（Epic）。
• エクスポートのデフォルトは落とし穴です（maya-usd readme）：frameRange は [1, 1]、defaultMeshScheme は catmullClark（法線なし）、スケルトンはオフ、ネームスペースは保持されます。すべてのフラグを指定してから、pxr で開き直します。
• 大規模化では、ハードウェアより構造が重要です（Markowski、Hübschmann、RISE、8UIW-g1_heg）：全範囲のキャッシュではなく値クリップを使います [00:37:03]。自身のレイヤーと、それより強いすべてのレイヤーをミュートします [00:26:19]。バージョンを固定し、assetInfo に記録します [00:23:01]。
• リファレンスの編集は名前と DAG パスで再生されます（Maya 2027 Help）：パブリッシュ済みの子ファイルの名前や構造は変更しません。修正の前と、バージョンを切り替えた後は毎回、リファレンスの状態（アンロード、欠落、失敗した編集）を確認します。ショットはアセットをリファレンスし、エンジンにはベイク済みのエクスポートを渡します。
• 最適化の前にプロファイルし、速さより正しさを優先します（Roselle、rhtERzmAoUM [00:04:14]、Using Parallel Maya 2027）：まず DG、Serial、Parallel の結果が一致することを確認します。ヘッドレスで得た数値が示すのは評価処理であり、描画ではありません。Python で構築とエクスポートを行い、ネイティブノードで評価します（Fragapane、_0mb4wIZi80 [00:55:10]）。

最初に確定する項目

入力	変更内容	指示がない場合のデフォルト
ターゲット	プリセット、チェック、ファイルレイアウト	Unreal 5、FBX 2020.2、アセットごとに1ファイル、ファイルごとに1クリップ
アセットの種類	static、skeletal、anim、cache、USD layer	リグ付きシーンではskeletal、それ以外ではstatic
シーンの規約	単位、上方向の軸、命名正規表現	cm、Y-up、mx_validateのデフォルト、スタジオに規約がない場合は_geo接尾辞（FlippedNormals）
フレームレート	E27、クリップの長さ	指示にあるエンジンまたはプロジェクトのレート。記載がない場合は報告し、再サンプリングは行わない
許可される修正	許可なく変更できる内容	history, smooth_preview, unknown_dead, namespaces。ウェイト、トポロジ、法線を変更するものは不可
インフルエンスの上限	上限または報告のみ	Unityは4（Unity manual）、Unrealはヒストグラムを報告
正とする情報源	名前、バージョン、範囲	出力と同じ場所にJSONマニフェストを置く
実行規模	ワーカー、分離	5ファイルで試行後、workers=1または2、プロセスを分離

ワークフロー

1. 事前確認、インベントリ、フィクスチャ。 P.preflight(out, scenes)：mayapy、localhost とホスト名の名前解決（macOS でバッチレンダリングが停止する原因になります）、ディスク、シーンの読み取り可能性を確認します。P.find_scenes(root) を使用します。ルールごとに小さなシーンを1つ用意し、それぞれで1つの問題だけを発生させます（test_engine_checks.py）。実際のファイル5つでチェーン全体を実行します。GATE：事前確認が成功すること、すべてのフィクスチャが検出されること、ファイルごとの所要時間がわかっていること。
2. バッチ処理。 P.batch(scenes, job, out, plugins=("fbx",), timeout=900)：シーンごとに1つの mx_run 子プロセスを起動し、スクリプトノードを無効にします。環境変数に MX_PIPELINE_OUT/STEM/SOURCE と、子プロセスごとの FBX ログ名を設定します。ジョブは status、issues、fixes、exports を返します（procedures.md P1）。isolation="session" は、信頼できる小さなファイルを多数処理する場合にのみ使用し、クラッシュしたファイルは分離して再実行します。GATE：シーンごとにレポートが1つあること、summary["sources_untouched"] が True であること、pass 以外のすべてのレコードについて説明があること。
3. 検証、読み取り専用。 まずリファレンスの状態を確認します：P.reference_issues(P.references_report())（R01 未ロード、R02 見つからない、R03 編集に失敗、R04 孤立した親）。次に mx_validate.validate(profile, roots) と P.check_engine_export(roots, engine, kind, rules={"fps": 30}) を実行します（E01～E27：単位、ルートが1つであること、名前、名前空間、行列、三角形化、UV とカラーセット、ロックされた法線、インフルエンス、コリジョン、ピボット、ジョイント、空のメッシュ、時間単位）。GATE：ファイルごとに問題の一覧があること、まだ何も変更されていないこと。
4. 安全な修正を適用し、バージョンを保存。 許可されている修正のみを行います。n-gon、非多様体、面の向き、対称性、単位、ジョイントの向きは報告しますが、修正しません（FlippedNormals、ToWRH4IXF7A [00:11:50]）。unlock_normals とインフルエンス上限の適用はオプトインです。上限適用では、ウェイトの移動量が0.1を超える場合は拒否します［追加］。P.save_version() は <out>/fixed/<stem>_fixed.ma に書き込みます。GATE：ノードごとに修正ログがあること、再検証で新たな失敗がないこと。
5. エクスポート。 P.fbx_export(path, roots, "unreal_skeletal")（プリセットは unreal_／unity_ ＋ static、skeletal、anim。P.fbx_commands(preset) で MEL を確認できます）。アニメーション：ベイク範囲を明示し、Unreal ではファイルごとにクリップを1つだけにし、ジョイントのみを対象にします。キャッシュ：P.abc_export（合成済みショットから -uvWrite -writeFaceSets を使用）。USD：P.usd_export(path, roots, frame_range=...)。GATE：<file>.settings.json で、照会し直したすべてのオプションを確認できること。FBX ログが見つかり、読み込まれていること（rep["fbx_log"]、X05）。
6. クリーンなシーンで検証。 P.fbx_takes(path)（インポートなし）、P.reimport_stats(path)、P.compare_stats(before, after) を使用します。さらに P.abc_verify と P.usd_verify を実行します。GATE：メッシュ、三角形、UV セット、ジョイント名、メッシュごとのバウンディングボックス、法線の向き（移動量は最大2％）、単位、上方向軸が一致すること。takes = clips + Take001。USD の default prim、時間範囲、法線を含むスキーム none、SkelRoot、metersPerUnit 0.01。
7. レポートと差分。 summary.json／summary.csv、P.export_manifest(summary)、P.publish_diff(previous, current) を使用します。サンプル（修正済みファイルのシート、エンジンへのインポート）を確認します。GATE：何が検証されていないかがレポートに記載されていること。

組み込みジョブはファイルごとにステージ3～6を実行します： P.batch(scenes, P.BUILTIN_EXPORT, out, plugins=("fbx",), job_args=["--preset", "unreal_skeletal", "--profile", "rig", "--fps", "30"]) （procedures.md P2）。

その他のジョブも同じ手順（procedures.md）：USD ショットレイヤーでは、編集ターゲットを1つにし、自身と上位のレイヤーをミュートします（P9）。マニフェストからリファレンスを取得し、名前空間が衝突すると例外を発生させます（P10）。OM2 は mx_audit.mfn_mesh、プラグイン、PySide6 パネルを通して読み取ります（P12、P13）。P.perf_census の後に P.eval_timing を実行します（P14）。modified を確認してから、mx_bridge を通して GUI 部分を処理します（P15）。

数値

値	基準	出典
FBX 2020.2（FBX202000［トークンを確認］）	Unreal インポート	Epic
cm、スケール係数 1.0；1 Unreal ユニット = 1 cm	Maya の作業単位	Maya 2027 Help、スケール
頂点あたり 4 つのインフルエンス	Unity のデフォルト	Unity manual
最低 15 本のボーン、T ポーズ	Unity humanoid	Unity manual
UCX_/UBX_/USP_/UCP_ + メッシュ名 + _00	Unreal のカスタムコリジョン	Epic
SOCKET_<mesh>_##、ファイルごとに 1 メッシュ	Unreal のソケット	Epic
Take001 は常に存在	FBX のテイク数	Maya 2027 Help
frameRange のデフォルトは [1, 1]	mayaUSDExport	maya-usd readme
レイヤーごとに 2 GB が失われる	Maya ファイルへの USD 保存	USD for Maya 2027
stdout は none、stderr は all（デフォルト）；mx_run：stderr は warning	MAYA_BATCH_*_LOGGING_LEVEL	devkit 2022；［追加］
最大ウェイト変化 0.1；バウンディングボックス対角線の 1e-3；法線の 2%（軸あたり 8 ビン）	自動インフルエンス上限；往復処理時の境界；往復処理時の法線	［追加］

品質ゲート

コード内： 事前チェックが OK；バッチの合計がすべてのファイルを計上し、ソースは変更されず、クラッシュでバッチが停止していない；修正前の参照状態が正常；修正前に検証を行い、修正後に修正ログを記録；エンジンチェックのエラーがゼロ（目標レートに対する E27）；エクスポートごとに設定サイドカーと FBX ログがある；エクスポートごとに往復処理が OK で、法線と軸を含む；fbx_takes の数が意図どおり；usd_verify が OK；内訳が空；速度に関する主張をする前に eval_timing(...)["consistent"] を確認；生成コードに対する test_offline_snippets_compile.py の lint がクリーン。評価基準： references/critique.md。

目視： 修正したファイルのサンプルを mx_review シートで確認（unlock_normals の後は法線モード）；各キャッシュをリグに対するプレイブラストで確認；インポート例をエンジン上で確認（ピボット、コリジョン、LOD 切り替え、マテリアルスロット）；マテリアルを引き継ぐ場合は USD のオリジナルと再インポート後のレンダーを比較；ツール UI のスクリーンショットを確認。

よくある間違い

間違い	どのような問題か	修正方法
1つの mayapy ループですべてのファイルを処理する	ファイル 57 でセグメンテーション違反が発生し、143 は実行されない	P.batch（ファイルごとに子プロセスを1つ）
FBX オプションを一度だけ設定し、リセットしない	2回目のエクスポートに1回目のテイクや設定が引き継がれる	fbx_export：プッシュ、リセット、設定、テイクのクリア、ポップ
FBX ログを無効にする、または一度も確認しない	バッチは「成功」するが、問題があったファイルがわからない（Maya Help）	ログを有効にし、子プロセスごとに MAYA_FBX_LOG_FILENAME を設定し、レポートに X05 を記載
四角形の接線と、エクスポーターによる三角形化	接線が誤り、「スムージングが完全にランダム」（Epic）	バインド前に、エッジを制御して Maya で polyTriangulate を実行
シアー、または親の非均等スケール	インポート後にパーツが飛んだり、歪んだりする	E05；フリーズするか、階層を再構築する
カウントのみの往復確認	カウントが同じでも、スムージング、軸、スケールが失われる	compare_stats：メッシュごとの境界ボックス、法線、単位、上方向の軸を確認
FBX または OBJ のインポート後に法線がロックされている	リグの変形中もシェーディングが固定されたままになる	E11 / locked_normals；リギング前にロックを解除する（FBXImportUnlockNormals）
アニメーションにベイク範囲がない	コンストレイントされたボーンが静止し、長さが誤っている	毎回 bake=(s, e) を指定する；Unreal 用にはファイルごとにクリップを1つにする
シーンは 30 fps、シーケンスは 24 fps	アニメーションがエンジンのシーケンスと同期しない	--fps を指定して E27 を実行する；ソースのレートを修正する
デフォルト設定で mayaUSDExport を使用する	1フレームのみ、メッシュがスムージングされ、スケルトンがない	P.usd_export を使うか、すべてのフラグを明示的に指定する
未ロードまたは編集に失敗したリファレンス	パーツが欠落し、キーが失われる	R01 から R03 でジョブを停止する；swap_reference を使い、子の名前は決して変更しない
すべてのシェイプで MFnMesh を使う	空のまま残ったメッシュが1つあるだけでファイルがクラッシュする	mx_audit.mfn_mesh；E24
n-gon やウェイトを自動修正する	シルエットや変形が変わる	レポートに記載する；最大差分を指定したオプトインの上限を設ける
確認せずにブリッジを呼び出す；macOS でバッチレンダーがハングする	警告が流れてしまい、レンダーが始まらない	stdout、stderr、maya_messages を読む；事前チェックを行い、/etc/hosts に localhost を追加する

引き継ぎ

すべてのペルソナから受け取るもの： 保存済みバージョン、受け取り側プロファイルの mx_validate レポート、mx_audit の数値、送信側が確認したシートまたはプレイブラスト、未検証リスト。 scenario-maya-modeling と scenario-maya-retopology-uv：原点に配置された静的メッシュ、三角形化の明記、UV、シーム上のハードエッジ、意図的でない限りロックされていない法線。scenario-maya-rigging と scenario-maya-deformation：参照可能なリグ、1つの変形スケルトン、Skin Tools レイヤーの削除、ターゲット内に収まったインフルエンス。scenario-maya-animation：クリップ名、範囲、レート。scenario-maya-fx と scenario-maya-groom：フレーム範囲を含むバージョン管理済みキャッシュ。scenario-maya-lookdev：受け渡しを想定したマテリアル（UsdPreviewSurface または MaterialX）。

引き渡すもの： エンジン対応ファイル（<out>/fbx/、キャッシュ、USD レイヤー）、それぞれの設定サイドカーと FBX ログ、<out>/fixed/ 内の修正版、ファイルごとのレポート、summary.json／.csv、マニフェストとパブリッシュ差分、未検証リスト。問題は ID で担当者に戻します。E07 と E11 は scenario-maya-modeling、E14 と E26 は scenario-maya-deformation（Delete Skin Layers ではウェイトが保持されます）、E02、E13、E27 は scenario-maya-rigging または scenario-maya-animation に戻します。

Maya 2027 に関する注意事項

• FBX オプションページでは、今も FBX 2019.2 がデフォルトとされています。バージョンを設定してください。2027 の FBX インポートではユーザー法線を読み取れます（What's New 2027）。MAYA_FBX_LOG_FILENAME と MAYA_FBX_LOG_DATETIME_ISO（2025）を使うと、並列処理の FBX ログを分けられます。macOS のログフォルダーは[要確認]です。
• バッチ出力：MAYA_DISABLE_ADP=1 と MAYA_BATCH_STDOUT/STDERR_LOGGING_LEVEL（devkit 2022）は mx_run が設定します。
• 2027.0 から 2027.2 では USD for Maya が 0.35 から 0.37 です。新規インストールでは MaterialX がデフォルトのマテリアルターゲット（0.34）ですが、readme には UsdPreviewSurface と記載されています。-parentScope は非推奨で、代わりに -rootPrim を使用します。
• Alembic は Ogawa のみです。2027.2 では、変形するエクスポートの UV セット順序に関するバグが修正されました。
• MFnMesh は空のメッシュで例外を発生させます（2022.1）。削除されたフラグと PySide の規則については scenario-maya-expert を参照してください。
• リファレンス：2027.1 では、ikRPsolver のリファレンスをアンロードした後に ls(modified=True) がクラッシュする問題が修正されました。2027.2 では、Node Editor を開いた状態でリファレンスを削除するとクラッシュすることがあります。

参照資料

• references/procedures.md：バッチジョブ、組み込みエクスポートジョブ、事前チェック、FBX（静的、スケルタル、クリップ、ログ、法線と軸の検証）、ロックされた法線、Alembic、GPU キャッシュ、USD エクスポートとレイヤー、リファレンスとその健全性、パブリッシュ差分、DG ノードプラグイン、PySide6 パネル、パフォーマンス、GUI 部分の完全なコードが記載されています。パイプラインコードを書く前に読み込んでください。
• references/expert-notes.md：出典別の判断とタイムスタンプ、および判断条件を含む意見の相違が記載されています。選択がブリーフに左右される場合に読み込んでください。
• references/critique.md：出力ごとの評価基準と、H01 から H34 までの各引き継ぎルールの測定箇所が記載されています。実行完了を報告する前に読み込んでください。
• references/gui-paths.md：同じタスクのメニューとオプションが記載されています。
• references/sources.md：認証情報、URL、最適なタイムスタンプを含むすべての出典が記載されています。
• scripts/mx_pipeline.py：オフラインでテスト済みのモジュール（docstring にすべての関数が記載されています）。