blender-to-unity

Blender → Unity 模型交接

将 Blender 中当前的模型导入已打开的 Unity 场景。两者通过本地文件系统衔接：Blender 导出文件，Unity 导入文件。两个服务之间不会直接通信。

前提条件

• mcp__blender__* 工具和 MCP for Unity 工具均已连接。
• Blender 场景中存在模型（使用 mcp__blender__get_scene_info / mcp__blender__get_object_info 确认）。如果场景为空，请停止并告知用户——此技能不会生成模型。
• import_model_file 位于 asset_gen 工具组中，而该组默认处于关闭状态（默认只加载 core）。请先使用 manage_tools 启用 asset_gen 组，或者直接通过 batch_execute 调用 C# 处理程序—— {"tool":"import_model_file","params":{"sourcePath":...,"name":...,"outputFolder":...}}（camelCase） ——该调用会按名称分发，不受工具组启用状态限制。

步骤

1. 解析 Unity 项目路径。 读取 mcpforunity://editor/state，获取项目根目录（编辑器 dataPath 的父目录）。确定导出格式：
   • 当模型带有骨骼绑定、动画、PBR（金属度/粗糙度）、自发光或透明效果时，使用 GLB（glTFast） — glTFast 会自动保留这些属性，无需后处理（参见 references/bridge-fidelity.md）。多材质区域在两种格式中都会保留，因此仅有多材质区域并不足以要求使用 GLB。
   • 否则使用 FBX — 适用于未安装 glTFast、模型仅包含普通几何体，或你明确需要使用内置导入器的 humanoid-avatar 工作流的情况。FBX 会丢失自发光/金属度（步骤 5 会恢复自发光），只有设置 animation_type 后才会显示动画（步骤 3）。
2. 从 Blender 导出到临时路径，通过 mcp__blender__execute_blender_code 执行：

   import bpy, os, tempfile
   out = os.path.join(tempfile.gettempdir(), "blender_to_unity.fbx")
   # Export the selection if any, else the whole scene:
   bpy.ops.export_scene.fbx(filepath=out, use_selection=bool(bpy.context.selected_objects),
                            apply_unit_scale=True, bake_space_transform=True)
   print(out)
   

   （glTF 分支：out_glb = os.path.join(tempfile.gettempdir(), "blender_to_unity.glb")，然后执行 bpy.ops.export_scene.gltf(filepath=out_glb, export_format='GLB', use_active_scene=True) — 其默认值 use_active_scene=False 可能会悄悄导出另一个已打开的场景。）
3. 使用 import_model_file 导入到 Unity： import_model_file(source_path=<temp path>, name=<asset name>, target_size=<final size in meters>)。 对于带骨骼绑定/动画的 FBX，还要传入 animation_type="generic"（或 "humanoid"；"legacy" 用于旧版 Animation 组件系统）— 导入器默认值为 "none"，会有意将网格导入为零个动画片段。GLB 会忽略此参数（glTFast 会自行导入动画），因此该参数仅适用于 FBX。 返回 { asset_path, asset_guid }。将 target_size 设为预期的最终尺寸，但仅将其视为提示：只有项目启用了 Auto-normalize 偏好设置时，导入时才会重新缩放；即使启用，对 Blender FBX 也不可靠（参见 Scale 说明）。步骤 4 会进行可靠的尺寸归一化。
4. 将模型放入场景，并归一化到目标尺寸。 确保场景中有摄像机和定向光（使用 manage_scene / manage_gameobject）。通过 manage_gameobject(action="create", prefab_path=<asset_path>, name=<asset name>, position=[x,y,z]) 在选定位置实例化模型。 然后以确定的方式归一化其尺寸 — Blender FBX 导入后通常会大约放大 100 倍 — 测量放置后模型的世界边界，并缩放模型，使其最大尺寸等于目标尺寸。通过 execute_code 运行（替换对象名称和目标尺寸，单位为米）：

   var go = GameObject.Find("<asset name>");
   var rs = go.GetComponentsInChildren<Renderer>();
   var b = rs[0].bounds; for (int i = 1; i < rs.Length; i++) b.Encapsulate(rs[i].bounds);
   float maxDim = Mathf.Max(b.size.x, Mathf.Max(b.size.y, b.size.z));
   float target = 2f; // intended size in meters
   if (maxDim > 0.0001f) go.transform.localScale *= target / maxDim;
   

5. 恢复 FBX 丢失的自发光效果（FBX 路径）。 Blender 场景通常会将颜色/辉光存储在材质自发光（以及其他 Principled 节点输入）中。FBX 会保留基础色/漫反射颜色，但不会保留自发光，因此霓虹灯 /“Tron”场景会导入为暗色主体和黑色点缀。如果导入效果相较 Blender 显得平淡，请恢复自发光： a. 通过 execute_blender_code 从 Blender 导出自发光材质：

   import bpy, json
   out = {}
   for m in bpy.data.materials:
       if not (m.use_nodes and m.node_tree): continue
       col, s = (0, 0, 0), 0.0
       p = next((n for n in m.node_tree.nodes if n.type == 'BSDF_PRINCIPLED'), None)
       es = next((k for k in ('Emission Color', 'Emission') if p and k in p.inputs), None)  # 4.x / 3.x name
       if es:
           col = tuple(p.inputs[es].default_value)[:3]
           s = float(p.inputs['Emission Strength'].default_value)
       e = next((n for n in m.node_tree.nodes if n.type == 'EMISSION'), None)
       if e and s == 0:
           col = tuple(e.inputs['Color'].default_value)[:3]; s = float(e.inputs['Strength'].default_value)
       if s > 0 and sum(col) > 0.01:
           out[m.name] = [round(col[0], 3), round(col[1], 3), round(col[2], 3), round(s, 3)]
   print(json.dumps(out))
   

   b. 在 Unity 中（使用 execute_code）：提取 FBX 的材质，使其可编辑 （对每个 Material 执行 AssetDatabase.ExtractAsset，然后执行 ImportAsset(fbx, ForceUpdate)），再对每个导出的名称设置 _EmissionColor = color * Mathf.Clamp(strength*0.45f, 1.5f, 5f)、 EnableKeyword("_EMISSION") 和 globalIlluminationFlags = RealtimeEmissive。以不区分大小写的方式匹配名称 — FBX 可能会更改大小写，并将一个材质拆分成多个变体 （EdgeCyan → EdgeCyan + EDGE_CYAN）；对每个匹配项都进行设置。添加全局 Bloom volume，并启用摄像机的 renderPostProcessing，使自发光真正产生辉光。
6. 验证：使用 manage_camera(action="screenshot", include_image=true)，并报告资源路径和截图。

注意事项

• 缩放。 Blender 中的模型导入 Unity 时，缩放几乎总是不正确——其 FBX 单位处理会导致模型在 Unity 中放大约 100 倍。只有在项目启用了 Auto-normalize 首选项时，import_model_file 的 target_size 才会在导入时调整缩放；而对于 Blender FBX，其导入器级别的标准化并不可靠（可能调整过大或过小，例如 target_size=2 的模型测量结果为 200 m）。可靠的解决方法是执行第 4 步中的测量边界并设置 localScale 流程，无论导入缩放或 Auto-normalize 首选项如何，都能确定性地达到目标尺寸。
• 材质与发光。 FBX 可以正常保留基础色／漫反射颜色和变换，但会丢弃发光和任何基于节点的颜色——因此，Blender 霓虹灯／“Tron”场景（颜色存储在发光属性中）会以暗色主体和黑色装饰导入。有两种解决方法：(a) 安装了 glTFast 时优先使用 glTF/GLB——glTF 的 PBR 模型原生支持 emissiveFactor 和 KHR_materials_emissive_strength，因此无需后续处理即可保留发光属性（bpy.ops.export_scene.gltf(filepath=out, export_format='GLB', use_active_scene=True)）；(b) 使用 FBX 时，执行第 5 步，导出 Blender 的发光属性并重新应用。还要检查网格是否有 color_attributes（顶点颜色）层——FBX 会保留其数据，但 URP Lit 不会显示这些颜色；这需要使用能读取顶点颜色的着色器，而不是 _EmissionColor。
• FBX 是默认格式，因为 Unity 的 MCP 中 glTFast 是可选的。如果导入时报错 "GLB import requires glTFast"，请重新导出为 FBX（或从 Dependencies 选项卡安装 glTFast）。
• 格式保真度。 references/bridge-fidelity.md 是一份经过测试的各格式支持内容对照表。总结：GLB (glTFast) 会自动保留纹理、金属度／粗糙度、发光、透明度和动画；FBX 会丢弃金属度和发光，需要设置 ModelImporter.animationType = Generic 才能显示变换动画，并且需要提取材质／纹理才能分配嵌入的纹理。两种格式都会烘焙修改器并保留几何体和顶点颜色数据（URP Lit 不会显示顶点颜色）。两种格式都不会保留程序化／节点材质——请先在 Blender 中将其烘焙为图像纹理。
• 动画不会自动播放。 导入的动画片段不会驱动模型，除非由 AnimatorController 驱动——放置的模型带有一个控制器为 null 的 Animator，所以看起来会静止。请使用 manage_animation（controller_create → 将动画片段添加为循环状态 → 将 controller_assign 分配给实例）来创建控制器，而不要手动编写 execute_code。参见桥接保真度注意事项 #7。
• 多材质区域会保留。 在 Blender 中按材质槽拆分的网格（例如皮肤／衬衫／裤子区域）会以每个子网格对应一种材质的形式导入——GLB 会原生保留基础色——因此你可以用不同材质区域为模型“穿衣”，导入后仍会完整保留。
• 每次交接只处理一个模型；批量处理时，请使用不同名称重复此流程。
• 此技能不会通过 MCP 桥接发送 API 密钥或文件字节——Unity 会从磁盘读取文件。
• import_model_file 只会复制单个源文件；对于多文件导出（带外部 .bin 文件的文本 .gltf，或带同级 .mtl／纹理文件的 .obj），请先将其压缩为 zip，再传入 .zip 文件——直接传入 .gltf／.obj 会导致其关联文件丢失。