MCreator 物品使用动画(Item Animation)配置全解:选项、联动行为与代码生成原理

原创2026-10-16 13:32:342,166 阅读
文章标签:桌面应用游戏开发代码生成低代码开发工具模板引擎

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.")

这条规则包含两层含义:

  1. 未指定动画(none)时,getUseAnimation 返回 UseAnim.NONE(参见映射表 _default/none 条目),物品本身不贡献特殊动画;
  2. 但原版游戏的物品使用逻辑仍可能触发手臂摆动:当玩家持物执行右击等动作且动作“成功”(返回 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)、界面自动联动规则,以及“未指定动画时手臂摆动仍可能播放”的原版机制,能帮助你准确控制自定义物品的使用手感,避免动画与功能逻辑冲突。

登录后查看全文
MCreator