Minecraft Custom Advancements Data Pack Guide

Written for Minecraft 26.3.

Minecraft custom advancements live in a data pack as JSON files. Each file has a display, one or more criteria and optional rewards. A file with no parent starts a new tab.

Before you start

• Minecraft Java Edition 26.3, data pack format 121.0.

• A data pack. See pack basics.

• Operator rights for /advancement.

Where the files go

Save advancements at data/<namespace>/advancement/<name>.json. The folder is advancement, singular, since 1.21 (it was advancements before). The ID of data/example/advancement/root.json is example:root.

Create a tab root

1. Create data/example/advancement/root.json.

2. Add a display with an icon, title and description. All three are required.

3. Add a criterion. minecraft:impossible never fires by itself, so only a command can grant it.

{
  "display": {
    "icon": { "id": "minecraft:emerald" },
    "title": { "text": "Welcome" },
    "description": { "text": "You joined the server." },
    "show_toast": false,
    "announce_to_chat": false
  },
  "criteria": {
    "joined": { "trigger": "minecraft:impossible" }
  }
}

Without a parent this file becomes a root, and background (root only) sets the tab picture. Grant the root from a function or command when a player joins.

Create a child

A child names its parent and uses a real trigger. This one fires when the player has 5 to 10 diamonds in their inventory:

{
  "parent": "example:root",
  "display": {
    "icon": { "id": "minecraft:diamond" },
    "title": { "text": "Shiny" },
    "description": { "text": "Collect five diamonds." },
    "frame": "goal"
  },
  "criteria": {
    "has_diamonds": {
      "trigger": "minecraft:inventory_changed",
      "conditions": {
        "items": [
          { "items": "minecraft:diamond", "count": { "min": 5 } }
        ]
      }
    }
  },
  "rewards": {
    "experience": 100
  }
}

• frame is task (default), goal or challenge.

• hidden (default false) hides it until it is earned.

• requirements lists groups of criteria. Leave it out to require all of them.

• rewards can also give recipes, loot tables or run a function.

Reward loot uses loot tables: see loot tables.

Grant and revoke

/advancement grant @s only example:root
/advancement grant @s from example:root
/advancement revoke @s everything

only affects one advancement, from adds its children, through adds parents and children, and until goes back to the root.

Check it worked

• Open the advancements screen (L): your tab should show.

• Grant the root, then pick up five diamonds. The child should complete.

• Revoke and repeat to test again.

Common problems

The tab does not appear

A root with no earned advancement can stay hidden. Grant it with only first.

It fails to load

A missing icon, title or description, or a circular parent, stops the file loading. Check the console.

Wrong folder

Use advancement, not advancements.

Icon items with data

Item data on an icon goes in components next to id, not in old NBT.

Do not mistype the parent. A parent that does not exist leaves the child unloaded with no in-game message.

More docs: debugging a pack.