> ## 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 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
```json theme={null}
"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](/advancements/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.
```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.
***
## 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](https://minecraft.wiki/w/Advancement/JSON_format#List_of_triggers).
| 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.
```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, NBT, and more.
```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.
***
## 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}
{
"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`.
```json theme={null}
"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 ` on a vanilla advancement that already does something similar and read the exported file. See [Commands](/commands/overview).