Создание достижений 26.1.2

Руководство по настройке генерации достижений через datagen.

ТРЕБОВАНИЯ

Сначала убедитесь, что вы установили datagen.

Установка

Для начала нам нужно создать провайдера. Создайте класс, который расширяет FabricAdvancementProvider и заполните базовые методы:

public class ExampleModAdvancementProvider extends FabricAdvancementProvider {
	protected ExampleModAdvancementProvider(FabricPackOutput output, CompletableFuture<HolderLookup.Provider> registryLookup) {
		super(output, registryLookup);
	}

	@Override
	public void generateAdvancement(HolderLookup.Provider wrapperLookup, Consumer<AdvancementHolder> consumer) {
	}
}

Чтобы завершить настройку, добавьте этот провайдер к вашей DataGeneratorEntrypoint в методе onInitializeDataGenerator.

pack.addProvider(ExampleModAdvancementProvider::new);

Структура достижений

Достижение состоит из нескольких различных компонентов. Помимо требований, называемых "критериями" (criterion), оно может содержать:

• DisplayInfo — указывает игре, как именно отображать достижение игрокам.
• AdvancementRequirements — списки списков критериев; для выполнения достижения требуется завершить как минимум один критерий из каждого подсписка.
• AdvancementRewards — награды, которые игрок получает за выполнение достижения.
• Strategy — стратегия, которая определяет, как достижение обрабатывает несколько критериев.
• Parent — родительское достижение. Организует иерархию, которую можно увидеть на экране "Достижения".

Простые достижения

Вот пример простого достижения за получение блока земли:

AdvancementHolder getDirt = Advancement.Builder.advancement()
		.display(
				Items.DIRT, // The display icon
				Component.literal("Your First Dirt Block"), // The title
				Component.literal("Now make a house from it"), // The description
				Identifier.withDefaultNamespace("gui/advancements/backgrounds/adventure"), // Background image for the tab in the advancements page, if this is a root advancement (has no parent)
				AdvancementType.TASK, // TASK, CHALLENGE, or GOAL
				true, // Show the toast when completing it
				true, // Announce it to chat
				false // Hide it in the advancement tab until it's achieved
		)
		// "got_dirt" is the name referenced by other advancements when they want to have "requirements."
		.addCriterion("got_dirt", InventoryChangeTrigger.TriggerInstance.hasItems(Items.DIRT))
		// Give the advancement an id
		.save(consumer, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "get_dirt"));

Вывод JSON

{
  "criteria": {
    "got_dirt": {
      "conditions": {
        "items": [
          {
            "items": "minecraft:dirt"
          }
        ]
      },
      "trigger": "minecraft:inventory_changed"
    }
  },
  "display": {
    "background": "minecraft:gui/advancements/backgrounds/adventure",
    "description": "Now make a house from it",
    "icon": {
      "id": "minecraft:dirt"
    },
    "title": "Your First Dirt Block"
  },
  "requirements": [
    [
      "got_dirt"
    ]
  ],
  "sends_telemetry_event": true
}

Родительские достижения (Parents)

Чтобы создать или расширить дерево достижений, мы можем указать родителя для нашего достижения. Для этого вызовите метод Advancement.Builder#parent(...) и передайте ссылку на родительское достижение:

Advancement.Builder.advancement()
		.parent(getDirt)
		// ...

Если прямой ссылки на родительское достижения нет (например, в качестве родителя используется ванильное достижение), можно создать плейсхолдер с помощью static метода класса Identifier.

Advancement.Builder.advancement()
		.parent(createPlaceholder(Identifier.withDefaultNamespace("adventure/root")))
		// ...

Теперь ваши достижения будут отображаться в виде древовидной структуры в меню достижений.

Множественные критерии (Multiple Criteria)

Чтобы использовать более сложные условия в наших достижениях, мы можем вызывать метод Advancement.Builder#addCriteria(...) несколько раз, добавляя дополнительные критерии:

Advancement.Builder.advancement()
		.addCriterion("ate_apple", ConsumeItemTrigger.TriggerInstance.usedItem(itemLookup, Items.APPLE))
		.addCriterion("ate_cooked_beef", ConsumeItemTrigger.TriggerInstance.usedItem(itemLookup, Items.COOKED_BEEF))
		// ...

По умолчанию для выполнения достижения должны быть выполнены все указанные критерии. Мы можем изменить это поведение, задав другую стратегию требований (AdvancementRequirements.Strategy):

Advancement.Builder.advancement()
		.addCriterion("brew_mundane", CriteriaTriggers.BREWED_POTION.createCriterion(
				new BrewedPotionTrigger.TriggerInstance(Optional.empty(), Optional.of(Potions.MUNDANE))
		))
		.addCriterion("brew_thick", CriteriaTriggers.BREWED_POTION.createCriterion(
				new BrewedPotionTrigger.TriggerInstance(Optional.empty(), Optional.of(Potions.THICK))
		))
		.requirements(AdvancementRequirements.Strategy.OR)
		// ...

Награды (Rewards)

Мы можем привязывать награды к нашим достижениям, которые будут выдаваться игроку сразу после их выполнения. Для этого нужно вызвать метод Advancement.Builder#rewards(...) и передать туда награды, которые мы хотим добавить:

Advancement.Builder.advancement()
		.rewards(AdvancementRewards.Builder.experience(10))
		// ...

Также доступны и другие типы наград:

Advancement.Builder.advancement()
		.rewards(
				new AdvancementRewards.Builder()
						// Give entries from a loot table
						.addLootTable(ModLootTables.ADVANCEMENT_COLLECT_NETHER_STAR)
						// Make recipes available in the recipe book
						.addRecipe(RecipeBuilder.getDefaultRecipeId(new ItemStackTemplate(Items.BEACON)))
						// Run a .mcfunction - https://minecraft.wiki/w/Function_(Java_Edition)
						.runs(Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "got_nether_star"))
						// Give experience points
						.addExperience(200)
		)
		// ...

Пользовательские критерии (Custom Criteria)

WARNING

Хотя генерация данных (datagen) может выполняться на стороне клиента, сами классы критериев (Criterion) и предикатов (Predicate) должны находиться в основном наборе исходного кода (main source set), доступном для обеих сторон, поскольку именно сервер должен отслеживать и проверять их выполнение.

Определения

Критерий (Criterion / мн. ч. Criteria) — это действие, которое может совершить игрок (или событие, которое может с ним произойти), засчитывающееся для прогресса достижения. В игре уже есть много стандартных критериев, которые находятся в пакете net.minecraft.advancements.criterion. Как правило, новый критерий нужен только в том случае, если вы добавляете в игру свою уникальную механику.

Условия (Conditions) — это параметры, которые проверяются критерием. Критерий засчитывается только в том случае, если выполнены все связанные условия. Обычно условия выражаются с помощью предикатов.

Предикат (Predicate) — это функциональный интерфейс, принимающий входное значение и возвращающий результат типа boolean(логическое значение). Например, предикат Predicate<Item> может возвращать true, если предмет является алмазом, а предикат Predicate<LivingEntity> — если существо не агрессивно по отношению к деревенским жителям.

Создание пользовательских критериев

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

public class ExampleModDatagenAdvancement implements ModInitializer {
	@Override
	public void onInitialize() {
		HashMap<Item, Integer> tools = new HashMap<>();

		PlayerBlockBreakEvents.AFTER.register(((level, player, blockPos, blockState, blockEntity) -> {
			if (player instanceof ServerPlayer serverPlayer) { // Only triggers on the server side
				Item item = player.getMainHandItem().getItem();

				Integer usedCount = tools.getOrDefault(item, 0);
				usedCount++;
				tools.put(item, usedCount);

				serverPlayer.sendSystemMessage(Component.nullToEmpty("You've used \"" + item + "\" as a tool " + usedCount + " times!"));
			}
		}));
	}
}

Обратите внимание, что этот код очень плохой. Так как HashMap не хранится в постоянном месте, она будет сбрасываться при каждом перезапуске игры. Это сделано исключительно для демонстрации критериев (Criterions). Начните игру и попробуйте!

Далее создадим наш пользовательский критерий UseToolCriterion. Для него понадобится собственный класс Conditions, поэтому мы создадим их оба сразу:

public class UseToolCriterion extends SimpleCriterionTrigger<UseToolCriterion.Conditions> {

	@Override
	public Codec<Conditions> codec() {
		return Conditions.CODEC;
	}

	public record Conditions(Optional<ContextAwarePredicate> playerPredicate) implements SimpleCriterionTrigger.SimpleInstance {
		public static Codec<UseToolCriterion.Conditions> CODEC = ContextAwarePredicate.CODEC.optionalFieldOf("player")
				.xmap(Conditions::new, Conditions::player).codec();

		@Override
		public Optional<ContextAwarePredicate> player() {
			return this.playerPredicate;
		}
	}
}

Ух, как много всего! Давайте во всём разберёмся.

• UseToolCriterion — это класс-наследник SimpleCriterionTrigger, к которому могут применяться условия Conditions.
• В Conditions есть поле playerPredicate. Все условия Conditions должны содержать предикат игрока (технически — LootContextPredicate).
• У Conditions также есть CODEC. Этот Codec - просто кодек для одного поля, playerPredicate, с дополнительными инструкциями для преобразования между ними (xmap).

INFO

Чтобы узнать больше о кодеках, см. страницу Codecs.

Нам понадобится способ проверить, выполнены ли условия. Давайте добавим вспомогательный метод в Conditions:

public boolean requirementsMet() {
	return true; // AbstractCriterion#trigger helpfully checks the playerPredicate for us.
}

Теперь, когда у нас есть критерий и его условия, нам нужно найти способ запустить его. Добавьте метод триггера к UseToolCriterion:

public void trigger(ServerPlayer player) {
	trigger(player, Conditions::requirementsMet);
}

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

public class ModCriteria {
	public static final UseToolCriterion USE_TOOL = CriteriaTriggers.register(Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "use_tool").toString(), new UseToolCriterion());
}

Чтобы убедиться, что наши критерии инициализируются в нужное время, добавьте пустой метод init:

public static void init() {
}

И вызовите его в инициализаторе вашего мода:

ModCriteria.init();

Наконец, нам нужно запустить наши критерии. Добавьте это туда, где мы отправили сообщение игроку в основном классе мода.

ModCriteria.USE_TOOL.trigger(serverPlayer);

Теперь ваш новый блестящий критерий готов к использованию! Давайте добавим его в наш провайдер:

AdvancementHolder breakBlockWithTool = Advancement.Builder.advancement()
		.parent(getDirt)
		.display(
				Items.DIAMOND_SHOVEL,
				Component.literal("Not a Shovel"),
				Component.literal("That's not a shovel (probably)"),
				null,
				AdvancementType.GOAL,
				true,
				true,
				false
		)
		.addCriterion("break_block_with_tool", ModCriteria.USE_TOOL.createCriterion(new UseToolCriterion.Conditions(Optional.empty())))
		.save(consumer, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "break_block_with_tool"));

Запустите задачу datagen снова — ваше новое достижение готово к использованию!

Условия с параметрами

Всё это хорошо, но что если мы хотим выдавать достижение только после 5-кратного выполнения условия? А почему не еще один в 10 раз? Для этого нам нужно задать условию параметр. Вы можете продолжать использовать UseToolCriterion или перейти на новый ParameterizedUseToolCriterion. На практике вам нужно иметь только параметризованный, но в этом уроке мы оставим оба.

Давайте работать снизу вверх. Нам нужно проверить, выполнены ли требования, поэтому давайте отредактируем наш метод Conditions#requirementsMet:

public boolean requirementsMet(int totalTimes) {
	return totalTimes > this.requiredTimes; // AbstractCriterion#trigger helpfully checks the playerPredicate for us.
}

requiredTimes не существует, поэтому сделайте его параметром Conditions:

public record Conditions(Optional<ContextAwarePredicate> playerPredicate, int requiredTimes) implements SimpleCriterionTrigger.SimpleInstance {
	@Override
	public Optional<ContextAwarePredicate> player() {
		return this.playerPredicate;
	}

	public boolean requirementsMet(int totalTimes) {
		return totalTimes > this.requiredTimes; // AbstractCriterion#trigger helpfully checks the playerPredicate for us.
	}
}

Теперь наш кодек выдает ошибку. Давайте напишем новый кодек для новых изменений:

public static Codec<ParameterizedUseToolCriterion.Conditions> CODEC = RecordCodecBuilder.create(instance -> instance.group(
		ContextAwarePredicate.CODEC.optionalFieldOf("player").forGetter(Conditions::player),
		Codec.INT.fieldOf("requiredTimes").forGetter(Conditions::requiredTimes)
).apply(instance, Conditions::new));

Двигаемся дальше, теперь нам нужно исправить наш метод trigger:

public void trigger(ServerPlayer player, int totalTimes) {
	this.trigger(player, conditions -> conditions.requirementsMet(totalTimes));
}

Если вы создали новый критерий, нам нужно добавить его в ModCriteria

public static final ParameterizedUseToolCriterion PARAMETERIZED_USE_TOOL = CriteriaTriggers.register(Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "parameterized_use_tool").toString(), new ParameterizedUseToolCriterion());

И вызываем его в нашем основном классе, прямо там, где был старый вариант:

ModCriteria.PARAMETERIZED_USE_TOOL.trigger(serverPlayer, usedCount);

Добавьте достижение в ваш provider:

AdvancementHolder breakBlockWithToolFiveTimes = Advancement.Builder.advancement()
		.parent(breakBlockWithTool)
		.display(
				Items.GOLDEN_SHOVEL,
				Component.literal("Not a Shovel Still"),
				Component.literal("That's still not a shovel (probably)"),
				null,
				AdvancementType.GOAL,
				true,
				true,
				false
		)
		.addCriterion("break_block_with_tool_five_times", ModCriteria.PARAMETERIZED_USE_TOOL.createCriterion(new ParameterizedUseToolCriterion.Conditions(Optional.empty(), 5)))
		.save(consumer, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "break_block_with_tool_five_times"));

Запустите datagen еще раз, и вы наконец-то закончили!

Условная загрузка ресурсов

Чтобы применить условную загрузку ресурсов к динамически генерируемому достижению, оберните объект-потребитель (consumer) методом withConditions и укажите любые условия ресурсов, которые вы хотите применить. В результате будет создано достижение с примененными условиями ресурсов:

Advancement.Builder.advancement()
		.display(
				ModBlocks.DUPLICATOR_BLOCK,
				Component.literal("Experimental Duplication"),
				Component.literal("Place a duplicator block with the Redstone Experiments flag enabled."),
				null,
				AdvancementType.CHALLENGE,
				false, false, false)
		.addCriterion("place_block", ItemUsedOnLocationTrigger.TriggerInstance.placedBlock(ModBlocks.DUPLICATOR_BLOCK))
		.save(withConditions(consumer,
						ResourceConditions.featuresEnabled(FeatureFlags.REDSTONE_EXPERIMENTS)), Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "experimental_duplication"));