avatar-animations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring Avatar Animations (Scene Emotes)

制作Avatar动画（场景表情）

This skill covers making the animation file: posing the official Decentraland avatar rig in Blender, exporting a clip as a

*_emote.glb

, verifying it, and handing it to the scene. The scene-side API that plays it —

triggerSceneEmote

stopEmote

AvatarEmoteCommand

, the

AvatarMask

enum, the permission — lives in player-avatar; this skill links there rather than repeating it.

Scope check before you start:

The user wants	Skill
A new animation of the player's avatar that doesn't exist yet	this skill
To play a built-in emote, or a `_emote.glb` that already exists	player-avatar
To play an animation clip baked into a `.glb` model/prop	animations-tweens
To animate an NPC	npcs
To move/rotate an entity procedurally	animations-tweens ( `Tween` )

本技能涵盖动画文件制作：在Blender中为官方Decentraland Avatar绑定摆姿势，将动画片段导出为

*_emote.glb

格式，验证后交付给场景。播放该动画的场景端API——

triggerSceneEmote

、

stopEmote

、

AvatarEmoteCommand

、

AvatarMask

枚举、权限——位于 player-avatar 技能中；本技能会链接到该部分，不再重复说明。

开始前的范围检查：

用户需求	对应技能
尚不存在的玩家Avatar新动画	本技能
播放内置表情，或已有的 `_emote.glb` 文件	player-avatar
播放烘焙到 `.glb` 模型/道具中的动画片段	animations-tweens
为NPC添加动画	npcs
以程序化方式移动/旋转实体	animations-tweens（ `Tween` ）

Workflow

工作流

Get the rig —
```
Avatar_File.blend
```
, never a hand-built armature. Download + bone/control/property reference:
```
{baseDir}/references/avatar-rig.md
```
.
Set up — set the scene to 30 fps (the shipped file is 24), capture the
```
Starting_Pose
```
values, create one new action per clip.
Author — pose
```
CTRL_
```
bones only, in Pose mode, keyframing every bone you touch at every keyframe.
Verify while authoring — print world positions (clipping, floor, animation area) and render four angles per keyframe into a contact sheet.
Export — one clip per file, armature only,
```
export_def_bones=True
```
,
```
ACTIVE_ACTIONS
```
.
Verify the GLB — parse the JSON chunk: 1 animation, 0 meshes, 63 nodes, 62 channels per path, duration =
```
(frames − 1) / 30
```
.
Hand off — rename to
```
*_emote.glb
```
, drop under
```
assets/animations/
```
, add the permission, play it (see player-avatar).

Ready-made

bpy

helpers for every step — the helper module, sign detection, render/contact-sheet setup, the export call, and the GLB verifier — are in

{baseDir}/references/blender-emote-patterns.md

How to drive Blender (headless CLI vs Blender MCP, binary paths, and the rule that you must never fall back from the MCP to headless silently) is already covered in

{baseDir}/../add-3d-models/references/blender-authoring.md

. Emote authoring uses exactly those two paths; do not re-derive them.

获取绑定 — 使用
```
Avatar_File.blend
```
，切勿使用手动构建的骨架。下载地址及骨骼/控件/属性参考：
```
{baseDir}/references/avatar-rig.md
```
。
设置场景 — 将场景帧率设为 30 fps（默认文件为24fps），记录
```
Starting_Pose
```
的数值，为每个动画片段创建一个新的动作（action）。
制作动画 — 仅在姿态模式下调整
```
CTRL_
```
前缀的骨骼，为所有你调整过的骨骼在每个关键帧都设置关键帧。
制作过程中验证 — 打印世界坐标（检查穿模、地面接触、动画区域）并为每个关键帧渲染四个角度，拼成联系表。
导出 — 每个文件仅包含一个动画片段，仅导出骨架，设置
```
export_def_bones=True
```
、
```
ACTIVE_ACTIONS
```
。
验证GLB文件 — 解析JSON块：1个动画、0个网格、63个节点、每个路径62个通道，时长 =
```
(帧数 − 1) / 30
```
。
交付 — 重命名为
```
*_emote.glb
```
，放入
```
assets/animations/
```
目录下，添加权限，播放动画（参见 player-avatar）。

每个步骤都有现成的

bpy

辅助工具——辅助模块、符号检测、渲染/联系表设置、导出调用、GLB验证器——都在

{baseDir}/references/blender-emote-patterns.md

中。

如何操作Blender（无头CLI vs Blender MCP、二进制路径，以及绝不能从MCP静默回退到无头模式的规则）已在

{baseDir}/../add-3d-models/references/blender-authoring.md

中说明。表情制作完全遵循这两种方式，请勿重新推导。

RULE: One new action per clip — and reset to the idle pose, not identity

规则：每个动画片段对应一个新动作——重置为空闲姿势，而非初始姿态

Create a fresh action for every clip. In Blender 4.4+/5 actions are slotted, and

Action.fcurves

no longer exists (curves live under

act.layers[0].strips[0].channelbags

python

act  = bpy.data.actions.new(name)
slot = act.slots.new('OBJECT', 'Avatar_Animation')
arm.animation_data.action = act
arm.animation_data.action_slot = slot

Before authoring anything,

scene.frame_set(0)

to evaluate

Starting_Pose

and capture every pose bone's transform. That snapshot — not the identity transform — is the baseline you reset to between keyframes. The rest pose of the armature is an A/T-pose; the idle the runtime blends from is

Starting_Pose

. Resetting to identity gives you a clip that snaps to a T-pose on the first frame.

为每个动画片段创建全新的动作。在Blender 4.4+/5版本中，动作是槽位化的，

Action.fcurves

已不存在（曲线位于

act.layers[0].strips[0].channelbags

下）：

python

act  = bpy.data.actions.new(name)
slot = act.slots.new('OBJECT', 'Avatar_Animation')
arm.animation_data.action = act
arm.animation_data.action_slot = slot

在制作任何内容之前，执行

scene.frame_set(0)

以评估

Starting_Pose

并记录每个姿态骨骼的变换。这个快照——而非初始变换——是你在关键帧之间重置的基准。骨架的静止姿势是A/T型姿势；运行时混合的空闲姿势是

Starting_Pose

。重置为初始姿态会导致动画片段在第一帧突然跳转到T型姿势。

RULE: Key everything you pose, at every keyframe

规则：为所有你调整过的姿势在每个关键帧都设置关键帧

scene.frame_set()

re-evaluates the active action and overwrites any un-keyed pose (

view_layer.update()

does not). A render taken after

frame_set

of a pose you forgot to key silently shows the idle instead — you will debug the wrong thing. So insert keys on location, rotation and scale for every control bone you touched, plus any custom property you changed:

python

pb.keyframe_insert('["FK > IK Leg L"]', frame=f)

On the first and last frame, also key location/rotation/scale on every deform bone. Channels left without boundary keys stay "open" and keep whatever a previously playing emote left there — the official docs call these emote overrides, and they show up as an avatar whose legs are still doing the last emote.

scene.frame_set()

会重新评估当前活动动作并覆盖所有未设置关键帧的姿势（

view_layer.update()

不会）。如果你忘记给某个姿势设置关键帧，在

frame_set

后渲染的画面会静默显示空闲姿势——你会调试错误的问题。因此，要为所有你调整过的控制骨骼的位置、旋转、缩放，以及任何你修改过的自定义属性插入关键帧：

python

pb.keyframe_insert('["FK > IK Leg L"]', frame=f)

在第一帧和最后一帧，还要为所有变形骨骼设置位置/旋转/缩放关键帧。没有边界关键帧的通道会保持“打开”状态，并保留上一个播放的表情留下的数值——官方文档称之为表情覆盖，表现为Avatar的腿还在做上一个表情的动作。

RULE: Upper arms — world axes for direction, local Y for twist

规则：上臂——方向用世界轴，扭转用局部Y轴

The upper-arm bone's local X is tilted. Rotating about it sweeps the arm across the chest, and a pose that should have both arms forward ends up with the arms crossed — this happens in practice and is not obvious in a front render. So set the arm's direction with world axes, converting the world axis into the bone's current frame first:

python

M = (arm.matrix_world @ pb.matrix).to_3x3().normalized()
local_axis = M.inverted() @ Vector(world_axis)
pb.rotation_quaternion @= Quaternion(local_axis, math.radians(deg))

Pure forward raise → world X.
Moving a raised arm in/out → yaw about world Z.

World axes alone do not give a perfect arm pose, though. Arms move in many directions, and the rig's animator works with world and local rotations together. Two things need the bone's local axes:

Twist — palm up/down, elbow pointing out or in, a wrist that has to face a prop — can only be done by rotating the bone about its own length, which is local Y on this rig (verified: local Y of
```
CTRL_FK_Avatar_Arm.*
```
is the bone axis; rotating it leaves the elbow where it is and only rolls the forearm and hand).
```
rl('CTRL_FK_Avatar_Arm.L', 'Y', deg)
```
.
Fine-tuning once the gross direction is right — a small local correction is often more precise than another world-axis rotation.

Elbows, knees, wrists and fingers hinge on their local X (Y/Z are locked on those controls) —

rl()

is correct there.

上臂骨骼的局部X轴是倾斜的。绕它旋转会让手臂扫过胸部，原本应该双臂向前的姿势最终会变成双臂交叉——这种情况在实际中经常发生，而且在正面渲染中不明显。因此，要用世界轴设置手臂的方向，先将世界轴转换到骨骼的当前坐标系中：

python

M = (arm.matrix_world @ pb.matrix).to_3x3().normalized()
local_axis = M.inverted() @ Vector(world_axis)
pb.rotation_quaternion @= Quaternion(local_axis, math.radians(deg))

纯向前抬起 → 世界 X 轴。
抬起的手臂向内/向外移动 → 绕世界 Z 轴偏航。

不过，仅用世界轴无法得到完美的手臂姿势。手臂可以向多个方向运动，绑定的动画师会结合世界和局部旋转一起使用。有两种情况需要用到骨骼的局部轴：

扭转——手掌向上/向下、肘部向外或向内、手腕必须朝向某个道具——只能通过绕骨骼自身长度旋转来实现，也就是这个绑定上的局部Y轴（已验证：
```
CTRL_FK_Avatar_Arm.*
```
的局部Y轴是骨骼轴向；绕它旋转不会移动肘部，只会转动前臂和手）。使用
```
rl('CTRL_FK_Avatar_Arm.L', 'Y', deg)
```
。
在大致方向正确后进行微调——小的局部校正通常比再次绕世界轴旋转更精确。

肘部、膝盖、手腕和手指绕其局部X轴铰接（这些控件的Y/Z轴是锁定的）——

rl()

在这些部位是正确的。

RULE: Legs mirror, the upper body does not — fix the pasted upper body by flipping X and Z

规则：腿部可镜像，上半身不可——通过翻转X和Z修正粘贴的上半身姿势

Blender's Pose ▸ Copy Pose / Paste X-Flipped only works on half of this rig (verified on

Avatar_File.blend

; numbers in

{baseDir}/references/avatar-rig.md

Legs and feet mirror normally, FK or IK — Paste X-Flipped is exact for IK legs and within ~3 cm for FK legs.
Shoulders, upper arms, forearms, hands and fingers do not — Paste X-Flipped lands the other hand 40–70 cm away. The rig animator's fix: on every pasted upper-body control, negate the X and Z values and keep Y. Example: a pasted arm reading X −0.5, Z 0.1 becomes X 0.5, Z −0.1. Apply it to the rotation (quaternion or Euler) and, on the IK hand and elbow controls, to the location too. Verified exact (0.000 m) for the whole arm chain, FK and IK, all 30 finger controls included.

mirror_side('L')

{baseDir}/references/blender-emote-patterns.md

does both steps for every control at once.

When you pose a single joint rather than mirroring, still detect its sign programmatically — rotate +15°, measure which way the downstream bone moved, cache (
```
auto_sign
```
). The same angle on
```
.L
```
and
```
.R
```
does not produce a symmetric pose.

Blender的姿态 ▸ 复制姿势 / 粘贴X翻转 仅对这个绑定的一半有效（已在

Avatar_File.blend

中验证；数值见

{baseDir}/references/avatar-rig.md

）：

腿和脚可以正常镜像，无论是FK还是IK——粘贴X翻转对IK腿是完全精确的，对FK腿误差在约3厘米以内。
肩膀、上臂、前臂、手和手指不行——粘贴X翻转后，另一只手会偏离40-70厘米。绑定动画师的解决方法是：对每个粘贴的上半身控件，取X和Z值的相反数，保持Y值不变。例如：粘贴的手臂数值为X −0.5、Z 0.1，要改成X 0.5、Z −0.1。对旋转（四元数或欧拉角）应用此规则，对于IK手和肘部控件，位置也要应用。已验证整个手臂链（包括FK和IK，以及全部30个手指控件）完全精确（误差0.000米）。

{baseDir}/references/blender-emote-patterns.md

中的

mirror_side('L')

可以一次性对所有控件执行这两个步骤。

当你为单个关节摆姿势而非镜像时，仍要通过程序检测其符号——旋转+15°，测量下游骨骼的移动方向，缓存结果（
```
auto_sign
```
）。对
```
.L
```
和
```
.R
```
使用相同的角度不会产生对称的姿势。

RULE: FK or IK — lose contact → FK, keep contact → IK

规则：FK或IK——失去接触用FK，保持接触用IK

Legs default to IK, arms to FK (

FK > IK *

properties on

CTRL_Avatar_UpperBody

). Switch only when the pose needs it, using one rule: if a hand or foot has to keep contact with the floor, a seat, a wall or a prop, it should be IK; if it loses contact, it should be FK.

FK legs: jumps, rolls, flying, handstands, swimming, legs dangling off a ledge or a theatre seat.
IK hands: push-ups, climbing, leaning on a table, both hands fixed on one prop.
Do not flip modes during walk cycles, dances or anywhere contact is lost only briefly — the defaults handle those, and every switch pops unless the two chains match exactly at that frame.
Key the
```
FK > IK
```
property itself when you change it, not just the bones.

Seated poses. Lower the body with

CTRL_Avatar_UpperBody

— it is the centre of gravity and moves the whole body.

CTRL_Avatar_Hips

moves only pelvis + legs and stretches the torso — wrong tool for sitting. Then decide per leg:

Feet	Legs
Both feet on the ground (chair, bench)	Stay IK: move `CTRL_IK_Foot.` to where the feet will rest, then drop the COG — the knees bend on their own, feet stay planted (verified: toes stay at Z = 0 through a 0.4 m drop). Aim the knees with `CTRL_Avatar_Knee.` .
One leg crossed over the other	Only the lifted leg to FK; the grounded one stays IK.
Feet off the ground (pond edge, theatre seat, high stool)	Both legs FK.

python

setprop('CTRL_Avatar_UpperBody', 'FK > IK Leg L', 0.0)   # only for a leg that leaves the ground
setprop('CTRL_Avatar_UpperBody', 'FK > IK Leg R', 0.0)

腿部默认使用IK，手臂默认使用FK（

CTRL_Avatar_UpperBody

上的

FK > IK *

属性）。仅在姿势需要时切换，遵循一条规则：如果手或脚必须与地面、座椅、墙壁或道具保持接触，就用IK；如果失去接触，就用FK。

FK腿：跳跃、翻滚、飞行、倒立、游泳、腿悬在悬崖或剧院座位外。
IK手：俯卧撑、攀爬、靠在桌子上、双手固定在一个道具上。
不要在行走循环、舞蹈或仅短暂失去接触的场景中切换模式——默认设置可以处理这些情况，而且每次切换都会产生跳变，除非两个骨骼链在该帧完全匹配。
切换时要为
```
FK > IK
```
属性本身设置关键帧，而不仅仅是骨骼。

坐姿。 用

CTRL_Avatar_UpperBody

降低身体——它是重心，会移动整个身体。

CTRL_Avatar_Hips

只会移动骨盆+腿，还会拉伸躯干——是错误的坐姿工具。然后每条腿单独决定：

脚部状态	腿部模式
双脚都在地面上（椅子、长凳）	保持IK：将 `CTRL_IK_Foot.` 移动到脚要放置的位置，然后降低重心——膝盖会自动弯曲，脚保持贴地（已验证：在0.4米的下降过程中，脚趾始终保持Z=0）。用 `CTRL_Avatar_Knee.` 调整膝盖朝向。
一条腿搭在另一条腿上	仅抬起的腿切换为FK；着地的腿保持IK。
双脚离地（池塘边、剧院座位、高凳）	双腿都用FK。

python

setprop('CTRL_Avatar_UpperBody', 'FK > IK Leg L', 0.0)   # 仅用于离开地面的腿
setprop('CTRL_Avatar_UpperBody', 'FK > IK Leg R', 0.0)

...then pose CTRL_FK_Avatar_UpLeg / _Leg / _Foot / _ToeBase on that side

...然后在该侧调整 CTRL_FK_Avatar_UpLeg / _Leg / _Foot / _ToeBase


Whatever the mode, check the feet: world Z of `Avatar_LeftToeBase` / `Avatar_RightToeBase` must stay **≥ 0** or the avatar sinks through the floor.


无论哪种模式，都要检查脚部：`Avatar_LeftToeBase` / `Avatar_RightToeBase` 的世界Z坐标必须**≥ 0**，否则Avatar会穿进地面。

RULE: Verify with numbers as well as renders

规则：既要用渲染验证，也要用数值验证

Renders catch composition; numbers catch clipping. Print world positions of hands, head, feet and any prop reference at every keyframe:

Keep hands ≥ ~0.3 m from the head centre when a limb passes the head. A throw over the shoulder clipped straight through the skull until the arm was routed outward first.
Keep hands ≥ ~0.10 m apart rather than overlapping at the centre line.
Keep the face visible in any default/holding pose — hold objects at upper-chest height with the head tilted down, not in front of the face.

Render four angles per keyframe (front three-quarter, straight front, side, top) with Workbench and tile them into one contact sheet. Iterate in a cheap pose-only stage first (seconds per run), and only then do the full build with exports.

渲染能检查构图；数值能检查穿模。在每个关键帧打印手、头、脚和任何道具参考点的世界坐标：

当肢体经过头部时，手与头部中心的距离保持**≥ ~0.3米**。有一个过肩投掷的动画曾直接穿过头骨，直到先把手臂向外调整才解决。
双手之间的距离保持**≥ ~0.10米**，不要在中心线处重叠。
在任何默认/持物姿势下，面部要可见——将物体举到上胸高度，头部微微低下，不要挡在脸前面。

为每个关键帧渲染四个角度（前四分之三视角、正前方、侧面、顶部），使用Workbench渲染器，并将它们拼成一张联系表。先在低成本的仅姿态阶段迭代（每次运行只需几秒），然后再进行完整的导出构建。

RULE: Stay inside the animation area

规则：待在动画区域内

Measured on the reference objects in

Avatar_File.blend

(world metres, Blender Z-up):

Reference object	Extent	Meaning
`Animation_Area_Reference`	4 × 4 × 4 m box — X, Y ∈ [−2, 2], Z ∈ [0, 4]	Everything stays inside for the whole clip: every body part, prop and particle. Nothing moves more than 4 m in any direction.
`Root_Animation_Area`	2 m diameter cylinder on the origin	The avatar root / centre of gravity ( `CTRL_Avatar_UpperBody` , i.e. `Avatar_Hips` ) travels at most 1 m forward, back, left or right — 2 m across. Vertically it may rise as far as the box allows (the docs say 4 m; the cylinder mesh in the file is 3 m tall).
`Ground_Reference`	plane at Z = 0	Nothing below it.

Legs, arms, head and props may leave the root cylinder — a kick or a cartwheel does — as long as they stay inside the box. Add the checks to the per-keyframe report:

|hips.x| ≤ 1

|hips.y| ≤ 1

, every deform bone head and tail inside the box, every toe Z ≥ 0 (

in_area()

{baseDir}/references/blender-emote-patterns.md

). The Decentraland Tools add-on's Validate Emote only warns when

CTRL_Avatar_UpperBody

moves more than 1 m horizontally or vertically from its first frame; it does not check the box, so the

in_area()

check is yours to run.

根据

Avatar_File.blend

中的参考对象测量（世界米，Blender Z轴向上）：

参考对象	范围	含义
`Animation_Area_Reference`	4 × 4 × 4 米的立方体——X、Y ∈ [−2, 2]，Z ∈ [0, 4]	所有内容在整个动画片段中都要待在里面：每个身体部位、道具、粒子。任何物体在任何方向上的移动都不能超过4米。
`Root_Animation_Area`	原点处直径2米的圆柱体	Avatar根节点/重心（ `CTRL_Avatar_UpperBody` ，即 `Avatar_Hips` ）向前、后、左、右的移动最多1米——总跨度2米。垂直方向可以上升到立方体允许的高度（文档说是4米；文件中的圆柱体网格高3米）。
`Ground_Reference`	Z=0的平面	任何物体不能低于它。

腿、手臂、头和道具可以离开根圆柱体——比如踢腿或侧手翻——只要它们待在立方体内。将这些检查添加到每个关键帧的报告中：

|hips.x| ≤ 1

、

|hips.y| ≤ 1

、所有变形骨骼的头部和尾部都在立方体内、所有脚趾Z ≥ 0（

{baseDir}/references/blender-emote-patterns.md

中的

in_area()

）。Decentraland Tools插件的Validate Emote 仅在

CTRL_Avatar_UpperBody

水平或垂直移动超过1米时发出警告；它不会检查立方体边界，因此

in_area()

检查需要你自己运行。

RULE: Loops must close; one-shots must land where the scene resumes

规则：循环动画必须闭合；一次性动画必须落在场景恢复的位置

Looping clip: make the first and last keyframes identical (e.g. frame 1 and frame 121 for a 4 s loop) or the loop pops.
One-shot clip: start and end in the resting pose the scene returns to — for a seated game, the seated holding pose; otherwise
```
Starting_Pose
```
.

循环动画片段：让第一帧和最后一帧完全相同（例如，4秒循环的第1帧和第121帧），否则循环会跳变。
一次性动画片段：开始和结束都要在场景返回的静止姿势——对于坐姿游戏，就是坐姿持物姿势；否则是
```
Starting_Pose
```
。

RULE: Export one clip per file, armature only

规则：每个文件导出一个动画片段，仅导出骨架

Delete every other object first — meshes,

WGT_*

widgets, reference planes,

Armature_Prop

, cameras, lights — and remove the

Starting_Pose

action, or the exporter emits two clips.

export_animation_mode='ACTIVE_ACTIONS'

is what guarantees exactly one animation per file. Full export call in

{baseDir}/references/blender-emote-patterns.md

Save an editable

.blend

(meshes included) before stripping, so the user can tweak the actions by hand afterwards.

先删除所有其他对象——网格、

WGT_*

控件、参考平面、

Armature_Prop

、相机、灯光——并移除

Starting_Pose

动作，否则导出器会输出两个片段。

export_animation_mode='ACTIVE_ACTIONS'

可以保证每个文件恰好有一个动画。完整导出调用见

{baseDir}/references/blender-emote-patterns.md

。

在删除对象之前先保存可编辑的

.blend

文件（包含网格），这样用户之后可以手动调整动作。

RULE: Verify the exported GLB before handing it over

规则：交付前验证导出的GLB文件

Parse the GLB's JSON chunk and assert: 1 animation, 0 meshes, 63 nodes (

Armature

+ 62 deform bones), 1 skin, 62 channels each for translation/rotation/scale, and

duration == (last_frame − first_frame) / 30

. Verifier script in

{baseDir}/references/blender-emote-patterns.md

. A duration mismatch means the scene FPS wasn't 30.

Typical size for a 1–4 s clip at

export_frame_step=1

is 70–110 KB — far under the 3 MB cap, so there is normally no reason to raise the sampling step.

解析GLB的JSON块并断言：1个动画、0个网格、63个节点（

Armature

+ 62个变形骨骼）、1个蒙皮、各62个位置/旋转/缩放通道，且

duration == (last_frame − first_frame) / 30

。验证脚本见

{baseDir}/references/blender-emote-patterns.md

。时长不匹配意味着场景帧率不是30。

1-4秒的片段在

export_frame_step=1

时的典型大小是 70-110 KB——远低于3 MB的上限，因此通常没有理由提高采样步长。

Upper-body (masked) animations

上半身（遮罩）动画

A masked emote is not a different file format — the same

.glb

is played with

mask: AvatarMask.AM_UPPER_BODY

at trigger time (API and enum details: player-avatar → "Emote masks"). What changes is what you should author.

Which bones the mask keeps — verified against the Explorer's

UpperBodyAvatarMask.mask

asset:

Animated:
```
Avatar_Spine
```
,
```
_Spine1
```
,
```
_Spine2
```
, both shoulders/arms/forearms/hands, all 40 finger bones,
```
Avatar_Neck
```
,
```
Avatar_Head
```
.
Ignored:
```
Avatar_Hips
```
and both legs (
```
UpLeg
```
/
```
Leg
```
/
```
Foot
```
/
```
ToeBase
```
) — these keep whatever the locomotion state or another emote is doing that frame.

Mechanically the renderer samples your clip each

LateUpdate

, then restores the non-masked bones' local position and rotation from the pose the Animator had already produced (

MaskedLegacyEmoteBlender

). So:

Hip/root motion in a masked clip has no effect.
```
Avatar_Hips
```
is outside the mask, so the drop you authored with
```
CTRL_Avatar_UpperBody
```
to sit the avatar down is discarded; the legs show the locomotion state (idle, walk, run).
A masked clip does NOT layer over another emote. Verified in the Explorer's
```
SceneMaskedEmoteSystem
```
: starting a masked emote on the local player stops any full-body emote that is playing, and starting a full-body emote cancels the masked one. So a masked clip cannot run on top of a chair's sitting emote — the avatar stands up. It layers only over locomotion, which is what the mask is for: carrying, holding or cheering while the player walks, runs or idles.
For a seated player, play the clip full body. Author a seated lower body into every clip (hips lowered, FK legs bent), trigger it unmasked, and have the scene replay the sitting emote (
```
triggerEmote({ predefinedEmote: 'sittingChair1' })
```
or the chair's own) when the clip ends and no looping seated clip takes over. A one-shot that returns to the same seated pose as your looping idle clip chains into it without a pop; the only visible pop is the height difference against the built-in sitting emote, which you tune with the hip drop.
Author the full body anyway, even for masked use. A plausible lower body makes the same file usable unmasked. The mask is a trigger-time decision, not a property of the file.
Masked emotes on the local player emit no
AvatarEmoteCommand
lifecycle events (documented in player-avatar). The scene must therefore time them itself — store each clip's duration alongside its path in scene config, since you know it exactly from the frame count.

Design notes for a seated holding pose that reads well: hips ≈ 0.6 m, hands at chest height, head tilted toward the hands.

The bone list and blending mechanism above were read from the Explorer source (
MaskedLegacyEmoteBlender
,
SceneMaskedEmoteSystem
,
CharacterEmoteSystem
on
main
, 2026-09); the "masked stops full-body" rule was confirmed in-world on a seated player. For the enum values and call signatures, trust player-avatar, which is verified against the shipped protocol.

遮罩表情不是不同的文件格式——同一个

.glb

文件在触发时使用

mask: AvatarMask.AM_UPPER_BODY

播放（API和枚举详情：player-avatar → "表情遮罩"）。改变的是你应该制作的内容。

遮罩保留哪些骨骼——已对照Explorer的

UpperBodyAvatarMask.mask

资源验证：

动画生效：
```
Avatar_Spine
```
、
```
_Spine1
```
、
```
_Spine2
```
、双肩/双臂/前臂/双手、全部40根手指骨骼、
```
Avatar_Neck
```
、
```
Avatar_Head
```
。
被忽略：
```
Avatar_Hips
```
和双腿（
```
UpLeg
```
/
```
Leg
```
/
```
Foot
```
/
```
ToeBase
```
）——这些会保持该帧的运动状态或另一个表情的动作。

从机制上讲，渲染器会在每次

LateUpdate

时采样你的动画片段，然后从Animator已经生成的姿势中恢复非遮罩骨骼的局部位置和旋转（

MaskedLegacyEmoteBlender

）。因此：

遮罩片段中的髋部/根节点运动无效。
```
Avatar_Hips
```
在遮罩之外，因此你用
```
CTRL_Avatar_UpperBody
```
制作的坐姿下沉会被丢弃；腿部会显示运动状态（空闲、行走、奔跑）。
遮罩片段不会叠加在另一个表情之上。 已在Explorer的
```
SceneMaskedEmoteSystem
```
中验证：在本地玩家上启动遮罩表情会停止正在播放的任何全身表情，而启动全身表情会取消遮罩表情。因此，遮罩片段不能在椅子的坐姿表情之上运行——Avatar会站起来。它只叠加在运动状态之上，这就是遮罩的用途：在玩家行走、奔跑或空闲时，进行携带、持物或欢呼。
对于坐姿玩家，要播放全身动画。 在每个片段中都制作坐姿下半身（髋部下沉、FK腿弯曲），不加遮罩触发，当片段结束且没有循环坐姿片段接替时，让场景重新播放坐姿表情（
```
triggerEmote({ predefinedEmote: 'sittingChair1' })
```
或椅子自己的表情）。如果一次性动画结束时回到与循环空闲片段相同的坐姿，就可以无缝衔接；唯一可见的跳变是与内置坐姿表情的高度差，你可以通过髋部下沉来调整。
即使是用于遮罩，也要制作全身动画。 合理的下半身可以让同一个文件在不加遮罩时也能使用。遮罩是触发时的决定，不是文件的属性。
本地玩家的遮罩表情不会发出
AvatarEmoteCommand
生命周期事件（已在 player-avatar 中记录）。因此场景必须自己计时——将每个片段的时长与其路径一起存储在场景配置中，因为你可以从帧数中准确得知时长。

坐姿持物姿势的设计建议，效果较好的是：髋部≈0.6米，手在胸部高度，头部向手的方向倾斜。

上述骨骼列表和混合机制来自Explorer源码（
main
分支，2026-09，
MaskedLegacyEmoteBlender
、
SceneMaskedEmoteSystem
、
CharacterEmoteSystem
）；"遮罩会停止全身表情"的规则已在坐姿玩家的游戏内验证。对于枚举值和调用签名，请以 player-avatar 为准，该部分已对照发布的协议验证。

File requirements

文件要求

Requirement	Value	Source
Frame rate	30 fps (Blender defaults to 24)	docs
Max length	10 s / 300 frames	docs
Format	`.glb`	docs
Max file size	3 MB	docs
Sampling rate	`1` by default; `2` or `3` to shrink	docs
Animation clips per file	exactly 1 (Emotes 2.0 may add 1 prop clip; sequences unsupported)	docs
File contents	deforming skeleton + animation only — no mesh, no control bones, no cameras/lights	docs
Start / end pose	both from the idle ( `Starting_Pose` )	docs
Deform-bone keys	location + rotation + scale on the first and last frame, every bone	docs
Animation area	root ≤ 1 m in each horizontal direction (2 m across); every mesh part and prop inside the 4 × 4 × 4 m `Animation_Area_Reference` box (see RULE above)	docs + measured
Filename	must end `_emote.glb` (case-insensitive)	player-avatar
Scene permission	`ALLOW_TO_TRIGGER_AVATAR_EMOTE` in `scene.json` `requiredPermissions`	player-avatar

Conventional location in the scene:

assets/animations/

. The glTF animation's name is irrelevant to the runtime — the file path is the identifier.

Blender's glTF exporter UI equivalents, if the user is exporting by hand: Include > Limit to > Visible Objects, Data > Armature > Export Deformation Bones Only, Animation > Sampling Animations.

The Decentraland Tools add-on's Validate Emote operator checks most of this (30 fps, ≤ 300 frames, exactly one armature action, first/last-frame keys on deform channels) before it will export, and warns — without blocking — when the COG moves more than 1 m horizontally or vertically. It does not check the 4 m bounding box.

要求	数值	来源
帧率	30 fps（Blender默认为24）	文档
最大长度	10秒 / 300帧	文档
格式	`.glb`	文档
最大文件大小	3 MB	文档
采样率	默认 `1` ；可设为 `2` 或 `3` 以缩小文件	文档
每个文件的动画片段数	恰好1个（Emotes 2.0可能会添加1个道具片段；不支持序列）	文档
文件内容	仅变形骨架 + 动画——无网格、无控制骨骼、无相机/灯光	文档
开始/结束姿势	都来自空闲姿势（ `Starting_Pose` ）	文档
变形骨骼关键帧	在第一帧和最后一帧为所有骨骼设置位置+旋转+缩放关键帧	文档
动画区域	根节点每个水平方向移动≤1米（总跨度2米）；每个网格部件和道具都在 4 × 4 × 4 米的 `Animation_Area_Reference` 立方体内（参见上述规则）	文档 + 实测
文件名	必须以 `_emote.glb` 结尾（不区分大小写）	player-avatar
场景权限	`scene.json` 的 `requiredPermissions` 中添加 `ALLOW_TO_TRIGGER_AVATAR_EMOTE`	player-avatar

场景中的常规位置：

assets/animations/

。glTF动画的名称与运行时无关——文件路径才是标识符。

如果用户手动导出，Blender的glTF导出器UI对应选项：Include > Limit to > Visible Objects、Data > Armature > Export Deformation Bones Only、Animation > Sampling Animations。

Decentraland Tools插件的Validate Emote 操作符会在导出前检查大部分要求（30 fps、≤300帧、恰好一个骨架动作、变形通道的首末帧关键帧），并且在重心水平或垂直移动超过1米时发出警告（但不会阻止导出）。它不会检查4米边界框。

Testing in the scene

在场景中测试

The fastest harness is a row of clickable primitive cubes —

MeshRenderer

MeshCollider

pointerEventsSystem.onPointerDown

with a generous

maxDistance

so they stay clickable from a chair — one per clip, plus a Stop cube and a mask toggle cube:

typescript

pointerEventsSystem.onPointerDown(
	{ entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: label, maxDistance } },
	() => void triggerSceneEmote({ src, loop: false, mask: upperBody ? AvatarMask.AM_UPPER_BODY : undefined })
)

Gate the whole harness behind a config flag and remove it before publishing.

The Explorer MCP's
trigger_emote
only plays URN/base emotes, not scene files — it cannot test a

_emote.glb

. Use in-scene triggers (see unity-explorer-mcp for driving the client around them).

最快的测试工具是一排可点击的基础立方体——

MeshRenderer

MeshCollider

pointerEventsSystem.onPointerDown

，设置足够大的

maxDistance

这样坐在椅子上也能点击——每个片段对应一个立方体，再加上一个停止立方体和一个遮罩切换立方体：

typescript

pointerEventsSystem.onPointerDown(
	{ entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: label, maxDistance } },
	() => void triggerSceneEmote({ src, loop: false, mask: upperBody ? AvatarMask.AM_UPPER_BODY : undefined })
)

将整个测试工具放在配置开关后面，发布前移除。

Explorer MCP的
trigger_emote
仅播放URN/基础表情，不播放场景文件——它无法测试

_emote.glb

。使用场景内触发器（参见 unity-explorer-mcp 了解如何操控客户端访问这些触发器）。

Cross-references

交叉引用

player-avatar —
```
triggerSceneEmote
```
/
```
stopEmote
```
/
```
AvatarEmoteCommand
```
/
```
AvatarMask
```
, the
```
_emote.glb
```
rule, the permission, and freezing the player with
```
InputModifier
```
during a full-body emote.
add-3d-models →
```
references/blender-authoring.md
```
— how to drive Blender at all (headless CLI vs MCP), plus general model export rules.
animations-tweens — animations baked into props and models, and procedural
```
Tween
```
motion.
npcs — animating
```
AvatarShape
```
NPCs and GLB NPCs.
Official docs: creating emotes · rig features · avatar rig

player-avatar —
```
triggerSceneEmote
```
/
```
stopEmote
```
/
```
AvatarEmoteCommand
```
/
```
AvatarMask
```
、
```
_emote.glb
```
规则、权限，以及在全身表情期间用
```
InputModifier
```
冻结玩家。
add-3d-models →
```
references/blender-authoring.md
```
— 如何操作Blender（无头CLI vs MCP），以及通用模型导出规则。
animations-tweens — 烘焙到道具和模型中的动画，以及程序化
```
Tween
```
运动。
npcs — 为
```
AvatarShape
```
NPC和GLB NPC添加动画。
官方文档：创建表情 · 绑定功能 · Avatar绑定