huayuehua15-netizen/unity-blender-mcp

Unity + Blender MCP 自律パイプライン

パスに関する注意: このファイル内の scripts/、references/、assets/ は、すべてこの SKILL.md が置かれているディレクトリを基準とします。 他のホストや別の作業ディレクトリに移動する場合は、まず SKILL.md のディレクトリを絶対パスに変換してから呼び出してください。 スクリプト実行時は必ず --python-exit-code 1 を指定してください: Blender はデフォルトで異常終了コードを 0 として返すため、このパラメータを忘れると監査失敗でも成功と表示されます。

概要

このスキルは、AI が MCP（Model Context Protocol）を通じて Blender と Unity を自律操作し、素材優先（Asset-First） のアプローチで 3D ゲームアセットを生産します。まず既存アセットを検索・再利用し、次に AI 生成を検討し、最後にゼロからのモデリングを行い、各アセットを「エンジンにインポートするだけで使える」状態に仕上げます。

核心原則：素材優先の決定木

「XX のモデル/アセットが欲しい」という要求を受けた場合、以下の順序で厳密に判断し、いきなり手作りしてはいけません：

1. MCP 内蔵素材ソース（最速、ダウンロード不要）：Blender MCP の search_sketchfab_models / search_polyhaven_assets（HDRI、PBR テクスチャ、写実モデル）；Unity MCP の import_model（Sketchfab）。
2. CC0 ゲーム素材サイト：Kenney、Quaternius、KayKit、Poly Haven、Poly Pizza——スタイルが統一され、そのままエンジンに使え、商用リスクゼロ。
3. 大手マーケットプレイスの無料エリア：Sketchfab（CC0/CC-BY かつダウンロード可能なものに絞る）、TurboSquid、CGTrader、Fab（Megascans）、BlenderKit。
4. 国内サイト：3d66、模之屋、愛給網など——ライセンスとフォーマットを必ず個別に確認（.max ファイルは Blender で開けないものが多い。03 参照）。
5. キャラクター/アニメーション：ボーンとアニメーションは優先的に Mixamo（無料自動リギング＋数千のモーション）、Quaternius アニメーション付きキャラクターパックを使用。
6. AI 生成：Blender MCP の Hyper3D Rodin / Hunyuan3D、Unity MCP の Tripo/Meshy——単一のはっきりしたオブジェクトに限り使用。シーン全体や地形には使わない。
7. Blender で自作（最終手段）：上記すべてで見つからない場合、または正確な機能構造/カスタムブランドアセットが必要な場合のみ、bpy/モデリングワークフローで自作。

どのソースから取得した素材も、Unity にインポートする前に必ず Blender で監査・クレンジング（ステップ 5）を実施してください。 ダウンロードした生の FBX を直接 Unity にドラッグしてはいけません。

作業開始前：MCP 接続とツール発見（セッションごとに必須）

MCP ツール名は実装によって異なります（Blender 側では ahujasid/blender-mcp、Unity 側では CoplayDev/unity-mcp または Unity 公式 com.unity.ai.assistant が一般的）。ツール名が固定されていると想定しないでください。

1. 現在のセッションで実際に公開されている MCP ツールを一覧表示し、それらを references/00-mcp-connection.md の「標準機能対応表」にマッピングします。
2. 接続状態を確認：
   • Blender：get_scene_info のようなシーン確認ツールを呼び出し、Blender が起動していてプラグインが接続済みであることを確認。
   • Unity：manage_editor / read_console のようなエディタ状態/コンソールツールを呼び出し、ブリッジが動作中であることを確認。
3. ツールがない、または接続されていない場合：00 のトラブルシューティング表に従うか、コマンドラインバッチ処理（blender --background --python、Unity batchmode）にフォールバックします。呼び出しが成功したふりをしてはいけません。
4. 初回接続時には、プロジェクトのレンダリングパイプライン（Built-in / URP / HDRP）と Unity バージョンを確認——マテリアルシェーダー、マスクチャンネルのパッキング方法が異なります。

標準作業サイクル（すべての操作で遵守）

現在の状態を確認（scene_info / コンソール）→ スクリーンショット/数値を取得して証拠を残す → 小さな変更を1つ実行
→ スクリーンショットか数値で検証 → 保存/記録 → 次のステップへ進む

• 読み取り優先: 何かを変更する前に、まずシーン/オブジェクトの情報を取得。Blender では変更前に bpy.ops.wm.save_as_mainfile でバックアップ。
• 小さく分割: Blender MCP の execute_blender_code にはタイムアウト（約180秒）があるため、複雑なタスクは複数のコードブロックに分割。各ブロックは自己完結型（自分で import bpy、名前でオブジェクトを選択し直し、前のブロックのメモリ変数に依存しない）。
• 結果は必ず可視化: Blender ではインポート/配置/エクスポートのたびに get_viewport_screenshot で検証。Unity では各ステップで read_console でエラーを確認し、階層/シーンクエリで結果を確認。
• 失敗しても無理に進まない: 同じ種類の操作が2回失敗したら、方法を変えるかチャネルを切り替え、現象を記録。同じ呼び出しを繰り返さない。

3つのワークフロー

フロー A：既存アセットを取得（最も一般的）

references/04-asset-reuse-workflow.md を読み、9 ステップを実行： 要件リスト → 素材検索 → 候補評価（ライセンス含む）→ ダウンロード・一時保存 → Blender 監査 → クレンジング・標準化 → FBX エクスポート → QA レンダリング・目視確認 → Unity インポート・検収。

• 監査：scripts/blender_asset_audit.py（ポリゴン数/マテリアル/UV/トランスフォーム/ボーン/アニメーションの JSON レポートを出力。予算と照らし合わせて採用/不採用を判断）。
• クレンジング＋エクスポート：scripts/blender_prep_unity.py（トランスフォーム適用、原点リセット、法線再計算、命名統一、Unity の正しいパラメータで FBX エクスポート）。
• QA レンダリング：scripts/blender_asset_qa_render.py（エクスポート後に標準的な照明/アングルで品質画像を自動生成。テクスチャ、メタリック・ラフネス、法線、形状を目視確認。--turntable N で複数アングルを出力。監査データ＋実際の目視の両方で合格したものだけが基準を満たしたと見なされる）。
• ライセンス：CC0 以外のアセットは、1行ずつ assets/asset-ledger.csv に登録（ライセンス種別、ソース URL、クレジット要件）。

フロー B：ゼロからアセットを作成

references/05-model-from-scratch.md を参照：参考図/寸法 → ローポリ形状作成 → ハイポリ詳細 → UV → 法線ベイク/PBR → ポリゴン数・テクセル予算のセルフチェック → フローAのエクスポート/インポート手順を実行。まず AI 生成で代用できないか判断。AI 生成品も同様に監査、リトポロジーが必要。

フロー C：Blender → Unity エンジン内設定

references/06-blender-to-unity.md を参照：モデル/マテリアル/アニメーションのインポート設定 → LOD → コリジョン → マテリアル・テクスチャチャンネルマッピング（URP/HDRP で異なる）→ Prefab 生成 → シーン配置/ライトベイク → ビルド。

• バッチインポート時は、assets/unity/Editor/AssetPostprocessor.cs を Unity プロジェクトの Assets/Editor/ に配置（ディレクトリゲート付きで、指定したインポートディレクトリのみ処理。プロジェクト全体を汚染しない）。

スクリプトとアセット

ファイル	用途	実行方法
scripts/blender_asset_audit.py	現在のシーンまたは指定したモデルファイルを監査し、JSON の「健康診断レポート」を出力	MCP：コードを貼り付けて実行。または blender --background --python scripts/blender_asset_audit.py -- モデルパス
scripts/blender_prep_unity.py	選択したアセットをクレンジングし、Unity 標準の FBX をエクスポート（オプションでアニメーションベイク）	MCP：コードを貼り付けて prep_and_export() を呼び出す。またはコマンドライン -- 出力パス
scripts/blender_asset_qa_render.py	アセットの QA レンダリング：自動フレーミング、HDRI/三点照明、AgX、ニュートラル背景で品質画像を生成。--turntable N で複数アングル対応	blender --background --python ... -- モデルパス 出力.png [--hdri パス] [--turntable 3]。MCP では現在のシーンをレンダリング
assets/unity/Editor/AssetPostprocessor.cs	Unity 側のインポート後処理：テクスチャを拡張子に応じて sRGB/法線/マスクに設定、モデルのスケール統一/法線/メッシュ設定	Unity プロジェクトの Assets/Editor/ にコピー
assets/asset-ledger.csv	アセットライセンス台帳テンプレート	CC0 以外のアセットは1行ずつ登録

参考ドキュメント一覧（必要に応じて読み込み）

• references/00-mcp-connection.md：MCP 接続/ツール発見/安全の鉄則/MCP がない場合のコマンドラインへのフォールバック
• references/01-blender-mcp-playbook.md：Blender MCP ツール一覧 + bpy よく使うコードスニペット集（インポート/クレンジング/マテリアル/LOD/エクスポート/スクリーンショット）
• references/02-unity-mcp-playbook.md：Unity MCP ツール一覧 + シーン/オブジェクト/アセット/マテリアル/スクリプト/ビルド操作
• references/03-asset-libraries.md：素材ライブラリ大全（ライセンス/フォーマット/選定/検索キーワード/3d66 など国内サイトの落とし穴）
• references/04-asset-reuse-workflow.md：素材再利用の9ステップフローと検収チェックリスト
• references/05-model-from-scratch.md：いつ自作するか、Blender ゲームアセット生成パイプライン、AI 生成品の処理
• references/06-blender-to-unity.md：Blender→Unity 標準パイプライン（軸/スケール/FBX パラメータ/マテリアルチャンネル/LOD/コリジョン/Humanoid）
• references/07-troubleshooting.md：症状→原因→修正対応表（ピンクマテリアル/スケール/法線/横向き/コリジョンなし/T ポーズ/足滑りなど）

安全の鉄則

• ユーザーの既存 Blender シーン/Unity シーンを変更する前に、別名でバックアップを保存。インポート、クレンジングはすべて独立した Blender シーンと Unity の Assets/Imports/ 一時ディレクトリ内で完了し、検収後に正式なディレクトリに移動。
• ユーザーのソースファイルを削除・上書きしない。ダウンロードしたオリジナルは一時領域に保持し、クレンジング結果は別名で保存。
• execute_blender_code と Unity の execute_code は任意のコードを実行できるため、現在のタスクに関係ない操作は禁止。危険な操作（削除、一括リネーム、上書きエクスポート）は、影響を受けるオブジェクトを一覧表示してから実行。
• ライセンスが不明瞭なもの（特に NC、学習目的のみ、3d66 の無料品、有料会員限定品）は、絶対に商用プロジェクトに使用しない。代わりに CC0 ソースか自作に切り替える。
• すべてのマテリアル/テクスチャ/モデル名は命名規則に従う（SM_/SK_/T_BC/N/RMA/M/M_/MI_）。日本語ファイル名や日本語テクスチャパスはエクスポート前にすべて英数字に変換。

完了定義（アセットレベル DoD）

Unity に納品する各アセットは、以下をすべて満たす必要があります：

• ライセンスが登録済み（CC0 でも出典を記録）、商用利用に支障がない
• 監査レポート：ポリゴン数が予算内、UV あり、N ゴン問題なし、トランスフォームが適用済み
• シーン内のスケールが正しい（人物約1.7m、周囲の物体との比率が現実的）、方向が正しい
• マテリアルがピンク色でない、テクスチャが欠落していない（テクスチャはパッケージ内/プロジェクト内に存在）、URP/HDRP のチャンネルが正しい
• 適切なコライダーがある。キャラクター/アニメーション付きオブジェクトはアバターが設定され、動作が正常
• Prefab が生成済み、LOD が要求通りに設定され、コンソールにエラーがない
• 重要なアングルの品質画像が blender_asset_qa_render.py で出力され、目視確認（テクスチャ/法線/メタリック・ラフネス/形状）を通過した後、ユーザーに確認を依頼