Generierung von Fortschritten 26.2

Ein Leitfaden zur Einrichtung der Generierung von Fortschritten mit dem Datengenerator.

VORAUSSETZUNGEN

Stelle sicher, dass du den Prozess der Einrichtung des Datengenerators zuerst abgeschlossen hast.

Einrichtung

Zuerst müssen wir unseren Provider erstellen. Erstelle eine Klasse, die von FabricAdvancementProvider erbt und fülle die Basismethoden aus:

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

Um die Einrichtung abzuschließen, füge den Provider zu deinem DataGeneratorEntrypoint in der onInitializeDataGenerator Methode hinzu.

pack.addProvider(ExampleModAdvancementProvider::new);

Struktur eines Fortschritts

Ein Fortschritt setzt sich aus mehreren Komponenten zusammen. Neben den Voraussetzungen, auch als "Kriterien" bezeichnet, kann er auch folgendes haben:

• Ein DisplayInfo, das dem Spiel mitteilt, wie der Fortschritt den Spielern angezeigt werden soll,
• AdvancementRequirements, bei denen es sich um Listen von Kriterien handelt, von denen mindestens ein Kriterium aus jeder Teilliste erfüllt sein muss,
• AdvancementRewards, die der Spieler für den Abschluss des Fortschritts erhält.
• Eine Strategy, die dem Fortschritt mitteilt wie er mehrere Kriterien verarbeiten soll, und
• Ein übergeordnetes Advancement, das die Hierachie organisiert, welche du in dem "Fortschritt" Fenster sehen kannst.

Einfacher Fortschritt

Hier ist ein einfacher Fortschritt, um einen Erdblock zu erhalten:

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 Ausgabe

{
  "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
}

Übergeordnet

Um einen Fortschrittsbaum anzulegen oder zu erweitern, können wir für unseren Fortschritt einen übergeordneten Eintrag festlegen. Rufe dazu Advancement.Builder#parent(...) auf und übergebe eine Referenz auf den übergeordneten Fortschritt.

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

Wenn keine direkte Referenz auf den übergeordneten Fortschritt vorhanden ist (z. B. bei Verwendung eines Vanilla Fortschritt als übergeordneter Eintrag), kann mithilfe einer Bezeichnung ein Platzhalter angelegt werden.

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

Deine Fortschritte sollten nun im Fortschrittsmenü als Baumstruktur angezeigt werden.

Mehrere Kriterien

Um unsere Fortschritte mit komplexeren Bedingungen zu versehen, können wir Advancement.Builder#addCriteria(...) mehrmals mit zusätzlichen Kriterien aufrufen.

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

Im Standard müssen alle Kriterien erfüllt sein, damit der Fortschritt abgeschlossen werden kann. Wir können dieses Verhalten ändern, indem wir eine andere Strategie anwenden.

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)
		// ...

Belohnungen

Wir können unseren Fortschritten Belohnungen zuweisen, die einem Spieler gewährt werden, sobald er den Fortschritt abgeschlossen hat. Dies erreichen wir, indem wir Advancement.Builder#rewards(...) mit den Belohnungen aufrufen, die wir hinzufügen möchten.

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

Es gibt mehrere andere Belohnungsarten:

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)
		)
		// ...

Benutzdefinierte Kriterien

WARNING

Während der Datengenerator auf der Client-Seite liegen kann, befinden sich Criterions und Predicates im Hauptquellenverzeichnis (beide Seiten), da der Server sie auslösen und auswerten muss.

Definitionen

Ein Kriterium (Plural: Kriterien) ist etwas, was Spieler machen können (oder was einem Spieler passieren kann) was möglicherweise einem Fortschritt angerechnet wird. Das Spiel kommt mit vielen Kriterien, welche in dem net.minecraft.advancements.criterion Packet gefunden werden können. Generell musst du nur ein neues Kriterium hinzufügen, wenn du eine benutzdefinierte Mechanik zum Spiel hinzufügst.

Bedingungen werden von Kriterien ausgewertet. Ein Kriterium wird nur gezählt, wenn alle relevanten Bedingungen zutreffen. Bedingungen werden in der Regel durch ein Prädikat ausgedrückt.

Ein Prädikat ist etwas, das einen Wert entgegennimmt und einen boolean zurück gibt. Zum Beispiel, ein Predicate<Item> gibt möglicherweise true zurück, wenn das Item ein Diamant ist, während ein Predicate<LivingEntity> möglicherweise true zurückgibt, wenn die Entität nicht gegenüber einem Dorfbewohner feindlich gesinnt ist.

Erstellen von benutzdefinierten Kriterien

Zuerst müssen wir eine neue Mechanik implementieren. Wir können dem Spieler jedes Mal, wenn er einen Block abbaut, mitteilen, welches Werkzeug er benutzt hat.

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

Beachte, dass dieser Code wirklich schlecht ist. Die HashMap wird nirgendwo dauerhaft gespeichert, daher wird sie bei jedem Neustart des Spiels zurückgesetzt. Es geht nur darum, Criterions aufzuzeigen. Starte das Spiel und teste es!

Als Nächstes erstellen wir unser benutzerdefiniertes Kriterium UseToolCriterion. Es wird seine eigene Klasse Conditions benötigen, also werden wir beide auf einmal erstellen:

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

Puh, das ist eine Menge! Schauen wir uns das mal genauer an.

• UseToolCriterion ist ein SimpleCriterionTrigger, auf das Conditions angewendet werden können.
• Conditions hat ein playerPredicate Feld. Alle Conditions sollten ein Spielerprädikat haben (technisch gesehen ein LootContextPredicate).
• Conditions haben auch einen CODEC. Dieser Codec ist einfach der Codec für sein einziges Feld, playerPredicate, mit zusätzlichen Anweisungen zur Konvertierung zwischen ihnen (xmap).

INFO

Um mehr über Codecs zu erfahren, sieh dir die Codecs Seite an.

Wir brauchen einen Weg, um zu überprüfen, ob Bedingungen erfüllt sind. Lasst uns eine Hilfsmethode zu Conditions hinzufügen:

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

Da wir nun ein Kriterium und seine Bedingungen haben, brauchen wir eine Möglichkeit, es auszulösen. Füge eine Auslösungsmethode zu UseToolCriterion hinzu:

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

Fast geschafft! Als nächstes benötigen wir eine Instanz unseres Kriteriums, mit der wir arbeiten können. Lasst und das Ganze in eine neue Klasse namens ModCriteria packen, die eine Hilfsmethode enthält, mit der sich neue Kriterien einfach registrieren lassen.

public class ModCriteria {
	public static final UseToolCriterion USE_TOOL = register("use_tool", new UseToolCriterion());

	private static <T extends CriterionTrigger<?>> T register(final String name, final T criterion) {
		return Registry.register(BuiltInRegistries.TRIGGER_TYPES, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, name), criterion);
	}
}

Um sicherzustellen, dass unsere Kriterien zum richtigen Zeitpunkt initialisiert werden, füge eine leere init-Methode hinzu:

public static void init() {
}

Und rufe es in deinem Mod-Initialisierer auf:

ModCriteria.init();

Schließlich müssen wir unser Kriterium auslösen. Füge dies zu der Stelle hinzu, an der wir in der Hauptmodklasse eine Nachricht an den Spieler geschickt haben.

ModCriteria.USE_TOOL.trigger(serverPlayer);

Dein neues Kriterium ist jetzt einsatzbereit! Lasst es uns zu unserem provider hinzufügen:

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

Führe den Datengenerator Task erneut aus und du hast einen neuen Fortschritt bekommen, mit dem du spielen kannst!

Bedingungen mit Parametern

Das ist alles schön und gut, aber was ist, wenn wir einen Fortschritt nur dann gewähren wollen, wenn wir etwas fünfmal getan haben? Und warum nicht noch einen bei zehn Mal? Hierfür müssen wir unserer Bedingung einen Parameter geben. Du kannst bei UseToolCriterion bleiben, oder du kannst mit einem neuen ParameterizedUseToolCriterion nachziehen. In der Praxis solltest du nur die parametrisierte Variante haben, aber für dieses Tutorial werden wir beide behalten.

Lass uns von unten nach oben arbeiten. Wir müssen prüfen, ob die Anforderungen erfüllt sind, also bearbeiten wir unsere Methode Conditions#requirementsMet:

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

requiredTimes existiert nicht, also mache es zu einem Parameter von 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.
	}
}

Jetzt ist unser Codec fehlerhaft. Lass uns einen neuen Codec für die neuen Änderungen schreiben:

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

Nun müssen wir unsere trigger-Methode korrigieren:

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

Wenn du ein neues Kriterium erstellt hast, müssen wir es zu ModCriteria hinzufügen

public static final ParameterizedUseToolCriterion PARAMETERIZED_USE_TOOL = register("parameterized_use_tool", new ParameterizedUseToolCriterion());

Und rufe sie in unserer Hauptklasse auf, genau dort, wo die alte Klasse ist:

ModCriteria.PARAMETERIZED_USE_TOOL.trigger(serverPlayer, usedCount);

Füge den Fortschritt zu deinem Provider hinzu:

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

Führe den Datengenerator erneut aus, und du bist endlich fertig!

Ressourcenbedingungen

Um eine Ressourcenbedingung auf einen datengenerierten Fortschritt anzuwenden, umschließe den Consumer mit withConditions und gebe die gewünschten Ressourcenbedingungen an. Dadurch wird ein Fortschritt generiert, auf den Ressourcenbedingungen angewendet werden:

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