Custom Advancement Criteria, Triggers, and Rewards

Learn how to define criteria and triggers in Custom Advancements JSON files, including requirements logic, common Minecraft 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
• "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. They are referenced only within the same advancement’s requirements field; they have no meaning outside the file.

criteria is a required top-level field. A file without it fails validation and is skipped with an error in the log — see Structure for all validation rules.

---

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.

---

Common Triggers

Custom Advancements does not add any trigger types of its own. It loads advancements that use any trigger Minecraft natively supports. The table below covers the triggers you are most likely to reach for; the complete list is documented on the Minecraft Wiki.

Trigger	When it fires
minecraft:tick	Every game tick — fires immediately, used for root advancements
minecraft:inventory_changed	The player’s inventory changes, e.g. an item is picked up
minecraft:player_killed_entity	The player lands the killing blow on an entity
minecraft:killed_by_crossbow	The player kills one or more entities with a crossbow
minecraft:location	Based on the player’s current position, biome, or dimension
minecraft:enter_block	The player’s hitbox enters a specific block
minecraft:bred_animals	The player breeds two animals
minecraft:consume_item	The player eats or drinks an item
minecraft:enchanted_item	The player enchants an item at an enchanting table
minecraft:nether_travel	Based on distance traveled in the Nether
minecraft:levitation	The player is levitated for a given duration or distance
minecraft:recipe_unlocked	The player unlocks a crafting recipe

Trigger condition formats changed between Minecraft versions. These pages document the 1.19.3 format — in particular, item predicates use an "item" key ({ "item": "minecraft:diamond" }), not the "id" key used in later 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.

"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, NBT, and more.

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

---

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

{
  "parent": "customadvancements:example",
  "criteria": {
    "back_to_the_roots": {
      "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"
                ]
              }
            }
          }
        }
      },
      "trigger": "minecraft:player_killed_entity"
    }
  },
  "display": {
    "announce_to_chat": true,
    "description": {
      "translate": "customadvancements.advancements.back_to_the_roots.description"
    },
    "frame": "task",
    "hidden": false,
    "icon": {
      "item": "minecraft:rotten_flesh"
    },
    "show_toast": true,
    "title": {
      "translate": "customadvancements.advancements.back_to_the_roots.title"
    }
  },
  "requirements": [
    [
      "back_to_the_roots"
    ]
  ],
  "rewards": {
    "experience": 50
  }
}

---

Rewards

The optional rewards object grants the player something when the advancement is completed. It is placed at the top level of the advancement JSON, alongside criteria and display.

"rewards": {
  "experience": 100,
  "loot": ["minecraft:chests/simple_dungeon"],
  "recipes": ["minecraft:crafting_table"],
  "function": "mymod:on_advancement_complete"
}

Field	Type	Description
experience	integer	XP points awarded
loot	array of strings	Loot tables rolled and given directly to the player’s inventory
recipes	array of strings	Recipes unlocked in the recipe book
function	string	Server-side function run as the player

All rewards sub-fields are optional; include only those you need.

Not sure what a complex conditions block should look like? Run /ca generate advancement <advancement> on a vanilla advancement that already does something similar and read the exported file. See Commands.