Community图像github.com

Blender 实时绑定

通过官方的 Blender MCP 套接字桥,在用户当前打开的 Blender 应用中实时进行 3D 资源的绑定、编辑、验证和导出。适用于骨架、蒙皮、机械/铰链绑定、驱动、自定义属性控制、评估网格验证、烘焙的 glTF 导出,以及仅在资源所有者明确要求时进行渲染。

Blender 实时绑定 是什么?

该技能使 AI 代理能够直接操控用户正在使用的实时 Blender 会话,实现交互式 3D 模型绑定、蒙皮、动画和导出。它通过官方的 Blender MCP 桥接器(`bl_ext.blenderlab.mcp`)在 `127.0.0.1:9876` 端口工作,确保所有操作仅在实时 GUI 环境中执行,绝不启动头批处理模式或关闭用户的应用程序。该技能强制执行严格规则:除非所有者明确要求,否则不使用渲染作为验证手段,而是依赖数值指标(顶点坐标、面面积比)来验证装配质量。其工作流程涵盖连接和检查资产、为机械部件设计刚性绑定拓扑(使用对角线配对处理剪刀/钳子形状)、通过剖切和顶点组准备网格、使用自定义属性驱动(0-1 范围内的“open”)进行控件和动画制作,并通过综合验证流程进行验证,包括通过重新导入 GLB 的评估网格(始终优先于骨骼数据)进行地面碰撞测量。支持 slotted actions (Blender 5.4) 和渲染自由 GLB QA,提供无 Blender 依赖的栅控。由于采用了实时会话方法,使得增量保存、视口聚焦和原子性、幂等性执行步骤成为可能。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/andypratama3/blender-mcp/tree/HEAD/skills/blender-live-rigging

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Blender 实时绑定 是做什么的?

驱动用户正在查看的 Blender 实例。无头批次处理,不关闭他们的应用程序。每个“完成”声明必须由从评估的依赖图 (depsgraph) 读取的数字支持。渲染默认关闭,仅在所有者要求时进行。

仓库文档(在需要深度时阅读,不必每次都读):

  • docs/MCP_BRIDGE.md — 协议、启动模式、陷阱、视口聚焦
  • docs/RIGGING_PLAYBOOK.md — 完整绑定方法及导出/恢复方案
  • docs/VERIFICATION.md — 指标阈值和代码片段
  • docs/RENDERING.md — 所有者请求的渲染路径
  • reference/roblox-avatar.md — R15 身体契约、原地行走 IK、FBX 验证
  • reference/blender-5x-api.md — 槽化动作 (slotted actions)、实测的 5.4 API、glTF 时间原点
  • reference/glb-qa.md — 无渲染的 GLB 门控、基线、负面测试证据
  • docs/CASE_STUDY_KNIGHT.md — 实测的 R15 角色 + 行走循环(仓库根目录)

如果此技能是从 andypratama3/blender-mcp 安装的,那么仓库根目录位于此文件向上三级 (skills/blender-live-rigging/SKILL.md)。

硬性规则

  1. 仅限实时 GUI。 确认 bpy.app.background == False。绝不在用户工作时关闭 Blender;如果必须因端口冲突重启,请先保存 .blend 文件并重新打开同一文件。
  2. 除非所有者要求,否则不进行渲染。 默认验证是数值化的:顶点坐标、宽度、面积、比率。当所有者明确要求渲染时,在实时会话中执行(参见 按需渲染)。
  3. 聚焦你正在编辑的视口,在更改前后都要执行:选择对象/骨骼,激活一个,运行 view3d.view_axis + view3d.view_selected。选择与资源平面匹配的轴(对于平面 XZ 资源使用 FRONT)。
  4. 始终使用评估后的网格,而不是原始网格:obj.evaluated_get(depsgraph).to_mesh()。
  5. 使用 scene.frame_set(f) 强制驱动求值 — view_layer.update() 是不够的。
  6. 在每个里程碑处使用 bpy.ops.wm.save_as_mainfile(filepath=..., compress=True) 进行增量保存;将交付物保留在项目文件夹内。
  7. 一次 execute = 一个原子、幂等步骤,返回证明其效果的指标。
  8. 测量网格上接触地面的部分,而不是骨骼。 骨尾可能位于鞋底上方 0.4 stud 处,因此骨尾门控可能通过,而靴子却陷入地下。使用评估网格的最低世界坐标顶点。

1. 连接

桥接器是 127.0.0.1:9876 上的官方插件 bl_ext.blenderlab.mcp。

lsof -nP -iTCP:9876 -sTCP:LISTEN          # 启动前端口必须空闲
open -a Blender --args --online-mode "/abs/path/file.blend"   # macOS
sleep 8 && lsof -nP -iTCP:9876 -sTCP:LISTEN

--online-mode 是必需的(自动启动需要 bpy.app.online_access),并且永远不要使用 --factory-startup(它会禁用扩展)。然后:

python3 scripts/blender_mcp.py 'import bpy
result = {"gui": not bpy.app.background, "file": bpy.data.filepath}'

2. 检查资源

导入 glTF,将 matrix_world 烘焙到网格数据中,删除空父级,焊接重复顶点 (remove_doubles(1e-5)),计算连接的壳数,并打印 ASCII 轮廓以找到平面、枢轴和移动部件:

blender -b --factory-startup --python scripts/inspect_glb.py -- "/path/asset.glb"

3. 决定绑定拓扑

对于机械资源:刚性部件,刚性权重,每个部件一根骨骼。对于剪刀/钳子形状,对角配对部件(左手柄 + 右钳口的一半),使手柄和钳口一起张开;中线分割会使钳口在张开时闭合。

将铰链枢轴放在手柄交汇处,将剖切线也放在那里,并对齐骨骼,使得 rotation_euler.x 就是世界的铰链轴:

d = (Vector(b.tail) - Vector(b.head)).normalized()
b.align_roll(Vector((d.z, 0.0, -d.x)))   # 局部 X == 世界 Y

4. 准备网格

在每个刚性部件边界处使用 use_fill=True 进行剖切,将封口偏移约 0.0004 以消除 Z-fighting,仅翻转封口面(保留 glTF 自定义分割法线),在合并前为每个部件分配顶点组,然后使用 ARMATURE 修改器进行父级化。

5. 控件和动画

一个自定义属性 (open,范围 0–1) 通过简单的驱动器表达式驱动每根骨骼,并使用 LIMIT_ROTATION 作为安全网。在驱动 rotation_euler 之前,设置 rotation_mode = "XYZ"。对属性(而不是骨骼)设置关键帧以用于循环动作,并设置 BEZIER + AUTO_CLAMPED。

6. 验证(在声明成功之前进行门控)

指标阈值
与源网格的静止偏差< 1e-5
循环接缝(最后一帧 vs 第一帧)0
张开/闭合面面积比0.99–1.01
手柄和钳口均向外移动> 0
已加权顶点100%
非流形 / 零面积面0
最低变形顶点与地面的距离≥ −0.006,站立脚 0 ± 0.006

scripts/verify_rig_glb.py 在一个独立的 Blender 进程中重新导入导出的 GLB(绝不干扰实时会话),并打印节点/蒙皮/动画计数以及第 1/15/30/60 帧的宽度。

对于运动,使用双骨骼 IK 针对踝部目标解算腿部,而不是手动设置关节角度,然后测量每一帧:

low = min((ev.matrix_world @ v.co).z for v in ev.to_mesh().vertices)  # 每帧

如果骨骼门控和网格门控不一致,则以网格门控为准。

6d. 无渲染 GLB QA

python3 scripts/glb_qa.py export/model.glb --loop --max-tris 20000
python3 scripts/glb_qa.py export/tool.glb --manifold

仅使用标准库,无需 Blender:它直接读取 GLB 容器并门控头部长度、访问器边界、权重和、未加权顶点、关节索引、绑定姿势计数、关键帧顺序、四元数范数、循环闭合、NaN 以及(使用 --manifold 时)边界边。任何失败均退出 1。verify_rig_glb.py 仍然负责移动部件的宽度测量。门控、基线以及它们捕获的五种故意损坏的文件:reference/glb-qa.md。

6b. 在实时会话中运行多文件项目脚本

导入自身模块的脚本必须在实时会话中通过路径加载:

import importlib.util, sys
spec = importlib.util.spec_from_file_location("walk_cycle", "/abs/project/walk_cycle.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["walk_cycle"] = mod          # 否则 dataclasses/imports 会看到重复
spec.loader.exec_module(mod)
result = mod.main(save=True)             # 返回一个包含测量门控的字典

保留 __main__ 用于头运行 (blender -b file.blend --python walk_cycle.py -- --save),并从桥接器调用 main(),这样同一个脚本可以服务于两种路径。

6c. Blender 5.x 上的动作(槽化)

Action.fcurves、Action.groups 和 Action.id_root 在 5.4 中不存在。使用辅助函数而不是重写 channelbag 遍历,并显式绑定槽:

# 实时会话 (cwd = 此技能文件夹);将审计结果作为 `result` 返回
python3 scripts/blender_mcp.py "import sys; sys.path.insert(0, 'scripts')
import action_compat
result = action_compat.audit()"

# 头运行;当槽未绑定时退出 1
blender -b file.blend --python scripts/action_compat.py
from action_compat import iter_fcurves, ensure_fcurve, assign_action
slot = assign_action(obj, action)                 # 单独分配会使 action_slot 为 None
ensure_fcurve(action, slot, 'pose.bones["Head"].rotation_euler', 1, group_name="HeadTwist")

实测的失败模式:将已具有槽的动作分配给不同的 ID 会导致 animation_data.action_slot is None,并且绑定停留在静止状态,没有任何错误(头部位于 4.0 而不是动画后的 3.92)。门控:action_compat.py 报告每个动画对象的 slot_assigned: true 和 slot_fcurves > 0。另外,使用 channelbag.fcurves.new(..., group_name=...),永远不要使用 action_group=。

详情和其余实测 API:reference/blender-5x-api.md。

7. 导出 glTF

glTF 没有驱动、自定义属性或约束。将它们烘焙:

  1. 重命名源动作 (*_src),以便烘焙后的动作获得一个干净的名称。
  2. 取消链接自定义形状小部件对象,否则它会变成一个空节点。
  3. 清除动作,pose_bone.driver_remove(...),在姿势极值处设置 rotation_euler[0] 的关键帧。
  4. 使用 export_skins=True、export_animations=True、export_animation_mode="ACTIONS"、export_yup=True 导出。
  5. 恢复:重新分配动作,删除烘焙内容,重新链接小部件,重新添加驱动,frame_set(1),保存。

关于“由于不支持的约束而烘焙动画”的警告是预期的。

按需渲染(仅限所有者)

触发条件:所有者明确要求渲染,或要求预览图像/视频。不要主动渲染,也不要将其作为验证手段。

Blender 5.4 将 EEVEE 暴露为 BLENDER_EEVEE(而非 BLENDER_EEVEE_NEXT),因此从枚举中选择,而不是硬编码特定版本的名称。glTF 场景没有相机和灯光——首先在 Render_Setup 集合中创建它们。

import bpy, math, os

scene = bpy.context.scene
engines = [i.identifier for i in bpy.types.RenderSettings.bl_rna.properties["engine"].enum_items]
scene.render.engine = next(e for e in ("BLENDER_EEVEE", "BLENDER_EEVEE_NEXT") if e in engines)

if scene.camera is None:
    cam_data = bpy.data.cameras.new("Preview_Cam")
    cam_data.type = "ORTHO"
    cam_data.ortho_scale = 1.0
    cam = bpy.data.objects.new("Preview_Cam", cam_data)
    scene.collection.objects.link(cam)
    cam.location = (0.0, -2.0, -0.055)
    cam.rotation_euler = (math.radians(90), 0.0, 0.0)
    scene.camera = cam

if not any(o.type == "LIGHT" for o in bpy.data.objects):
    light_data = bpy.data.lights.new("Preview_Key", "AREA")
    light_data.energy = 300
    light_data.size = 2.0
    light = bpy.data.objects.new("Preview_Key", light_data)
    scene.collection.objects.link(light)
    light.location = (1.5, -2.0, 1.5)
    light.rotation_euler = (math.radians(55), 0.0, math.radians(35))

scene.render.resolution_x = 1920
scene.render.resolution_y = 1080
scene.render.resolution_percentage = 100
scene.render.image_settings.file_format = "PNG"
scene.render.filepath = "/abs/project/render/preview.png"
bpy.ops.render.render(write_still=True)
result = {"image": scene.render.filepath,
          "size": os.path.getsize(scene.render.filepath),
          "engine": scene.render.engine, "camera": scene.camera.name}

此路径的规则:首先保存 .blend,写入 <project>/render/,报告绝对路径和文件大小,提高客户端超时时间,并且永远不要对包含未保存更改的文件启动头渲染。

Blender 5.4 陷阱

症状原因修复
驱动无变化依赖图未求值scene.frame_set(f)
Action.fcurves 缺失槽化动作 (slotted actions)act.layers[0].strips[0].channelbags[*].fcurves,或 scripts/action_compat.py
绑定不移动,无错误分配的动作没有绑定到该 ID 的槽assign_action() / 设置 animation_data.action_slot
fcurves.new(action_group=...) TypeError5.4 关键字是 group_namecb.fcurves.new(path, index, group_name="...")
asset.mark() 轮询失败操作读取 Outliner 选择obj.asset_mark() API
属性关键帧被忽略错误的数据路径'["open"]'
.001 动作后缀名称冲突首先重命名源动作
GLB 中出现小部件对象仍在场景集合中在导出期间取消链接
Unrecognized command--factory-startup / 扩展关闭重新在线启动
自动启动静默端口被占用释放端口,重新启动(不重试)
渲染枚举错误错误的引擎名称从枚举中选择 BLENDER_EEVEE
enum "OCTAHEDRAL" not found骨架显示是数据,不是对象rig.data.display_type = "OCTAHEDRAL"
bpy.context.window 为 None后台构建没有窗口用 window_manager.windows 保护
FBX 重新导入使角色浮空导入器将根标记为连接的骨骼并丢弃其平移使用 scripts/inspect_fbx.py 验证文件,而不是往返

交付物

  • .blend — 权威绑定,在静止帧保存,包含 README_RIG 文本块。
  • .glb — 蒙皮 + 动画,通过重新导入验证。
  • 项目文件夹中的 README.md,包含枢轴、骨骼、属性、角度、数字。

相关技能