minestom-advancements

Minestom advancements

Advancements render the vanilla achievements screen. A tab holds a tree: one AdvancementRoot plus child Advancements linked by parent. Get the manager from the server.

AdvancementManager manager = MinecraftServer.getAdvancementManager();

Build a tab

import net.minestom.server.advancements.*;
import net.minestom.server.item.Material;
import net.kyori.adventure.text.Component;

AdvancementRoot root = new AdvancementRoot(
    Component.text("Getting Started"),          // title
    Component.text("Your first steps"),         // description
    Material.GRASS_BLOCK,                        // icon
    FrameType.TASK,                              // TASK | GOAL | CHALLENGE
    0f, 0f,                                      // x, y in the tree
    "minecraft:textures/block/stone.png");       // background texture

AdvancementTab tab = manager.createTab("myserver:main", root);

Add children, linking each to its parent:

Advancement first = new Advancement(
    Component.text("First Blood"),
    Component.text("Defeat an enemy"),
    Material.IRON_SWORD,
    FrameType.GOAL,
    1f, 0f);                                     // x offset from root

tab.createAdvancement("myserver:first_blood", first, root);

Show to a player

tab.addViewer(player);
tab.removeViewer(player);

Progress & toasts

first.setAchieved(true);          // marks complete (and pops the toast if enabled)
first.showToast(true);            // show the toast popup on completion

Per-player progress — important

All viewers of one AdvancementTab share the same progress. To give players independent progress, create a separate AdvancementTab per player (e.g. build it in AsyncPlayerConfigurationEvent/spawn and addViewer only that player). Don't share one tab across players if their states differ.

events.addListener(PlayerSpawnEvent.class, e -> {
    Player p = e.getPlayer();
    AdvancementTab tab = manager.createTab("myserver:" + p.getUuid(), buildRoot());
    // ... populate ...
    tab.addViewer(p);
});

Notes & gotchas

• Namespaced IDs are lowercase namespace:id.
• Coordinates (x, y) are tree layout positions, not world coords; space children out so lines don't overlap.
• FrameType.CHALLENGE renders the fancy purple frame + completion sound.
• See minestom-adventure-text for titles/components used in advancement names, and minestom-events for hooking grant logic onto gameplay events.

Sources: https://minestom.net/docs/feature/advancements