Advancement Generation

A guide to setting up advancement generation with datagen.

WARNING

This page is written for version 1.21.10. Documentation for older versions may be incomplete.

PREREQUISITES

Make sure you've completed the datagen setup process first.

Setup

First, we need to make our provider. Create a class that extends FabricAdvancementProvider and fill out the base methods:

java

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

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

To finish setup, add this provider to your DataGeneratorEntrypoint within the onInitializeDataGenerator method.

java

pack.addProvider(ExampleModAdvancementProvider::new);

Advancement Structure

An advancement is made up a few different components. Along with the requirements, called "criterion," it may have:

Some DisplayInfo that tell the game how to show the advancement to players,
AdvancementRequirements, which are lists of lists of criteria, requiring at least one criterion from each sub-list to be completed,
AdvancementRewards, which the player receives for completing the advancement.
A Strategy, which tells the advancement how to handle multiple criterion, and
A parent Advancement, which organizes the hierarchy you see on the "Advancements" screen.

Simple Advancements

Here's a simple advancement for getting a dirt block:

java

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
				ResourceLocation.withDefaultNamespace("textures/gui/advancements/backgrounds/adventure.png"), // 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, ExampleMod.MOD_ID + ":get_dirt");

WARNING

When building your advancement entries, remember that the function accepts the ResourceLocation of the advancement in String format!

JSON Output

json

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

One More Example

Just to get the hang of it, let's add one more advancement. We'll practice adding rewards, using multiple criterion, and assigning parents:

java

final HolderLookup.RegistryLookup<Item> itemLookup = wrapperLookup.lookupOrThrow(Registries.ITEM);
AdvancementHolder appleAndBeef = Advancement.Builder.advancement()
		.parent(getDirt)
		.display(
				Items.APPLE,
				Component.literal("Apple and Beef"),
				Component.literal("Ate an apple and beef"),
				null, // Children don't need a background, the root advancement takes care of that
				AdvancementType.CHALLENGE,
				true,
				true,
				false
		)
		.addCriterion("ate_apple", ConsumeItemTrigger.TriggerInstance.usedItem(itemLookup, Items.APPLE))
		.addCriterion("ate_cooked_beef", ConsumeItemTrigger.TriggerInstance.usedItem(itemLookup, Items.COOKED_BEEF))
		.save(consumer, ExampleMod.MOD_ID + ":apple_and_beef");

Custom Criteria

WARNING

While datagen can be on the client side, Criterions and Predicates are in the main source set (both sides), since the server needs to trigger and evaluate them.

Definitions

A criterion (plural: criteria) is something a player can do (or that can happen to a player) that may be counted towards an advancement. The game comes with many criteria, which can be found in the net.minecraft.advancements.critereon [sic] package. Generally, you'll only need a new criterion if you implement a custom mechanic into the game.

Conditions are evaluated by criteria. A criterion is only counted if all the relevant conditions are met. Conditions are usually expressed with a predicate.

A predicate is something that takes a value and returns a boolean. For example, a Predicate<Item> might return true if the item is a diamond, while a Predicate<LivingEntity> might return true if the entity is not hostile to villagers.

Creating Custom Criteria

First, we'll need a new mechanic to implement. Let's tell the player what tool they used every time they break a block.

java

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

		PlayerBlockBreakEvents.AFTER.register(((world, 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!"));
			}
		}));
	}
}

Note that this code is really bad. The HashMap is not stored anywhere persistent, so it will be reset every time the game is restarted. It's just to show off Criterions. Start the game and try it out!

Next, let's create our custom criterion, UseToolCriterion. It's going to need its own Conditions class to go with it, so we'll make them both at once:

java

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

	}
}

Whew, that's a lot! Let's break it down.

UseToolCriterion is a SimpleCriterionTrigger, which Conditions can apply to.
Conditions has a playerPredicate field. All Conditions should have a player predicate (technically a LootContextPredicate).
Conditions also has a CODEC. This Codec is simply the codec for its one field, playerPredicate, with extra instructions to convert between them (xmap).

INFO

To learn more about codecs, see the Codecs page.

We're going to need a way to check if the conditions are met. Let's add a helper method to Conditions:

java

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

Now that we've got a criterion and its conditions, we need a way to trigger it. Add a trigger method to UseToolCriterion:

java

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

Almost there! Next, we need an instance of our criterion to work with. Let's put it in a new class, called ModCriteria.

java

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

To make sure that our criteria are initialized at the right time, add a blank init method:

java

// :::datagen-advancements:mod-criteria
public static final UseToolCriterion USE_TOOL = CriteriaTriggers.register(ExampleMod.MOD_ID + ":use_tool", new UseToolCriterion());
// :::datagen-advancements:mod-criteria
// :::datagen-advancements:new-mod-criteria
public static final ParameterizedUseToolCriterion PARAMETERIZED_USE_TOOL = CriteriaTriggers.register(ExampleMod.MOD_ID + ":parameterized_use_tool", new ParameterizedUseToolCriterion());

// :::datagen-advancements:mod-criteria

And call it in your mod initializer:

java

ModCriteria.init();

Finally, we need to trigger our criteria. Add this to where we sent a message to the player in the main mod class.

java

ModCriteria.USE_TOOL.trigger(serverPlayer);

Your shiny new criterion is now ready to use! Let's add it to our provider:

java

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, ExampleMod.MOD_ID + ":break_block_with_tool");

Run the datagen task again, and you've got your new advancement to play with!

Conditions with Parameters

This is all well and good, but what if we want to only grant an advancement once we've done something 5 times? And why not another one at 10 times? For this, we need to give our condition a parameter. You can stay with UseToolCriterion, or you can follow along with a new ParameterizedUseToolCriterion. In practice, you should only have the parameterized one, but we'll keep both for this tutorial.

Let's work bottom-up. We'll need to check if the requirements are met, so let's edit our Conditions#requirementsMet method:

java

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

requiredTimes doesn't exist, so make it a parameter of Conditions:

java

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

		// :::datagen-advancements:new-requirements-met
		public boolean requirementsMet(int totalTimes) {
			return totalTimes > requiredTimes; // AbstractCriterion#trigger helpfully checks the playerPredicate for us.
		}

		// :::datagen-advancements:new-requirements-met
	}
}

Now our codec is erroring. Let's write a new codec for the new changes:

java

		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));
		// :::datagen-advancements:new-parameter
		@Override
		public Optional<ContextAwarePredicate> player() {
			return playerPredicate;
		}

		// :::datagen-advancements:new-requirements-met
		public boolean requirementsMet(int totalTimes) {
			return totalTimes > requiredTimes; // AbstractCriterion#trigger helpfully checks the playerPredicate for us.
		}

		// :::datagen-advancements:new-requirements-met
	}
}

Moving on, we now need to fix our trigger method:

java

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

If you've made a new criterion, we need to add it to ModCriteria

java

public static final ParameterizedUseToolCriterion PARAMETERIZED_USE_TOOL = CriteriaTriggers.register(ExampleMod.MOD_ID + ":parameterized_use_tool", new ParameterizedUseToolCriterion());

// :::datagen-advancements:mod-criteria
// :::datagen-advancements:mod-criteria-init
public static void init() {
}

And call it in our main class, right where the old one is:

java

ModCriteria.PARAMETERIZED_USE_TOOL.trigger(serverPlayer, usedCount);

Add the advancement to your provider:

java

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, ExampleMod.MOD_ID + ":break_block_with_tool_five_times");

Run datagen again, and you're finally done!

Creating Your First Item

Block Entities

GUIs and Screens

Particles

Client Resources

Server Resources

Migrating Mappings

Page Authors

Files Referenced

Page Authors

Advancement Generation

Setup

Advancement Structure

Simple Advancements

One More Example

Custom Criteria

Definitions

Creating Custom Criteria

Conditions with Parameters

Page Authors

Files Referenced

Page Authors

Advancement Generation ​

Setup ​

Advancement Structure ​

Simple Advancements ​

One More Example ​

Custom Criteria ​

Definitions ​

Creating Custom Criteria ​

Conditions with Parameters ​

Advancement Generation

Setup

Advancement Structure

Simple Advancements

One More Example

Custom Criteria

Definitions

Creating Custom Criteria

Conditions with Parameters