Advancements

The complete advancement JSON format — display, criteria, all 58 triggers, requirements logic and rewards — plus the single most important datapack pattern: using an invisible advancement as a silent, self-rearming event listener.

Overview & folder

An advancement is a single JSON file at data/<namespace>/advancement/<path>.json. Its resource id is <namespace>:<path>, with subfolders folding into the path — data/foo/advancement/story/root.json becomes foo:story/root. Advancements do three jobs:

• Track player progress toward a goal (the visible Advancements GUI screen).
• Fire rewards (XP, loot, recipes, and — critically for datapacks — a function) the instant all requirements are met.
• Serve as a silent event listener for datapack logic (see Event-listener detection — the single most important trick in this document).

Only criteria is strictly required for a functional advancement; everything else is optional. A root advancement (no parent) with a valid display creates a tab.

Root JSON schema

The top-level fields of an advancement file:

A criterion is "<name>": { "trigger": "<id>", "conditions": { ... } }. The <name> is arbitrary and is what you reference in requirements[] and in advancement grant @s only <adv> <name>. conditions is trigger-specific and always optional — omit it and the trigger fires on any occurrence of that event.

data/example/advancement/detect/eat_apple.json — silent event-listener skeleton

{
  "criteria": {
    "ate": {
      "trigger": "minecraft:consume_item",
      "conditions": {
        "item": { "items": ["minecraft:apple"] }
      }
    }
  },
  "rewards": {
    "function": "example:on_eat_apple"
  }
}

No display → invisible in the GUI, no toast, no chat spam. A pure logic hook.

The display object

Present to make the advancement visible in the GUI. Omit it entirely for silent detectors.

The icon object

data/example/advancement/root.json — full displayed root advancement

{
  "display": {
    "icon": { "id": "minecraft:grass_block" },
    "title": { "text": "Example Pack", "color": "gold" },
    "description": "The start of a custom tree",
    "background": "minecraft:textures/gui/advancements/backgrounds/stone.png",
    "frame": "task",
    "show_toast": true,
    "announce_to_chat": false,
    "hidden": false
  },
  "criteria": {
    "tick": { "trigger": "minecraft:tick" }
  }
}

data/example/advancement/challenges/beat_ender_dragon.json — challenge with multiple rewards

{
  "parent": "example:root",
  "display": {
    "icon": { "id": "minecraft:dragon_egg" },
    "title": "Dragonslayer",
    "description": "Defeat the Ender Dragon",
    "frame": "challenge",
    "show_toast": true,
    "announce_to_chat": true
  },
  "criteria": {
    "killed_dragon": {
      "trigger": "minecraft:player_killed_entity",
      "conditions": { "entity": { "type": "minecraft:ender_dragon" } }
    }
  },
  "rewards": {
    "experience": 500,
    "loot": ["example:rewards/dragon_loot"],
    "function": "example:grant_dragon_title"
  }
}

The rewards object

All four fields are independent and optional; a completed advancement fires every one present, simultaneously.

Complete trigger list (58)

All 58 vanilla trigger ids, pulled verbatim from the machine-readable registry (misode/mcmeta, trigger_type/data.json, tracking snapshot 26.3-snapshot-3). Prefix each with minecraft:. Because that branch is newer than the 1.21 baseline, triggers that did not exist in 1.21.0 are flagged below the table.

Condition schemas

Every trigger's conditions also accepts "player": [ <predicate conditions...> ] — a list of predicate objects tested against the triggering player — except minecraft:impossible. It is omitted from the schemas below for brevity.

Most-used trigger conditions

minecraft:impossible — no conditions. Never fires on its own. Used purely as a reward/flag holder.

minecraft:tick — no conditions (beyond player). Fires every tick. Combine with a player predicate to test state continuously.

minecraft:inventory_changed

{
  "items": [ { /* item predicate: matches an added item */ } ],
  "slots": {
    "empty":    <int or {"min":_,"max":_}>,
    "full":     <int or range>,
    "occupied": <int or range>
  }
}

Each entry in items[] must match at least one item currently in the inventory.

minecraft:consume_item

{ "item": { /* item predicate for the consumed item */ } }

minecraft:location

{ "location": [ { /* location predicate: position/biome/structure/dimension/block/fluid/light/smokey */ } ] }

Polled roughly every 20 ticks. Use for "player is in biome / structure / dimension".

minecraft:player_killed_entity (also entity_killed_player, kill_mob_near_sculk_catalyst)

{
  "entity":       { /* entity predicate for the victim, or a list of predicate conditions */ },
  "killing_blow": { /* damage-type predicate: how it died */ }
}

minecraft:item_used_on_block (right-click an item onto a block)

{
  "location": [
    {
      "condition": "minecraft:location_check",
      "predicate": { "block": { "blocks": ["minecraft:..."], "state": { } } }
    }
    /* plus a location predicate whose `tool` sub-field matches the item used */
  ],
  "item": { /* item predicate for the used item (version-dependent placement) */ }
}

The block is tested via a location predicate; the held item is tested via that predicate's tool item sub-predicate (or the item field, depending on version). minecraft:placed_block uses the same location array shape, describing the placed block's state, position and the tool/item used.

minecraft:recipe_crafted

{
  "recipe_id":   "minecraft:...",              /* required: which recipe */
  "ingredients": [ { /* item predicate */ } ]  /* optional: which items went in */
}

This is what powers "craft with a specific item" detection — it exposes recipe_id and per-slot ingredients.

minecraft:using_item (polled while holding right-click on an item)

{ "item": { /* item predicate; use predicates:{minecraft:custom_data:...} for custom items */ } }

minecraft:slide_down_block

{ "block": "minecraft:honey_block", "state": { "<property>": "<value>" } }

minecraft:allay_drop_item_on_block

{
  "location": [ { /* location/block predicate for the drop target */ } ],
  "item":     { /* item predicate for the dropped item */ }
}

Sub-predicate quick reference

requirements AND/OR logic

requirements is an array of arrays of criterion names. The completion rule:

If requirements is omitted, the default is one sublist per criterion → all criteria must be met (pure AND).

Pure AND (default, written explicitly)

"criteria": { "a": {...}, "b": {...}, "c": {...} },
"requirements": [ ["a"], ["b"], ["c"] ]

Pure OR — "any one of N"

"criteria": { "a": {...}, "b": {...}, "c": {...} },
"requirements": [ ["a", "b", "c"] ]

Completing a or b or c grants it — the canonical "detect one of several items/events" form.

Mixed — (a OR b) AND c

"requirements": [ ["a", "b"], ["c"] ]

Event-listener detection pattern

Advancements are the cleanest event listeners in vanilla datapacks. The loop:

1. Write an advancement whose criterion is the event you want (consume_item, player_killed_entity, using_item, item_used_on_block, …), with no display so it is invisible/silent.
2. Give it a rewards.function that runs your logic as @s (the player).
3. Inside that function, revoke the advancement from that player so it can fire again: advancement revoke @s only <namespace>:<path>.

Because the reward function runs with @s = the completing player and revocation re-arms the listener, this yields reliable, per-player, single-execution event handling with no per-tick scanning — far cheaper and more precise than polling scoreboards for most discrete events.

Detect eating a custom golden apple

data/mypack/advancement/detect/ate_special.json

{
  "criteria": {
    "ate": {
      "trigger": "minecraft:consume_item",
      "conditions": {
        "item": {
          "items": ["minecraft:golden_apple"],
          "predicates": { "minecraft:custom_data": "{special:true}" }
        }
      }
    }
  },
  "rewards": { "function": "mypack:on_ate_special" }
}

data/mypack/function/on_ate_special.mcfunction

# @s is the player who just ate the item
effect give @s minecraft:regeneration 10 2
playsound minecraft:entity.player.levelup player @s
# re-arm the listener so it can fire again next time
advancement revoke @s only mypack:detect/ate_special

Right-click detection via item_used_on_block

Detect right-clicking a custom wand on any block:

data/mypack/advancement/detect/wand_use.json

{
  "criteria": {
    "used": {
      "trigger": "minecraft:item_used_on_block",
      "conditions": {
        "item": { "predicates": { "minecraft:custom_data": "{wand:true}" } }
      }
    }
  },
  "rewards": { "function": "mypack:on_wand_use" }
}

data/mypack/function/on_wand_use.mcfunction

execute at @s anchored eyes run particle minecraft:end_rod ^ ^ ^2 0 0 0 0 1
advancement revoke @s only mypack:detect/wand_use

Mob-kill counter

data/mypack/advancement/detect/killed_zombie.json

{
  "criteria": {
    "kill": {
      "trigger": "minecraft:player_killed_entity",
      "conditions": { "entity": { "type": "minecraft:zombie" } }
    }
  },
  "rewards": { "function": "mypack:count_zombie_kill" }
}

data/mypack/function/count_zombie_kill.mcfunction

scoreboard players add @s zombie_kills 1
advancement revoke @s only mypack:detect/killed_zombie
execute if score @s zombie_kills matches 100.. run function mypack:reward_100_kills

Detection cookbook

Recipe-unlock advancements

Recipes appear in the player's recipe book only once unlocked. Two mechanisms:

1. Automatic discovery — obtaining any item that is an ingredient (or the result) of a recipe auto-unlocks it. This is driven by auto-generated advancements under the minecraft:recipes/... id space.
2. rewards.recipes on an advancement — completing an advancement unlocks the listed recipes. This is exactly how vanilla's minecraft:recipes/<category>/<name> advancements work: each is a hidden advancement whose criteria (inventory_changed, recipe_unlocked, …) detect "player has an ingredient", and whose reward is "recipes": ["minecraft:<recipe>"].

data/minecraft/advancement/recipes/misc/example.json — auto-generated recipe advancement shape

{
  "parent": "minecraft:recipes/root",
  "criteria": {
    "has_ingredient": {
      "trigger": "minecraft:inventory_changed",
      "conditions": { "items": [ { "items": ["minecraft:paper"] } ] }
    },
    "has_the_recipe": {
      "trigger": "minecraft:recipe_unlocked",
      "conditions": { "recipe": "minecraft:example" }
    }
  },
  "requirements": [ ["has_ingredient", "has_the_recipe"] ],
  "rewards": { "recipes": ["minecraft:example"] }
}

Note the no display (recipe advancements are invisible) and the OR requirement — it grants the moment either the ingredient is obtained or the recipe is otherwise unlocked.

To unlock recipes from any advancement, add to its rewards:

"rewards": { "recipes": ["mypack:secret_sword", "mypack:secret_shield"] }

Suppressing the recipe-unlock toast

The "recipe unlocked!" pop-up is controlled on the recipe side, not the advancement side: set "show_notification": false in the recipe JSON.

data/mypack/recipe/secret_sword.json

{
  "type": "minecraft:crafting_shaped",
  "group": "swords",
  "show_notification": false,
  "pattern": ["#", "#", "/"],
  "key": { "#": "minecraft:netherite_ingot", "/": "minecraft:stick" },
  "result": { "id": "minecraft:netherite_sword" }
}

Tabs, roots & backgrounds

Any advancement without a parent and with a valid display becomes a tab in the Advancements GUI. Child advancements (those with parent) render inside their root's tab. The game auto-arranges children into columns, drawing connector arrows to the nearest visible ancestor. A custom tree therefore needs exactly one root per tab.

data/mypack/advancement/root.json — the tab

{
  "display": {
    "icon": { "id": "minecraft:nether_star" },
    "title": "My Pack",
    "description": "Custom challenges",
    "background": "minecraft:textures/gui/advancements/backgrounds/adventure.png",
    "show_toast": false,
    "announce_to_chat": false
  },
  "criteria": { "auto": { "trigger": "minecraft:tick" } }
}

data/mypack/advancement/step_one.json — a child

{
  "parent": "mypack:root",
  "display": {
    "icon": { "id": "minecraft:iron_pickaxe" },
    "title": "Getting Started",
    "description": "Mine some iron",
    "frame": "task"
  },
  "criteria": {
    "iron": {
      "trigger": "minecraft:inventory_changed",
      "conditions": { "items": [ { "items": ["minecraft:iron_ingot"] } ] }
    }
  }
}

Background textures

background is a texture resource path (relative to assets, including the .png). Vanilla tab backgrounds live at minecraft:textures/gui/advancements/backgrounds/:

To use a custom background, ship it in a resource pack at assets/mypack/textures/gui/advancements/backgrounds/mytab.png and reference "background": "mypack:textures/gui/advancements/backgrounds/mytab.png". The texture tiles across the tab; use a seamless 16×16 (or larger) tileable image.

Sources

• Advancement JSON format (schema) — minecraft.wiki
• Advancement definition (schema, triggers, requirements semantics) — minecraft.wiki
• Advancement (GUI concepts, tabs) — minecraft.wiki
• Trigger registry (verbatim, 26.3-snapshot-3) — misode/mcmeta
• mcmeta version pin (version.json, data_pack_version 110)
• Entity predicate — minecraft.wiki
• Data pack (folder rename to singular, 24w21a / pack_format 48) — minecraft.wiki
• Recipe (Java Edition) — show_notification, group, recipe unlocking — minecraft.wiki
• Advancement-based item / right-click detection pattern — MCC wiki
• Carrot-on-a-stick right-click detection — datapack.wiki
• Misode advancement generator (field/UI reference)