scenario-blender-rigging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blender rigging

Blender 骨骼绑定（rigging）

Expert rigging means the rig is specified by bone placement, proven by deformation under stress poses, and shaped around what the animator will actually use. The stance of every source expert: place joints precisely, generate or build the simplest mechanism that works, then pose it, measure it, render it and fix it before calling it done. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-blender-expert (execution channel, review loop, 5.2 API changes).

Module:

scripts/bx_rig.py

(tested on 5.2.1, headless and GUI).

import sys; sys.path.append("<skills>/scenario-blender-rigging/scripts"); import bx_rig as R

专业的 rigging 意味着：rig 由骨骼布置来定义，在应力姿势下通过变形得到验证，并围绕动画师真正会使用的操作来设计。每一位来源专家的共同立场都是：精确放置关节，生成或构建最简单且可行的机制，然后摆姿势、测量、渲染并修复，完成前不要草率收尾。如果这里提到的某个同级 skill 在可用 skills 中缺失，请让用户安装（

npx skills add scenario-labs/skills --skill <name>

）；无人值守时，则根据 tool schemas 继续执行并标记该缺口。

必需背景： scenario-blender-expert（执行通道、审查循环、5.2 API 变更）。

Module：

scripts/bx_rig.py

（已在 5.2.1 上测试，支持 headless 和 GUI）。

import sys; sys.path.append("<skills>/scenario-blender-rigging/scripts"); import bx_rig as R

。

Stance (the expert delta)

核心原则（专家增量）

Placement is the specification. Joints sit in the center of the volume they move, not on the anatomical skeleton ("bones simulate bone, muscle and tissue"); knees and elbows get a slight pre-bend because the chain's curvature IS the IK plane; rolls put each hinge on one local axis so the animator uses one curve (CGDive; Demeter: the bend, not the roll, decided where his pole landed).
The metarig is the source, the generated rig is disposable. Every fix goes into metarig bones, Rigify parameters or a post-generation script; regenerating keeps control names, so weights and animation survive (CGDive, Demeter, Ivan Cappiello).
Automatic weights fail silently.
```
parent_set
```
returns FINISHED while a warning says bone heat failed; measure unweighted vertices and empty deform groups, and fall back to a voxel proxy plus Data Transfer (CGDive; verified). They also leak across the crotch and armpits: strip .L weights from the right half.
Weights are judged in motion, firm beats mushy. Paint in pose or against a test animation; limit each seam to 2 or 3 bones ("bones fighting for influence"); slight intersection is better than rubbery transitions; rigid parts are assigned at 1.0, never painted (CGDive, Demeter, Dikko).
Everything that deforms together gets weights from the same source, transferred and applied, so garments cannot drift while animating (Dikko, CGDive).
Export decides the deformation tools. Four twist bones per segment instead of Preserve Volume; Preserve Volume, Corrective Smooth and B-bones are Blender-only, which is why Rigify segments its DEF bones (CGDive, Ivan).
The animator is the client. Cut features nobody uses, restrict only what breaks the rig, keep automated bones hand-animatable (constraint plus child, Mix Add, Transformation instead of drivers), stop when fit for purpose (Wayne Dixon, Demeter, CGDive).
Faces are per-character hybrids. There is no generic stylized face (Demeter); production faces mix joints, ribbons, shape keys and lattices (Rik Schutte).

布置就是规格。 关节位于其驱动体积的中心，而不是解剖学骨架上（“骨骼模拟骨骼、肌肉和组织”）；膝盖和肘部要略微预弯，因为骨骼链的曲率就是 IK 平面；roll 要让每个铰链位于同一条局部轴上，让动画师只需使用一条曲线（CGDive；Demeter：决定其 pole 落点的是弯折，而不是 roll）。
metarig 是源头，生成的 rig 可以丢弃。 所有修复都应写入 metarig 骨骼、Rigify 参数或生成后脚本；重新生成后控制名称保持不变，因此权重和动画得以保留（CGDive、Demeter、Ivan Cappiello）。
自动权重会静默失败。
```
parent_set
```
返回 FINISHED，但警告信息却说 bone heat failed；应测量未加权顶点和空的 deform groups，并回退到 voxel proxy + Data Transfer 方案（CGDive；已验证）。自动权重还可能横跨胯部和腋部发生渗漏：从右半边剥离
```
.L
```
权重。
权重要在运动中判断，硬朗胜过软塌。 在姿势中或针对测试动画进行绘制；每条接缝最多限制到 2 或 3 根骨骼（“骨骼争夺影响权重”）；轻微交叠优于橡皮般的过渡；刚性部件直接赋权为 1.0，绝不绘制（CGDive、Demeter、Dikko）。
所有一起变形的对象都应从同一来源获取权重， 转移并应用这些权重，使服装在动画中不会漂移（Dikko、CGDive）。
导出目标决定可用的变形手段。 每个分段使用 4 根 twist bones，而不是 Preserve Volume；Preserve Volume、Corrective Smooth 和 B-bones 仅适用于 Blender，因此 Rigify 会对 DEF 骨骼进行分段（CGDive、Ivan）。
动画师才是客户。 删掉没人使用的功能，只限制会破坏 rig 的部分，确保自动生成的骨骼仍可手动动画化（使用 constraint 加 child、Mix Add、Transformation，而不是 drivers），达到用途要求后即可停止（Wayne Dixon、Demeter、CGDive）。
面部 rig 是逐角色定制的混合方案。 不存在通用的风格化面部 rig（Demeter）；生产级面部会混合 joints、ribbons、shape keys 和 lattices（Rik Schutte）。

Establish first

首先确定

Input	Changes	Default when silent
Target: Blender render vs game/FBX	segmented DEF bones, max 4 influences, no Preserve Volume / Corrective Smooth / B-bone deformation	Blender-only keyframe animation
Character: biped, quadruped, mechanical, prop	metarig preset or custom samples; rigid islands	biped, Rigify
Face need and style	none / Rigify face / bones + shape keys + on-face controls	body rig + eye and jaw bones only
Fingers	Rigify Human (fingers + face) vs Basic Human	Basic Human (CGDive: first rig)
Pose, pieces, scale	T or A pose, separate eyes/teeth/clothes, real scale	measure; fix in the model check
Animator conventions	FK/IK defaults, side colors, finger controls	legs IK, arms FK, follow 0; left blue, right red (ask)

输入	变更	未说明时的默认值
目标：Blender 渲染还是游戏/FBX	对 DEF 骨骼分段，最多 4 个 influences，不使用 Preserve Volume / Corrective Smooth / B-bone deformation	仅用于 Blender 的 keyframe animation
角色：双足、四足、机械结构、道具	metarig preset 或 custom samples；rigid islands	双足角色、Rigify
面部需求与风格	无 / Rigify face / bones + shape keys + on-face controls	body rig + 仅包含 eye 和 jaw bones
手指	Rigify Human（fingers + face）与 Basic Human	Basic Human（CGDive：首个 rig）
姿势、部件、尺寸	T 或 A pose，eyes/teeth/clothes 分离，真实尺寸	进行测量；在模型检查中修复
动画师惯例	FK/IK 默认值、侧面颜色、手指 controls	腿部 IK、手臂 FK、follow 0；左侧蓝色、右侧红色（需询问）

Choose the path

选择路径

Rigify	Manual / scripted rig
Humans and animals with standard anatomy, many characters sharing controls, fast production-grade result	Unusual anatomy, mechanical parts, strict game-engine hierarchies, rigs that must stay small, or when the brief asks for a custom control scheme
`add_metarig` then `fit_metarig` , `generate`	`new_bone` , `twist_chain` , `fk_ik_switch` , `ik_chain` , `foot_roll` , `make_def_layer` , `organize`
Metarig types: arm exactly 3 bones, leg 4 + heel, spine 3+, super_copy 1 bone	DEF / MCH / CTRL: only DEF deforms, MCH is never animated, everything else is a control

Rigify	手工/脚本 rig
适用于具有标准解剖结构的人类和动物、多个角色共享 controls、需要快速获得生产级结果的项目	适用于异常解剖结构、机械部件、严格的游戏引擎层级、必须保持精简的 rig，或需求明确要求自定义 control scheme 的项目
`add_metarig` ，然后 `fit_metarig` 、 `generate`	`new_bone` 、 `twist_chain` 、 `fk_ik_switch` 、 `ik_chain` 、 `foot_roll` 、 `make_def_layer` 、 `organize`
metarig 类型：arm 恰好 3 根 bones，leg 4 根加 heel，spine 3 根以上，super_copy 1 根 bone	DEF / MCH / CTRL：只有 DEF 产生变形，MCH 从不参与动画，其他所有骨骼均作为 controls

Workflow

工作流

Model check.
```
R.model_check([body, *parts], fix=True)
```
: transforms applied (shape keys included), feet on Z=0, centered on X, facing -Y, about 1.8 m for an adult human. Apply Mirror modifiers or keep their mirror object. GATE:
```
model_check(...)["problems"] == []
```
.
Landmarks.
```
lm = R.landmarks(body, eyes=eyes)
```
: cross-sections find crotch, hips, ankle, neck, armpit, wrist; eye centers from the eye mesh; nose tip and chin from the face profile. Override any joint with
```
overrides={...}
```
. GATE: joint order sane,
```
lm["notes"]
```
empty or explained.
Fit. Rigify:
```
meta = R.add_metarig("basic"|"human")
```
,
```
R.fit_metarig(meta, lm)
```
(joints as shared points, pre-bends, hinge rolls, left side symmetrized; hands and face by similarity, coarse). Manual: build the deform skeleton with
```
new_bone
```
from the same landmarks. GATE:
```
R.check_metarig(meta, body) == []
```
AND
```
R.placement_sheet([body, eyes], out, arm_obj=meta, views=("front","right","top"))
```
looked at; zoom the head with
```
center=
```
,
```
size=
```
.
Face (Rigify Human). Fit, then
```
R.upgrade_face(meta)
```
(irreversible; eyelid follow Z 0.3, bottom lip 0.9, Overwrite Widget Meshes on). Stylized hero face: bones for jaw, eyes, tongue plus shape keys instead (stage 7).
Generate or build.
```
rig, err = R.generate(meta)
```
;
```
err
```
is the first Rigify error line naming the bone ("Cannot connect chain - bone position is disjoint", "Expected 2 eye corners"): fix the metarig, regenerate. Manual: twist chains, FK/IK layers with settings properties, IK with solved pole angle, foot roll, symmetrize,
```
mirror_drivers
```
,
```
make_def_layer
```
,
```
organize
```
, widgets. GATE (manual):
```
static_cycles == []
```
,
```
cycle_check() == []
```
,
```
root_test < 1e-4
```
, FK and IK coincide at rest, pole error < 1e-3.
Bind.
```
rep = R.bind(rig, body, garments=[shirt, pants], rigid={eyes: None, teeth: "DEF-teeth.T"})
```
: auto weights, verification, proxy fallback, cross-side strip, garment transfer (applied), rigid islands, clean and normalize, Armature after Mirror and before Subdivision. GATE:
```
rep["ok"]
```
,
```
unweighted == 0
```
, no non-deform groups; for export
```
max_influences=4
```
.
Range of motion.
```
dr = R.deformation_report(rig, [body, *garments], R.RIGIFY_POSES)
```
,
```
R.flag_report(dr)
```
, then
```
R.pose_sheet(...)
```
and
```
R.joint_sheet(...)
```
close-ups and LOOK at them. GATE: no leaks, no unexplained collapse, renders acceptable at armpit, elbow, wrist twist, groin, knee, collar.
Fix, in this order. Placement or roll problems: back to the metarig and regenerate. Weights: targeted data edits (
```
strip_opposite_side
```
,
```
assign_rigid
```
,
```
smooth_weights
```
with a vertex mask,
```
clean_weights
```
). Volume at deep bends: corrective shape keys (
```
volume_restore_targets
```
,
```
corrective_from_targets
```
,
```
corrective_driver
```
). Blender-only candy wrapper:
```
preserve_volume_mask
```
. Re-run stage 7 after every fix; re-check earlier poses (CGDive).
Usability and delivery. Controls visible with In Front off, widgets, side colors, MCH/DEF hidden, at least one Rigify UI row,
```
rig_ui.py
```
needs Auto Run in a GUI, switches exactly 0 or 1, rest pose clean, test action removed. Report numbers, renders and what was not verified.

模型检查。
```
R.model_check([body, *parts], fix=True)
```
：已应用变换（包括 shape keys），双脚位于 Z=0，在 X 方向居中，朝向 -Y，成人身高约 1.8 m。应用 Mirror modifiers，或保留对应的 mirror object。GATE：
```
model_check(...)["problems"] == []
```
。
地标。
```
lm = R.landmarks(body, eyes=eyes)
```
：通过横截面定位 crotch、hips、ankle、neck、armpit、wrist；eye 中心取自 eye mesh；nose tip 和 chin 取自 face profile。使用
```
overrides={...}
```
覆盖任何 joint。GATE：joint 顺序合理，
```
lm["notes"]
```
为空或已有合理解释。
适配。 Rigify：
```
meta = R.add_metarig("basic"|"human")
```
，
```
R.fit_metarig(meta, lm)
```
（joints 作为共享点、预弯、hinge rolls、左侧对称；hands 和 face 通过相似性进行粗略适配）。手工方案：使用相同 landmarks，通过
```
new_bone
```
构建 deform skeleton。GATE：
```
R.check_metarig(meta, body) == []
```
，并且实际查看了
```
R.placement_sheet([body, eyes], out, arm_obj=meta, views=("front","right","top"))
```
；通过
```
center=
```
、
```
size=
```
放大头部。
面部（Rigify Human）。 适配后调用
```
R.upgrade_face(meta)
```
（不可逆；eyelid follow Z 0.3，bottom lip 0.9，开启 Overwrite Widget Meshes）。风格化主角面部：改用 jaw、eyes、tongue bones 加 shape keys，而不是标准面部方案（阶段 7）。
生成或构建。
```
rig, err = R.generate(meta)
```
；
```
err
```
是第一行指明 bone 名称的 Rigify 错误（"Cannot connect chain - bone position is disjoint"、"Expected 2 eye corners"）：修复 metarig 后重新生成。手工方案：构建 twist chains、带 settings properties 的 FK/IK layers、采用已解算 pole 角度的 IK、foot roll、symmetrize、
```
mirror_drivers
```
、
```
make_def_layer
```
、
```
organize
```
和 widgets。GATE（手工）：
```
static_cycles == []
```
、
```
cycle_check() == []
```
、
```
root_test < 1e-4
```
，静止时 FK 与 IK 重合，pole error < 1e-3。
绑定。
```
rep = R.bind(rig, body, garments=[shirt, pants], rigid={eyes: None, teeth: "DEF-teeth.T"})
```
：自动权重、验证、proxy fallback、cross-side strip、garment transfer（已应用）、rigid islands、clean 和 normalize；Armature modifier 位于 Mirror 之后、Subdivision 之前。GATE：
```
rep["ok"]
```
、
```
unweighted == 0
```
、不存在 non-deform groups；导出时设置
```
max_influences=4
```
。
活动范围。
```
dr = R.deformation_report(rig, [body, *garments], R.RIGIFY_POSES)
```
、
```
R.flag_report(dr)
```
，然后生成
```
R.pose_sheet(...)
```
和
```
R.joint_sheet(...)
```
近景，并务必实际查看这些结果。GATE：没有渗漏或无法解释的塌陷；armpit、elbow、wrist twist、groin、knee、collar 的渲染均可接受。
按此顺序修复。 布置或 roll 问题：返回 metarig 并重新生成。权重：使用有针对性的数据编辑（
```
strip_opposite_side
```
、
```
assign_rigid
```
、带 vertex mask 的
```
smooth_weights
```
、
```
clean_weights
```
）。深弯时体积问题：corrective shape keys（
```
volume_restore_targets
```
、
```
corrective_from_targets
```
、
```
corrective_driver
```
）。Blender 专属的 candy-wrapper 问题：
```
preserve_volume_mask
```
。每次修复后重跑阶段 7；同时复查更早的姿势（CGDive）。
可用性与交付。 关闭 In Front 时 controls 仍应可见，显示 widgets 和 side colors，隐藏 MCH/DEF，至少保留一行 Rigify UI；
```
rig_ui.py
```
在 GUI 中需要启用 Auto Run；switches 的值必须严格为 0 或 1；rest pose 保持干净，并移除 test action。报告数值、渲染结果以及未经验证的项目。

Numbers

数值

Value	Relative to	Source
Knee/elbow pre-bend 1 to 3 deg (fit: 1.2% of limb length, 2.7 deg); check 1 to 15	chain in the bend view	CGDive; check [added]
4 twist bones, Copy Rotation 1.0 / 0.66 / 0.33 / 0.1 (thigh 0.05)	from the driving end	CGDive
IK chain length 2; IK Stretch 0.1; lock IK Y/Z on shin and forearm	IK bone	Wayne, CGDive
Foot roll: heel X [-90, 0], toe X [0, 90], inside/outside Z one-sided	pivot local, roll 0, pointing up	CGDive (verified)
Weight brush Add, strength 0.1 to 0.2, Auto Normalize; seams Mix 0.5 at strength 1	Weight Paint	CGDive
Clean near-zero weights before blurring (Demeter); limit 0.001 (CGDive), 0.01 in `bind` [added]; 4 influences for games	per vertex	Demeter, CGDive
Eyelid follow 0.15 (bone face); Rigify eyelid follow Z 0.3 (default 0.7); jaw bottom lip 0.9; mouth corners follow jaw 0.5	face	CGDive
Palm 0.5 / 0.25; elbow plate 0.2 of forearm rotation	Copy Rotation Local, Mix Add	CGDive
Finger curl: Transformation Scale Z 0..1 to Rot Z 90..0 deg, Extrapolate	finger control	CGDive
Action constraint: keys frames 1 and 10, LINEAR, max = measured control travel	control local Y	CGDive, Demeter
Shoulder test range about 20 to 30 deg of clavicle raise	anatomy	CGDive
Face: about 16 Stop Staring shapes; 52 ARKit for mocap	shape keys	CGDive
Proxy voxel H/180, then H/90, H/45	character height	[added, verified]
Collapse < 0.85, bulge > 1.25 (joint band), leak > 0.001 H, strain 0.5 to 1.6	rest	[added]

数值	参照对象	来源
Knee/elbow 预弯 1 到 3 度（适配：肢体长度的 1.2%，即 2.7 度）；检查值 1 到 15	弯折视图中的 chain	CGDive；检查值 [added]
每个分段 4 根 twist bones，Copy Rotation 1.0 / 0.66 / 0.33 / 0.1（thigh 为 0.05）	从驱动端算起	CGDive
IK chain 长度 2；IK Stretch 0.1；锁定 shin 和 forearm 上的 IK Y/Z	IK bone	Wayne、CGDive
Foot roll：heel X [-90, 0]，toe X [0, 90]，inside/outside Z 为单侧	pivot local，roll 0，朝上	CGDive（已验证）
Weight brush 使用 Add，strength 为 0.1 到 0.2，开启 Auto Normalize；接缝 Mix 0.5，strength 为 1	Weight Paint	CGDive
在模糊处理前清理接近零的权重（Demeter）；将权重限制在 0.001（CGDive）， `bind` 中为 0.01 [added]；游戏用途限制为 4 个 influences	每个 vertex	Demeter、CGDive
Eyelid follow 0.15（bone face）；Rigify eyelid follow Z 0.3（默认 0.7）；jaw bottom lip 0.9；mouth corners follow jaw 0.5	face	CGDive
Palm 0.5 / 0.25；elbow plate 为 forearm rotation 的 0.2	Copy Rotation Local、Mix Add	CGDive
Finger curl：Transformation Scale Z 0..1 映射到 Rot Z 90..0 度，并使用 Extrapolate	finger control	CGDive
Action constraint：关键帧位于第 1 和第 10 帧，使用 LINEAR，max = measured control travel	control local Y	CGDive、Demeter
Shoulder 测试范围：clavicle raise 约 20 到 30 度	anatomy	CGDive
Face：约 16 个 Stop Staring shapes；mocap 使用 52 个 ARKit	shape keys	CGDive
Proxy voxel：H/180，然后 H/90、H/45	character height	[added, verified]
Collapse < 0.85，bulge > 1.25（joint band），leak > 0.001 H，strain 0.5 到 1.6	rest	[added]

Quality gates

质量门槛

Code (all in

bx_rig

check_metarig

weight_report

(unweighted, empty_major, non_deform_groups, over4, sum_dev, mirror_err),

deformation_report

flag_report

(strain, joint volume bands, cross-side leak, new self-intersections via bx_audit),

static_cycles

cycle_check

root_test

twist_angles

solve_pole_angle

rigid_check

Visual: placement sheet (front, right, top; head zoom) before generating; pose sheet of

RIGIFY_POSES

(front, right, three-quarter); joint close-ups (arm joints front/top/three-quarter, others front/right/three-quarter) at every flagged pose. Look for armpit collapse, pointy or pinched elbows and knees, candy-wrapper wrists, groin and butt volume, collar clipping, garments sliding or intersecting, teeth and eyes lagging, widgets hidden inside the mesh. Numbers passed while a render showed broken arms or crease spikes during testing: always open the render. Rubric:

references/critique.md

代码（均在

bx_rig

中）：

check_metarig

、

weight_report

（unweighted、empty_major、non_deform_groups、over4、sum_dev、mirror_err）、

deformation_report

flag_report

（strain、joint volume bands、cross-side leak、通过 bx_audit 检出的 new self-intersections）、

static_cycles

、

cycle_check

、

root_test

、

twist_angles

、

solve_pole_angle

、

rigid_check

。

视觉检查：生成前制作 placement sheet（front、right、top；head zoom）；制作

RIGIFY_POSES

的 pose sheet（front、right、three-quarter）；对每个被标记的姿势制作 joint close-ups（arm joints 使用 front/top/three-quarter，其他关节使用 front/right/three-quarter）。检查 armpit collapse、尖锐或被夹扁的 elbows 和 knees、candy-wrapper wrists、groin 和 butt volume、collar clipping、服装滑动或相交、牙齿和眼睛滞后、widgets 隐藏在 mesh 内部等问题。即便数值通过测试，但渲染显示手臂断裂或测试中出现折痕尖峰，也始终要打开渲染结果查看。评分标准：

references/critique.md

。

Common mistakes

常见错误

Mistake	What it looks like	Fix
Metarig scale or pose not applied	generated rig differs in size or pose	apply scale, Apply Pose as Rest Pose
Neck moved without the spine tip	"bone position is disjoint"	move joints as units ( `move_points` )
Straight knee or elbow	IK bends sideways or backward	pre-bend in the bend view
Parented to the metarig	mesh follows nothing useful	bind to the generated rig
Heat failure unnoticed	mesh does not move	`weight_report` ; proxy route
Armature below Subdivision, or before Mirror	slow; mirrored half copies the posed half	`armature_first`
Left thigh weights on the right leg	opposite side moves	`strip_opposite_side`
Eyes and teeth auto-weighted	drift, poke through	`assign_rigid`
Live Data Transfer on clothes	weights change while animating	apply it
Driver on an animatable bone	channel cannot be keyed	Transformation or Copy Rotation Mix Add
Inherit Rotation off for isolation	root rotation breaks the limb	follow bones (World Copy Loc/Rot/Scale)
IK target parented inside its chain	jitter, flips	clear parent; `static_cycles`
Re-parenting a connected bone	head jumps to the new parent's tail	`reparent` clears use_connect first
Symmetrize expected to copy drivers; `.L.001` names	right side dead	`mirror_drivers` ; `side_of`
IK/FK left at 0.86	mixed, unreadable deformation	exactly 0 or 1

错误	表现	修复
未应用 metarig 的 scale 或 pose	生成的 rig 尺寸或姿势不同	应用 scale，使用 Apply Pose as Rest Pose
移动 neck 时未同时移动 spine tip	出现"bone position is disjoint"	将 joints 作为一个整体移动（ `move_points` ）
knee 或 elbow 完全伸直	IK 向侧面或向后弯折	在 bend view 中加入 pre-bend
将 mesh 父子关联到 metarig	mesh 没有产生有用的跟随效果	绑定到生成的 rig
未发现 Heat failure	mesh 完全不动	使用 `weight_report` ；改走 proxy 方案
Armature 位于 Subdivision 下方，或放在 Mirror 之前	运行缓慢；镜像半边会复制已摆姿势的半边	使用 `armature_first`
左 thigh 的权重应用到右腿	对侧发生运动	使用 `strip_opposite_side`
eyes 和 teeth 使用了自动权重	漂移或穿出 mesh	使用 `assign_rigid`
衣服使用实时 Data Transfer	动画过程中权重发生变化	应用该修改
在可动画骨骼上使用 Driver	无法为 channel 设置关键帧	使用 Transformation 或 Copy Rotation Mix Add
为隔离而关闭 Inherit Rotation	root rotation 导致 limb 断裂	使用 follow bones（World Copy Loc/Rot/Scale）
IK target 被父子关联到自身 chain 内部	抖动或翻转	清除父子关联；使用 `static_cycles`
重新设置 connected bone 的父子关系	head 跳到新 parent 的 tail	`reparent` 会先清除 use_connect
期望 Symmetrize 复制 drivers；名称变为 `.L.001`	右侧失效	使用 `mirror_drivers` ；使用 `side_of`
IK/FK 停留在 0.86	变形混合且难以阅读	严格设为 0 或 1

Blender 5.2 notes

Blender 5.2 注意事项

Rigify ships disabled on factory startup (
```
enable_rigify
```
); the Human metarig still has the legacy face (upgrade it); Overwrite Widget Meshes still defaults off.
Bone collections and per-bone colors replace layers and bone groups;
```
edit_bones.new()
```
joins no collection; pose selection is
```
pose.bones[n].select
```
.
```
parent_set
```
appends the Armature modifier last; weight operators (
```
vertex_group_smooth
```
,
```
_clean
```
) need Weight Paint mode headless;
```
bx_rig
```
does clean, normalize and limit on data instead.
```
shape_key_add
```
leaves new keys at value 1.0 in 5.2.1: set 0 before driving [verified].
```
VertexGroup.remove
```
with out-of-range indices crashes 5.2.1 [verified].
Setting a parent's
```
tail
```
moves a connected child's
```
head
```
;
```
EditBone.transform
```
on a connected group double-moves shared ends [verified]: use
```
transform_bones
```
.
Python drivers start with keys (0,0),(1,1); remap them (
```
remap_driver
```
). Action constraints pick the action slot automatically. Only Insert Available is on by default;
```
keyframe_insert
```
from Python is unaffected.
Custom shapes: Affect Gizmo (
```
use_transform_at_custom_shape
```
), Use As Pivot (
```
use_transform_around_custom_shape
```
). 5.2 adds Duplicate and Rename and Add Bone align Axes.

Rigify 在出厂设置启动时处于禁用状态（
```
enable_rigify
```
）；Human metarig 仍带有 legacy face（需升级）；Overwrite Widget Meshes 仍默认关闭。
Bone collections 和 per-bone colors 取代了 layers 和 bone groups；
```
edit_bones.new()
```
不会加入任何 collection；姿势选择方式为
```
pose.bones[n].select
```
。
```
parent_set
```
会将 Armature modifier 追加到最后；权重操作符（
```
vertex_group_smooth
```
、
```
_clean
```
）在 headless 模式下需要处于 Weight Paint 模式；
```
bx_rig
```
直接在数据上执行 clean、normalize 和 limit。
```
shape_key_add
```
在 5.2.1 中会让新 shape key 的值保持为 1.0：驱动前先设为 0 [已验证]。对越界索引执行
```
VertexGroup.remove
```
会使 5.2.1 崩溃 [已验证]。
设置 parent 的
```
tail
```
会移动 connected child 的
```
head
```
；对 connected group 执行
```
EditBone.transform
```
会使共享端点移动两次 [已验证]：应使用
```
transform_bones
```
。
Python drivers 初始键为 (0,0)、(1,1)；对其进行重映射（
```
remap_driver
```
）。Action constraints 会自动选择 action slot。默认仅启用 Insert Available；从 Python 调用
```
keyframe_insert
```
不受影响。
Custom shapes：Affect Gizmo（
```
use_transform_at_custom_shape
```
）、Use As Pivot（
```
use_transform_around_custom_shape
```
）。5.2 新增 Duplicate、Rename 和 Add Bone align Axes。

References

参考资料

```
references/procedures.md
```
: full tested code for each stage and the test script behind it; load before writing rig code.
```
references/expert-notes.md
```
: judgment by expert (placement, Rigify internals, weighting, mechanisms, faces) with timestamps; load when a decision is not covered above.
```
references/critique.md
```
: the review rubric; load at every gate.
```
references/sources.md
```
: videos, experts, best timestamps.

```
references/procedures.md
```
：每个阶段的完整测试代码及其背后的测试脚本；编写 rig 代码前应先加载。
```
references/expert-notes.md
```
：专家对各项决策的判断（布置、Rigify 内部机制、权重、机制、面部），并附有时间戳；当上述内容未涵盖某项决策时加载。
```
references/critique.md
```
：审查评分标准；每个 GATE 都应加载。
```
references/sources.md
```
：视频、专家和最佳时间戳。