События 26.1.2

Руководство по использование событий предоставляемых Fabric API.

Fabric API предоставляет систему, которая позволяет модам реагировать на действия или явления, так же известные как события, происходящие в игре.

События — это хуки, которые удовлетворяют общим сценариям использования и/или обеспечивают улучшенную совместимость и производительность между модами, которые подключаются к одним и тем же областям кода. Использование событий часто заменяет использование mixins.

API Fabric предоставляет события для важных областей кодовой базы 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;
});

Добавление предмета к существующим таблицам лута

Иногда вам может понадобиться добавить предметы в таблицы добычи. Например, добавляя свои капли в ванильный блок или сущность.

Самое простое решение — замена файла таблицы добычи — это может сломать другие моды. А что, если они захотят изменить и их? Мы рассмотрим, как можно добавлять предметы в таблицы добычи, не переопределяя таблицу.

Мы добавим особый элемент в таблицу лута угольной руды.

Прослушивание загрузки таблицы добычи

В API Fabric есть событие, которое запускается при загрузке таблиц добычи, LootTableEvents.MODIFY. Вы можете зарегистрировать обратный вызов для него в вашем инициализаторе мода. Давайте также проверим, что текущая таблица добычи — это таблица добычи угольной руды:

LootTableEvents.MODIFY.register((key, tableBuilder, source, registries) -> {
	// Let's only modify built-in loot tables and leave data pack loot tables untouched by checking the source.
	// We also check that the loot table ID is equal to the ID we want.
	if (source.isBuiltin() && COAL_ORE_LOOT_TABLE_ID.equals(key)) {
		// ...
	}
});

Добавление предметов в таблицу добычи

Чтобы добавить предмет, нам нужно добавить пул с записью предмета в таблицу добычи.

Мы можем создать пул с помощью LootPool#lootPool и добавить его в таблицу добычи.

В нашем пуле пока нет элементов, поэтому мы создадим запись элемента с помощью LootItem#lootTableItem и добавим ее в пул.

LootTableEvents.MODIFY.register((key, tableBuilder, source, registries) -> {
	// Let's only modify built-in loot tables and leave data pack loot tables untouched by checking the source.
	// We also check that the loot table ID is equal to the ID we want.
	if (source.isBuiltin() && COAL_ORE_LOOT_TABLE_ID.equals(key)) {
		// We make the pool and add an item
		LootPool.Builder poolBuilder = LootPool.lootPool().add(LootItem.lootTableItem(Items.EGG));
		tableBuilder.withPool(poolBuilder);
	}
});

Собственные события

В некоторых областях игры отсутствуют хуки, предоставляемые API Fabric, поэтому вы можете либо использовать mixin, либо создать собственное событие.

Мы рассмотрим создание события, которое запускается при стрижке овец. Процесс создания события:

• Создание интерфейса обратного вызова события
• Запуск события из mixin
• Создание тестовой реализации

Создание интерфейса обратного вызова

Интерфейс обратного вызова описывает, что должно быть реализовано слушателем событий, которые будут прослушивать ваше событие. Интерфейс обратного вызова также описывает, как событие будет вызываться из нашего mixin. Традиционно, объект Event помещают в качестве поля в интерфейс обратного вызова, который будет идентифицировать наше фактическое событие.

Для нашей реализации Event мы выберем использование события на основе массива. Массив будет содержать все слушатели событий, которые прослушивают событие.

Наша реализация будет вызывать слушатели событий по порядку до тех пор, пока один из них не вернет InteractionResult.PASS. Это означает, что слушатель событий может с помощью возвращаемого значения указать: «отменить это», «одобрить это» или «не важно, передать следующему слушателю событий».

Использование InteractionResult в качестве возвращаемого значения — это общепринятый способ заставить обработчики событий взаимодействовать таким образом.

Вам необходимо создать интерфейс, имеющий экземпляр «События» и метод для реализации ответа. Базовая настройка обратного вызова для стрижки овец выглядит следующим образом:

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);
}

Давайте рассмотрим это более подробно. При вызове мы перебираем всех слушателей:

(listeners) -> (player, sheep) -> {
	for (SheepShearCallback listener : listeners) {
		// ...
	}
}

Затем для каждого слушателя мы вызываем метод interact, чтобы получить его ответ. Вот сигнатура метода interact, который мы объявили в этом интерфейсе:

InteractionResult interact(Player player, Sheep sheep);

Если слушатель сообщает, что необходимо прервать операцию (возвращая FAIL) или полностью завершить её (SUCCESS), обратный вызов возвращает результат и завершает цикл.

InteractionResult.PASS переходит к следующему слушателю, пока не будут вызваны все слушатели и в конце концов не будет возвращено значение PASS:

	if (result != InteractionResult.PASS) {
		return result;
	}
return InteractionResult.PASS;

Мы можем добавить комментарии 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.
 */

Запуск события из Mixin'а

Теперь у нас есть базовый скелет события, но нам нужно его запустить. Поскольку мы хотим, чтобы событие вызывалось, когда игрок пытается постричь овцу, мы вызываем событие invoker в Sheep#mobInteract, когда вызывается shear() (т. е. овцу можно стричь, а игрок держит ножницы):

@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);
		}
	}
}

Создание тестовой имплементации

Теперь нам нужно протестировать наше событие. Вы можете зарегистрировать слушатель в своем методе инициализации (или в другой области, если вам так удобнее) и добавить туда пользовательскую логику.

Вот пример, в котором вместо шерсти к ногам овцы падает алмаз:

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;
});

Если вы зайдете в игру и пострижете овцу, вместо шерсти должен выпасть алмаз.