huayuehua15-netizen/unity-blender-mcp

Unity + Blender MCP Autonomous Pipeline

Path Convention: All scripts/, references/, and assets/ paths in this file are relative to the directory containing this SKILL.md. When moving to a different host or working directory, first resolve the SKILL.md directory into an absolute path before invoking. Always include --python-exit-code 1 when running scripts from the command line: Blender's default exit code for abnormal termination is 0; without this flag, a failed audit may be reported as successful.

Overview

This skill enables an AI to autonomously operate Blender and Unity via MCP (Model Context Protocol) following an Asset-First approach to produce 3D game assets: first search and reuse, then AI generate, and only as a last resort model from scratch — delivering each asset as a "ready-to-import-into-engine" final product.

Core Principle: Asset-First Decision Tree

When receiving any request for a "model/asset XX", strictly follow this order — do not start modeling from scratch immediately:

1. MCP Built-in Asset Sources (fastest, zero downloads): Blender MCP's search_sketchfab_models / search_polyhaven_assets (HDRI, PBR textures, realistic models); Unity MCP's import_model (Sketchfab).
2. CC0 Game Asset Sites: Kenney, Quaternius, KayKit, Poly Haven, Poly Pizza — consistent style, directly usable in engines, zero commercial risk.
3. Free Sections of Major Markets: Sketchfab (filter CC0/CC-BY and Downloadable), TurboSquid, CGTrader, Fab (Megascans), BlenderKit.
4. Domestic Sites (China): 3d66, Mofu House, Aigei Network — must check licensing and format individually (many .max files cannot be opened in Blender — see 03).
5. Characters/Animations: Prioritize Mixamo (free auto-rigging + thousands of animations) and Quaternius animated character packs for skeletons and animations.
6. AI Generation: Blender MCP's Hyper3D Rodin / Hunyuan3D, Unity MCP's Tripo/Meshy — use only for single, clearly-defined objects, not entire scenes/terrain.
7. Blender Custom Build (last resort): Use bpy/modeling workflows only when nothing above is found, or precise functional structure/custom brand assets are required.

Assets from any source must go through Blender audit and cleaning (Step 5) before entering Unity. Do not drag downloaded raw FBX directly into Unity.

Before Starting: MCP Connection and Tool Discovery (Mandatory Every Session)

MCP tool names vary by implementation (commonly ahujasid/blender-mcp for Blender; CoplayDev/unity-mcp or Unity official com.unity.ai.assistant for Unity) — do not assume fixed tool names.

1. First, list the MCP tools exposed in the current session and map them against the "Standard Capability Comparison Table" in references/00-mcp-connection.md.
2. Check connection status:
   • Blender: Call a scene inspection tool (e.g., get_scene_info) to confirm Blender is open and the plugin is Connected.
   • Unity: Call an editor state/console tool (e.g., manage_editor / read_console) to confirm the bridge is Running.
3. If tools are missing or not connected: Follow the troubleshooting table in 00, or fall back to command-line batch mode (blender --background --python, Unity batchmode). Do not pretend calls succeeded.
4. On first connection, confirm the project's render pipeline (Built-in / URP / HDRP) and Unity version — material shaders and mask channel packaging differ.

Standard Work Loop (Follow for Every Operation)

Check state (scene_info / console) → screenshot/read for evidence → execute single small change
→ verify with screenshot or read → save/record → proceed to next step

• Read before write: Get scene/object info before modifying anything; save backup with bpy.ops.wm.save_as_mainfile in Blender before making changes.
• Small chunks: Blender MCP's execute_blender_code has a timeout (~180s); split complex tasks into multiple code blocks. Each block must be self-contained (import bpy, re-select objects by name — do not rely on variables from previous blocks).
• Results must be visible: Verify every Blender import/placement/export with get_viewport_screenshot; in Unity, check errors with read_console after each step and confirm results via hierarchy/scene queries.
• Do not force failures: If two attempts with the same operation fail, switch method or channel, record the symptoms, and do not retry the same call repeatedly.

Three Workflows

Workflow A: Reuse an Existing Asset (Most Common)

Read references/04-asset-reuse-workflow.md and follow the 9 steps: Requirements list → Search for assets → Candidate evaluation (including licensing) → Download to staging → Blender audit → Clean and standardize → Export FBX → QA render & visual inspection → Unity import & validation.

• Audit: scripts/blender_asset_audit.py (outputs a JSON report of polycount/materials/UVs/transforms/skeleton/animation — compare against budget to decide keep/discard).
• Cleaning + Export: scripts/blender_prep_unity.py (applies transforms, resets origin, recalculates normals, uniform naming, exports FBX with correct Unity parameters).
• QA Render: scripts/blender_asset_qa_render.py (automatically generates a quality image with standard lighting and framing after export; inspect textures, metalness/roughness, normals, shape; --turntable N for multi-angle shots — only pass data+human verification).
• Licensing: Register every non-CC0 asset in assets/asset-ledger.csv (license type, source URL, attribution requirements).

Workflow B: Create an Asset from Scratch

Read references/05-model-from-scratch.md: Reference images/dimensions → Low-poly blockout → High-poly detail → UVs → Bake normals/PBR → Self-check polycount and texel budget → Follow A's export/import steps. First determine if AI generation can replace it; AI-generated assets also require audit and retopology.

Workflow C: Blender → Unity Engine Setup

Read references/06-blender-to-unity.md: Model/material/animation import settings → LODs → Colliders → Material texture channel mapping (URP/HDRP differences) → Generate Prefab → Scene placement/light bake → Build.

• For batch imports, place assets/unity/Editor/AssetPostprocessor.cs into the Unity project's Assets/Editor/ (with directory gating to only process the specified import folder — won't pollute the entire project).

Scripts and Assets

File	Purpose	How to Run
scripts/blender_asset_audit.py	Audit current scene or specified model file, output JSON inspection report	MCP: paste and execute code; or blender --background --python scripts/blender_asset_audit.py -- <model path>
scripts/blender_prep_unity.py	Clean selected assets and export Unity-standard FBX (with optional animation baking)	MCP: paste code then call prep_and_export(); or command line -- <output path>
scripts/blender_asset_qa_render.py	Asset QA render: auto-framing, HDRI/three-point lighting, AgX, neutral background produces quality image; supports --turntable N multi-angle	blender --background --python ... -- <model path> <output.png> [--hdri <path>] [--turntable 3]; MCP paste renders current scene
assets/unity/Editor/AssetPostprocessor.cs	Unity import post-processor: set sRGB/normal/mask based on texture suffix, uniform scale/normal/mesh settings for models	Copy to Unity project Assets/Editor/
assets/asset-ledger.csv	Asset licensing ledger template	One row per non-CC0 asset

Reference Document Index (Load as Needed)

• references/00-mcp-connection.md: MCP connection/tool discovery/safety rules/command-line fallback without MCP
• references/01-blender-mcp-playbook.md: Blender MCP tool table + bpy common code snippet library (import/clean/material/LOD/export/screenshot)
• references/02-unity-mcp-playbook.md: Unity MCP tool table + scene/object/asset/material/script/build operations
• references/03-asset-libraries.md: Asset library encyclopedia (licensing/format/selection/search keywords/pitfalls of domestic sites like 3d66)
• references/04-asset-reuse-workflow.md: Asset reuse 9-step workflow and acceptance checklist
• references/05-model-from-scratch.md: When to build from scratch, Blender game asset generation pipeline, handling AI-generated assets
• references/06-blender-to-unity.md: Blender→Unity standard pipeline (axis/scale/FBX parameters/material channels/LOD/colliders/Humanoid)
• references/07-troubleshooting.md: Symptom→cause→fix reference table (pink materials/scale/normals/fallen/collision missing/T-pose/sliding feet, etc.)

Safety Rules

• Before modifying a user's existing Blender/Unity scene, save a backup separately; all imports and cleaning must be done in separate Blender scenes and Unity's Assets/Imports/ staging directory — only move to the final directory after passing acceptance.
• Do not delete or overwrite user source files; keep downloaded originals in staging, save cleaning outputs separately.
• execute_blender_code and Unity's execute_code can execute arbitrary code — prohibit operations unrelated to the current task; for dangerous operations (deletion, batch renaming, overwrite exports), first list the affected objects before executing.
• Assets with unclear licenses (especially NC, learning-only, 3d66 free items, paid membership items) must never enter commercial projects — prefer switching to CC0 sources or building from scratch.
• All material/texture/model naming must follow conventions (SM_/SK_/T_BC/N/RMA/M/M_/MI_); Chinese filenames and Chinese texture paths must be converted to English before export.

Definition of Done (Asset-Level DoD)

Every asset delivered to Unity must satisfy:

• License recorded (CC0 must also note the source), clear for commercial use with no blockers
• Audit report: polycount within budget, UVs present, no N-gon issues, transforms applied
• Correct in-scene scale (human ~1.7m, proportional to surrounding objects), correct orientation
• Materials not pink, textures not missing (textures included in package/within project), URP/HDRP channels correct
• Appropriate colliders present; characters/animated assets have Avatar configured and animations work correctly
• Prefab generated, LOD configured as required, console shows no errors
• Key-angle quality image rendered by blender_asset_qa_render.py and visually inspected (textures/normals/metalness-roughness/shape) — then confirm with the user