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)。
硬性规则
- 仅限实时 GUI。 确认
bpy.app.background == False。绝不在用户工作时关闭 Blender;如果必须因端口冲突重启,请先保存.blend文件并重新打开同一文件。 - 除非所有者要求,否则不进行渲染。 默认验证是数值化的:顶点坐标、宽度、面积、比率。当所有者明确要求渲染时,在实时会话中执行(参见 按需渲染)。
- 聚焦你正在编辑的视口,在更改前后都要执行:选择对象/骨骼,激活一个,运行
view3d.view_axis+view3d.view_selected。选择与资源平面匹配的轴(对于平面 XZ 资源使用FRONT)。 - 始终使用评估后的网格,而不是原始网格:
obj.evaluated_get(depsgraph).to_mesh()。 - 使用
scene.frame_set(f)强制驱动求值 —view_layer.update()是不够的。 - 在每个里程碑处使用
bpy.ops.wm.save_as_mainfile(filepath=..., compress=True)进行增量保存;将交付物保留在项目文件夹内。 - 一次
execute= 一个原子、幂等步骤,返回证明其效果的指标。 - 测量网格上接触地面的部分,而不是骨骼。 骨尾可能位于鞋底上方 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 没有驱动、自定义属性或约束。将它们烘焙:
- 重命名源动作 (
*_src),以便烘焙后的动作获得一个干净的名称。 - 取消链接自定义形状小部件对象,否则它会变成一个空节点。
- 清除动作,
pose_bone.driver_remove(...),在姿势极值处设置rotation_euler[0]的关键帧。 - 使用
export_skins=True、export_animations=True、export_animation_mode="ACTIONS"、export_yup=True导出。 - 恢复:重新分配动作,删除烘焙内容,重新链接小部件,重新添加驱动,
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=...) TypeError | 5.4 关键字是 group_name | cb.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,包含枢轴、骨骼、属性、角度、数字。