> ## Documentation Index > Fetch the complete documentation index at: https://customadvancements-wiki.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Custom Advancement Criteria, Triggers, and Rewards > Learn how to define criteria and triggers in Custom Advancements JSON files, including requirements logic, common Minecraft 1.16.5 triggers, and rewards. Criteria define the conditions a player must meet to earn an advancement. Each criterion listens for a specific game event — called a **trigger** — and optionally narrows it down with a `conditions` block. An advancement can require one criterion or many, and the `requirements` field gives you precise control over which combination must be satisfied. ## Criteria Object Structure The `criteria` field is a JSON object where each key is an arbitrary name you give to a criterion, and the value is an object with: * `"trigger"` — the namespaced ID of the Minecraft advancement trigger to listen for (required) * `"conditions"` — an optional object whose shape depends on the chosen trigger ```json theme={null} "criteria": { "has_diamond": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [ { "item": "minecraft:diamond" } ] } } } ``` Criterion names are arbitrary strings, but they must be unique within the advancement. They are referenced only by that advancement's own `requirements` field and in log output; they have no meaning outside the file. ## Requirements Logic The optional `requirements` field is a two-dimensional array that expresses a logical combination of criteria using AND and OR. * The **outer** array is AND — every inner array must be satisfied. * Each **inner** array is OR — at least one criterion in the group must be satisfied. ```json theme={null} "requirements": [ ["criterion_a", "criterion_b"], ["criterion_c"] ] ``` This reads as: `(criterion_a OR criterion_b) AND criterion_c`. If `requirements` is omitted, every criterion defined in the `criteria` object must be satisfied, which is equivalent to putting each criterion in its own group. ### Combined AND/OR Example ```json theme={null} "criteria": { "has_food": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [{ "item": "minecraft:bread" }] } }, "has_weapon": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [{ "item": "minecraft:iron_sword" }] } }, "has_armor": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [{ "item": "minecraft:iron_chestplate" }] } }, "has_alt_armor": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [{ "item": "minecraft:chainmail_chestplate" }] } } }, "requirements": [ ["has_food"], ["has_weapon"], ["has_armor", "has_alt_armor"] ] ``` The player must have bread AND an iron sword AND either an iron or a chainmail chestplate. ## Common Triggers Custom Advancements does not add any trigger types of its own. It loads advancements that use any trigger Minecraft 1.16.5 natively supports. The table below covers the triggers most useful for custom advancements; the complete list is documented on the [Minecraft Wiki — Advancement triggers](https://minecraft.wiki/w/Advancement/JSON_format#List_of_triggers). | Trigger | When it fires | Key condition fields | | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | | `minecraft:tick` | Every game tick | None — always fires | | `minecraft:inventory_changed` | The player's inventory changes | `items` — array of item predicates | | `minecraft:player_killed_entity` | The player lands the killing blow on an entity | `entity` — entity condition array; `killing_blow` — damage source predicate | | `minecraft:enter_block` | The player's hitbox enters a block | `block`, `state` | | `minecraft:location` | Checked periodically against the player's position | `position`, `biome`, `dimension`, `feature` | | `minecraft:consume_item` | The player finishes eating or drinking | `item` — item predicate | | `minecraft:placed_block` | The player places a block | `block`, `state`, `item`, `location` | | `minecraft:recipe_unlocked` | A recipe is added to the player's recipe book | `recipe` | | `minecraft:bred_animals` | The player breeds two mobs | `parent`, `partner`, `child` | | `minecraft:tame_animal` | The player tames an animal | `entity` | | `minecraft:villager_trade` | The player completes a villager trade | `item`, `villager` | | `minecraft:fishing_rod_hooked` | The player reels in a fishing rod | `item`, `entity`, `rod` | | `minecraft:shot_crossbow` | The player fires a crossbow | `item` | | `minecraft:killed_by_crossbow` | The player kills entities with one crossbow shot | `unique_entity_types`, `victims` | | `minecraft:summoned_entity` | The player summons an entity | `entity` | | `minecraft:nether_travel` | The player leaves the Nether after entering through a portal | `distance`, `entered`, `exited` | Trigger names and condition formats are version-specific. The examples on this page use the Minecraft **1.16.5** format — most notably, item predicates use `"item"` rather than `"id"`, which differs from later Minecraft versions. ## Trigger Examples ### minecraft:tick The simplest possible criterion. The `minecraft:tick` trigger fires on every game tick, so the advancement completes the instant the player loads in. This is the standard pattern for root advancements, which need to complete immediately so their tab is always visible. ```json theme={null} "criteria": { "requirement": { "trigger": "minecraft:tick" } } ``` ### minecraft:inventory\_changed Fires whenever the player's inventory is modified. The `items` array lists item predicates — each object can match by `"item"` (exact item), `"tag"` (item tag), count, durability, enchantments, and NBT. ```json theme={null} "criteria": { "requirement": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [ { "item": "minecraft:dirt" } ] } } } ``` This criterion fires as soon as any dirt appears in the player's inventory. ### minecraft:player\_killed\_entity Fires when the player is the direct cause of an entity's death. The `entity` field is an array of condition objects, each with a `"condition"` type key. The `killing_blow` field inspects the damage source, including the item held when the kill was made. ```json theme={null} "criteria": { "back_to_the_roots": { "trigger": "minecraft:player_killed_entity", "conditions": { "entity": [ { "condition": "minecraft:entity_properties", "entity": "this", "predicate": { "type": "minecraft:zombie", "flags": { "is_baby": false } } } ], "killing_blow": { "direct_entity": { "equipment": { "mainhand": { "items": [ "minecraft:rotten_flesh" ] } } } } } } } ``` This criterion fires when the player kills an adult zombie while holding rotten flesh in their main hand. ### minecraft:location Fires periodically based on where the player is standing. Useful for "reach this dimension/biome" objectives. ```json theme={null} "criteria": { "in_nether": { "trigger": "minecraft:location", "conditions": { "dimension": "minecraft:the_nether" } } } ``` ## Complete Example: back\_to\_the\_roots.json The following is the full `back_to_the_roots.json` example file shipped with the mod. It demonstrates a single-criterion advancement with an explicit `requirements` array and an experience reward. ```json back_to_the_roots.json theme={null} { "display": { "icon": { "item": "minecraft:rotten_flesh" }, "title": { "translate": "customadvancements.advancements.back_to_the_roots.title" }, "description": { "translate": "customadvancements.advancements.back_to_the_roots.description" }, "frame": "task", "show_toast": true, "announce_to_chat": true, "hidden": false }, "parent": "customadvancements:example", "criteria": { "back_to_the_roots": { "trigger": "minecraft:player_killed_entity", "conditions": { "entity": [ { "condition": "minecraft:entity_properties", "entity": "this", "predicate": { "type": "minecraft:zombie", "flags": { "is_baby": false } } } ], "killing_blow": { "direct_entity": { "equipment": { "mainhand": { "items": [ "minecraft:rotten_flesh" ] } } } } } } }, "requirements": [ ["back_to_the_roots"] ], "rewards": { "experience": 50 } } ``` ## Rewards The optional `rewards` object grants the player something when the advancement is completed. It sits at the top level of the advancement JSON, alongside `criteria` and `display`. Every sub-field is optional — include only the ones you need, and combine as many as you like. ```json theme={null} "rewards": { "experience": 500, "loot": ["minecraft:chests/simple_dungeon"], "recipes": ["minecraft:iron_sword"], "function": "mypack:on_complete" } ``` | Field | Type | Description | | ------------ | ---------------- | ------------------------------------------------------------------------------------------------ | | `experience` | integer | XP **points** (not levels) added directly to the player's XP bar | | `loot` | array of strings | Loot tables rolled once each, with the resulting items placed directly in the player's inventory | | `recipes` | array of strings | Recipes unlocked in the player's recipe book | | `function` | string | A single function run as and at the player who earned the advancement | The loot table field is named `loot` in Minecraft 1.16.5 — not `loot_tables`. Referenced loot tables, recipes, and functions must exist on the server when the advancement is completed, otherwise the game logs an error and skips that reward. Only one `function` can be specified per advancement. If you need to run several, point it at a function that calls the others. For complete working files that put criteria, requirements, and rewards together, see [Examples](/advancements/examples).