> ## 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
> Define criteria and triggers in Custom Advancements JSON files for Minecraft 1.18.2, including requirements logic, common 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` is required on every advancement file. A file without it fails validation and is skipped at load time.
***
## 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 and have no effect 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.
***
## Common Triggers
Custom Advancements does not add any trigger types of its own. It loads advancements that use any trigger Minecraft 1.18.2 natively supports.
| 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 predicate objects |
| `minecraft:player_killed_entity` | The player lands the killing blow on an entity | `entity` — entity condition array; `killing_blow` — damage source predicate |
| `minecraft:killed_by_crossbow` | The player kills one or more entities with a single crossbow shot | `victims`, `unique_entity_types` |
| `minecraft:enter_block` | The player enters a specific block | `block`, `state` |
| `minecraft:item_used_on_block` | The player uses an item on a block | `location`, `item` |
The full list of vanilla triggers and their condition schemas is documented on the [Minecraft Wiki](https://minecraft.wiki/w/Advancement/JSON_format#List_of_triggers). Make sure you are reading the schema for **Java Edition 1.18.2** — the item predicate format in particular changed 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, which need to be granted 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 matches by `"item"` (an exact item ID), `"tag"` (an item tag), count, durability, 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.
In Minecraft 1.18.2 an item predicate uses the **singular** key `"item"` with a single item ID string. The `"items": [...]` array-of-IDs form inside a predicate belongs to Minecraft 1.20.5 and later and will not parse here. To match several different items, list several predicate objects, or use `"tag"` with an item tag.
Matching an item tag instead of a single item:
```json theme={null}
"conditions": {
"items": [
{
"tag": "minecraft:stone_tool_materials"
}
]
}
```
### 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: A Multi-Field Advancement
The following child advancement is granted when the player obtains a Nether Star, and awards 100 experience points on completion.
```json get_star.json theme={null}
{
"display": {
"icon": {
"item": "minecraft:nether_star"
},
"title": {
"text": "Star Collector",
"color": "gold"
},
"description": {
"text": "Obtain a Nether Star."
},
"frame": "challenge",
"show_toast": true,
"announce_to_chat": true
},
"parent": "customadvancements:my_root",
"criteria": {
"get_star": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [
{
"item": "minecraft:nether_star"
}
]
}
}
},
"rewards": {
"experience": 100
}
}
```
Save this file as `customadvancements/customadvancements/story/get_star.json` and run `/ca reload`. It is registered under the resource location `customadvancements:story/get_star`.
***
## 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`.
```json theme={null}
"rewards": {
"experience": 50,
"loot": ["minecraft:chests/simple_dungeon"],
"recipes": ["minecraft:iron_sword"],
"function": "mymod:on_complete"
}
```
The number of experience points awarded to the player.
A list of loot table resource locations. Each table is rolled and the resulting items are placed directly in the player's inventory.
```json theme={null}
"loot": ["minecraft:chests/simple_dungeon"]
```
A list of recipe resource locations to unlock in the player's recipe book.
```json theme={null}
"recipes": ["minecraft:crafting_table"]
```
A single function resource location, run as the player when the advancement is granted.
```json theme={null}
"function": "mynamespace:my_function"
```
All `rewards` sub-fields are optional; include only those you need.
In Minecraft 1.18.2 the loot table field is called `loot`, not `loot_tables`. Using the wrong key causes the rewards block to fail parsing.
For complete working files, see [Examples](/advancements/examples). For the top-level field reference, see [Structure](/advancements/structure).