Пользовательские компоненты данных 26.1.2

Узнайте, как добавлять пользовательские данные к вашим товарам, используя новую систему компонентов 1.20.5.

WARNING

Эта страница написана для версии 26.1.2. Документация для более старых версий может быть неполной.

По мере того как ваши элементы становятся более сложными, вам может потребоваться хранить специальные данные, связанные с каждым элементом. Игра позволяет хранить постоянные данные в ItemStack, и начиная с версии 1.20.5 мы делаем это с помощью Компонентов данных.

Компоненты данных заменяют данные NBT из предыдущих версий структурированными типами данных, которые можно применять к ItemStack для хранения постоянных данных об этом стеке. Компоненты данных имеют пространство имен, что означает, что мы можем реализовать собственные компоненты данных для хранения пользовательских данных о ItemStack и доступа к ним позже. Полный список компонентов данных vanilla можно найти на этой странице вики 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()
);

Здесь есть несколько вещей, на которые стоит обратить внимание. В первой и четвертой строках вы можете увидеть ?. Он будет заменен типом значения вашего компонента. Мы скоро это заполним.

Во-вторых, вы должны предоставить Идентификатор, содержащий предполагаемый идентификатор вашего компонента. Это пространство имен с идентификатором вашего мода.

И наконец, у нас есть DataComponentType.Builder, который создаёт фактический экземпляр DataComponentType, подлежащий регистрации. Здесь содержится еще одна важная деталь, которую нам нужно будет обсудить: Codec вашего компонента. В настоящее время это поле пустое, но мы скоро его заполним.

Базовые компоненты данных

Базовые компоненты данных (например, 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. Обратите внимание, что этот метод помечен как устаревший, поскольку Mojang работает над тем, чтобы поведение предметов обрабатывалось исключительно через компоненты, а не через сами предметы.

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 через ItemComponentTooltipProviderRegistry. Это вызывается в onInitialize в ModInitializer.

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

Не забудьте обновить ваш lang-файл (/assets/example-mod/lang/en_us.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]

При наведении курсора на этот предмет в инвентаре вы увидите количество, отображаемое во всплывающей подсказке!

Однако если вы дадите себе новый предмет Counter без пользовательского компонента, игра вылетит при наведении курсора на предмет в инвентаре. В отчете о сбое вы должны увидеть такую ​​ошибку:

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)

As expected, since the ItemStack doesn't currently contain an instance of our custom component, calling stack.get() with our component type will return 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));
	}
}

Запустите игру снова и наведите курсор на предмет без компонента. Вы должны увидеть надпись «Использовано 0 раз», и игра больше не будет вылетать.

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

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

При наведении курсора на этот элемент подсказка должна отсутствовать.

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

Теперь попробуем обновить значение нашего компонента. Мы собираемся увеличивать количество кликов каждый раз, когда используем наш элемент Counter. Чтобы изменить значение компонента в 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;
}

Теперь попробуйте запустить игру и щелкнуть правой кнопкой мыши, держа в руке предмет Counter. Если вы откроете свой инвентарь и снова посмотрите на предмет, вы увидите, что показатель использования увеличился пропорционально количеству кликов по нему.

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

Вы также можете удалить компонент из 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 AdvancedCustomComponent() {
}

Обратите внимание, что после имени класса стоят скобки. Здесь мы определяем список свойств, которые должен иметь наш компонент. Давайте добавим число с плавающей точкой и логическое значение с именами температура и сожженный соответственно.

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

Поскольку мы определяем пользовательскую структуру данных, для нашего варианта использования не будет готового Кодека, как в случае с базовым компонентом. Это значит, что нам придется создать собственный кодек. Давайте определим его в нашем классе записи, используя RecordCodecBuilder, на который мы сможем ссылаться после регистрации компонента. Более подробную информацию об использовании RecordCodecBuilder можно найти в этом разделе страницы Кодеки.

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

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

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

Наконец, мы вызываем apply() и передаем конструктор нашей записи. Более подробную информацию о создании кодеков и более сложных вариантах использования можно найти на странице Кодеки.

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

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

Теперь начинайте игру. Попробуйте применить компонент с помощью команды /give. Значения составных компонентов передаются как объект, заключенный в {}. Если вы поставите пустые фигурные скобки, вы увидите сообщение об ошибке, сообщающее, что требуемый ключ temperature отсутствует.

Добавьте значение температуры к объекту, используя синтаксис temperature:8.2. При желании можно также передать значение для burnt, используя тот же синтаксис, но либо true, либо false. Теперь вы должны увидеть, что команда действительна и может предоставить вам элемент, содержащий компонент.

Получение, настройка и удаление дополнительных компонентов

Использование компонента в коде такое же, как и раньше. Использование stack.get() вернет экземпляр вашего класса record, который затем можно использовать для чтения значений. Поскольку записи доступны только для чтения, вам потребуется создать новый экземпляр записи, чтобы обновить значения.

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

// set new component values
stack.set(ModComponents.ADVANCED_CUSTOM_COMPONENT, new AdvancedCustomComponent(8.4f, true));

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

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

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

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

Теперь вы можете хранить пользовательские данные в ItemStack. Используйте ответственно!

Добавление продвинутых всплывающих подсказок

Поскольку у нас есть собственный класс компонента, мы можем реализовать TooltipProvider следующим образом и избежать устаревшего метода appendHoverText

public record AdvancedCustomComponent(float temperature, boolean burnt) implements TooltipProvider {
	@Override
	public void addToTooltip(Item.TooltipContext context, Consumer<Component> tooltip, TooltipFlag flag, DataComponentGetter components) {
		tooltip.accept(Component.translatable("item.example-mod.temperature.info", this.temperature).withStyle(ChatFormatting.GOLD));
		tooltip.accept(Component.translatable("item.example-mod.burnt.info", this.temperature).withStyle(ChatFormatting.GOLD));
	}
}

Затем вы можете зарегистрировать TooltipProvider через ItemComponentTooltipProviderRegistry. Это вызывается в onInitialize в ModInitializer.

ItemComponentTooltipProviderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.ADVANCED_CUSTOM_COMPONENT);