MCreator 物品使用动画(Item Animation)配置全解:选项、联动行为与代码生成原理
MCreator 物品使用动画(Item Animation)配置全解:选项、联动行为与代码生成原理
当玩家手持自定义物品执行动作(如食用、饮用、拉弓瞄准)时,游戏会播放对应的第一人称动画。在 MCreator 中,这一行为由物品元素(Item)的 Animation(动画) 属性控制。本文基于 MCreator 官方帮助文档 plugins/mcreator-localization/help/default/item/animation.md(及其 中文版、德语版),结合仓库内物品元素源码、生成模板与版本转换器,完整说明该属性的全部可选值、界面配置位置、自动联动规则,以及它是如何被翻译成最终 Forge/NeoForge 模组代码的。读完本文,你将能在 MCreator 中准确配置物品动画,并理解“未指定动画时默认手臂摆动仍可能播放”这一行为背后的机制。
1. 什么是物品使用动画
根据官方帮助文档的定义:
Animation 是玩家使用该物品执行动作时所播放的动画。
例如:
- 设置为
eat的苹果类食物,玩家持有时会看到经典的“进食”动画; - 设置为
drink的药水,会呈现“饮用”动画; - 设置为
bow的弓箭类远程武器,长按时会出现拉弓蓄力动画; - 设置为
spyglass的望远镜,右击会呈现举镜观察动画。
该属性在数据层面对应物品元素(Item)中的 animation 字段。在 src/main/java/net/mcreator/element/types/Item.java 中可以看到其声明:
@NonNullMappable("eat") public ItemUseAnimation animation;
它由独立的数据类型 ItemUseAnimation 承载,该类继承自 MappableElement,通过 NameMapper 绑定到名为 itemuseanimations 的数据列表,也就是说所有可选值都来自该数据列表,而不是自由填写的字符串。
2. 可选动画值一览
可选值由核心插件的数据列表 plugins/mcreator-core/datalists/itemuseanimations.yaml 定义,共 12 项:
| 可选值 | 表现效果(对应原版物品) |
|---|---|
none |
不播放任何使用动画(默认值,普通物品) |
eat |
进食动画(食物、甜浆果等) |
drink |
饮用动画(药水、蜂蜜瓶等) |
block |
格挡动画(盾牌) |
bow |
拉弓蓄力动画(弓) |
trident |
投掷三叉戟的瞄准动画 |
crossbow |
弩的上弦/瞄准动画 |
spyglass |
望远镜举镜观察动画 |
toot_horn |
山羊角吹奏动画 |
brush |
刷子刷扫动画(1.20+) |
bundle |
收纳袋开合动画(1.20.5+) |
spear |
长矛投掷动画 |
值得注意的是,不同生成器(generator)版本实际支持的可映射值并不完全一致。例如在 NeoForge 1.21.1 生成器的映射表 plugins/generator-1.21.1/neoforge-1.21.1/mappings/itemuseanimations.yaml 中,trident 与 bundle 未出现;而对应更高版本 Minecraft(26.3.x 系列,即 Minecraft 1.21.5+)的 NeoForge 生成器映射表 plugins/generator-26.3.x/neoforge-26.3/mappings/itemuseanimations.yaml 则完整包含 trident、bundle 等全部值,且二者都提供了 _default: ...NONE 的默认兜底映射。因此,在低版本生成器中配置高版本专属动画值时,需要留意映射是否可用。
3. 在 MCreator 界面中的配置位置
该属性的配置入口位于物品元素的 “使用属性”(Use properties) 区域。在 src/main/java/net/mcreator/ui/modgui/ItemGUI.java 中,界面的构建代码如下:
JPanel itemUseSubpane = new JPanel(new GridLayout(2, 2, 2, 2));
ComponentUtils.makeSection(itemUseSubpane, L10N.t("elementgui.item.use_properties"));
itemUseSubpane.setEnabled(false);
itemUseSubpane.add(HelpUtils.wrapWithHelpButton(this.withEntry("item/animation"),
L10N.label("elementgui.item.item_animation")));
itemUseSubpane.add(animation);
itemUseSubpane.add(HelpUtils.wrapWithHelpButton(this.withEntry("item/use_duration"),
L10N.label("elementgui.item.use_duration")));
itemUseSubpane.add(useDuration);
其中 animation 是一个 DataListComboBox 下拉框,HelpUtils.wrapWithHelpButton(...) 会在其旁显示一个问号按钮,点击后即弹出本文所对应的帮助文档 item/animation.md。与其同行的 Use duration(使用时长) 字段(对应 Item.java 中的 useDuration,单位为游戏刻,默认 0)同样影响使用动画的表现:例如弓类武器的蓄力时间、食物的食用时长都依赖它。
操作步骤:新建或打开一个物品元素 → 切换到属性页中的使用相关区域 → 在 Animation 下拉框中选择所需动画 → 根据需要调整 Use duration。
4. 与食物、远程武器配置的自动联动
MCreator 会根据其他配置自动调整动画值,避免出现互相矛盾的设置。这一点在 ItemGUI.java 中体现得十分明确:
(1)勾选“食物”(Is food)时,自动将动画设为 eat、使用时长设为 32 刻:
isFood.addActionListener(_ -> {
updateFoodPanel();
if (!isEditingMode()) {
animation.setSelectedItem("eat");
useDuration.setValue(32);
}
});
(2)开启“远程武器”(Enable ranged)时,若当前动画为 none 则自动切换为 bow,并把使用时长设为 72000 刻(无限蓄力上限),渲染模型切换为远程物品模型:
if (!isEditingMode()) {
if ((int) useDuration.getValue() == 0)
useDuration.setValue(72000);
if (renderType.getSelectedItem() == normal)
renderType.setSelectedItem(rangedItem);
if ("none".equals(animation.getSelectedItem()))
animation.setSelectedItem("bow");
}
(3)关闭远程武器时,动画自动重置回 none:
animation.setSelectedItem("none");
这些联动保证:普通物品默认 none、食物默认 eat、远程武器默认 bow,与玩家的直觉一致。从源码结构看,它们只是界面层的自动默认值,用户仍可在下拉框中自由覆盖。
5. 生成代码:动画如何落到模组里
动画属性最终通过 FreeMarker 模板被写进生成的物品 Java 类中。不同 Minecraft 版本的生成器实现略有差异,这里对比两个典型实现。
5.1 NeoForge 1.21.1 生成器
在 plugins/generator-1.21.1/neoforge-1.21.1/templates/item/item.java.ftl 中:
<#if data.hasNonDefaultAnimation()>
@Override public UseAnim getUseAnimation(ItemStack itemstack) {
return ${data.animation};
}
</#if>
<#if !data.isFood && data.animation.getUnmappedValue() == "eat">
@Override public SoundEvent getEatingSound() {
return SoundEvents.EMPTY;
}
<#elseif !data.isFood && data.animation.getUnmappedValue() == "drink">
@Override public SoundEvent getDrinkingSound() {
return SoundEvents.EMPTY;
}
</#if>
这里的 hasNonDefaultAnimation() 判断定义在 Item.java:
public boolean hasNonDefaultAnimation() {
return isFood ? !animation.getUnmappedValue().equals("eat") : !animation.getUnmappedValue().equals("none");
}
也就是说:食物默认就是 eat,无需重写动画方法;非食物只有设置了非 none 的动画才生成 getUseAnimation 重写。同时,对于非食物却设置了 eat/drink 动画的情况,模板会额外静音进食/饮用音效(返回 SoundEvents.EMPTY),以避免非食物物品发出不协调的吃喝声音。
使用时长 getUseDuration 的生成条件也与之配套(item.java.ftl):
<#if (!data.isFood && data.useDuration != 0) || (data.isFood && data.useDuration != 32)>
@Override public int getUseDuration(ItemStack itemstack, LivingEntity livingEntity) {
return ${data.useDuration};
}
</#if>
即非食物且时长为 0(不设置使用)时不生成,食物的默认 32 刻也不生成,减少冗余代码。
5.2 NeoForge 26.3.x 生成器(更高版本)
在更新的生成器 plugins/generator-26.3.x/neoforge-26.3/templates/item/item.java.ftl 中,动画机制发生了两个明显变化:
变化一:枚举类型更名。 生成的返回类型由 UseAnim 改为 ItemUseAnimation:
<#if !data.isFood && data.animation.getUnmappedValue() != "none">
@Override public ItemUseAnimation getUseAnimation(ItemStack itemstack) {
return ${data.animation};
}
</#if>
这与该版本 NeoForge API 中 ItemUseAnimation 枚举的重命名一致。
变化二:食物动画改由 consumable 组件接管。 在 item.java.ftl 的食物属性构建中:
<#if data.hasCustomFoodConsumable()>,
<#if data.animation.getUnmappedValue() == "eat">
Consumables.defaultFood()
<#elseif data.animation.getUnmappedValue() == "drink">
Consumables.defaultDrink()
<#else>
Consumables.defaultFood().animation(${data.animation})
</#if>
...
<#elseif data.animation.getUnmappedValue() == "drink">,
Consumables.DEFAULT_DRINK
</#if>
可见在 Minecraft 1.21.5+ 中,食物的播放动画已内嵌进 Consumable 组件(defaultFood() 本身即携带吃动画),因此 getUseAnimation 只对非食物物品生效。这也是 Item.java 中 hasCustomFoodConsumable() 方法存在的原因——它判断食物是否使用了非默认(非 eat/drink 且时长非 32 刻)的自定义食用配置。
6. “默认手臂摆动动画”的机制说明
帮助文档中特别强调:
如果没有指定动画,无论物品的使用结果如何,都会播放默认的手臂摆动动画。
(对应英文原文 "Depending on the item use result, the default arm swing animation may still be played even if no animation is specified.")
这条规则包含两层含义:
- 未指定动画(
none)时,getUseAnimation返回UseAnim.NONE(参见映射表_default/none条目),物品本身不贡献特殊动画; - 但原版游戏的物品使用逻辑仍可能触发手臂摆动:当玩家持物执行右击等动作且动作“成功”(返回
SUCCESS/CONSUME结果)时,客户端会默认播放一次手臂挥动(arm swing)动画。因此即便你的自定义物品设置为none,只要它绑定了右击使用逻辑(例如 item.java.ftl 中生成的use()方法),玩家使用后仍可能看到一次摆动,这是原版引擎的兜底行为,并非 MCreator 的额外处理。
理解了这一点,就能解释为什么给普通物品配置“使用后执行程序”逻辑时,画面里总会出现一次手臂挥动——它是游戏对“物品被成功使用”的通用反馈。
7. 版本迁移与默认值保护
动画属性在历史元素类型迁移中也保持了一致性,这从仓库中的转换器可见一斑:
- 食物 → 物品(v2022_1):FoodToItemConverter.java 将旧食物元素的动画值原样带入新物品元素:
item.animation = new ItemUseAnimation(workspace, food.get("animation").getAsString()); - 远程武器 → 投射物 + 物品(v2023_4):RangedItemToProjectileAndItemConverter.java 迁移时保留原动画,缺失时以
bow兜底:if (rangedItem.get("animation") != null) item.animation = new ItemUseAnimation(workspace, rangedItem.get("animation").getAsString()); else item.animation = new ItemUseAnimation(workspace, "bow"); - 唱片 → 物品(v2024_4):MusicDiscToItemConverter.java 则直接指定
none,因为唱片本身没有使用动画。
同时,Item 的字段上标有 @NonNullMappable("eat")(Item.java),意味着该字段非空且默认值映射为 eat。由于 ItemUseAnimation 的映射列表在不同版本间会动态更新,读取旧工作区时该注解保证了字段总能取得一个合法值,不会因版本数据列表变化而出现空引用。
8. 实战建议
- 普通右击功能性物品:保持
none,但要注意第 6 节所述的手臂摆动兜底行为,必要时通过控制use()的返回值来避免动作“成功”; - 食物:保持默认的
eat+ 32 刻即可;若想自定义食用动画(例如饮料类食物),可改用drink或在高版本生成器中通过 consumable 组件指定其他动画; - 远程武器:开启 Enable ranged 后自动获得
bow,长按蓄力动画与 72000 刻的useDuration会协同工作; - 版本差异:跨版本升级工作区时,
trident、bundle等较新动画值在旧生成器中可能无法映射,迁移后应检查生成代码中的getUseAnimation/ItemUseAnimation返回值是否与目标版本 API 匹配。
总结
物品使用动画是 MCreator 物品元素中一个“小而关键”的属性:它由 itemuseanimations.yaml 数据列表驱动,在 ItemGUI 中通过带帮助按钮的下拉框配置,并由不同版本生成器模板翻译为 getUseAnimation 或 consumable 组件代码。理解其默认值(食物 eat、远程武器 bow、普通物品 none)、界面自动联动规则,以及“未指定动画时手臂摆动仍可能播放”的原版机制,能帮助你准确控制自定义物品的使用手感,避免动画与功能逻辑冲突。