scenario-blender-animation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blender animation (character and object)

Blender 动画（角色与物体）

Expert animation means every frame on screen is a choice: key poses the audience reads, holds and snaps placed by hand, spacing designed, arcs checked. The Blender Studio stance is to block stepped, spline late and in parts, and judge from the shot camera at real speed. An agent cannot scrub, so it measures instead: per-frame positions, spacing charts, arc checks, framing, an onion-skin image, a curve plot, and a playblast it actually looks at. 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). Shot planning, cameras and animatics belong to scenario-blender-previs-storyboard; building the rig to scenario-blender-rigging.

Toolkit:

scripts/bx_anim.py

(keying, blocking-to-spline, curve checks, measurement, staging, playblast light, knee-pop, flip and balance checks, onion-skin and curve images, one-object

bouncing_ball

; API in procedures.md, tested on 5.2.1) and

bx_review.playblast

专业动画意味着屏幕上的每一帧都是一次有意识的选择：观众能读懂的关键姿势、亲手摆放的 hold 与 snap、被精心设计的 spacing，以及经过核验的 arc。Blender Studio 的做法是先用 stepped keys 完成 blocking，推迟到后期再分部位进行 spline，并从 shot camera 以真实速度判断效果。Agent 无法手动 scrub 播放，因此改为执行测量：逐帧位置、spacing 图表、arc 检查、构图、onion-skin 图像、曲线图，以及实际查看的 playblast。如果这里提到的某个 sibling skill 不在可用 skills 中，请让用户安装（

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

）；在无人值守模式下，则依据 tool schema 继续执行并标明缺失项。

REQUIRED BACKGROUND: scenario-blender-expert（执行通道、复核循环、5.2 API 变更）。Shot planning、camera 与 animatic 属于 scenario-blender-previs-storyboard；构建 rig 属于 scenario-blender-rigging。

Toolkit：

scripts/bx_anim.py

（关键帧设置、blocking 转 spline、曲线检查、测量、场景搭建、playblast 灯光、knee-pop、翻转与平衡检查、onion-skin 与曲线图像、单物体

bouncing_ball

；API 详见 procedures.md，已在 5.2.1 上测试）以及

bx_review.playblast

。

Stance (the expert delta)

Stance（专家方法）

Stay stepped long ("Blocking+"). Hjalti Hjalmarsson: juniors spline too early; computer in-betweens are "unintentional interpolated poses" that make notes hard. Keep adding hand-made breakdowns while stepped; splining is short and late.
Never convert the whole blocking to Bezier. Rik Schutte: key every main control on every key pose, copy each pose to the end of its hold ("pillars"), then spline the body only; face and fingers stay stepped until their own pass. Measured on 5.2.1: the naive conversion drifted 84% of the next move across a hold, the pillars held at exactly 0.
Snaps are authored. Rik: hold, then change pose in 2 to 3 frames; only big deliberate moves are left to interpolation. [added, measured] A contact inside continuous motion (a jump landing) is not a hold: pillaring it cut the body's speed at impact from 0.101 to 0.007 m per frame, a floaty landing.
Odd frames, even gaps; breakdowns shape arcs and steer the eye. Alex Nagy: key poses on odd frames with even spacing so a true middle frame exists. The breakdown sets the arc first, the timing second; favoring it late leaves more travel for the last frames, and the fastest part draws the eye.
The handle type is a timing decision. AUTO_CLAMPED keeps holds flat; AUTO overshoots between two equal keys (Alex uses it to push a pose or cushion a settle); VECTOR for hard hits, contacts and take-offs (Alex, Dillon Gu); FREE for burst spacing and exact arcs (Raymond Luc, Joey Carlino).
Lead with one part, layer the rest. Rik blocks a torso-only rhythm pass first; Dillon leads body mechanics with the COG and acting with the head or eyes. Overlap goes into the blocking, and a head never turns on one axis only (Rik).
Lip sync is rhythm before shapes. Rik: jaw first, stepped, opened big only on accents; off-sync is a missing preparation, not a global offset; M, B, P closed at least 2 frames and closed before the sound.
Spacing is felt, arcs are checked, the shot must read. Raymond: the audience should feel spacing tricks, not see them. Pablo Fournier: arcs are the most important check (root, hands, feet, nose), in camera space. Hjalti (in scenario-blender-previs-storyboard): after each cut the eye must find one thing, so a subject lost in an empty frame fails however good the curves are.

长时间保持 stepped（“Blocking+”）。 Hjalti Hjalmarsson：初级动画师过早使用 spline；计算机生成的 in-between 是“非预期的插值姿势”，会让 notes 难以落实。在 stepped 阶段持续添加手工 breakdown；spline 处理应当短且晚。
绝不把整段 blocking 转换为 Bezier。 Rik Schutte：在每个 key pose 上为所有主要 control 设置关键帧，将每个 pose 复制到其 hold 的末端（“pillars”），然后只对身体进行 spline；脸部和手指在各自处理前保持 stepped。5.2.1 实测：naive conversion 会在一个 hold 中让下一动作漂移 84%，而 pillars 精确保持在 0。
Snap 需要手工创作。 Rik：先保持 hold，再用 2 到 3 帧改变 pose；只有幅度较大且有意图的动作才留给 interpolation。[新增，实测] 连续运动中的 contact（例如跳跃落地）不是 hold：为它添加 pillar 后，撞击时身体速度从每帧 0.101 米降至 0.007 米，造成漂浮式落地。
奇数帧、偶数间隔；breakdown 塑造 arc 并引导视线。 Alex Nagy：在奇数帧设置 key pose，并保持偶数间隔，从而存在真正的中间帧。breakdown 先确定 arc，再确定 timing；把它处理得越晚，留给最后几帧的位移就越多，而速度最快的部分会吸引视线。
控制柄类型是 timing 决策。 AUTO_CLAMPED 可让 hold 保持平直；AUTO 会在两个等值 key 之间产生 overshoot（Alex 用它推出 pose 或缓冲 settle）；VECTOR 适用于强力 hit、contact 和 take-off；FREE 适用于 burst spacing 和精确 arc（Raymond Luc、Joey Carlino）。
以一个部位带头，再叠加其余部位。 Rik 先只对躯干进行 rhythm pass；Dillon 以 COG 引导身体机制，以头部或眼睛引导表演。Overlap 应纳入 blocking；头部转动不能只涉及一个轴（Rik）。
口型同步先处理 rhythm，再处理 shape。 Rik：先处理 jaw，保持 stepped，仅在 accent 处大幅张开；不同步通常是因为缺少预备动作，而不是需要整体偏移；M、B、P 至少闭合 2 帧，并在发出对应音素前闭合。
Spacing 应被感知，arc 要被检查，镜头必须清晰可读。 Raymond：观众应感受到 spacing 的运用，而不是看出这些技巧。Pablo Fournier：arc 是最重要的检查项（root、双手、双脚、鼻尖），需要在 camera space 中检查。Hjalti（位于 scenario-blender-previs-storyboard）：每次 cut 后，眼睛必须找到一个视觉落点，因此主体若在空旷画面中丢失，即便曲线再好也算失败。

Establish first

先确定基础条件

Input	Why it changes the plan	Default when silent
Medium, fps	Film 24 (Hjalti); games often 30 with fixed hit or release frames (Picaut)	24 fps
Camera	Locked acting shot: judge only through the camera (Rik). Moving, re-framable or gameplay camera: poses work from every direction (Leo Silly-Pelissier, Picaut)	locked camera
Style	Stepped on twos and never splined (Sprite Fright shots, Rik) vs splined; stylized vs naturalistic (Leo)	splined, stylized
Rig	Control names, IK/FK, rotation modes. Generated Rigify [verified]: `torso` , `hips` , `chest` , `head` , `foot_ik.L` , `upper_arm_fk.L` , `jaw_master` ; `["IK_FK"]` on `upper_arm_parent.L` (0 IK, 1 FK); legs have `IK_Stretch` 1.0; rest legs are 99.6% straight; main controls QUATERNION	FK arms when arcs matter, IK when hands touch things (Joey, Tony Garcia)
Named object	A brief that names the animated object expects every channel on it	one object, `bouncing_ball(obj=...)`
Audio, transcript	Beats, accents, phoneme preparation	beats from the brief
Reference	Timing and beats, never a trace (Hjalti)	none: write a beat list
Budget	Rik: about 3 s a week in big studios, 5 to 6 s on his acting shot; Flow: 2 s per animator per day	state what the budget buys

Input	影响方案的原因	未说明时的默认值
媒介、fps	电影通常为 24 fps（Hjalti）；游戏通常为 30 fps，并固定 hit 或 release 帧（Picaut）	24 fps
Camera	固定表演镜头：只通过 camera 判断（Rik）。移动、可重新构图或 gameplay camera：pose 需要从各个方向都成立（Leo Silly-Pelissier、Picaut）	固定 camera
风格	以 twos stepped 且从不 spline（Sprite Fright shots，Rik），或采用 spline；风格化或写实（Leo）	spline、风格化
Rig	control 名称、IK/FK、rotation mode。已生成的 Rigify [已验证]： `torso` 、 `hips` 、 `chest` 、 `head` 、 `foot_ik.L` 、 `upper_arm_fk.L` 、 `jaw_master` ； `upper_arm_parent.L` 上有 `["IK_FK"]` （0 为 IK，1 为 FK）；腿部的 `IK_Stretch` 为 1.0；rest pose 中双腿 99.6% 伸直；主要 controls 使用 QUATERNION	arc 重要时手臂用 FK；手需要接触物体时用 IK（Joey，Tony Garcia）
指定物体	任务 brief 指定了动画物体时，预期需要为它的每个 channel 设置动画	单一物体， `bouncing_ball(obj=...)`
音频、转录稿	beats、accents 与音素预备	依据 brief 提取 beats
参考素材	只参考 timing 和 beats，绝不描摹（trace）（Hjalti）	无：编写 beat list
预算	Rik：大型工作室约为每周 3 秒，大型表演镜头需要 5 到 6 秒；Flow：每位动画师每天 2 秒	说明预算能换取哪些成果

Workflow

Plan. Beat list with frames: every acting beat in order (Hjalti counts about 8 per shot), sub-beats notice, react, realize, respond (Rik), the leading part per beat. With audio,
```
audio_envelope
```
+
```
accent_frames
```
; hit a pose just before its audio peak (Alex). Start mid-action (Rik). GATE: beat table written.
Set up and stage the shot (P1, P18): fps, range, sound, passepartout 0.99, Simplify for previews. Place the camera, then
```
staging_report(subject, frames)
```
with the real render size: subject height, how much of the frame the action covers, entry, final pose margin. Playblast look:
```
playblast_lighting(key_dir=(0, 0, 1))
```
(overhead key converted to Workbench's camera space: the shadow sits under the subject, the gap is its height, contact is where they meet),
```
floor_slab
```
,
```
rotation_texture
```
on anything that rolls. GATE:
```
flags
```
empty;
```
shadow_frames
```
visible in the air and touching at a contact; camera stills looked at.
Block A, key poses stepped. Strongest, longest-held pose first (Alex). Build each pose COG, feet (weight over the support foot, feet never twins, knees soft), hips, chest, head, arms. Pose in world terms with
```
world_pose
```
(rig axes are arbitrary), key with
```
key_pose(..., keytype='EXTREME')
```
, CONSTANT, all main controls. GATE: pose strip
```
onion_skin(frames=keys, spread=...)
```
shows clear silhouettes and contrast;
```
balance_report
```
margin >= 0 on held poses.
Blocking+ (still stepped).
```
breakdown
```
at the middle frame with per-part
```
factors
```
(COG dips, extremities delayed at 0.2 to 0.3, directed part favored late; after a take-off the body is ballistic, about 2/3 of the rise in 3 of 7 frames, and the feet must follow);
```
ease_inbetweens
```
for 20/80 (Pablo); overshoots and settles; overlap offsets; key types as a confidence map (Hjalti). GATE: stepped playblast approved; notes on intent stopped (Leo: none after Block B).
Spline the body with
```
blocking_to_spline(rig, body_bones, transition=3, interpolate={...})
```
: big moves and continuous contacts in
```
interpolate
```
; VECTOR on foot contacts and take-offs. GATE:
```
hold_drift
```
< 1e-5,
```
overshoots
```
only wanted settles, face still CONSTANT,
```
motion_report
```
without unintended constant spacing,
```
ballistic_fit
```
on the airborne COG with
```
g_ratio
```
near 1.0 and a small residual,
```
limb_extension
```
never above 1.0.
Re-inject energy (Leo: splining softens): timing accents, overshoots, desynchronized parts,
```
offset_keys
```
1 to 2 frames per chain link (Dillon), head lag 2 to 3 frames in cycles (Joey), contacts that slide rather than glue (Rik). Fingers: little overlap, no bounce. GATE: arcs clean in camera pixels (
```
to_camera(..., res=(w, h))
```
,
```
motion_report(dims=2)
```
).
Face and lip sync, stepped (P6, P7): jaw rhythm, corners (never dead center), shapes from a pose library on the lower face minus the jaw, accents and asymmetry in small doses, tongue last, then spline the face. Eyes dart in 1 to 2 frames and lead the head; brows 3 to 10 frames (Rik). GATE:
```
transitions
```
meets those counts; accents clearly fewer than syllables.
Polish.
```
foot_slip
```
under 1 mm,
```
lowest_point
```
for penetration,
```
rotation_flips
```
empty (
```
fix_rotation_flips
```
),
```
limb_extension
```
under 0.99 wherever the leg should stay bent, smears 1 frame (Pablo), burst spacing only now (Raymond), subdivision on. GATE: critique.md rubric passes on the final playblast, onion skin and graph image.

Variants. Bouncing ball (P16, P18):

bouncing_ball(obj=ANIM_ball, first_apex=-3, fit=False, ...)

keys ONE object: exact parabolas under one gravity through whole-frame contacts, odd or even flights so small hops keep their height, squash on the contact frame and stretch along the velocity through a world-aligned squash modifier (the roll is never twisted), roll = distance / radius, constant-deceleration roll, a 6-frame hold.

first_apex

before

start

throws it in from off-screen. Weight mapping is [added]: tune by render. Walk (Joey, 30 fps): contact 0, down 5, passing 10, up 15, 40-frame cycle; heel curve straight during contact, root linear with REPEAT_OFFSET (P5). Jump:

tests/code/blender-animation/test_rigify_jump.py

is the worked example (Rigify human, blocking to spline).

Plan。 编写带帧号的 beat list：按顺序列出每个表演 beat（Hjalti 每镜头约 8 个），再拆分为 notice、react、realize、respond 等 sub-beats（Rik），并确定每个 beat 的 leading part。配合音频时，使用
```
audio_envelope
```
+
```
accent_frames
```
；让 pose 恰好出现在音频峰值之前（Alex）。可以从动作中途开始（Rik）。GATE：写出 beat table。
设置并搭建镜头（P1、P18）：设置 fps、range、sound、passepartout 0.99，并为预览启用 Simplify。先放置 camera，再以真实 render size 调用
```
staging_report(subject, frames)
```
：检查主体高度、动作占画面的比例、入画情况和最终 pose 的边距。检查 playblast 灯光：
```
playblast_lighting(key_dir=(0, 0, 1))
```
（将顶部 key light 转换到 Workbench 的 camera space：阴影位于主体下方，空隙等于主体高度，contact 位于二者相接处），使用
```
floor_slab
```
，并为任何会滚动的物体使用
```
rotation_texture
```
。GATE：
```
flags
```
为空；
```
shadow_frames
```
在腾空时可见，并在 contact 时与地面接触；已实际查看 camera stills。
Block A，以 stepped 方式设置 key poses。 先从最强力、保持时间最长的 pose 开始（Alex）。按 COG、双脚（重心落在支撑脚上，双脚不能做成 twins，膝盖放松）、hips、chest、head、arms 的顺序构建每个 pose。以世界空间中的姿态关系进行摆放，并通过
```
world_pose
```
实现（rig 轴向是任意的），使用
```
key_pose(..., keytype='EXTREME')
```
设置关键帧，设为 CONSTANT，并覆盖所有主要 controls。GATE：pose strip
```
onion_skin(frames=keys, spread=...)
```
显示清晰且有反差的 silhouette；hold pose 的
```
balance_report
```
margin >= 0。
Blocking+（仍保持 stepped）。 在中间帧使用
```
breakdown
```
，并为各部位设置
```
factors
```
（COG 下沉；四肢末端延迟 0.2 到 0.3；受引导的部位靠后处理；起跳后身体按 ballistic 运动，在 7 帧中的 3 帧内完成约 2/3 的上升，双脚必须跟随）；使用
```
ease_inbetweens
```
实现 20/80（Pablo）；加入 overshoot 与 settle；设置 overlap offset；使用 key type 表示置信度映射（Hjalti）。GATE：stepped playblast 获批；涉及动作意图的 notes 已不再出现（Leo：Block B 之后不再有）。
对身体进行 spline。 使用
```
blocking_to_spline(rig, body_bones, transition=3, interpolate={...})
```
：将大幅动作和连续 contact 放入
```
interpolate
```
；脚部 contact 与 take-off 使用 VECTOR。GATE：
```
hold_drift
```
< 1e-5，
```
overshoots
```
仅出现在预期的 settle 上，脸部仍为 CONSTANT，
```
motion_report
```
未显示非预期的 constant spacing，腾空状态下 COG 的
```
ballistic_fit
```
中
```
g_ratio
```
接近 1.0 且残差很小，
```
limb_extension
```
从未超过 1.0。
重新注入能量（Leo：spline 会削弱力度）：调整 timing accent、overshoot 和不同步的部位，
```
offset_keys
```
在每条 chain link 上错开 1 到 2 帧（Dillon），循环中头部延迟 2 到 3 帧（Joey），contact 可以滑动而不是黏住（Rik）。手指只做少量 overlap，不做弹跳。GATE：在 camera pixels 中 arc 保持干净（
```
to_camera(..., res=(w, h))
```
、
```
motion_report(dims=2)
```
）。
脸部与口型同步，保持 stepped（P6、P7）：先处理 jaw rhythm，再处理嘴角（绝不能完全居中），使用 lower face（排除 jaw）的 pose library 制作 shape，少量加入 accent 与 asymmetry，最后处理 tongue，然后再 spline 脸部。视线在 1 到 2 帧内快速移动，并先于 head；眉部变化使用 3 到 10 帧（Rik）。GATE：
```
transitions
```
满足这些帧数；accent 数量明显少于音节数。
Polish。
```
foot_slip
```
< 1 mm，使用
```
lowest_point
```
检查穿透，
```
rotation_flips
```
为空（
```
fix_rotation_flips
```
），需要保持弯曲的腿部其
```
limb_extension
```
< 0.99，smear 持续 1 帧（Pablo），到此时才使用 burst spacing（Raymond），开启 subdivision。GATE：最终 playblast、onion skin 和 graph image 均通过
```
critique.md
```
rubric。

变体。 Bouncing ball（P16、P18）：

bouncing_ball(obj=ANIM_ball, first_apex=-3, fit=False, ...)

为一个物体设置关键帧：让整帧 contact 之间的运动遵循同一重力并形成精确抛物线；腾空段可使用奇数或偶数帧数，让小跳弹保持其高度；在 contact 帧进行 squash，并沿速度方向通过与世界坐标对齐的 squash modifier 进行 stretch（roll 始终不发生扭曲）；roll = distance / radius；采用恒定减速度滚动；设置 6 帧 hold。

first_apex

位于

start

之前时，物体从画面外抛入。Weight mapping 属于 [新增]：按 render 调整。Walk（Joey，30 fps）：contact 0、down 5、passing 10、up 15，40 帧循环；contact 期间 heel curve 保持直线，root 使用带 REPEAT_OFFSET 的线性插值（P5）。Jump：

tests/code/blender-animation/test_rigify_jump.py

是完整示例（Rigify human，从 blocking 到 spline）。

Numbers

数值

Item	Value	Source
Snappy pose change	2 to 3 frames after the hold	Rik
Aggressive change	4 frames instead of 8	Alex
Hold to read an idea	6 frames	Alex
Settle	1 to 2 frames, 4 soft	Alex
Reaction after stimulus	about 6 frames	Rik
Eye dart / brow change	1 to 2 / 3 to 10 frames	Rik
Ease rule	80% of the remaining way per in-between (slow-in); mirror 20%	Pablo
Smear	1 frame, sometimes 2	Pablo
Micro-anticipation	last 1 to 2 frames before hit or release pushed to an extreme	Picaut
Head lag in a cycle / foot offset	2 to 3 frames / 1 frame	Joey / Rik
Real gravity at 24 fps	acceleration 0.01703 m/frame^2; a quadratic fit's leading coefficient is half (-0.00852). `gravity()`	physics [added]
Subject size in frame	12% of frame height minimum, 15% or more for a single subject	[added] E3: both runs measured 10%
IK leg extension	under 0.99 of full length while meant bent; above 1.0 = IK stretch	[added]
Pinwheel on a rolling object	roll per frame under 360 / sectors degrees	[added] wagon-wheel

Item	Value	Source
快速利落的 pose 变化	hold 之后 2 到 3 帧	Rik
强烈变化	4 帧而非 8 帧	Alex
为读懂一个意图而保持	6 帧	Alex
Settle	1 到 2 帧，另加 4 帧柔和过渡	Alex
刺激后的反应	约 6 帧	Rik
视线快速移动／眉部变化	1 到 2／3 到 10 帧	Rik
Easing 规则	每个 in-between 走完剩余距离的 80%（slow-in）；镜像为 20%	Pablo
Smear	1 帧，有时为 2 帧	Pablo
微量预备	hit 或 release 前最后 1 到 2 帧推向极端	Picaut
循环中的头部延迟／双脚偏移	2 到 3 帧／1 帧	Joey／Rik
24 fps 下的真实重力	加速度 0.01703 m/frame^2；二次拟合的首项系数为其一半（-0.00852）。 `gravity()`	physics [新增]
主体在画面中的尺寸	最低为画面高度的 12%；单一主体应达到 15% 或以上	[新增] E3：两次运行均实测为 10%
IK 腿部伸展	需要保持弯曲时低于全长的 0.99；高于 1.0 即为 IK stretch	[新增]
滚动物体的 pinwheel 效应	每帧滚动小于 360°／分扇区角度	[新增] wagon-wheel

Quality gates

Measurable: slot named after the character; key poses CONSTANT and typed before approval;

hold_drift

~0;

overshoots

only on settles;

foot_slip

< 1 mm;

lowest_point

never below the floor (sample sub-frames);

transitions

for darts, brows, snaps, plosives;

ballistic_fit

g_ratio near 1 at real scale;

motion_report

: sharp turns only at contacts, no arc wobble or start-stops inside a move;

staging_report

flags empty with shadow frames visible;

limb_extension

rotation_flips

balance_report

as above;

roll_aliasing

ok. Visual (open every image): pose strip, onion skin through the shot camera with tracks,

graph_image

, playblast frame sheets (subject size, entry, shadow gap closing at contacts, spin readable), orbit views when the camera is not locked.

可量化项： slot 以角色命名；获批前，key poses 均为 CONSTANT 且已设置类型；

hold_drift

约为 0；

overshoots

仅出现在 settle 上；

foot_slip

< 1 mm；

lowest_point

从不低于地面（对子帧采样）；

transitions

覆盖 darts、brows、snaps 和 plosives；真实尺度下

ballistic_fit

的

g_ratio

接近 1；

motion_report

显示急转只发生在 contact 上，动作内部没有 arc 晃动或走走停停；

staging_report

的 flags 为空且 shadow frames 可见；

limb_extension

、

rotation_flips

、

balance_report

符合上述要求；

roll_aliasing

正常。

视觉项（需打开每一张图检查）：pose strip、通过带轨迹的 shot camera 拍摄的 onion skin、

graph_image

、playblast 帧表（主体尺寸、入画情况、contact 处逐渐闭合的阴影空隙、可读的旋转），以及 camera 未锁定时的 orbit views。

Common mistakes

常见错误

Mistake	What it looks like	Fix
Whole blocking to Bezier	"floaty spaghetti"	`blocking_to_spline` with pillars, body only
Pillar on a continuous contact	body brakes before impact	put that frame in `interpolate` ; VECTOR on the foot
AUTO handles on a hold	hold drifts past the pose	AUTO_CLAMPED; AUTO only for a settle
Heel curve eased during contact	foot slides (5.8 cm per step measured)	VECTOR or zero-length FREE handles
Jaw open on every syllable	chattering mouth	big opens on `accent_frames` only
BOUNCE easing for a ball	no squash frame ever shows	`bouncing_ball` or keyed whole-frame contacts
Squash on a parent that also aims	pattern twists on stretch frames (55 degrees measured on the old rig)	`squash_modifier` (world axes) on the object itself
Flights rounded to even frames	hops lose or gain height, gravity changes per bounce (0.98 to 1.31 measured)	whole-frame contacts, odd flights allowed, one gravity
Framing the whole set	subject 10% of frame, top 40% empty	move in or shorten the travel until `staging_report` is clean
`display.light_direction` read as world	shadow hidden behind the subject (0 px)	`playblast_lighting(key_dir=...)`
Arcs checked in normalized camera coords	false sharp turns at apexes (aspect squeezes x)	`to_camera(..., res=(w, h))`
Legs straight at stand or push-off	IK stretch lengthens the leg (18% in the first jump draft)	soft knees, feet breakdown after take-off, VECTOR take-off

Mistake	表现	Fix
将整段 blocking 转换为 Bezier	“漂浮的意大利面”	使用带 pillars 的 `blocking_to_spline` ，仅处理身体
在连续 contact 上使用 pillar	身体在撞击前刹车	将该帧放入 `interpolate` ；脚部使用 VECTOR
在 hold 上使用 AUTO 控制柄	hold 越过 pose 继续漂移	AUTO_CLAMPED；AUTO 只用于 settle
contact 期间对 heel curve 使用 easing	脚部滑步（实测每步 5.8 cm）	VECTOR，或使用长度为零的 FREE 控制柄
每个音节都张开 jaw	嘴巴颤动	只在 `accent_frames` 上大幅张嘴
对球使用 BOUNCE easing	始终看不到 squash 帧	`bouncing_ball` ，或以整帧 contact 设置关键帧
在同时承担 aim 的 parent 上做 squash	stretch 帧上的图案发生扭曲（old rig 实测为 55 度）	在物体自身上使用 `squash_modifier` （world axes）
将腾空段取整到偶数帧	小跳弹丢失或增加高度，每次弹跳的重力都不同（实测为 0.98 到 1.31）	使用整帧 contact，允许奇数帧腾空，并保持同一重力
将整个 set 纳入构图	主体仅占画面的 10%，顶部 40% 空白	推进镜头或缩短移动距离，直到 `staging_report` 干净
将 `display.light_direction` 当作 world 读取	阴影藏在主体后方（0 px）	`playblast_lighting(key_dir=...)`
在 normalized camera coords 中检查 arc	在 apex 处产生虚假的急转（aspect 压缩 x）	`to_camera(..., res=(w, h))`
站立或蹬地时将腿伸直	IK stretch 拉长腿部（首个 jump draft 中为 18%）	保持 soft knees，起跳后让双脚 breakdown 跟随，起跳使用 VECTOR

Blender 5.2 notes

```
action.fcurves
```
is gone: channelbags via
```
bpy_extras.anim_utils
```
(
```
bx_anim.channelbag
```
). Assigning an action animates only if a slot matches; otherwise set
```
ad.action_slot
```
.
One layer per action (
```
layers.new
```
raises); layer with the NLA plus an ADD or COMBINE action (
```
push_layer
```
).
```
keyframe_points.insert
```
gives BEZIER AUTO_CLAMPED; a Keyframe reference dies at the next insert on that curve.

Headless:

anim.keyframe_insert

fails;

pose.breakdown

and

pose.blend_to_neighbor

need explicit

prev_frame

next_frame

;

render.opengl

refuses, so playblasts are Workbench renders.

Workbench
```
scene.display.light_direction
```
is camera-relative;
```
matrix_world
```
is stale until
```
view_layer.update()
```
, so convert after it.

GN modifier inputs key at

modifiers["X"].properties.inputs.Socket_n.value

Playblast audio: sound strip plus
```
render.ffmpeg.audio_codec = 'AAC'
```
.
Keymap: Up = previous key, Down = next (5.0). Not in 5.2: action layers, paste-pose blending, range world-space copy (5.3).

```
action.fcurves
```
已移除：通过
```
bpy_extras.anim_utils
```
获取 channelbag（
```
bx_anim.channelbag
```
）。只有在 slot 匹配时，assign action 才会产生动画；否则应设置
```
ad.action_slot
```
。
每个 action 只能有一个 layer（调用
```
layers.new
```
会报错）；创建包含 NLA 以及一个 ADD 或 COMBINE action 的 layer（
```
push_layer
```
）。
```
keyframe_points.insert
```
默认生成 BEZIER AUTO_CLAMPED；对某条 curve 下一次执行 insert 后，先前的 Keyframe 引用会失效。
Headless：
```
anim.keyframe_insert
```
会失败；
```
pose.breakdown
```
和
```
pose.blend_to_neighbor
```
必须显式提供
```
prev_frame
```
／
```
next_frame
```
；
```
render.opengl
```
会拒绝执行，因此 playblast 使用 Workbench render。
Workbench 的
```
scene.display.light_direction
```
相对于 camera；
```
matrix_world
```
在调用
```
view_layer.update()
```
前为 stale，因此应在 update 后再转换。

GN modifier 的输入关键帧路径为

modifiers["X"].properties.inputs.Socket_n.value

。

Playblast 音频：添加 sound strip，并设置
```
render.ffmpeg.audio_codec = 'AAC'
```
。
快捷键映射：Up = previous key，Down = next（5.0）。5.2 中没有：action layers、paste-pose blending、range world-space copy（5.3）。

References

```
references/expert-notes.md
```
: principles, numbers and disagreements by expert, with timestamps; load when choosing between approaches or writing notes.
```
references/procedures.md
```
: full tested code for every procedure (setup, blocking, spline, walk, lip sync, facial timing, contact pin, slots, layers, pose library, playblast, measurement, ball, staging, knee/flip/balance); load before writing code.
```
references/critique.md
```
: the review rubric per stage, staging thresholds and their calibration, how these animators phrase notes; load at every gate.
```
references/sources.md
```
: the 14 source videos, what each is best for, best timestamps.

```
references/expert-notes.md
```
：包含各专家提出的原则、数值和分歧，并附时间戳；在不同方案之间做选择或编写 notes 时加载。
```
references/procedures.md
```
：包含每项流程的完整测试代码（setup、blocking、spline、walk、lip sync、facial timing、contact pin、slots、layers、pose library、playblast、measurement、ball、staging、knee/flip/balance）；编写代码前加载。
```
references/critique.md
```
：包含各阶段的 review rubric、staging 阈值及其校准方式，以及动画师表述 notes 的方式；每个 GATE 都应加载。
```
references/sources.md
```
：包含 14 个来源视频、各自最适用的内容以及最佳时间戳。