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 且 Downloadable）、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 已開、插件已 Connect；
   • Unity：呼叫編輯器狀態/控制臺類工具（如 manage_editor / read_console）確認橋接 Running。
3. 工具缺失或未連接：按 00 的排查表處理，或退化為命令列批次處理（blender --background --python、Unity batchmode），不要裝作呼叫成功。
4. 首次接入時確認專案的渲染管線（Built-in / URP / HDRP）與 Unity 版本——材質 shader、遮罩通道打包方式都不同。

標準工作循環（每個操作都遵守）

檢查現狀（scene_info / 控制臺）→ 截圖/讀數留證 → 小步執行單個變更
→ 截圖或讀數驗證 → 存盤/記錄 → 再進行下一步

• 先讀後寫：改任何東西前先獲取場景/物件資訊；Blender 改前先 bpy.ops.wm.save_as_mainfile 備份。
• 小塊執行：Blender MCP execute_blender_code 有逾時（約 180s），複雜任務拆成多個程式碼塊；每塊自包含（自己 import bpy、按名字重新選擇物件，不依賴上一塊的記憶體變數）。
• 結果必須可見：Blender 每次匯入/擺放/導出後用 get_viewport_screenshot 驗證；Unity 每步用 read_console 查報錯、用層級/場景查詢確認結果。
• 失敗不硬闖：同類操作失敗兩次，換方法或換通道，記錄現象，不要反覆重試同一呼叫。

三條工作流

流程 A：拿一個現成資產（最常用）

讀 references/04-asset-reuse-workflow.md，走 9 步： 需求單 → 搜素材 → 候選評估（含授權）→ 下載暫存 → Blender 稽核 → 清洗標準化 → 導出 FBX → 質檢渲染目檢 → Unity 匯入驗收。

• 稽核：scripts/blender_asset_audit.py（輸出面數/材質/UV/變換/骨骼/動畫的 JSON 報告，對照預算決定去留）。
• 清洗 + 導出：scripts/blender_prep_unity.py（應用變換、原點歸位、法線重算、統一命名、按 Unity 正確參數導出 FBX）。
• 質檢渲染：scripts/blender_asset_qa_render.py（導出後自動出一張標準燈光/取景的品質圖，目檢貼圖、金屬粗糙度、法線、造型；--turntable N 可出多視角，稽核過的資料 + 眼睛確認都通過才算合格）。
• 授權：非 CC0 資產逐項登記到 assets/asset-ledger.csv（授權類型、來源 URL、署名要求）。

流程 B：從零做一個資產

讀 references/05-model-from-scratch.md：參考圖/尺寸 → 低模搭型 → 高模細節 → UV → 烘焙法線/PBR → 面數與 texel 預算自檢 → 走 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	資產質檢渲染：自動取景、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 資產登記一行

參考文件索引（按需載入）

• 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-pose/腳滑等）

安全鐵律

• 改使用者現有 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-gon 問題、變換已應用
• 場景內縮放正確（人物約 1.7m、與周圍物體比例真實），方向正確
• 材質不粉、貼圖不丟（貼圖隨包/在專案內），URP/HDRP 通道正確
• 有合適碰撞體，角色/帶動畫件已配 Avatar 且動作正常
• 已生成 Prefab，LOD 按要求配置，控制臺無報錯
• 關鍵視角品質圖已由 blender_asset_qa_render.py 出圖並目檢通過（貼圖/法線/金屬粗糙度/造型），再交付使用者確認