blender-animation-rigging

Blender 动画与绑定专家

概述

本技能提供 Blender 5.x 动画与绑定方面的专家指导：插入关键帧、编辑 FCurve、驱动器、骨骼约束、创建骨架、IK/FK 链、形态键、NLA 条带，以及使用 Python 自动化动画工作流。包含 5.1 的变更（Smooth Gaussian FCurve 修改器、应用到基础形态、分层动作性能优化）。参考文件包含完整的约束目录和 Python API 用法模式。

MCP 优先方案

优先使用官方 Blender MCP Server（Blender Lab，Blender 5.1+），在正在运行的 Blender 会话中直接插入关键帧、创建骨架、配置约束和烘焙动作。仅当 MCP 服务未连接时，才退而改用输出 Python 脚本。

**检测：**在会话开始时，查找名称匹配 execute_blender_code、get_objects_summary 或 search_api_docs 的工具——这些工具属于官方 blender-mcp 服务。如果存在其中任意一个，即表示 MCP 可用。

本技能使用的工具：

• execute_blender_code — 在实时会话中运行 bpy Python（主要操作）
• get_objects_summary、get_object_detail_summary — 在修改场景前检查场景状态
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — 清点文件内容
• search_api_docs、get_python_api_docs、search_manual_docs — 在调用前确认正确的 API/操作符名称
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 验证视觉效果
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 操作界面以显示更改
• render_thumbnail_to_path、render_viewport_to_path — 捕获快速视觉反馈

**工作流：**使用 get_* / search_* 工具检查 → 通过 execute_blender_code 修改 → 使用截图或摘要工具验证。代码块应保持精简且幂等，以便轻松定位故障。

设置方法：参见 docs/blender-mcp-setup.md。

任务决策树

• “为对象 X 制作动画” -> 使用关键帧插入模式（参见“关键帧模式”）
• “创建绑定 / 骨架” -> 参见“骨架创建”部分和 references/python_api.md
• “设置 IK” -> 参见“IK 链设置”
• “创建驱动器” -> 参见“驱动器示例”
• “添加约束” -> 查阅 references/constraint_reference.md，了解正确的类型和属性
• “处理形态键” -> 参见“形态键模式”
• “使用 NLA 编辑器” -> 参见“NLA 管理”
• “编辑 FCurve” -> 参见 references/python_api.md 中的“FCurve 操作”
• “骨骼滚转/朝向不正确” -> 参见“模式切换注意事项”

Blender 5.1 变更

Smooth（Gaussian）FCurve 修改器（5.1 新增）

1. 新的 FCurve 修改器类型：'SMOOTH'，混合模式为 'GAUSSIAN'
2. 提供比旧版 Smooth 修改器更平滑的插值效果
3. 通过 Python 应用：fcurve.modifiers.new('Smooth', 'SMOOTH')，然后设置混合类型
4. 适用于减少动作捕捉数据中的抖动

应用到基础形态（5.1 新增）

1. 将当前姿势应用为新的静止姿势（将姿势烘焙到静止姿势）的操作符
2. Python：bpy.ops.pose.apply_to_basis()
3. 适用于绑定后修正骨骼朝向

分层动作性能优化（5.1）

1. 显著提升分层（非破坏性）动画的性能
2. 降低复杂 NLA/图层设置的评估开销
3. 启用分层动画时，视口播放效果更好

ANIM_OT_convert_legacy_action 已移除（5.1）

1. bpy.ops.anim.convert_legacy_action 操作符已移除
2. 旧版单条带 NLA 动作现在由分层动作系统自动处理
3. 更新任何引用此操作符的脚本

关键帧模式

基础关键帧设置

import bpy

obj = bpy.context.active_object

# Set value and insert keyframe
obj.location = (0, 0, 0)
obj.keyframe_insert(data_path="location", frame=1)

obj.location = (5, 0, 0)
obj.keyframe_insert(data_path="location", frame=60)

# Keyframe specific channel (e.g., X location only)
obj.keyframe_insert(data_path="location", index=0, frame=1)

# Keyframe rotation
obj.rotation_euler = (0, 0, 0)
obj.keyframe_insert(data_path="rotation_euler", frame=1)

# Keyframe scale
obj.keyframe_insert(data_path="scale", frame=1)

可设置关键帧的属性

属性	data_path	组件
位置	"location"	0=X，1=Y，2=Z
旋转（欧拉）	"rotation_euler"	0=X，1=Y，2=Z
旋转（四元数）	"rotation_quaternion"	0=W，1=X，2=Y，3=Z
缩放	"scale"	0=X，1=Y，2=Z
自定义属性	'["prop_name"]'	—
材质值	通过材质节点输入	—
形态键值	"value"（在键块上）	—
修改器属性	'modifiers["name"].property'	—

骨架创建

import bpy
from mathutils import Vector

# Create armature data and object
armature = bpy.data.armatures.new("MyArmature")
arm_obj = bpy.data.objects.new("MyArmature", armature)
bpy.context.collection.objects.link(arm_obj)
bpy.context.view_layer.objects.active = arm_obj

# Enter edit mode to create bones
bpy.ops.object.mode_set(mode='EDIT')
edit_bones = armature.edit_bones

# Root bone
root = edit_bones.new("Root")
root.head = (0, 0, 0)
root.tail = (0, 0, 0.5)

# Spine chain
spine = edit_bones.new("Spine")
spine.head = root.tail
spine.tail = (0, 0, 1.0)
spine.parent = root
spine.use_connect = True

chest = edit_bones.new("Chest")
chest.head = spine.tail
chest.tail = (0, 0, 1.5)
chest.parent = spine
chest.use_connect = True

# Arm bones (left)
upper_arm_l = edit_bones.new("UpperArm.L")
upper_arm_l.head = (0.2, 0, 1.4)
upper_arm_l.tail = (0.7, 0, 1.4)
upper_arm_l.parent = chest

lower_arm_l = edit_bones.new("LowerArm.L")
lower_arm_l.head = upper_arm_l.tail
lower_arm_l.tail = (1.2, 0, 1.4)
lower_arm_l.parent = upper_arm_l
lower_arm_l.use_connect = True

# Return to object mode
bpy.ops.object.mode_set(mode='OBJECT')

IK 链设置

import bpy

arm_obj = bpy.data.objects["MyArmature"]
bpy.context.view_layer.objects.active = arm_obj
bpy.ops.object.mode_set(mode='POSE')

# Add IK constraint to the last bone in the chain
pose_bone = arm_obj.pose.bones["LowerArm.L"]
ik = pose_bone.constraints.new('INVERSE_KINEMATICS')
ik.target = bpy.data.objects["IK_Target"]  # Empty or other object
ik.chain_count = 2  # Number of bones in chain (0 = to root)
ik.use_rotation = False  # Optional: also match target rotation
ik.influence = 1.0

# IK with pole target (for knee/elbow direction)
ik.pole_target = bpy.data.objects["Pole_Target"]
ik.pole_angle = 0.0  # Adjust if elbow/knee points wrong direction

bpy.ops.object.mode_set(mode='OBJECT')

驱动器示例

简单表达式驱动器

import bpy

obj = bpy.context.active_object

# Add driver to Z location
fcurve = obj.driver_add("location", 2)  # index 2 = Z
driver = fcurve.driver
driver.type = 'SCRIPTED'
driver.expression = "frame / 24"  # Z = current second

带变量的驱动器

# Drive Y scale from another object's X location
fcurve = obj.driver_add("scale", 1)  # Y scale
driver = fcurve.driver
driver.type = 'SCRIPTED'

var = driver.variables.new()
var.name = "ctrl_x"
var.type = 'TRANSFORMS'
var.targets[0].id = bpy.data.objects["Controller"]
var.targets[0].transform_type = 'LOC_X'
var.targets[0].transform_space = 'WORLD_SPACE'

driver.expression = "ctrl_x * 2"

来自自定义属性的驱动器

fcurve = obj.driver_add("location", 0)  # X location
driver = fcurve.driver
driver.type = 'SCRIPTED'

var = driver.variables.new()
var.name = "my_val"
var.type = 'SINGLE_PROP'
var.targets[0].id = bpy.data.objects["Controller"]
var.targets[0].data_path = '["my_custom_property"]'

driver.expression = "my_val"

驱动器变量类型

类型	描述
'SINGLE_PROP'	RNA 属性的值
'TRANSFORMS'	对象/骨骼的变换通道
'ROTATION_DIFF'	两根骨骼之间的旋转差
'LOC_DIFF'	两个对象/骨骼之间的距离
'CONTEXT_PROP'	活动场景/视图层属性

TRANSFORMS 变量的变换类型

LOC_X、LOC_Y、LOC_Z、ROT_X、ROT_Y、ROT_Z、ROT_W、SCALE_X、SCALE_Y、SCALE_Z、SCALE_AVG

形态键模式

创建形态键

import bpy

obj = bpy.context.active_object
mesh = obj.data

# Create basis (reference shape)
if mesh.shape_keys is None:
    obj.shape_key_add(name="Basis", from_mix=False)

# Add shape keys
key_smile = obj.shape_key_add(name="Smile", from_mix=False)
# Modify vertices for the smile shape
for i, v in enumerate(key_smile.data):
    if mesh.vertices[i].co.z > 0.5:  # Upper face
        v.co.y += 0.1

key_frown = obj.shape_key_add(name="Frown", from_mix=False)
for i, v in enumerate(key_frown.data):
    if mesh.vertices[i].co.z > 0.5:
        v.co.y -= 0.1

为形态键添加动画

# Access shape keys
shape_keys = obj.data.shape_keys
key_blocks = shape_keys.key_blocks

# Set value and keyframe
key_blocks["Smile"].value = 0.0
key_blocks["Smile"].keyframe_insert(data_path="value", frame=1)

key_blocks["Smile"].value = 1.0
key_blocks["Smile"].keyframe_insert(data_path="value", frame=30)

形态键属性

key = key_blocks["Smile"]
key.value = 0.5           # Current blend value (0-1)
key.slider_min = 0.0      # Minimum slider value
key.slider_max = 1.0      # Maximum slider value
key.mute = False           # Mute this shape key
key.relative_key = key_blocks["Basis"]  # Reference shape
key.vertex_group = ""      # Limit influence to vertex group

NLA 管理

创建和管理 NLA 条带

import bpy

obj = bpy.context.active_object

# Ensure animation data exists
if obj.animation_data is None:
    obj.animation_data_create()

# Push current action to NLA track
action = obj.animation_data.action
if action:
    track = obj.animation_data.nla_tracks.new()
    track.name = "Walk Cycle"
    strip = track.strips.new(name="Walk", start=1, action=action)
    obj.animation_data.action = None  # Clear active action

NLA 条带属性

strip.frame_start = 1
strip.frame_end = 60
strip.repeat = 3.0              # Loop count
strip.scale = 1.0               # Time scale (0.5 = half speed)
strip.blend_type = 'REPLACE'    # REPLACE, COMBINE, ADD, SUBTRACT, MULTIPLY
strip.influence = 1.0           # Blend influence (0-1)
strip.mute = False
strip.use_auto_blend = True     # Auto-blend between adjacent strips
strip.blend_in = 5.0            # Blend-in frames
strip.blend_out = 5.0           # Blend-out frames
strip.use_reverse = False       # Play in reverse
strip.extrapolation = 'HOLD'    # NOTHING, HOLD, HOLD_FORWARD

模式切换注意事项

1. 编辑骨骼与姿势骨骼：armature.edit_bones 只能在 EDIT 模式下访问。object.pose.bones 可在 POSE 和 OBJECT 模式下访问。
2. 骨骼数据丢失：切换模式会更新骨骼数据。切勿在模式切换期间缓存编辑骨骼引用。
3. 约束目标：必须在 POSE 模式下设置。约束属性可在 OBJECT 模式下读取。
4. 编辑模式下的形态键：在 EDIT 模式下修改网格会修改活动形态键，而不是基础形态键（除非基础形态键处于活动状态）。
5. 关键帧插入上下文：keyframe_insert() 可在任何模式下使用，但 bpy.ops.anim.keyframe_insert() 需要正确的上下文。
6. 骨骼滚转：在 EDIT 模式下设置 edit_bone.roll。滚转不正确会导致 IK 平面翻转。
7. 静止姿势与姿势：armature.bones[].head_local 是静止姿势。pose.bones[].head 是姿势位置（只读，根据矩阵计算）。

动画问题调试

• 动画不播放：检查帧范围（起始/结束），检查是否已分配动作，检查 NLA 条带是否被静音
• 关键帧位于错误通道：检查 FCurve 上的 data_path 和 array_index
• IK 翻转：调整极向目标位置，或在编辑模式下调整骨骼滚转
• 驱动器未更新：检查是否存在循环依赖，确保表达式语法有效，并检查变量目标
• 形态键未混合：检查 Basis 形态键是否存在，以及 relative_key 是否设置正确
• 约束不起作用：检查影响值（0 = 已禁用），检查目标对象是否存在，并检查骨骼名称拼写

约束参考

如需查看所有约 45 种约束的完整目录，包括类型字符串、属性和用例，请参阅 references/constraint_reference.md。

主要类别：

• 运动跟踪：搜索 "Track" 或 "Motion"
• 变换控制：搜索 "Copy"、"Limit" 或 "Transform"
• IK/绑定：搜索 "Inverse"、"Spline" 或 "Stretch"
• 关系：搜索 "Child Of"、"Pivot" 或 "Follow"

Python API 参考

如需了解完整的 Python API 模式，包括关键帧插入、FCurve 操作、驱动器创建、骨架/骨骼设置、NLA 条带和形态键管理，请参阅 references/python_api.md。