Події 26.1.2

Посібник того, як використовувати події, надані Fabric API.

API Fabric надає систему, яка дозволяє модам реагувати на дії або випадки, які також визначаються як події, що відбуваються в грі.

Події — це хуки, які задовольняють звичайні сценарії використання та/або забезпечують покращену сумісність і продуктивність між модами, які використовуються однакові області коду. Використання подій часто замінює використання міксинів.

API Fabric надає події для важливих областей у кодовій базі Minecraft, до яких можуть бути зацікавлені кілька хуків.

Події представлені екземплярами net.fabricmc.fabric.api.event.Event, які зберігають і викликають callbacks. Часто існує один екземпляр події для зворотного виклику, який зберігається в статичному полі 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);
	}
});

Власні події

Деякі області гри не мають хуків, наданих Fabric API, тому ви можете використовувати міксин або створити власну подію.

Ми розглянемо створення події, яка запускається, коли вівцю стрижуть. Процес створення події:

• Створення інтерфейсу зворотного виклику події
• Запуск події з міксина
• Створення тестової реалізації

Створення інтерфейсу зворотного виклику події

Інтерфейс зворотного виклику описує, що має бути реалізоване слухачами подій, які слухатимуть вашу подію. Інтерфейс зворотного виклику також описує, як подія буде викликана з нашого міксина. Традиційно розміщувати об’єкт 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);
}

Розгляньмо це глибше. Коли виклик викликається, ми повторюємо всі слухачі:

(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.
 */

Запуск події з міксина

Тепер у нас є основна структура подій, але нам потрібно його запустити. Оскільки ми хочемо, щоб подія викликалася, коли гравець намагається підстригти вівцю, ми викликаємо подію 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;
});

Якщо ви входите в гру і стрижете вівцю, замість вовни повинен випасти діамант.