Власні компоненти даних

Оскільки ваші предмети стають складнішими, вам може знадобитися зберігати спеціальні дані, пов’язані з кожним предметом. Гра дозволяє зберігати постійні дані в ItemStack, а з версії 1.20.5 ми це робимо за допомогою компонентів даних.

Компоненти даних замінюють дані NBT із попередніх версій структурованими типами даних, які можна застосувати до ItemStack для зберігання постійних даних про цей стек. Компоненти даних мають простір назви, тобто ми можемо реалізувати власні компоненти даних для зберігання спеціальних даних про ItemStack і доступу до них пізніше. Повний список компонентів даних можна знайти на цій сторінці Вікі Minecraft.

Разом із реєстрацією власних компонентів ця сторінка охоплює загальне використання API компонентів, яке також стосується компонентів усталеного типу. Ви можете переглянути та отримати доступ до визначень усіх компонентів у класі DataComponents.

Реєстрація компонентів

Як і будь-що інше у вашому моді, вам потрібно буде зареєструвати свій спеціальний компонент за допомогою DataComponentType. Цей тип компонента приймає загальний аргумент, що містить тип значення вашого компонента. Ми зосередимося на цьому більш детально нижче, коли будемо розглядати звичайні і розширені компоненти.

Виберіть розумний клас, щоб розмістити це. Для цього прикладу ми створимо новий пакет під назвою component і клас, який буде містити всі наші типи компонентів під назвою ModComponents. Переконайтеся, що ви викликаєте ModComponents.initialize() у своєму ініціалізаторі мода.

public class ModComponents {
	protected static void initialize() {
		ExampleMod.LOGGER.info("Registering {} components", ExampleMod.MOD_ID);
		// Technically this method can stay empty, but some developers like to notify
		// the console, that certain parts of the mod have been successfully initialized
	}
}

Це базовий шаблон для реєстрації типу компонента:

public static final DataComponentType<?> MY_COMPONENT_TYPE = Registry.register(
    BuiltInRegistries.DATA_COMPONENT_TYPE,
    Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "my_component"),
    DataComponentType.<?>builder().persistent(null).build()
);

Тут варто звернути увагу на кілька речей. У першому та четвертому рядках ви можете побачити ?. Це буде замінено типом значення вашого компонента. Ми незабаром заповнимо це.

По-друге, ви повинні надати Identifier, що містить призначений ідентифікатор вашого компонента. Це простір назв з ID вашого мода.

Нарешті, у нас є DataComponentType.Builder, який створює фактичний екземпляр DataComponentType, який реєструється. Тут міститься ще одна важлива деталь, яку нам потрібно буде обговорити: Кодек вашого компонента. Наразі це null, але незабаром ми його також заповнимо.

Звичайні компоненти даних

Звичайні компоненти даних (наприклад, minecraft:damage) складаються з одного значення даних, наприклад int, float, boolean або String.

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

public static final DataComponentType<Integer> CLICK_COUNT_COMPONENT = Registry.register(
		BuiltInRegistries.DATA_COMPONENT_TYPE,
		Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "click_count"),
		DataComponentType.<Integer>builder().persistent(Codec.INT).build()
);

Ви бачите, що тепер ми передаємо <Integer> як наш загальний тип, вказуючи, що цей компонент зберігатиметься як одне значення int. Для нашого кодека ми використовуємо наданий кодек ExtraCodecs.POSITIVE_INT. Ми можемо обійтися використанням звичайних кодеків для таких простих компонентів, як цей, але для складніших сценаріїв може знадобитися спеціальний кодек (про це коротко розглянемо пізніше).

Якщо ви запустите гру, ви зможете ввести таку команду:

Коли ви виконуєте команду, ви повинні отримати предмет, що містить компонент. Однак наразі ми не використовуємо наш компонент, щоб зробити щось корисне. Почнімо з читання значення компонента таким чином, який ми можемо побачити.

Читання значення компонента

Додаймо новий предмет, який буде збільшувати лічильник щоразу, коли ним натиснули ПКМ. Вам слід прочитати сторінку власні інтерактивні предмети, на якій описано методи, які ми використовуватимемо в цьому посібнику.

public class CounterItem extends Item {
	public CounterItem(Properties properties) {
		super(properties);
	}

}

Не забудьте зареєструвати предмет у своєму класі ModItems.

public static final Item COUNTER = register("counter", CounterItem::new, new Item.Properties());

Ми збираємося додати код підказки, щоб показати поточне значення кількості натискань, коли ми наводимо курсор на наш предмет в інвентарі. Ми можемо використати метод get() у нашому ItemStack, щоб отримати значення нашого компонента таким чином:

int count = stack.get(ModComponents.CLICK_COUNT_COMPONENT);

Це поверне поточне значення компонента як тип, який ми визначили під час реєстрації нашого компонента. Потім ми можемо використовувати це значення, щоб додати запис підказки. Додайте цей рядок до методу appendHoverText у класі CounterItem:

public void appendHoverText(ItemStack stack, TooltipContext context, TooltipDisplay displayComponent, Consumer<Component> textConsumer, TooltipFlag type) {
  int count = stack.get(ModComponents.CLICK_COUNT_COMPONENT);
  textConsumer.accept(Component.translatable("item.example-mod.counter.info", count).withStyle(ChatFormatting.GOLD));
}

WARNING

Починаючи з версії 1.21.5, appendHoverText застаріло. Тепер рекомендовано реалізувати TooltipProvider як такий. Для цього знадобиться створення спеціального класу компонентів.

public record ComponentWithTooltip(int clickCount) implements TooltipProvider {
	@Override
	public void addToTooltip(TooltipContext tooltip, Consumer<Component> textConsumer, TooltipFlag type, DataComponentGetter components) {
		textConsumer.accept(Component.translatable("item.example-mod.counter.info", this.clickCount).withStyle(ChatFormatting.GOLD));
	}
}

Потім ви можете зареєструвати TooltipProvider через ComponentTooltipAppenderRegistry. Це викликається в onInitialize в ModInitializer.

ComponentTooltipAppenderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);

Крім того, ви можете використовувати ItemTooltipCallback, щоб замінити appendHoverText. Це викликається в onInitializeClient в ClientModInitializer.

ItemTooltipCallback.EVENT.register((stack, context, type, tooltip) -> {
	Integer count = stack.get(ModComponents.CLICK_COUNT_COMPONENT);

	if (count != null) {
		tooltip.add(Component.translatable("item.example-mod.counter.info", count).withStyle(ChatFormatting.GOLD));
	}
});

Не забудьте оновити файл мови (/assets/example-mod/lang/en_us.json, для української uk_ua.json) і додати ці два рядки:

{
  "item.example-mod.counter": "Counter",
  "item.example-mod.counter.info": "Used %1$s times"
}

Запустіть гру та виконайте цю команду, щоб отримати новий лічильник із кількістю 5.

/give @p example-mod:counter[example-mod:click_count=5]

Коли ви наведете курсор на цей предмет у своєму інвентарі, ви побачите кількість, що показується у спливній підказці!

Однак, якщо ви дасте собі новий лічильник без спеціального компонента, гра аварійно завершить роботу, коли ви наведете курсор на предмет у своєму інвентарі. Ви повинні побачити таку помилку у звіті про збій:

java.lang.NullPointerException: Cannot invoke "java.lang.Integer.intValue()" because the return value of "net.minecraft.world.item.ItemStack.get(net.minecraft.core.component.DataComponentType)" is null
        at com.example.docs.item.custom.CounterItem.appendHoverText(LightningStick.java:45)
        at net.minecraft.world.item.ItemStack.getTooltipLines(ItemStack.java:767)

Як і очікувалося, оскільки ItemStack наразі не містить екземпляра нашого спеціального компонента, виклик stack.get() із нашим типом компонента поверне значення null.

Є три рішення, які ми можемо використати для розв'язання цієї проблеми.

Установлення усталеного значення компонента

Коли ви реєструєте свій предмет і передаєте об’єкт Item.Properties своєму конструктору предмета, ви також можете надати список компонентів усталено, які застосовуються до всіх нових предметів. Якщо ми повернемося до нашого класу ModItems, де ми реєструємо CounterItem, ми зможемо додати усталене значення для нашого спеціального компонента. Додайте це, щоб нові предмети показували кількість 0.

public static final Item COUNTER = register(
		"counter",
		CounterItem::new,
		new Item.Properties()
				// Initialize the click count component with a default value of 0
				.component(ModComponents.CLICK_COUNT_COMPONENT, 0)
);

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

WARNING

За допомогою команд можна видалити усталений компонент із ItemStack. Вам слід звернутися до наступних двох розділів, щоб правильно впоратися зі сценарієм, коли компонент відсутній у вашому предметі.

Читання з усталених значенням

Крім того, під час читання значення компонента ми можемо використовувати метод getOrDefault() нашого об’єкта ItemStack, щоб повернути вказане усталене значення, якщо компонент відсутній у стосі. Це захистить від будь-яких помилок, спричинених відсутнім компонентом. Ми можемо налаштувати код підказки так:

int count = stack.getOrDefault(ModComponents.CLICK_COUNT_COMPONENT, 0);

Як бачите, цей метод приймає два аргументи: тип нашого компонента, як і раніше, і усталене значення яке повертається, якщо компонента немає.

Перевірка наявності компонента

Ви також можете перевірити наявність певного компонента в ItemStack за допомогою методу has(). Це приймає тип компонента як аргумент і повертає true або false залежно від того, чи містить стек цей компонент.

boolean exists = stack.has(ModComponents.CLICK_COUNT_COMPONENT);

Виправлення помилки

Ми підемо до третього варіанту. Тож разом із додаванням усталеного значення компонента також перевіримо, чи присутній компонент у стосі, і покажемо лише підказку, якщо вона є.

public void appendHoverText(ItemStack stack, TooltipContext context, TooltipDisplay displayComponent, Consumer<Component> textConsumer, TooltipFlag type) {
	if (stack.has(ModComponents.CLICK_COUNT_COMPONENT)) {
		int count = stack.get(ModComponents.CLICK_COUNT_COMPONENT);
		textConsumer.accept(Component.translatable("item.example-mod.counter.info", count).withStyle(ChatFormatting.GOLD));
	}
}

Запустіть гру ще раз і наведіть вказівник мишки на предмет без компонента, ви повинні побачити, що він показує «Used 0 times» і більше не завершує роботу гри.

Спробуйте створити собі лічильник, видаливши наш спеціальний компонент. Для цього можна використати цю команду:

/give @p example-mod:counter[!example-mod:click_count]

При наведенні курсора на цей предмет підказка повинна бути відсутня.

Оновлення значення компонента

Тепер спробуймо оновити значення нашого компонента. Ми будемо збільшувати кількість натискань кожного разу, коли використовуємо наш лічильник. Щоб змінити значення компонента в ItemStack, ми використовуємо метод set() таким чином:

stack.set(ModComponents.CLICK_COUNT_COMPONENT, newValue);

Це бере наш тип компонента та значення, яке ми хочемо встановити. У цьому випадку це буде наша нова кількість натискань. Цей метод також повертає старе значення компонента (якщо воно є), що може бути корисним у деяких ситуаціях. Наприклад:

int oldValue = stack.set(ModComponents.CLICK_COUNT_COMPONENT, newValue);

Налаштуймо новий метод use(), щоб зчитувати стару кількість натискань, збільшити її на один, а потім встановити оновлену кількість натискань.

public InteractionResult use(Level level, Player user, InteractionHand hand) {
	ItemStack stack = user.getItemInHand(hand);

	// Don't do anything on the client
	if (level.isClientSide()) {
		return InteractionResult.SUCCESS;
	}

	// Read the current count and increase it by one
	int count = stack.getOrDefault(ModComponents.CLICK_COUNT_COMPONENT, 0);
	stack.set(ModComponents.CLICK_COUNT_COMPONENT, ++count);

	return InteractionResult.SUCCESS;
}

Тепер спробуйте запустити гру та натиснути ПКМ з предметом лічильника в руці. Якщо ви відкриєте свій інвентар і подивіться на предмет знову, ви побачите, що число використання зросло на кількість разів, які ви натискали на нього.

Видалення значення компонента

Ви також можете видалити компонент зі свого ItemStack, якщо він більше не потрібен. Це робиться за допомогою методу remove(), який приймає тип вашого компонента.

stack.remove(ModComponents.CLICK_COUNT_COMPONENT);

Цей метод також повертає значення компонента перед видаленням, тому ви також можете використовувати його наступним чином:

int oldCount = stack.remove(ModComponents.CLICK_COUNT_COMPONENT);

Розширенні компоненти даних

Вам може знадобитися зберегти кілька атрибутів в одному компоненті. Наприклад, компонент minecraft:food зберігає кілька значень, пов’язаних із їжею, як-от nutrition, saturation, eat_seconds тощо. У цьому посібнику ми називатимемо їх «композитними» компонентами.

Для складених компонентів ви повинні створити клас record для зберігання даних. Це тип, який ми зареєструємо в нашому типі компонента, і що ми будемо читати та записувати під час взаємодії з ItemStack. Почніть зі створення нового класу записів у пакеті component, який ми створили раніше.

public record MyCustomComponent() {
}

Зверніть увагу, що після назви класу є набір дужок. Тут ми визначаємо список властивостей, які ми хочемо мати у нашого компонента. Додаймо float і логічне значення, які називаються temperature і burnt відповідно.

public record MyCustomComponent(float temperature, boolean burnt) {
}

Оскільки ми визначаємо спеціальну структуру даних, для нашого випадку використання не буде попередньо наявного Codec, як у випадку з базовим компонентом. Це означає, що нам доведеться створити власний кодек. Визначмо один у нашому класі записів за допомогою RecordCodecBuilder, на який ми зможемо посилатися після реєстрації компонента. Щоб отримати докладніші відомості про використання RecordCodecBuilder, ви можете звернутися до цього розділу сторінки кодеків.

public static final Codec<MyCustomComponent> CODEC = RecordCodecBuilder.create(builder -> {
	return builder.group(
		Codec.FLOAT.fieldOf("temperature").forGetter(MyCustomComponent::temperature),
		Codec.BOOL.optionalFieldOf("burnt", false).forGetter(MyCustomComponent::burnt)
	).apply(builder, MyCustomComponent::new);
});

Ви бачите, що ми визначаємо список настроюваних полів на основі примітивних типів Codec. Однак ми також повідомляємо їй, як називаються наші поля, використовуючи fieldOf(), а потім використовуючи forGetter(), щоб повідомити грі, який атрибут нашого запису заповнити.

Ви також можете визначити необов’язкові поля, використовуючи optionalFieldOf() і передаючи усталене значення як другий аргумент. Будь-які поля, не позначені як додаткові, будуть обов’язковими під час налаштування компонента за допомогою /give, тому переконайтеся, що ви позначили будь-які необов’язкові аргументи як такі під час створення кодека.

Нарешті, ми викликаємо apply() і передаємо конструктор нашого запису. Щоб дізнатися більше про те, як створити кодеки та про складніші варіанти використання, обов’язково прочитайте сторінку кодеків.

Реєстрація складеного компонента аналогічна попередній. Ми просто передаємо наш клас запису як загальний тип, а наш настроюваний Codec — методу codec().

public static final DataComponentType<MyCustomComponent> MY_CUSTOM_COMPONENT = Registry.register(
		BuiltInRegistries.DATA_COMPONENT_TYPE,
		Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "custom"),
		DataComponentType.<MyCustomComponent>builder().persistent(MyCustomComponent.CODEC).build()
);

Тепер запустіть гру. Використовуючи команду /give, спробуйте застосувати компонент. Значення складених компонентів передаються як об’єкт, укладений у {}. Якщо ви поставите порожні фігурні дужки, ви побачите повідомлення про помилку про те, що необхідний ключ temperature відсутній.

Додайте значення температури до об’єкта за допомогою синтаксису temperature:8.2. Ви також можете додатково передати значення для burnt, використовуючи той самий синтаксис, але або true або false. Тепер ви маєте побачити, що команда дійсна та може надати вам предмет, що містить компонент.

Отримання, налаштування та видалення додаткових компонентів

Використання компонента в коді таке ж, як і раніше. Використання stack.get() поверне екземпляр вашого класу record, який потім можна використовувати для читання значень. Оскільки записи доступні лише для читання, вам потрібно буде створити новий екземпляр свого запису, щоб оновити значення.

// read values of component
MyCustomComponent comp = stack.get(ModComponents.MY_CUSTOM_COMPONENT);
float temp = comp.temperature();
boolean burnt = comp.burnt();

// set new component values
stack.set(ModComponents.MY_CUSTOM_COMPONENT, new MyCustomComponent(8.4f, true));

// check for component
if (stack.contains(ModComponents.MY_CUSTOM_COMPONENT)) {
    // do something
}

// remove component
stack.remove(ModComponents.MY_CUSTOM_COMPONENT);

Ви також можете встановити усталене значення для складеного компонента, передавши об’єкт компонента у ваш Item.Properties. Наприклад:

public static final Item COUNTER = register(
    "counter",
    CounterItem::new,
    new Item.Properties().component(ModComponents.MY_CUSTOM_COMPONENT, new MyCustomComponent(0.0f, false))
);

Тепер ви можете зберігати власні дані в ItemStack. Використовуйте відповідально!