手部条件动画

条件动画是一系列通过特殊命名规则定义的动画，仅在满足特定条件时触发播放。借助这种设计，开发者无需深入理解动画控制器机制，即可快速实现所需的交互效果。

手部条件动画机制

由于手部动画体系较为复杂，我们将其独立为单独的配置文件进行管理。

默认模型的手部条件动画均存储于 arm.animation.json 文件中，会在玩家手持对应物品并执行相关操作时自动播放。

该类动画优先级高于主动画，会覆盖主动画中与手部相关的动画组，因此禁止在手部动画中添加非手部相关的动画组。

若未配置特定手部动画，游戏将调用默认的 use_mainhand use_offhand swing_hand 等基础动画。

原版机制知识补充

以下为 Minecraft 原版机制的关键概念说明：

• 主手（mainhand）：默认为右手，对应玩家主要操作的交互手（如攻击、使用物品）。
• 副手（offhand）：默认为左手，通常用于持有盾牌、副手物品等。
• 使用（use）：玩家手持物品时按下右键触发的操作（如进食、饮用药水、使用弓箭/盾牌等）。
• 挥动（swing）：玩家点击鼠标左键触发的动作，默认仅主手可触发（如攻击、投掷物品）。
• 持有（hold）：玩家手持物品且未执行任何操作时的状态（如待机时的武器握持姿势）。
• 标签系统（Tag）：用于归类同类物品（如所有剑类物品），具体标签可参考 Minecraft 标签维基。
• 物品 ID 查询：按下 F3 + H 可显示物品 ID（示例如下）：
  

使用动画（Use Animations）

使用动画包含10 个内置分类，兼容大多数模组场景，具体规则如下：

动画名称	触发场景	时长说明
use_mainhand:eat use_offhand:eat	食用食物时播放	约 1.5 秒
use_mainhand:drink use_offhand:drink	饮用药水、牛奶桶时播放	约 1.5 秒
use_mainhand:shield use_offhand:shield	举盾防御时播放	动态触发，持续至松手
use_mainhand:block use_offhand:block	处于防御状态（如持盾）时播放	持续防御期间循环播放
use_mainhand:bow use_offhand:bow	拉弓瞄准期间播放	建议 ≥60 秒或静态动画
use_mainhand:spear use_offhand:spear	握持三叉戟时播放	建议 ≥60 秒或静态动画
use_mainhand:crossbow use_offhand:crossbow	装填/使用十字弓时播放	建议 ≥60 秒或静态动画
use_mainhand:spyglass use_offhand:spyglass	使用望远镜时播放	建议 ≥60 秒或静态动画
use_mainhand:toot_horn use_offhand:toot_horn	吹奏山羊角时播放	建议 ≥60 秒或静态动画
use_mainhand:brush use_offhand:brush	使用刷子（考古）时播放	动态触发，持续操作中

自定义使用动画规则

支持通过物品 ID或标签扩展自定义动画，示例如下：

动画名称	触发条件	命名规则
use_mainhand$minecraft:shield use_offhand$minecraft:shield	手持盾牌（ID 匹配）时使用	$ 后跟物品 ID
use_mainhand#minecraft:dirt use_offhand#minecraft:dirt	手持泥土类物品（标签匹配）时使用	# 后跟物品标签

挥动动画（Swing Animations）

主手挥动动画以 swing 开头，副手挥动动画以 swing_offhand 开头，支持通过物品 ID/标签扩展。

特殊机制：动画一旦触发，将播放至结束，无法中途中断。

内置挥动动画分类

动画名称	触发场景
swing:sword swing_offhand:sword	挥动剑类武器时播放
swing:axe swing_offhand:axe	挥动斧类工具时播放
swing:pickaxe swing_offhand:pickaxe	挥动镐类工具时播放
swing:shovel swing_offhand:shovel	挥动铲类工具时播放
swing:hoe swing_offhand:hoe	挥动锄类工具时播放
swing:shield swing_offhand:shield	挥动盾牌（如攻击动作）时播放
swing:throwable_potion swing:throwable_potion	投掷药水时播放
swing:fishing_rod swing:fishing_rod	抛竿/收竿时播放 2.3.0 新增

自定义挥动动画示例

动画名称	触发条件	命名规则
swing$minecraft:shield	手持盾牌（ID 匹配）时左键挥动	$ 后跟物品 ID
swing#minecraft:dirt	手持泥土类物品（标签匹配）时挥动	# 后跟物品标签

持有动画（Hold Animations）

持有动画在玩家手持物品且未执行操作时播放，切换物品时动画将从头开始播放，建议使用较长时长的循环动画。

• 主手持有以 hold_mainhand 开头，副手持有以 hold_offhand 开头，可同时播放。
• 支持通过物品 ID/标签扩展，特殊物品（如充能十字弓）需使用固定命名。

内置持有动画分类

动画名称	触发场景
hold_mainhand:empty hold_offhand:empty	空手时播放
hold_mainhand:charged_crossbow hold_offhand:charged_crossbow	手持充能十字弓时播放
hold_mainhand:crossbow hold_offhand:crossbow	手持未充能十字弓时播放
hold_mainhand:fishing_rod hold_offhand:fishing_rod	手持钓鱼竿（未抛竿）时播放 2.3.0 新增
hold_mainhand:fishing	手持已抛竿的钓鱼竿时播放（唯一特殊命名）
hold_mainhand:slashblade hold_offhand:slashblade	持有拔刀剑时播放 2.3.0 新增
hold_mainhand:sword hold_offhand:sword	持剑待机时播放
hold_mainhand:axe hold_offhand:axe	持斧待机时播放
hold_mainhand:shield hold_offhand:shield	持盾待机时播放
hold_mainhand:throwable_potion hold_offhand:throwable_potion	持有投掷药水时播放
hold_mainhand:eat hold_offhand:eat	持有食物时播放
hold_mainhand:drink hold_offhand:drink	持有药水/牛奶桶时播放

自定义持有动画示例

动画名称	触发条件	命名规则
hold_mainhand$minecraft:shield hold_offhand$minecraft:shield	持盾待机时播放	$ 后跟物品 ID
hold_mainhand#minecraft:dirt hold_offhand#minecraft:dirt	手持泥土、草方块类物品（标签匹配）时待机	# 后跟物品标签