模型篇
模型状态动画名称
各类模型的状态动画名称与触发条件
生物状态动画名
生物会在以下状态时播放对应动画，优先级从高到低排列。如果动画文件中不存在对应名称的动画，则跳过该状态，继续检查下一个。
| 动画名 | 触发条件 | 说明 |
|---|---|---|
die | 实体死亡时 | 播放后定格在最后一帧，实体延迟 5 秒后从世界移除 |
swim | 实体在水中时 | |
fly | 实体在鞘翅滑翔时 | |
jump | 实体跳跃时 | 仅对玩家类型实体生效 |
attack | 实体挥动手臂时 | |
damage | 实体受到伤害时 | |
run | 实体移动中且正在冲刺 | 非潜行状态 |
sneak_walk | 实体潜行并移动时 | |
walk | 实体行走时 | 非潜行状态 |
sneak | 实体潜行静止时 | |
idle | 兜底状态 | 始终满足条件，循环播放 |
服务端可通过 AnimationCommand 下发动画指令，其优先级高于上述所有状态。命令动画支持设置持续时间，过期后自动回退到状态动画。
玩家状态动画名
对于玩家，状态机支持自定义。若未设置自定义状态机，则按以下默认逻辑播放动画。
默认状态下，玩家动作分为主轨道和副轨道两个轨道并行处理，主轨道控制身体姿态，副轨道控制手部动作，两个轨道的动画会混合叠加。
主轨道
控制玩家的整体身体姿态。所有动画默认以循环方式播放，仅 die 为单次播放并定格在最后一帧。优先级从高到低：
| 动画名 | 触发条件 | 播放方式 | 过渡时间 |
|---|---|---|---|
die | 玩家死亡 | 单次定格 | 5 tick |
ride_pig | 骑乘猪 | 循环 | 5 tick |
ride_boat | 骑乘船 | 循环 | 5 tick |
ride | 骑乘任何载具（通用） | 循环 | 5 tick |
swim | 玩家正在游泳 | 循环 | 5 tick |
swim_stand | 玩家在水中但未游泳 | 循环 | 5 tick |
fly | 创造模式飞行 | 循环 | 5 tick |
fall_fly | 鞘翅飞行 | 循环 | 5 tick |
climb_walk | 爬行姿态且正在移动（不在水中） | 循环 | 5 tick |
climb | 爬行姿态（不在水中） | 循环 | 5 tick |
ladder_up | 在梯子上向上攀爬 | 循环 | 5 tick |
ladder_down | 在梯子上向下攀爬 | 循环 | 5 tick |
ladder_idle | 在梯子上静止 | 循环 | 5 tick |
jump | 跳跃中 | 循环 | 5 tick |
run | 移动中且冲刺（非潜行） | 循环 | 5 tick |
sneak_walk | 潜行并移动 | 循环 | 5 tick |
walk | 行走（非潜行） | 循环 | 5 tick |
sneak | 潜行静止 | 循环 | 5 tick |
idle | 兜底状态，始终满足 | 循环 | 5 tick |
die 动画播放后会定格在最后一帧，实体延迟 5 秒后从世界移除。首次进入某个状态时过渡时间为 0（立即切换），后续状态切换才使用表中的过渡时间。
副轨道
控制玩家的手部动作，与主轨道动画通过混合权重叠加播放。
副轨道的动画分为两种播放模式：
- 单次播放：动画播放一次后才允许切换到新状态，播放期间即使触发条件不再满足也不会中断。
- 连击序列：多个动画按顺序循环播放（如
sword_1→sword_2→sword_3→sword_1...），整个序列循环执行。
混合权重说明：
- 权重
1：副轨道动画以完整权重叠加到主轨道上。 - 权重
-1：副轨道动画以特殊混合方式叠加，通常用于单手动作，避免覆盖主轨道的身体姿态。
优先级从高到低：
| 动画名 | 触发条件 | 播放方式 | 过渡时间 | 权重 |
|---|---|---|---|---|
sword_1 / sword_2 / sword_3 | 挥动主手且持剑 | 连击序列循环 | 5 tick | 1 |
punch_1 / punch_2 | 挥动主手且空手 | 连击序列循环 | 5 tick | 1 |
break_right | 挥动主手（持其他物品） | 单次播放 | 5 tick | -1 |
break_left | 挥动副手 | 单次播放 | 5 tick | -1 |
bow_right | 主手使用弓 | 单次播放 | 3 tick | -1 |
bow_left | 副手使用弓 | 单次播放 | 3 tick | -1 |
crossbow_right | 主手装填弩 / 持已装填的弩 | 单次播放 | 3 / 5 tick | -1 |
crossbow_left | 副手装填弩 / 持已装填的弩 | 单次播放 | 3 / 5 tick | -1 |
trident_throw_right | 主手投掷三叉戟 | 单次播放 | 3 tick | -1 |
trident_throw_left | 副手投掷三叉戟 | 单次播放 | 3 tick | -1 |
shield_block_right | 主手盾牌格挡 | 单次播放 | 3 tick | -1 |
shield_block_left | 副手盾牌格挡 | 单次播放 | 3 tick | -1 |
eat_right | 主手吃/喝 | 单次播放 | 3 tick | -1 |
eat_left | 副手吃/喝 | 单次播放 | 3 tick | -1 |
spyglass_right | 主手使用望远镜 | 单次播放 | 3 tick | -1 |
spyglass_left | 副手使用望远镜 | 单次播放 | 3 tick | -1 |
toot_horn_right | 主手使用山羊号角 | 单次播放 | 3 tick | -1 |
toot_horn_left | 副手使用山羊号角 | 单次播放 | 3 tick | -1 |
brush_right | 主手使用刷子 | 单次播放 | 3 tick | -1 |
brush_left | 副手使用刷子 | 单次播放 | 3 tick | -1 |
use_right | 主手使用物品（通用兜底） | 单次播放 | 3 tick | -1 |
use_left | 副手使用物品（通用兜底） | 单次播放 | 3 tick | -1 |
empty | 无手部动作（兜底） | 循环 | 500 tick | 1 |
- 带有
_right/_left后缀的动画分别对应主手和副手操作。如果模型中未定义对应动画，则跳过该状态。 crossbow_right/crossbow_left在装填中过渡时间为 3 tick，持握已装填弩时为 5 tick。empty的 500 tick 超长过渡时间用于从手部动作平滑回到无动作状态。- 当服务端下发 AnimationCommand 时，副轨道会进入等待状态，将控制权交给主轨道。
第一人称物品动画名
用于第一人称视角下手持物品的动画，类似 FPS 游戏的武器动画系统。物品切换时会自动执行收起/拔出流程。
切换流程
- 切换物品时，当前物品播放
holster（收起）动画 - 收起完成后切换模型
- 新物品播放
draw（拔出）动画 - 拔出完成后进入默认状态循环
物品需要存在 draw 或 idle 动画之一，才会被识别为有效的第一人称物品模型。
动画名称
| 动画名 | 触发条件 | 播放方式 |
|---|---|---|
holster | 切换物品时收起当前物品 | 播放一次 |
draw | 切换物品时拔出新物品 | 播放一次 |
sword_1 / sword_2 / sword_3 | 主手挥剑 | 连击序列，按 1→2→3 循环 |
run | 移动中且冲刺（非潜行） | 循环 |
walk | 行走（非潜行） | 循环 |
idle | 兜底状态 | 循环 |
盔甲架状态动画名
盔甲架模型支持服务端下发的动画指令和默认待机动画。
| 动画名 | 触发条件 |
|---|---|
| 服务端指令动画 | 通过 AnimationCommand 下发，优先级最高 |
idle | 默认待机，循环播放 |
方块状态动画名
方块模型支持服务端下发的动画指令、距离触发动画和默认待机动画。优先级从高到低：
| 动画名 | 触发条件 |
|---|---|
closeTo_in | 玩家进入方块设定距离范围时的过渡动画，播放一次 |
closeTo | 玩家在方块设定距离范围内时，循环播放 |
idle | 默认待机，循环播放 |
物品 / 展示物状态动画名
物品模型和展示物模型仅支持默认待机动画。
| 动画名 | 触发条件 |
|---|---|
idle | 默认待机，循环播放 |