事件
Fabric API 提供的事件的使用指南。
WARNING
本页面适用于 26.2 版本。 针对旧版本的文档可能不完整。
Fabric API 提供了一个系统,允许模组对游戏中发生的行为或事(也被定义为 事件 (events) )做出反应。
事件是一种 Hook ,可满足常见的使用情况,并且增强和优化多个模组间对于同一代码区间的 Hook 的兼容性。使用事件往往就可以替代 mixin 的使用。
Fabric API 为 Minecraft 代码库中的重要区域提供事件,许多模组制作者可能有兴趣将其接入。
事件由 net.fabricmc.fabric.api.event.Event 实例表示,该实例存储并调用 回调(CallBack)。一个回调通常只有一个事件实例,存储在回调接口的静态字段 EVENT 中,但也有其他可能。例如,ClientTickEvents 会为多个相关连的事件分组。
回调
回调是作为参数传递给事件的一段代码。当游戏触发事件时,将执行所传递的代码。
回调接口
每个事件都有一个对应的回调接口。回调是通过在事件实例上调用 register() 方法注册的,其参数为一个回调接口的实例。
监听事件
这个例子注册一个 AttackBlockCallback,当玩家徒手击打不掉落物品的方块时,伤害玩家。
AttackBlockCallback.EVENT.register((player, level, hand, pos, direction) -> {
BlockState state = level.getBlockState(pos);
// Manual spectator check is necessary because AttackBlockCallbacks fire before the spectator check
if (!player.isSpectator() && player.getMainHandItem().isEmpty() && state.requiresCorrectToolForDrops() && level instanceof ServerLevel serverLevel) {
player.hurtServer(serverLevel, level.damageSources().generic(), 1.0F);
}
return InteractionResult.PASS;
});2
3
4
5
6
7
8
9
10
自定义事件
游戏中某些区域并没有 Fabric API 提供的事件,因此需要使用 mixin 或者创建自己的事件。
我们将创建一个在羊剪毛时触发的事件。创建事件的过程是:
- 创建事件回调接口
- 从 mixin 触发事件
- 创建测试实现
创建事件回调接口
事件回调接口描述了您监听的事件必须实现哪些功能,同时也描述了我们如何从 mixin 中调用这个事件。通常在回调接口中创建一个 Event 字段作为我们实际事件的唯一标识符。
对于我们 Event 的实现,我们选择用数组来存储他们。该数组将包含所有监听这个事件的监听器。
我们实现这个事件时,将依次调用这个数组中的所有监听器,直到某个监听器返回非 InteractionResult.PASS。这意味着一个监听器可以使用返回值表明“取消”、“批准”或者“无所谓,传递给下一个监听器处理”。
使用 InteractionResult 作为返回值是各个事件处理器之间的常规协作方式。
您将需要创建一个带有 Event 实例和响应实现方法的接口。一个典型的剪羊毛回调像是这样:
public interface SheepShearCallback {
Event<SheepShearCallback> EVENT = EventFactory.createArrayBacked(SheepShearCallback.class,
(listeners) -> (player, sheep) -> {
for (SheepShearCallback listener : listeners) {
InteractionResult result = listener.interact(player, sheep);
if (result != InteractionResult.PASS) {
return result;
}
}
return InteractionResult.PASS;
}
);
InteractionResult interact(Player player, Sheep sheep);
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
让我们更深入地看看。当 invoker 被调用时,我们将遍历所有监听器:
(listeners) -> (player, sheep) -> {
for (SheepShearCallback listener : listeners) {
// ...
}
}2
3
4
5
然后,我们在每个监听器上调用 interact 方法来获取监听器的响应。以下是我们在该接口中声明的 interact 的签名:
InteractionResult interact(Player player, Sheep sheep);如果监听器指示我们需要取消(返回 FAIL)或完全完成(返回 SUCCESS)事件,则回调返回结果并结束循环。
InteractionResult.PASS 会继续调用下一个监听器,直到所有监听器都被调用,并且最终返回 PASS:
if (result != InteractionResult.PASS) {
return result;
}
return InteractionResult.PASS;2
3
4
我们可以在回调类的顶部添加 Javadoc 注释注明每一种 InteractionResult 的作用。在本例中,它应该是这样的:
/**
* Callback for shearing a sheep.
* Called before the sheep is sheared, items are dropped, and items are damaged.
* Upon return:
* - SUCCESS cancels further processing and continues with normal shearing behavior.
* - PASS falls back to further processing and defaults to SUCCESS if no other listeners are available
* - FAIL cancels further processing and does not shear the sheep.
*/2
3
4
5
6
7
8
从 mixin 中触发事件
我们现在有基本的事件框架了,但还需要触发它。我们希望在玩家试图剪羊毛时调用事件,所以我们要在当 Sheep#mobInteract 中的shear() 被调用时去调用事件的 invoker(例如:羊可以被剪毛且玩家手持剪刀)
@Mixin(Sheep.class)
public class SheepMixin {
@Inject(at = @At(value = "INVOKE", target = "Lnet/minecraft/world/entity/animal/sheep/Sheep;shear(Lnet/minecraft/server/level/ServerLevel;Lnet/minecraft/sounds/SoundSource;Lnet/minecraft/world/item/ItemStack;)V"), method = "mobInteract", cancellable = true)
private void onShear(final Player player, final InteractionHand hand, final CallbackInfoReturnable<InteractionResult> info) {
InteractionResult result = SheepShearCallback.EVENT.invoker().interact(player, (Sheep) (Object) this);
if (result == InteractionResult.FAIL) {
info.setReturnValue(result);
}
}
}2
3
4
5
6
7
8
9
10
11
创建测试实现
现在我们需要测试一下我们的事件。你可以在初始化方法(如果需要,在其他区域也可以)中注册监听器,并在其中添加自定义逻辑。
这里有一个例子——羊的脚上掉落的不是羊毛,而是一颗钻石:
SheepShearCallback.EVENT.register((player, sheep) -> {
sheep.setSheared(true);
// Create diamond item entity at sheep's position.
ItemStack stack = new ItemStack(Items.DIAMOND);
ItemEntity itemEntity = new ItemEntity(player.level(), sheep.getX(), sheep.getY(), sheep.getZ(), stack);
player.level().addFreshEntity(itemEntity);
return InteractionResult.FAIL;
});2
3
4
5
6
7
8
9
10
如果你进入游戏并剪羊毛,掉落的应该是钻石而不是羊毛。












