Advancement Generation

Advancements can be generated for a mod by constructing a new AdvancementProvider and providing AdvancementSubProviders. Advancements can either be created and supplied manually or, for convenience, created using Advancement.Builder. The provider must be added to the DataGenerator.

note

NeoForge provides an extension for the AdvancementProvider called ForgeAdvancementProvider which integrates better for generating advancements. So, this documentation will use ForgeAdvancementProvider along with the sub provider interface ForgeAdvancementProvider.AdvancementGenerator.

// On the MOD event bus
@SubscribeEvent
public void gatherData(GatherDataEvent event) {
    event.getGenerator().addProvider(
        // Tell generator to run only when server data are generating
        event.includeServer(),
        output -> new ForgeAdvancementProvider(
          output,
          event.getLookupProvider(),
          event.getExistingFileHelper(),
          // Sub providers which generate the advancements
          List.of(subProvider1, subProvider2, /*...*/)
        )
    );
}

ForgeAdvancementProvider.AdvancementGenerator

A ForgeAdvancementProvider.AdvancementGenerator is responsible for generating advancements, containing a method which takes in a registry lookup, the writer (Consumer<Advancement>), and the existing file helper..

// In some subclass of ForgeAdvancementProvider$AdvancementGenerator or as a lambda reference

@Override
public void generate(HolderLookup.Provider registries, Consumer<Advancement> writer, ExistingFileHelper existingFileHelper) {
  // Build advancements here
}

Advancement.Builder

Advancement.Builder is a convenience implementation for creating Advancements to generate. It allows the definition of the parent advancement, the display information, the rewards when the advancement has been completed, and the requirements to unlock the advancement. Only the requirements need to be specified to create an Advancement.

Although not required, there are a number of methods that are important to know of:

Method	Description
parent	Sets the advancement which this advancement is directly linked to. Can either specify the name of the advancement or the advancement itself if its generated by the modder.
display	Sets the information to display to the chat, toast, and advancement screen.
rewards	Sets the rewards obtained when this advancement is completed.
addCriterion	Adds a condition to the advancement.
requirements	Specifies if the conditions must all return true or at least one must return true. An additional overload can be used to mix-and-match those operations.

Once an Advancement.Builder is ready to be built, the #save method should be called which takes in the writer, the registry name of the advancement, and the file helper used to check whether the supplied parent exists.

// In some ForgeAdvancementProvider$AdvancementGenerator#generate(registries, writer, existingFileHelper)
Advancement example = Advancement.Builder.advancement()
  .addCriterion("example_criterion", triggerInstance) // How the advancement is unlocked
  .save(writer, name, existingFileHelper); // Add data to builder