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

"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.

"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

"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.

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.

"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.

"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.

"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.

"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.

back_to_the_roots.json

{
  "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.

"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.