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 net.neoforged.neoforge.common.data.AdvancementProvider which integrates better for generating advancements. So, this documentation will use net.neoforged.neoforge.common.data.AdvancementProvider along with the sub provider interface AdvancementProvider.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 AdvancementProvider(
            output,
            event.getLookupProvider(),
            event.getExistingFileHelper(),
            // Sub providers which generate the advancements
            List.of(subProvider1, subProvider2, /*...*/)
        )
    );
}

AdvancementProvider.AdvancementGenerator

An AdvancementProvider.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 AdvancementProvider$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 ResourceLocation 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 unlock this 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 IAdvancementBuilderExtension#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 AdvancementProvider.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