MCreator 物品触发器详解:When finish using(完成使用物品时)过程的触发机制与实战配置

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

MCreator 物品触发器详解:When finish using(完成使用物品时)过程的触发机制与实战配置

导读

本文围绕 MCreator 物品定义中的 "When finish using"(玩家完成使用物品时) 过程触发器展开,说明其触发时机、前置条件、可用依赖变量、典型应用场景,并结合仓库源码(ItemGUI.java 与各生成器模板)讲解其在生成的 Minecraft Java 版代码中的底层实现原理。读完本文,你将掌握如何在 MCreator 中正确配置该触发器,并清楚它与"每刻使用中""停止使用"等相邻触发器的区别与配合方式。

一、触发器概述:何为"完成使用物品"

在 MCreator 的物品编辑界面中,"When finish using"(对应源码 onFinishUsingItem,中文界面文案为"玩家完成使用物品时",见 texts_zh_CN.properties 中的 elementgui.item.player_useitem_finish)是物品"使用事件"一族中的核心触发器之一。

根据该帮助文档(德文原版、默认英文版)的定义:

该过程在物品被右键点击并持续按住、直到用满整个物品使用时长(use duration)之后被调用。例如,吃完一个食物物品之后就会执行该过程。

通俗地说,凡是"长按右键蓄力/进食,直到进度条走完"这类交互,在动作完成的那一刻都会触发此过程。它是"使用完整结束"的标志性事件。

触发时机与使用流程的关系

一次完整的物品使用生命周期在 MCreator 中被拆分为多个可编程事件,When finish using 位于流程末端:

  1. 右键点击物品 → 触发 When right clicked(when_right_clicked.md)等事件,同时物品进入"使用中"状态;
  2. 使用进行中 → 每 tick(游戏刻,1/20 秒)触发 Every tick while using(every_tick_while_using.md);
  3. 使用时长用尽 → 触发 When finish using(本文主题),物品使用完成;
  4. 若中途松开右键提前打断 → 触发 When stopped using(when_stopped_using.md),而非"完成使用"。

二、前置条件:use duration 必须大于 0

原文档明确强调了一条关键限制:

该触发器仅在物品使用时长(use duration)大于 0 时才起作用。

use duration 即物品编辑界面中的"使用时长"参数(use_duration.md),它决定物品"一次使用"能持续多久:

  • 食物类物品:该数值定义了玩家吃完一个食物所需的 tick 数(默认值为 32 tick,约 1.6 秒,见 ItemGUI.java 中对食物默认使用时长的设置);
  • 远程/蓄力类物品:该数值决定长按右键的最大蓄力时间,开启远程武器(enable ranged item)时默认被置为 72000 tick(ItemGUI.java),即 Minecraft 中"无限蓄力"的惯用上限值;
  • 若 use duration 为 0,物品"使用中"状态不会成立,When finish using、Every tick while using、When stopped using 等依赖使用时长的触发器均不会生效。

在源码层面,这一约束在编辑器 UI 中也有体现:useDuration.addChangeListener(_ -> onStoppedUsing.setEnabled((int) useDuration.getValue() > 0))(ItemGUI.java),即当使用时长 ≤ 0 时,相关使用事件选择器会被禁用,防止配置出无效过程。

三、可用依赖变量(Dependencies)

在 MCreator 过程编辑器中配置 When finish using 时,可以引用以下依赖变量(见 ItemGUI.java 中 ProcedureSelector 的 Dependency.fromString 定义):

变量 类型 含义
x / y / z number 使用物品时实体所在位置的坐标
world world 使用物品时所在的游戏世界
entity entity 使用物品的实体(通常为玩家)
itemstack itemstack 被使用的物品堆栈

一个典型的过程代码骨架如下(示意):

// 生成代码中该过程回调的依赖注入示意
double x = entity.getX();
double y = entity.getY();
double z = entity.getZ();
Level world = world;
Entity entity = entity;
ItemStack itemstack = usedItemstack;

注意:与 When stopped using、Every tick while using 不同,When finish using 不提供 time:number 依赖(已使用时长),因为触发时使用已完整结束。

四、典型应用场景

结合原文档给出的"吃完食物"示例以及 MCreator 的实际玩法,该触发器适合以下场景:

  • 食物吃完后的后置效果:例如吃下某种"魔法果实"后执行过程——给予玩家状态效果、补充体力、触发区域事件等;
  • 蓄力/充能武器蓄满后的发射逻辑:长按右键蓄力满后自动触发远程攻击、召唤实体或投掷物;
  • 使用完成的结算逻辑:记录使用次数、修改计分板、播放音效粒子、掉落副产品等。

与"使用结果物品"(eat result item)的配合

对食物类物品,MCreator 还提供"使用结果物品"(eatResultItem)配置。从生成模板可以看出,When finish using 过程与食用结果物品的返还逻辑会在同一个重写方法中协同执行(详见下一节),因此你可以在该触发器中读取"食用前的物品堆栈"副本并据此编写逻辑。

五、源码级原理:finishUsingItem 重写与生成逻辑

要理解该触发器为何"在使用完整结束后调用",需要查看 MCreator 为生成物品 Java 代码所用的 FreeMarker 模板。两个生成器版本均有对应实现:

1.21.1 NeoForge 生成器

plugins/generator-1.21.1/neoforge-1.21.1/templates/item/item.java.ftl 中,当存在 data.onFinishUsingItem 过程或使用结果物品时,模板会重写 Minecraft 的 finishUsingItem 方法:

@Override public ItemStack finishUsingItem(ItemStack itemstack, Level world, LivingEntity entity) {
    ItemStack usedItemstack = itemstack.copy();   // 先拷贝"使用前"的物品堆栈供过程使用
    ItemStack retval = /* 若配置了 eat result item,此处构造结果物品 */;
    super.finishUsingItem(itemstack, world, entity);   // 调用原版逻辑(如食物的饥饿值恢复)

    // 注入 When finish using 过程代码,注入依赖:
    // x=entity.getX(), y=entity.getY(), z=entity.getZ(),
    // world=world, entity=entity, itemstack=usedItemstack
    // ...
    if (itemstack.isEmpty()) {
        return retval;   // 食物被吃完,返回结果物品
    } else {
        // 未吃完(如创造模式)时尝试放入玩家背包,失败则掉落
        return itemstack;
    }
}

这里有两个值得注意的实现细节:

  • 模板在调用 super.finishUsingItem(...) 之前就拷贝了物品堆栈(itemstack.copy()),并把这份副本注入给过程代码,保证过程中对物品的修改不会破坏原版进食结算;
  • 过程中使用的是 entity.getX()/getY()/getZ() 实时坐标,因此即使实体在使用期间移动,坐标依赖仍保持正确。

26.3.x NeoForge 生成器

plugins/generator-26.3.x/neoforge-26.3/templates/item/item.java.ftl 中实现思路一致,仅在结果物品处理上更简洁:

@Override public ItemStack finishUsingItem(ItemStack itemstack, Level world, LivingEntity entity) {
    ItemStack usedItemstack = itemstack.copy();
    ItemStack retval = super.finishUsingItem(itemstack, world, entity);
    // 注入 When finish using 过程代码(依赖同上)
    return retval;
}

两个版本的共同结论:该触发器最终映射到 Minecraft 原生的 Item#finishUsingItem 回调,只有当物品的 getUseDuration() 为正、且玩家确实把使用进度条用满时,游戏才会调用此方法——这与帮助文档"仅在使用时长大于 0 时有效"的说明在机制层面完全吻合。

相邻触发器的底层映射(便于对比)

  • Every tick while using:模板中映射为物品使用中的逐 tick 回调(见 item.java.ftl,且当远程物品配置 shoot constantly 时也会用到);
  • When stopped using:映射为物品被提前释放(松开右键)的回调(item.java.ftl)。

六、实战配置步骤

  1. 在 MCreator 中新建或打开一个物品元素,进入"物品"标签页的"使用事件"(Use events)分组;
  2. 确认 Use duration(使用时长) 大于 0——若你的物品是食物,MCreator 会自动设为 32 tick;若是远程物品则会设为 72000 tick,无需手动调整;
  3. 点击 "玩家完成使用物品时"(When finish using)过程选择器,新建或选择一个已存在的过程;
  4. 在过程编辑器中按需引用 x、y、z、world、entity、itemstack 依赖编写逻辑;
  5. 保存并重新生成工作区代码,即可在游戏中验证:长按右键直至使用进度条走完,触发过程。

验证小技巧:可在过程中放置 console_log(日志输出)步骤配合游戏控制台观察触发时机;同时留意与 When stopped using 的区别——中途松开右键只会触发后者,不会触发 When finish using。

七、小结

When finish using 是 MCreator 物品"使用完成"阶段的标志性触发器,其生效以使用时长大于 0 为前提,语义为"完整用满使用时长后执行"。通过源码可见,它在生成的 Java 代码中对应 Item#finishUsingItem 重写,且在过程执行前会拷贝物品堆栈副本以保证逻辑安全。将它与 when_right_clicked.md、every_tick_while_using.md、when_stopped_using.md 组合使用,即可完整覆盖"右键点击 → 使用中 → 完成/打断"的全流程,实现食物效果、蓄力武器、使用结算等丰富玩法。

登录后查看全文
MCreator