scenario-maya-expert

Maya エキスパート（ルーターおよびエージェントプロトコル）

Maya のエキスパート作業はスクリプトではなく、ループで進めます。大きな要素から小さな要素へと作り、各段階でディテールを加える前に、計測し、レンダリングし、確認して修正します。このスキルは、すべての Maya タスクが従うプロトコルであり、ほかの scenario-maya-* スキルが呼び出す共通ツールキットであり、それらの案内図でもあります。対象は、Python 経由で操作する macOS Apple Silicon 上の Maya 2027 です。ここで名前を挙げた関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で作業を続行する場合は、ツールのスキーマに基づいて進め、不足している点を明記してください。

ステータス（2026-09-24）： Maya 2027 はまだインストールされていません。scripts/ と references/ 内の Maya 呼び出しは、まだ Maya で実行されていません。純粋な Python の部分と Maya レイヤーのロジックは、フェイクを使ってオフラインで実行され、テストに合格しています。Maya のインストール後、最初に実行するのは次のコマンドです： tests/code/maya-expert/run_all.sh。その後、 archive/tests/maya-expert/<stamp>/results/test_00_probe.json を読み、ここで [verify] と記された項目を修正してください。

1. 実行チャネル

チャネル	用途	ルール
scripts/mx_run.py を使うヘッドレス mayapy	監査、検証、エクスポート、Arnold のレビュー用レンダー、バッチ処理、ビューポートを必要としないすべての作業	python3 mx_run.py [--scene f.ma] [--plugins mtoa,fbx,abc,usd] job.py -- args。シーンごとに子プロセスを 1 つ起動します。クラッシュまたはハングが発生しても、影響するジョブは 1 つです。最後の stdout 行は MX_RESULT {json} です。終了コードは、成功が 0、ジョブエラーが 1、タイムアウトが 4 です。子プロセスには MAYA_DISABLE_ADP=1 と、ログレベル warning の Maya の stderr が渡されます（デバッグ時は --maya-log all）。スクリプトノードは無効です。ソースを上書きしないでください。新しいバージョンを --save-as で保存してください。
scripts/mx_bridge.py を使うライブ GUI Maya	プレイブラスト、ビューポートのキャプチャ、インタラクティブツール、ユーザーが開いているシーン	Emmanuel がスクリプトエディターで mx_bridge_server.start() を一度実行します。その後、Bridge().run(code) を呼び出します。コードの長さに制限はなく、複数のステートメントを記述できます。タイムアウト時も含め、各レコードには result、stdout、stderr、maya_messages（Maya の警告とエラー）、およびトレースバックが含まれます。呼び出すたびにこれらを確認してください。1 回の呼び出しが 1 つのアンドゥチャンクになります。シーンを置き換える前に cmds.file(q=True, modified=True) を確認してください。モーダル UI は開かないでください。完了したら stop() を呼び出してください。

自分で GUI Maya を起動しないでください［追加］。ライセンスを 1 つ使用し、ブリッジなしでは操作できません。同じマシンで同時に実行できる Arnold レンダーは 1 つだけです［追加］。 mayapy：/Applications/Autodesk/maya2027/Maya.app/Contents/bin/mayapy（Maya 2027 Help）。 mx_run.find_mayapy() は、$MX_MAYAPY、$MAYA_LOCATION/bin/mayapy（macOS では MAYA_LOCATION の末尾が Maya.app/Contents）の順に確認し、その後、最新の /Applications/Autodesk/maya20*/ を確認します。セッション開始時に cmds.about(version=True) を記録してください。Smart Bevel、MtoA、USD for Maya は、2027.x によって異なります。

ブリッジでファイルを使う理由： commandPort のデフォルトは MEL で、バッファーは 4096 文字です（コマンドが長すぎると接続が閉じられ、結果が長すぎるとエラーになります）。また、1 つのステートメントの結果しか返しません（Maya 2027 Help、commandPort、Python in Maya）。mx_bridge は短い行を 1 つ送信し、ファイルを介してコードと結果をやり取りします（GG_MayaMCP はハンドラーをあらかじめインストールし、Palmer は 2 回のラウンドトリップを使用します）。セキュリティ：ポートは 127.0.0.1:<port> として開かれ［lsof で確認］、認証はありません。Maya のヘルプでは、INET ポートを開くと、system() を含む任意のコマンドがユーザーとして実行されると警告しています。個人用マシンでのみ使用し、セッション終了後は閉じてください。

機能マトリクス（ドキュメントに基づくものです。プローブテストで各行を確認、または修正します）：

操作	ヘッドレス mayapy	ブリッジ経由の GUI	根拠
cmds / OpenMaya による編集、ファイル IO、リファレンス、FBX、Alembic、USD エクスポート	はい	はい	Maya 2027 Help、Python in Maya
Arnold の静止画（mx_review）	はい、CPU；Arnold バッチライセンスがない場合はウォーターマーク付き	はい	Arnold batch docs
Render -r hw2 によるビューポートスタイルのフレーム	ドキュメント記載あり、macOS では未検証	該当なし	コマンドラインレンダリングのドキュメント
playblast、modelEditor、ビューポートのキャプチャ	いいえ（モデルパネルが必要）［要確認］	はい、mx_review.playblast	スクリプティングの要約
ツールコンテキスト：Quad Draw、Multi-Cut、スカルプト、Paint Skin Weights、Skin Tools、3D ペイント、XGen ブラシ	いいえ	インタラクティブ操作のみ（ストローク API なし）：基盤となるコマンドをスクリプト化	Maya 2027 Help
scriptJob	いいえ	はい、再生中を除く	Maya 2027 Help、scriptJobs
maya.utils.executeInMainThreadWithResult	いいえ、「バッチモードでは利用できません」	はい	Maya 2027 Help、スレッド処理
maya.utils.executeDeferred	アイドルイベントの実行時のみ［要確認］	はい	同上
MMessage コールバック	［要確認］	はい	スクリプティングの要約
commandPort	Theodore 2014 によると存在しない［要確認］	はい	MCP ブリッジに関する注記
PySide6 ウィンドウ、workspaceControl	いいえ	はい	Qt6 移行ドキュメント
Flow Retopology（クラウド）	いいえ：サインインとネットワーク接続が必要［追加］	はい	バージョン間の差分
confirmDialog、input()、pdb、ファイルダイアログ	いずれも不可	いずれも不可：Maya のメインスレッドとブリッジをブロックします	Maya 2027 Help、標準入力

2. エキスパートのループ（あらゆるドメイン）

1. 数値で概要を伝えます。 目的（エンジン、映画、静止画、アニメーション）、予算（ポリゴン数、テクスチャサイズとテクセル密度、フレーム範囲と fps）、スタイル、参考資料、期限を示します。概要に記載がない場合は、そのドメインのスキルに記載されたデフォルトを採用し、明記します。
2. ドメインスキルに沿って、全体から細部へと段階を進めます。細部から始めてはいけません。
3. 小さく冪等なスクリプトで各段階を構築します（名前で取得または作成し、作成したものにタグを付け、選択状態に依存しないようにします）。
4. 測定可能なチェック（mx_audit.verdict、mx_validate、そのドメインの数値）と、画像リーダーで開いたレンダー（ヘッドレスでの mx_review.review シート、または GUI でのプレイブラスト）の両方で段階を検証します。エキスパートはモデルを常に回転させて確認します。コンタクトシートはエージェントにとってのオービットです。そのドメインの references/critique.md に基づいて評価します。
5. 次に進む前に修正します。ブロックアウトで見つかった問題はスクリプト 1 本の修正で済みますが、テクスチャリング後に見つかると、段階全体のやり直しになります。
6. 証拠を添えて納品します。保存済みのバージョン、監査と検証の JSON、シートまたはプレイブラスト、未検証項目の一覧を含めます。

レンダーを実際に確認せずに、モデル、リグ、ショット、レンダーを完成したと報告してはいけません。まず数値、次に目視です。Fragapane が示す、ツールの一致を判定する基準は、期待値行列の逆行列に計算値行列を掛けると単位行列になることです。「見た目が合っている」ことではありません（Cult of Rig、[01:16:03]）。dcc-mcp のショーケースでは、差分が 0.0、色のずれが最大でも 1/255 であることを示して主張を裏付けています。

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

概要	スキルチェーン	成果物
ハードサーフェスのプロップまたはゲームアセット	scenario-maya-modeling, scenario-maya-retopology-uv, scenario-maya-lookdev, scenario-maya-pipeline-scripting (FBX)	ローポリ、UV、PBR セット、再インポートして比較した FBX
AI 生成メッシュの仕上げ	scenario-3d, 生メッシュに対する mx_audit、scenario-maya-retopology-uv, scenario-maya-lookdev, scenario-maya-pipeline-scripting	指定した予算内に収め、生成したハイポリからベイクしたクリーンな UV 付きアセット
キーフレームアニメーション用キャラクター	scenario-maya-modeling, scenario-maya-retopology-uv, scenario-maya-rigging, scenario-maya-deformation, scenario-maya-animation (可動域テスト)	リファレンス付きリグファイル、変形のプレイブラスト
ゲームキャラクター	scenario-maya-rigging と scenario-maya-animation のゲーム向けオプションを使った同じチェーン、その後 scenario-maya-pipeline-scripting	Unreal または Unity 用の FBX スケルタルメッシュとクリップ
アニメーションショット	scenario-maya-animation (scenario-maya-rigging で修正)、その後 scenario-maya-lighting-rendering	承認済みプレイブラスト、その後レンダー
ルックデブまたはヒーロー静止画	scenario-maya-lookdev, scenario-maya-lighting-rendering	ターンテーブル、ライティング済みレンダー、AOV
FX ショット	scenario-maya-fx (nCloth, Bifrost, MASH)、その後 scenario-maya-lighting-rendering	バージョン管理されたキャッシュ、レンダー
グルーミング済みキャラクター	scenario-maya-groom, scenario-maya-lookdev (ヘアシェーダー), scenario-maya-lighting-rendering	グルーム、キャッシュ、レンダー
パイプラインまたはバッチツール	mx_run と mx_validate を基盤に構築した scenario-maya-pipeline-scripting	ツールと JSON レポート

引き継ぎの要件： 引き継ぎには必ず、新しく保存したバージョン（ソースを上書きしないこと）、受け取り側のプロファイルに対する fail のない mx_validate レポート、メッシュの mx_audit 数値、送信者が確認したシートまたはプレイブラスト、未検証項目の一覧を含めます。単位は cm、上方向は Y のままにします（Maya 2027 Help。Unreal の単位は 1 cm です）。

From, to	Gate in code	Look at
modeling から retopology-uv または rigging	validate(profile="model") がクリーンであること、変形するメッシュにロックされた法線がないこと、サブディバイドまたは変形するメッシュに n-gon が 0 個であること、フリーズ済みで履歴がないこと（FlippedNormals）、キャラクターが X 軸で対称で、原点のグリッド上に立ち、Y-up で +Z を向いていること（Quick Rig で必要）	シルエットとクレイシート
retopology-uv から lookdev または rigging	すべての面にマッピングがあること、UV が 0-1 または整然とした UDIM タイル内にあること、テクセル密度が px/cm で指定されていること、意図的に重ねている場合を除き、重なりがないこと	ワイヤーフレームと法線のシート
rigging または deformation から animation	リグが参照されており、インポートされていないこと、profile="rig" がクリーンであること、引き渡し前に Skin Tools レイヤーが削除されていること（Maya 2027 Help：Delete Skin Layers はウェイトを保持します）	可動域のプレイブラスト
animation から lighting	profile="shot", rules={"fps": ...} がクリーンであること、参照が読み込まれていること、キャッシュがバージョン管理されていること（Alembic は Ogawa のみ）	最終プレイブラスト
lookdev から lighting	file_paths のチェックに合格すること、ファイルノードごとに色空間が設定されていること	ターンテーブル
fx または groom から lighting	キャッシュがフレーム範囲とともにバージョン管理されていること、Nucleus と Bifrost が 1 unit = 1 m を前提としていること（Maya 2027 Help）	キャッシュのプレイブラスト

4. 共通ツールキット（scripts/、Mayaではまだ実行されていません）

インポート：import sys; sys.path.insert(0, "<this skill>/scripts")。ブリッジサーバーはこのフォルダーを Mayaのsys.pathに追加するため、GUIでもBridge().call("mx_audit", "audit", "crate_geo")を実行できます。

• mx_run.py：find_mayapy()、 run_subprocess(job, args, scene=, plugins=, timeout=, save_as=, maya_log=)（親側で実行し、解析済みの dictを返します）、child_environment()、run(job, args)（mayapy内で実行）。
• mx_bridge.py / mx_bridge_server.py： Bridge(port=7001).ping() / run(code) / call(module, fn, *a, reload=True) / fetch(id)、 format_record(rec)、サーバーのstart() / stop() / handle(id)。
• mx_audit.py：audit(mesh, texture_size=2048, units="cm")は、カウント、バレンスごとの極、 非多様体、ラミナ、ゼロ面積、境界と穴、巻き方向、UVセットと境界ボックス、 UDIMタイル、重複および折り畳まれたシェル、シェルごとのテクセル密度、フリーズされたトランスフォーム、 ピボット、ヒストリ、命名、インスタンス、X軸対称性、エッジ長のCVを返します。verdict(report, profile="game"|"film"|"subd")は error: / warn: / info:の各行を列挙します。audit_all(roots)。すべてのスキル向けのガード： mfn_mesh(shape)（メッシュが空の場合はNone）、is_empty_mesh、split_history（バインドポーズとウェイトドライバーは ヒストリに含まれません）。
• mx_review.py：review(targets, out_dir, views, modes, resolution=1024, tile=512, focus=None)： front、side、back、threequarter、top、low、clay、wire、silhouette、normals、オプトインのchecker （checker_repeats=）とカスタムのshader_modes=、subdiv=。ラベル付きシート1枚とタイル、 各ビューのカメラ（r["cameras"]、review.json、pixel_ray）を出力し、ユーザーの設定を復元します。スキルではこれらの オプションを使用し、_Sessionは使用しません。turntable(targets, out_dir, frames=24)、 playblast(path, start, end, display={...})（GUIのみ）。
• mx_validate.py：validate(profile="model"|"rig"|"shot", roots=None, rules=None, fix=())： 命名、ネームスペース、ヒストリ、フリーズされたトランスフォーム、非多様体、ラミナ、Nゴン、UV、 ロックされた法線、スムージング、レンダー統計、レイヤー、セット、未使用ノードと不明なノード、 プラグイン、リファレンス、スクリプトノード、単位と上方向、フレームレート、欠落ファイルを検証します。SAFE_FIXES、修正中もUUIDで保持されるルート （roots_after）。

5. Mayaコードのルール（汎用コードでよくある誤り）

• 選択に依存せず、明示的に指定する： すべてのコマンドにノード名を渡し、selectしてから操作するのは避けてください。 作成コマンドの戻り値を取得してください（polyCubeは[transform, history]を返し、#で名前が展開されます）。指定した名前ではなく、 戻り値を使用してください（Autodesk入門シリーズ）。
• 短い名前が重複する可能性があるものには、ロングネームまたはUUIDを使用してください。ls、 listRelatives、listConnectionsの後にはor []を付けてください（追加、検証済み）。
• Undoの管理は自分で行ってください： GUIでの編集はtry/finallyを使ってUndoチャンクで囲みます。OpenMaya 2.0による書き込みは Undoキューに反映されません。また、OM2でcmdsが作成したノードを削除すると、Undoが破損します（Fragapane、 [01:17:49]）。重い読み取りと行列の処理にはOM2を、ユーザーがUndoできる編集にはcmdsを使用してください。
• 単位： OpenMayaはセンチメートルとラジアンを使用し、cmdsはUIの単位と度を返します（追加、 test_00_probeで検証済み）。
• 自分が作成していないノードには触れないでください。 自分のノードにはタグ（ネームスペース、属性、またはセット）を付け、タグを使って クリーンアップします。ステージのバージョンを保存し、ソースは上書きしないでください。
• メインスレッドのみ： メインスレッド以外で実行するとcmdsは例外を発生させます（Maya 2027 Help）。

6. 記憶しているコードを壊す Maya 2027 の落とし穴

• PySide6 のみを使用し、PySide2 のフォールバックは含めないでください（PySide2 がインストールされていると、2027.0 でクラッシュしました）。 dockControl は廃止されました：workspaceControl を使用します。
• 新しいシーンでは OpenPBR Surface が使用されます。そのパラメーターは Standard Surface から引き継がれません（エミッションはニット単位、薄膜はマイクロメートル単位、SSS の半径の役割が入れ替わっています）。
• addDoubleLinear、multiplyDoubleLinear、pointMatrixMult は、それぞれ addDL、multiplyDL、pointMatrixMultDL になりました（2026）。power のような一般的な名前は、単位のないノードを作成するようになりました。
• 削除されたフラグ：getAttr(noEvaluation=)、attributeQuery(computeModifies=)。すべてのキーを対象にするには cutKey(time=(None, None)) を使用します。
• macOS の Arnold：CPU のみで、OptiX は使用できません。新しいシーンでは OIDN imager が使用されます。Maya IPR は MtoA 5 以降では動作しません（Arnold RenderView を使用）。ライセンスエラーが発生すると、ARNOLD_FORCE_ABORT_ON_LICENSE_FAIL=0 を設定しない限り、バッチレンダリングは中断されます。
• カラー：OCIO v2 と ACEScg を使用します。2026.2 以降、デフォルトの入力色空間は sRGB Encoded Rec.709 (sRGB) です。名前をハードコードせず、問い合わせてください。
• Skin Tools のレイヤーがあると、削除するまで従来のウェイトツール（Mirror、Copy、Hammer、Paste、Normalize、Set Max Influences）がブロックされます。
• maya -render は廃止されました：Render -r <renderer> を使用します。Render Setup と従来のレンダーレイヤーは、1 つのセッション内では併用できません。
• mayaUSDExport のデフォルト：frameRange は [1,1]、スキームは catmullClark、map1 は st に名称変更されています。
• 空のメッシュでは MFnMesh が例外を発生させます（mx_audit.mfn_mesh を使用してください）。MItGeometry ですべての頂点を対象にするには、グループに -1 を指定する必要があります。PyMEL は同梱されていません。Python のバージョンは文書化されていないため、確認してください。

参考資料

• references/maya-2027-traps.md：エージェントのコードを壊すもの、古い名前から 2027 年の置き換え先への対応、出典をまとめた完全な一覧です。記憶を頼りにコードを書く前、または 2025 年以前のチュートリアルに従う前に読み込んでください。
• references/cmds-reliability.md：信頼性の高い maya.cmds と OpenMaya 2.0 のためのイディオムと、テスト待ちの手順をまとめています（戻り値の型、評価済みデータと元データの違い、OM2 のパターン、取り消し、冪等な get-or-create、バッチ処理の衛生管理）。複雑なスクリプトを書く前に読み込んでください。
• references/sources.md：このスキルとツールキットのすべての出典と、それぞれの活用に最適な場面をまとめています。
• このセット以外の関連スキル：scenario-3d（Maya で仕上げるメッシュを生成）、scenario-zbrush-expert、scenario-blender-expert（同じプロトコルを使用する姉妹チーム）。