Index

Generic info

1. Intro
2. Errors

File editing

3. Location

4. Referencing
5. Replacing default advancements

6. Editing

Shared data structures

7. JSON structure
8. Shared: range
9. Shared: location object
10. Shared: distance object
11. Shared: status effects object
12. Shared: item object
13. Shared: entity object
14. Shared: block object
15. Shared: damage object
16. Shared: damage flags object
17. Shared: death object

Customizing advancements

18. Criteria

19. Requirements
20. Display

21. Rewards
22. Tree display

Conclusion

23. Q&A
24. External links

Generic info

Intro

Errors

Game Output window

To open the Game Output window when launching the game, you must enable it in the "Settings" tab of the launcher.



This window will show the error and stacktrace explaining the issue.

Log files

If you no longer have the Game Output window open, you can check the output log. You can quickly access the Minecraft program files in the launcher by navigating to Launch Options -> + Add New, and clicking the "Go to folder" button:



From there, navigate to the /logs/latest.log file, which will contain the stacktrace. In this case, the error is stating that the advancement has a display, but is missing a description:

[07:02:59] [Server thread/ERROR]: Parsing error loading custom advancement custom:example
com.google.gson.JsonSyntaxException: Missing description
    at qe.a(SourceFile:447) ~[17w15a.jar:?]
    at r.a(SourceFile:66) ~[17w15a.jar:?]

[/pre]
[spoiler=Advancement(s)]
Paste advancement(s) here, along with filepath[/spoiler]
[spoiler=Error]
Paste error & stacktrace here[/spoiler]
[pre]

File editing

File location

Namespaces

The root folder that you create within the /advancements/ folder will be referred to as the "namespace". This is what separates collections of advancements, such as for different mods or maps. File/folder names must all be lowercase to circumvent issues with differing operating system file structures.

From the image example above, "skylinerwadvancements", "anothermod", and "minecraft" are the namespaces.

The "minecraft" namespace in particular should only be used to overwrite default advancements, such as with the intent to prevent them from working. Place any new advancements in a new namespace and not within "minecraft".

Referencing

[namespace]:[filepath/to/advancement]

Example, targeting the file /data/advancements/anothermod/challenges/kill_creepers.json:

anothermod:challenges/kill_creepers

By excluding the namespace, it will automatically assume it's meant to be "minecraft":

story/elytra = minecraft:story/elytra

Replacing default advancements

{
    "display": {
        "icon": {
            "item": "minecraft:elytra"
        },
        "title": "Learn to Fly"
    },
    "parent": "minecraft:story/enter_end_gateway",
    "criteria": {
        "elytra": {
            "trigger": "minecraft:inventory_changed",
            "conditions": {
                "items": [
                    {
                        "item": "minecraft:elytra",
                        "data": 1
                    }
                ]
            }
        }
    }
}

List of default advancements

The following is a list of default advancements. Be aware that this will dramatically change over time.

https://pastebin.com/L7G1RBdC

Editing

1. Click Save or Save As.
2. Set "Save as type" to "All files (*.*)".
3. Name your file and append the name with ".json".
4. Set "Encoding" to "UTF-8".
5. Save.

Image example:

2. Notepad++ is a great alternative to using plain Notepad. Instructions for saving a .json in UTF-8:

1. Change the encoding to either "UTF-8" or "UTF-8 without BOM" under the "Encoding" menu. See image below.
2. Click Save or Save As.
3. Set "Save as type" to "All files (*.*)".
4. Name your file and append the name with ".json".
5. Save.

Image example:

3. Atom has multiple platform support. Instructions for saving a .json in UTF-8:

1. Change the encoding to "UTF-8" under the "Select Encoding" menu. See image below.
2. Click Save or Save As.
3. Set "Save as type" to "All files (*.*)".
4. Name your file and append the name with ".json".
5. Save.

Image example:

Shared data structures

JSON Structure

{
    "criteria": {
        "custom_trigger_name": {
            "trigger": "namespace:trigger_name",
            "conditions": {
                "durability": 1,
                "durability": {"min":1,"max":1},
                "delta": 1,
                "delta": {"min":1,"max":1},
                "slots": {
                    "occupied": 1,
                    "occupied": {"min":1,"max":1},
                    "full": 1,
                    "full": {"min":1,"max":1},
                    "empty": 1,
                    "empty": {"min":1,"max":1}
                },
                "items": [
                    {
                        "item": "minecraft:stone",
                        "count": 1,
                        "count": {"min":1,"max":1},
                        "data": 1,
                        "data": {"min":1,"max":1},
                        "durability": 1,
                        "durability": {"min":1,"max":1},
                        "potion": "minecraft:invisibility",
                        "enchantments": [
                            {
                                "enchantment": "minecraft:sharpness",
                                "levels": 1,
                                "levels": {"min":1,"max":1}
                            }
                        ]
                    }
                ],
                "item": {
                    "item": "minecraft:stone",
                    "count": 1,
                    "count": {"min":1,"max":1},
                    "data": 1,
                    "data": {"min":1,"max":1},
                    "durability": 1,
                    "durability": {"min":1,"max":1},
                    "potion": "minecraft:invisibility",
                    "enchantments": [
                        {
                            "enchantment": "minecraft:sharpness",
                            "levels": 1,
                            "levels": {"min":1,"max":1}
                        }
                    ]
                },
                "levels": 1,
                "levels": {"min":1,"max":1},
                "recipe": "minecraft:chest",
                "position": {
                    "x": 1,
                    "x": {"min":1,"max":1},
                    "y": 1,
                    "y": {"min":1,"max":1},
                    "z": 1,
                    "z": {"min":1,"max":1}
                },
                "biome": "minecraft:void",
                "feature": "EndCity",
                "dimension": "overworld",
                "from": "overworld",
                "to": "overworld",
                "block": "minecraft:stone",
                "state": {
                    "state_name": "state_value"
                },
                "entity": {
                    "type": "minecraft:creeper",
                    "distance": 1,
                    "distance": {"min":1,"max":1}
                },
                "killing_blow": {
                    "bypasses_armor": true,
                    "bypasses_invulnerability": true,
                    "bypasses_magic": true,
                    "is_explosion": true,
                    "is_fire": true,
                    "is_magic": true,
                    "is_projectile": true,
                    "direct_entity": {
                        "type": "minecraft:creeper",
                        "distance": 1,
                        "distance": {"min":1,"max":1}
                    },
                    "source_entity": {
                        "type": "minecraft:creeper",
                        "distance": 1,
                        "distance": {"min":1,"max":1}
                    }
                },
                "distance": 1,
                "distance": {"min":1,"max":1},
                "parent": {
                    "type": "minecraft:creeper",
                    "distance": 1,
                    "distance": {"min":1,"max":1}
                },
                "partner": {
                    "type": "minecraft:creeper",
                    "distance": 1,
                    "distance": {"min":1,"max":1}
                }
                "child": {
                    "type": "minecraft:creeper",
                    "distance": 1,
                    "distance": {"min":1,"max":1}
                },
                "potion": "minecraft:invisibility",
                "level": 1,
                "level": {"min":1,"max":1},
                "damage": {
                    "dealt": 1,
                    "dealt": {"min":1,"max":1},
                    "taken": 1,
                    "taken": {"min":1,"max":1},
                    "blocked": true,
                    "type": {
                        "bypasses_armor": true,
                        "bypasses_invulnerability": true,
                        "bypasses_magic": true,
                        "is_explosion": true,
                        "is_fire": true,
                        "is_magic": true,
                        "is_projectile": true,
                        "direct_entity": {
                            "type": "minecraft:creeper",
                            "distance": 1,
                            "distance": {"min":1,"max":1}
                        },
                        "source_entity": {
                            "type": "minecraft:creeper",
                            "distance": 1,
                            "distance": {"min":1,"max":1}
                        }
                    },
                    "source_entity": {
                        "type": "minecraft:creeper",
                        "distance": 1,
                        "distance": {"min":1,"max":1}
                    }
                }
            }
        }
    },
    "requirements": [["generic_trigger_name"]],
    "parent": "namespace:path/to/parent_advancement",
    "display": {
        "icon": {
            "item": "minecraft:stone_pickaxe",
            "data": 0
        },
        "title": "Display title",
        "description": "Display description",
        "frame": "task",
        "background": "minecraft:path/to/texture.png"
    },
    "rewards": {
        "recipes": ["namespace:path/to/recipe"],
        "loot": ["namespace:path/to/loot_table"],
        "experience": 1,
        "commands": ["/say Command to run upon completion"]
    }
}

Shared: range

"occupied": 3

To check between two values, the range must be specified as an object containing "min" and "max" numbers. The following checks if the compared value is between 1 and 3.

"occupied": {
    "min": 1,
    "max": 3
}

You can alternatively specify only the minmum or only the maximum, which will ignore a check for the opposing limiter. For example, the following checks if there are at least 3 occupied slots. The player's inventory could have 7 occupied slots and they will still match.

"occupied": {
    "min": 3
}

Versus the opposite, where the following checks if there are at most 2 occupied slots. The player's inventory could have 0 occupied slots and they will still match.

"occupied": {
    "max": 2
}

Shared: location object

"location_object": {
    "position": {
        "y": {
            "max": 62.0
        }
    }
}

2. "biome"

The "biome" string specifies the name ID of the biome that the player must stand within. You can find a list of name IDs for biomes here. The following checks if the player has visited the "minecraft:desert" biome.

"location_object": {
    "biome": "minecraft:desert"
}

3. "feature"

The "feature" string specifies the name ID of a structure. The player must be standing within the bounding box of that structure to be detected. The following checks if the player is inside an "EndCity" structure.

"location_object": {
    "feature": "EndCity"
}

4. "dimension"

The "dimension" string specifies the name ID of a dimension to find the player in. Accepted values are "overworld", "the_nether", and "the_end". The following checks if the player is anywhere in the nether.

"location_object": {
    "dimension": "the_nether"
}

Shared: distance object

"distance_object": {
    "x": {
        "max": 40.0
    }
}

2. "absolute"

The "absolute" range checks if the player is within a number of blocks on all axes. You would use this instead of "x/y/z" if all axes are uniform. The following checks if the player is outside a 5-block range of an origin.

"distance_object": {
    "absolute": {
        "min": 5.0
    }
}

3. "horizontal"

The "horizontal" range checks if the player is within a number of blocks on the X and Z axes, ignoring the Y axis. The following checks if the player is withn a 10-block range of an origin, but only on the X and Z axes.

"distance_object": {
    "horizontal": {
        "max": 10.0
    }
}

Shared: status effects object

"effects_object": {
    "minecraft:levitation": {
        "amplifier": {
            "min": 10
        }
    }
}

2. "duration"

The "duration" range checks the remaining duration in ticks of the specified effect. The following checks if the effect has at least 15 seconds (300 ticks) remaining.

"effects_object": {
    "minecraft:levitation": {
        "duration": {
            "max": 300
        }
    }
}

3. "ambient"

The "ambient" boolean checks if the effect has the "ambient" flag set to true.

"effects_object": {
    "minecraft:levitation": {
        "ambient": true
    }
}

4. "visible"

The "visible" boolean checks if the effect has the "visible" flag set to true.

"effects_object": {
    "minecraft:levitation": {
        "visible": true
    }
}

Shared: item object

"item_object": {
    "item": "minecraft:redstone"
}

2. "data"

The "data" integer specifies a metadata of the item. The following checks if the item is a polished granite block.

"item_object": {
    "item": "minecraft:stone",
    "data": 2
}

3. "durability

The "data" range specifies the remaining durability of an item. The following checks if the item has 400 or more durability remaining.

"item_object": {
    "durability": {
        "min": 400
    }
}

4. "count"

The "count" range specifies the number of items in a single stack. This cannot be used to check the number of items across the inventory as a whole. The following checks if the item has 16 or more in its stack.

"item_object": {
    "count": {
        "min": 16
    }
}

5. "potion"

The "potion" string specifies the default brewed potion ID that the item must contain, specified in the Potion NBT string. The wiki contains a list of those IDs here.

"item_object": {
    "potion": "minecraft:invisibility"
}

The item does not have to be a potion. As long as the item has the Potion NBT string, it will match:

/give @p minecraft:stone 1 0 {Potion:"minecraft:invisibility"}

6. "enchantments"

The "enchantments" list checks the item's enchantments (whether in the ench NBT list for all items excluding books, or the StoredEnchantments NBT list for only books) for matching data. If only an empty object is specified, the player's inventory is checked for any enchanted items.

"item_object": {
    "enchantments": [
        {
            
        }
    ]
}

The "enchantment" string will specify the enchantment ID to look for. The following checks the item for the Sharpness enchantment.

"item_object": {
    "enchantments": [
        {
            "enchantment": "minecraft:sharpness"
        }
    ]
}

The "levels" range will specify the range of levels to find for an enchantment. The following checks if the player has any enchantments level 3 or higher.

"item_object": {
    "enchantments": [
        {
            "levels": {
                "min": 3
            }
        }
    ]
}

And combining it with an ID, the following checks if the player has Sharpness 5.

"item_object": {
    "enchantments": [
        {
            "enchantment": "minecraft:sharpness"
            "levels": 5
        }
    ]
}

7. "nbt"

The "nbt" string compares the raw NBT input to the item's NBT data. This raw data starts within the "tag" compound of the item format and must be surrounded by curly brackets. The following checks if the item has a specific display name.

"item_object": {
    "nbt": "{display:{Name:\"Test\"}}"
}

Shared: entity object

"entity_object": {
    "type": "minecraft:creeper"
}

2. "distance"

The "distance" distance object specifies the distance between the advancement-earning player and an entity's origin. The following checks if the player is within 10 blocks of the entity.

"entity_object": {
    "distance": {
        "absolute": {
            "max": 10
        }
    }
}

3. "location"

The "location" location object checks data concerning the entity's location in the world. The following checks if the entity is in the desert biome.

"entity_object": {
    "location": {
        "biome": "minecraft:desert"
    }
}

4. "effects"

The "effects" status effects object checks data concerning the entity's status effects. The following checks if the entity has Speed 2.

"entity_object": {
    "effects": {
        "minecraft:speed": {
            "amplifier": 2
        }
    }
}

5. "nbt"

The "nbt" string compares the raw NBT input to the entity's NBT data. This raw data starts within the root of the entity format and must be surrounded by curly brackets. The following checks if the entity has a specific tag within its "Tags" list.

"entity_object": {
    "nbt": "{Tags:[\"findme\"]}"
}

Shared: block object

"block_object": {
    "block": "minecraft:tallgrass"
}

2. "state"

The "state" object contains a list of custom keys, much like "criteria" does. The names for these keys will correspond to the blockstate name you want to detect, and the value corresponds to possible values for that blockstate. For "minecraft:tallgrass", the "type" blockstate specifies which of the tallgrass blocks it is. The "block" string must be specified to use this condition. The following checks if the tallgrass is a fern.

"block_object": {
    "block": "minecraft:tallgrass",
    "state": {
        "type": "fern"
    }
}

Shared: damage object

"damage_object": {
    "dealt": {
        "min": 4.0
    },
    "source_entity": {
        "type": "minecraft:arrow"
    }
}

2. "taken"

A range checking the incoming damage after damage reduction. For example, the following checks if the resulting damage after reductions was at least 5.0.

"damage_object": {
    "taken": {
        "min": 5.0
    }
}

3. "blocked"

Checks if the incoming damage was successfully blocked, provided that the "damage_flags_object.bypasses_armor" ("unblockable") flag isn't true. The following checks if the player failed to block a skeleton's attack (either by an arrow or melee weapon).

"damage_object": {
    "blocked": false,
    "source_entity": {
        "type": "minecraft:skeleton"
    }
}

4. "type"

A damage flag object that checks various flags about the damage. The following checks if the damage was a projectile caused by a skeleton (though does not necessarily mean the direct cause of the damage was an arrow).

"damage_object": {
    "type": {
        "is_projectile": true
    },
    "source_entity": {
        "type": "minecraft:skeleton"
    }
}

5. "source_entity"

An entity object that checks information about either the entity hit or the entity dealing the damage. Note that for players being the source entity, the nested "type" string can essentially only be "minecraft:player". The following checks if a skeleton was at least 10 blocks away when it hit the player.

"damage_object": {
    "source_entity": {
        "type": "minecraft:skeleton",
        "distance": {
            "min": 10
        }
    }
}

Shared: damage flags object

"damage_object": {
    "bypasses_armor": true
}

2. "bypasses_invulnerability"

Checks if the damage source can inflict damage on creative mode players. This is true for: void damage. The following checks if the incoming damage is not caused by the Void or /kill.

"damage_object": {
    "bypasses_invulnerability": false
}

3. "bypasses_magic"

Checks the "damageIsAbsolute" flag for the incoming damage. This is true for: starvation. The following checks if the player is taking starvation damage.

"damage_object": {
    "bypasses_magic": true
}

4. "is_explosion"

Checks the "explosion" flag for the incoming damage. This is true for: creepers, ender crystals, TNT, Minecart TNT, ghast fireballs, beds, the wither, and wither skulls. The following checks if the "explosion" flag is true.

"damage_object": {
    "explosion": true
}

5. "is_fire"

Checks the "fire" flag for the incoming damage. This is true for: standing in a fire block, being on fire, standing on magma, standing in lava, ghast fireballs, and blaze fireballs. The following checks if the player is not taking damage from fire sources.

"damage_object": {
    "is_fire": false
}

6. "is_magic"

Checks the "magicDamage" flag for the incoming damage. This is true for: thorns, Instant Damage effect, Poison effect, part of Guardian laser damage, evocation fangs, and un-owned wither skulls (via /summon). The following checks if the incoming damage is flagged as magic damage.

"damage": {
    "is_magic": true
}

7. "is_projectile"

Checks the "projectile" flag for the incoming damage. This is true for: arrows, ghast fireballs, blaze fireballs, enderpearls, eggs, snowballs, shulker bullets, and llama spit. The following checks if the incoming damage is specifically not a projectile.

"damage": {
    "is_projectile": false
}

8. "source_entity"

An entity object that specifies the "owner" of the damage. For example, if the player was hit by an arrow shot by a skeleton, the skeleton would be the "source entity". The damage object already makes use of this check, so it is pointless to specify a source entity twice. This particular check is still useful for triggers that only use a damage flags object rather than a damage object.

"damage": {
    "source_entity": {
        "type": "minecraft:skeleton"
    }
}

9. "direct_entity"

An entity object that specifies the direct cause of the damage. For example, if the player was hit by an arrow shot by a skeleton, the arrow would be the "direct entity". The following ensures the player was hit by an arrow shot by a skeleton.

"damage": {
    "direct_entity": {
        "type": "minecraft:arrow"
    },
    "source_entity": {
        "type": "minecraft:skeleton"
    }
}

Shared: death object

"death_object": {
    "entity": {
        "type": "minecraft:creeper"
    }
}

2. "killing_blow"

A damage flags object that contains damage flags about the killing blow against the dead entity. Be aware that this is not the damage object, so the options from that object are unavailable. The following checks if the entity had died due to an explosion.

"death_object": {
    "killing_blow": {
        "is_explosion": true
    }
}

Customizing advancements

Criteria

{
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:bred_animals"
        },
        "take_damage": {
            "trigger": "minecraft:entity_hurt_player"
        }
    }
}

While the following advancement is granted provided either the "custom_test_name" and "take_damage" criteria succeeds. See the Requirements section for more details.

{
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:bred_animals"
        },
        "take_damage": {
            "trigger": "minecraft:entity_hurt_player"
        }
    },
    "requirements": [["custom_test_name"], ["take_damage"]]
}

The custom criteria names are local to that file and cannot be referred to in other files.

Triggers

Go to list of triggers

Processing order of triggers

The following timeline describes the order in which specific triggers activate in each game tick. This can be useful when running a function as a reward. For example, if you needed to run commands before entities are processed (and after command blocks are processed), the "minecraft:tick" trigger will do so. If you needed to run commands after entities are processed, you would use the "gameLoopFunction" gamerule to run the necessary function.

Requirements

{
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:entity_hurt_player"
        },
        "trigger_2": {
            "trigger": "minecraft:used_ender_eye"
        }
    },
    "requirements": [
        ["trigger_1"], ["trigger_2"]
    ]
}

Both "trigger_1" and "trigger_2" criteria must be fulfilled before the advancement can be granted. Since that would be the case without "requirements", it is not necessary to use it here. Using logical operators, this can be viewed as:

"trigger_1" && "trigger_2"

Modifying the requirements list slightly, which joins "trigger_2" with "trigger_1":

{
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:entity_hurt_player"
        },
        "trigger_2": {
            "trigger": "minecraft:used_ender_eye"
        }
    },
    "requirements": [
        ["trigger_1", "trigger_2"]
    ]
}

Now either "trigger_1" or "trigger_2" must be completed to be granted the advancement. Using logical operators, this can be viewed as:

"trigger_1" || "trigger_2"

{
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:entity_hurt_player"
        },
        "trigger_2": {
            "trigger": "minecraft:used_ender_eye"
        },
        "trigger_3": {
            "trigger": "minecraft:player_killed_entity"
        }
    },
    "requirements": [
        ["trigger_1"],
        ["trigger_2", "trigger_3"]
    ]
}

The advancement is granted if the "trigger_1" criterion is met, while either "trigger_2" and "trigger_3" are also met. If only "trigger_1" is completed, the advancement is not granted. Using logical operators, this can be viewed as:

"trigger_1" && ("trigger_2" || "trigger_3")

And modifying the requirements slightly:

{
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:entity_hurt_player"
        },
        "trigger_2": {
            "trigger": "minecraft:used_ender_eye"
        },
        "trigger_3": {
            "trigger": "minecraft:player_killed_entity"
        }
    },
    "requirements": [
        ["trigger_1", "trigger_2", "trigger_3"]
    ]
}

The advancement is granted if any of the criteria are met. Using logical operators, this can be viewed as:

"trigger_1" || "trigger_2" || "trigger_3"

Display

Title, description, & icon

When the "display" object exists, the "title", "description", and "icon" tags must be specified. The background for the icon for each advancement will range from gray to red depending on the number of criteria fulfilled in that advancement.

1. "title"

The title can either be a simple string or a text component object. This title is shown in the "Advancements" menu when hovering over the icon, as well as in the popup notification when completing the advancement.

Given the following advancement, which uses a simple string for the title:

{
    "display": {
        "title": "Stew",
        "description": "",
        "icon": {
            "item": "minecraft:mushroom_stew"
        },
        "background": "minecraft:textures/gui/advancements/backgrounds/stone.png"
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:location"
        }
    }
}

This will display as:



Or you can specify formatting for the text using the text component (note that many text component features are unavailable, such as selectors, scores, and event listeners):

{
    "display": {
        "title": {"text":"Stew","obfuscated":true},
        "description": "",
        "icon": {
            "item": "minecraft:mushroom_stew"
        },
        "background": "minecraft:textures/gui/advancements/backgrounds/stone.png"
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:location"
        }
    }
}

This will display as:



2. "description"

The description can either be a simple string or a text component object. This description is shown in the "Advancements" menu when hovering over the icon, but not in the popup notification when completing the advancement. The description can be blank for no description to appear, but the tag itself must still exist.

Given the following advancement, which uses a simple string for the description:

{
    "display": {
        "icon": {
            "item": "minecraft:elytra"
        },
        "title": "Learn to Fly",
        "description": "Learn how to fly using a new pair of elytra.",
        "background": "minecraft:textures/gui/advancements/backgrounds/stone.png"
    },
    "criteria": {
        "elytra": {
            "trigger": "minecraft:inventory_changed",
            "conditions": {
                "items": [
                    {
                        "item": "minecraft:elytra",
                        "data": 1
                    }
                ]
            }
        }
    }
}

This will display as:



Or you can specify formatting for the text using the text component (note that many text component features are unavailable, such as selectors, scores, and event listeners):

{
    "display": {
        "icon": {
            "item": "minecraft:elytra"
        },
        "title": "Learn to Fly",
        "description": {"text":"Learn how to fly using a new pair of elytra.","italic":true},
        "background": "minecraft:textures/gui/advancements/backgrounds/stone.png"
    },
    "criteria": {
        "elytra": {
            "trigger": "minecraft:inventory_changed",
            "conditions": {
                "items": [
                    {
                        "item": "minecraft:elytra",
                        "data": 1
                    }
                ]
            }
        }
    }
}

This will display as:



3. "icon"

The "icon" object holds a required item ID and an optional metadata value of the item. This icon is shown in the "Advancements" menu, as well as in the popup notification when completing the advancement. The following icon specifies red wool

"icon": {
    "item": "minecraft:wool",
    "data": 14
}

Background

The "background" is an optional string for all advancements, but is only used by "root" advancements (i.e. when no parent is defined). This is the background that appears behind all of the icons. The value is a resource location to any image within a resource pack. For example, the following advancement will display a tiled gold block background, coming from the default block texture:

{
    "display": {
        "title": "Stew",
        "description": "",
        "icon": {
            "item": "minecraft:mushroom_stew"
        },
        "background": "minecraft:textures/blocks/gold_block.png"
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:location"
        }
    }
}

Image of the result:

Frame

An optional "frame" string modifies the border shape around the icon, accepting one of three possible values: "task", "challenge", and "goal". When not specified, it will default to "task".

The following advancement makes use of the "challenge" frame.

{
    "display": {
        "title": "Stew",
        "description": "",
        "icon": {
            "item": "minecraft:mushroom_stew"
        },
        "background": "minecraft:textures/blocks/gold_block.png",
        "frame": "challenge"
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:location"
        }
    }
}

The following advancement makes use of the "goal" frame.

{
    "display": {
        "title": "Stew",
        "description": "",
        "icon": {
            "item": "minecraft:mushroom_stew"
        },
        "background": "minecraft:textures/blocks/gold_block.png",
        "frame": "goal"
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:location"
        }
    }
}

Show toast

An optional "show_toast" boolean can be specified in order to prevent the popup notification in the upper right-hand corner of the screen from appearing when the player fulfills an advancement. It defaults to true, and setting it to false will hide the popup.

{
    "display": {
        "title": "Stew",
        "description": "",
        "icon": {
            "item": "minecraft:stone"
        },
        "background": "minecraft:textures/blocks/gold_block.png",
        "show_toast": false
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:tick"
        }
    }
}

Announce to chat

An optional "announce_to_chat" boolean can be specified in order to prevent a chat message from being sent telling all players that somebody fulfilled an advancement. It defaults to true, and setting it to false will prevent chat messages from being sent.

{
    "display": {
        "title": "Stew",
        "description": "",
        "icon": {
            "item": "minecraft:stone"
        },
        "background": "minecraft:textures/blocks/gold_block.png",
        "announce_to_chat": false
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:tick"
        }
    }
}

The announceAdvancements gamerule can globally disable fulfillment messages, overriding the value of "announce_to_chat" for individual advancements.

/gamerule announceAdvancements false

Hidden

An optional "hidden" boolean can be specified in order to prevent child advancements from displaying in the "Advancements" menu until they are completed.

{
    "display": {
        "title": "Stew",
        "description": "",
        "icon": {
            "item": "minecraft:stone"
        },
        "background": "minecraft:textures/blocks/gold_block.png",
        "announce_to_chat": false,
        "hidden": true
    },
    "criteria": {
        "trigger_1": {
            "trigger": "minecraft:impossible"
        }
    }
}

Rewards

"recipes"

This list specifies multiple recipes to unlock for the player upon completing the advancement. The following advancement unlocks the "minecraft:redstone" and "minecraft:ladder" recipes together.

{
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:entity_hurt_player"
        }
    },
    "rewards": {
        "recipes": ["minecraft:redstone", "minecraft:ladder"]
    }
}

"loot"

This list specifies multiple loot tables to process, providing the player with the resulting item(s). The following advancement provides players with items from "minecraft:entities/creeper" and "minecraft:chests/simple_dungeon".

{
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:entity_hurt_player"
        }
    },
    "rewards": {
        "loot": ["minecraft:entities/creeper", "minecraft:chests/simple_dungeon"]
    }
}

"experience"

This number (not range) specifies the amount of experience (not levels) to reward the player with.

{
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:entity_hurt_player"
        }
    },
    "rewards": {
        "experience": 500
    }
}

"function"

This string specifies a single function file to run, with the value being the resource location to that function. The player will be considered the command sender and CommandStats trigger target, which means sender bias (such as from "@s") will always target that player, and that player will trigger their own stored CommandStats. Each command will run in the specified order in the function. If the advancement is granted via command block, all of the listed commands will execute immediately, allowing other command blocks further in the chain to run based off of the results of the advancement's function being run (although you do not need to use advancements for this if focusing on functions).

{
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:entity_hurt_player"
        }
    },
    "rewards": {
        "function": "path:to/function"
    }
}

{
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:entity_hurt_player"
        }
    },
    "rewards": {
        "recipes": ["minecraft:redstone", "minecraft:ladder"],
        "loot": ["minecraft:entities/creeper", "minecraft:chests/simple_dungeon"],
        "experience": 500,
        "function": "path:to/function"
    }
}

Tree display

Root

A root advancement will be one without a parent defined. If a root has a display, it will be the left-most icon in the tree. If a root does not have a display, a tab in the "Advancements" menu will not be shown, effectively hiding all branches in the tree. The popup notification for branches will be displayed even in that case, allowing you to show the player custom notifications without having to have a tab in the "Advancements" menu.

A root can also control the background of the tab.

The following is a proper root that will be shown in the menu, as it has both a display and no parent:

{
    "display": {
        "icon": {
            "item": "minecraft:diamond"
        },
        "title": "A Root",
        "description": "The root of this tree.",
        "background": "minecraft:textures/gui/advancements/backgrounds/stone.png"
    },
    "criteria": {
        "impossible": {
            "trigger": "minecraft:impossible"
        }
    }
}

While the following is an invisible root, as it has neither a display nor a parent:

{
    "criteria": {
        "impossible": {
            "trigger": "minecraft:impossible"
        }
    }
}

Branches

A branch is defined by having a "parent" string. The parent specifies the resource location of another advancement, where the branch visually extends from the parent. Note that the parent does not actually need to be completed in order for the branch to be completed.

The visual structure of the tree will be automatically generated.

For example, the following set of advancements defines a root and two branches, where the branches are direct descendents of the root:

/custom/root.json

{
    "display": {
        "icon": {
            "item": "minecraft:sapling"
        },
        "title": "A Root",
        "description": "The root of this tree.",
        "background": "minecraft:textures/gui/advancements/backgrounds/stone.png"
    },
    "criteria": {
        "auto": {
            "trigger": "minecraft:location"
        }
    }
}

/custom/branch_a.json

{
    "display": {
        "icon": {
            "item": "minecraft:stick"
        },
        "title": "Branch 1",
        "description": "One branch of the tree."
    },
    "parent": "custom:root",
    "criteria": {
        "auto": {
            "trigger": "minecraft:location"
        }
    }
}

/custom/branch_b.json

{
    "display": {
        "icon": {
            "item": "minecraft:blaze_rod"
        },
        "title": "Branch 2",
        "description": "Another branch of the tree."
    },
    "parent": "custom:root",
    "criteria": {
        "auto": {
            "trigger": "minecraft:location"
        }
    }
}

Visual:



Changing /custom/branch_b.json to the following will cause it to branch off of "custom:branch_a" rather than the root:

{
    "display": {
        "icon": {
            "item": "minecraft:blaze_rod"
        },
        "title": "Branch 2",
        "description": "Another branch of the tree."
    },
    "parent": "custom:branch_a",
    "criteria": {
        "auto": {
            "trigger": "minecraft:location"
        }
    }
}

Which would then show as a direct line of branches:



Since you can have multiple branches per parent, complex trees can be created. The following image is a segment from the default "story" tab for vanilla Minecraft, showing complex connections between branches:

Conclusion

Q&A

External links