Starting in 1.12, achievements, now referred to as "advancements", have become data-driven via modifiable JSON files rather than hard-coded. This allows map makers, modders, and server owners to modify and add advancements to their liking.
Advancements have a multitude of options, ranging from triggers based on the player's inventory to what biome they're in. Rewards can optionally be given, such as unlocking a recipe, providing an item, or providing experience. A new command, /advancement, has been introduced to supplement the files.
Advancements use the JSON format to store the advancement information in external files.
Errors
When an advancement fails for whatever reason, you can find failure messages in the Game Output window in the log files.
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:?]
If you need assistance with your advancements, please post relevant advancement(s), as well as the error and stacktrace if applicable, in the following format:
[/pre]
[spoiler=Advancement(s)]
Paste advancement(s) here, along with filepath[/spoiler]
[spoiler=Error]
Paste error & stacktrace here[/spoiler]
[pre]
File editing
File location
Advancements are saved within the world folder to be distributed with the world itself. More specifically, inside the /data/advancements/ folder. Here is an example structure within the world folder, where "New World" is the name of the world folder:
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
When referencing an advancement, whether it's from a parent or in a command, you must follow the following format excluding the .json extension:
[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
You can create an advancement within the "minecraft" namespace with the same name as a default advancement. Anything that uses the default advancement will then use your custom one.
For example, given the filepath /data/advancements/minecraft/story/elytra.json, the following advancement will replace the default advancement that triggers by having any elytra in the inventory, and instead triggers by having an elytra slightly damaged in the inventory (which can trigger when starting to fly):
You will need to use a UTF-8 compliant text editor when creating and saving advancements that use unicode characters (such as the section symbol). By not encoding in UTF-8, special characters may not be saved correctly and Minecraft may fail to parse the data.
File/folder names must all be lowercase to circumvent issues with differing operating system file structures.
1. Windows Notepad is capable of saving as UTF-8, though will default to ANSI. Instructions for saving a .json in UTF-8:
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
The following is a list of all possible keys for advancements.
A large number of advancement features make use of a "range" object, which is a comparison of the incoming number (such as the number of occupied inventory slots) to the specified range of numbers.
To check for an exact value, simply declare the range as a number. The following checks if the compared value is exactly 3.
"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
A location object contains a small amount of data to specify an origin, biome, or generated structure. All options are available anywhere that this location object is used.
1. "position"
The "position" object contains "x", "y", and "z"ranges to check the global position of the player in the world. You do not need to specify all of the axes. For example, the following checks if the player is at Y62 or lower.
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.
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
The distance object contains information about the distance between the advancement-earning player and an unspecified origin. The origin cannot be directly defined but changes depending on the trigger; see each trigger that uses this for specific information. All options are available anywhere that this location object is used.
1. "x", "y", "z"
The "x", "y", and "z"ranges each check if the player is a number of blocks in either direction of the origin in the specified axis. You do not need to specify all of the axes. For example, the following checks if the player is within 40 blocks in either the positive or negative X direction of the origin.
"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.
A status effect object contains nested objects, whose key names reflect status effect IDS. All options are available anywhere that this item object is used.
1. "amplifier"
The "amplifier"range checks the amplifier of the specified effect. The following checks if the amplifier is 10 or higher.
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.
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.
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.
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.
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.
An entity object contains a handful of data to compare to an incoming entity. All options are available anywhere that this entity object is used.
1. "type"
The "type" string specifies the entity ID to match against. For example, the following checks if the incoming entity is a creeper.
"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.
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
A block object contains a handful of data to compare to an incoming block. All options are available anywhere that this entity object is used.
1. "block"
The "block" string specifies a base block ID to detect the player in. For example, the following checks if the block has the base ID of "minecraft:tallgrass" (includes grass, fern, and double tallgrass).
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.
A damage object contains a large amount of information about the incoming or outgoing damage. All options are available anywhere that this damage object is used.
1. "dealt"
A range checking the raw incoming damage before damage reduction. For example, the following checks the damage of an un-owned arrow (via /summon) before that damage was either reduced or blocked with a shield entirely.
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).
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).
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.
A damage flags object checks different flags concerning the incoming or outgoing damage. All options are available anywhere that this damage flags object is used.
1. "bypasses_armor"
Checks the "unblockable" flag for the incoming damage. This is true for: fire, suffocation (blocks & world border), entity cramming, drowning, starving, falling, flying into a wall, void (the Void & /kill), health recalcuation, magic damage, and wither effect damage. The following checks if the damage is caused by any damage that cannot be blocked.
"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.
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.
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.
The death object contains information about both the killer/killed entity (changing depending on the trigger) and the killing blow. All options are available anywhere that this death object is used.
1. "entity"
An entity object that will either describe the entity that was killed or the killer itself, depending on the trigger being used; see each trigger that uses this for specific information. To be clear: this does not always describe the entity that died. The following checks if the killed entity or killer was a creeper.
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.
An advancement must include a set of rules that activate the advancement, specified in the "criteria" object. Each object nested within will contain a custom name of your choosing, to later be used with the optional "requirements" list or the /advancement command. When the player matches a criterion at any point, that fulfillment will be remembered, allowing the player to fulfill all criteria over time rather than all at the same time.
Within each criterion there must be a trigger, specified by the "trigger" string.
If "requirements" is not specified, then all criteria must be met for the advancement to be granted.
The following advancement is granted provided both the "custom_test_name" and "take_damage" criteria succeeds, where the names can be anything you want. The player can breed animals together, and then at any point in the future take damage to complete the advancement (or vice versa). As "requirements" is not specified, both criteria must be fulfilled.
While the following advancement is granted provided either the "custom_test_name" and "take_damage" criteria succeeds. See the Requirements section for more details.
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
The "requirements" list specifies a Conjunctive Normal Form structure to accompany criteria. It essentially allows boolean logic to determine when the advancement is granted based on the accompanying criteria. The list contains more lists, which in turn contains strings that equal the names of the criteria. You would use this if you want to use an OR operation. Each new list is a new AND operation, while each comma-separated string within the list is an OR operation.
If "requirements" is not specified, then all criteria must be fulfilled. If this list is specified, then every criteria must be included in "requirements" to determine which ones need to be fulfilled.
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":
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:
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
The optional "display" object contains information about the display in the "Advancements" menu. If this object does not exist, the advancement will be hidden from the "Advancements" menu and popup notifications will not appear.
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:
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):
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:
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.
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.
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.
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.
The "rewards" object specifies multiple types of rewards to provide the player upon completing the advancement.
"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.
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".
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).
When an advancement has a display, it will be shown in the "Advancements" menu under a relevant tab. Root advancements will be the "owner" of a tab, with new tabs appearing for each unique root:
Any advancements referring to the root will be its children and are displayed in a branching tree:
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:
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"
}
}
}
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:
Certain triggers make use of subcriteria, specified in the "conditions" object. The data stored within is dependent on the type of trigger, and not all triggers need or use it.
The following is a list of all possible triggers that can be used, along with any extra applicable data. Open the spoiler before clicking a link to be taken to the description.
This triggers when the player successfully breeds two animals. If two players cause a pair of animals to breed, the animal that "births" the baby will trigger the advancement for whoever fed that animal. For example, the following succeeds if the player breeds any two animals together:
There are 3 conditions for this trigger: "parent", "partner", and "child".
1. "parent", "partner"
Both the "parent" and "partner"entity objects describe either of the parents. Both entities in the taming process could be the parent or the partner. For example, all of the following triggers checks if either parent is a cow.
A time that you'd use both "parent" and "partner" is when you want to check to see if the entity types are a specific pairing, whether it be two of the same entity or two different entities. The following will trigger only if the parents are a mix of a cow and a sheep, which cannot be fulfilled in vanilla.
The only animal pairing that can have different parents are horses and donkeys, which create a mule. If you wanted to check if the player bred a horse and a horse together, you must specify both the parent and partner as a horse because otherwise it would trigger if the player bred a horse and a donkey.
You can also specify the parents and child. For example, the following triggers if the parents include a horse and a donkey, while the child is a mule (although that makes the check for parents useless as that's the only way to get a mule).
This triggers when the player removes any item from the output slots of a brewing stand. Note that this doesn't mean the player has to have brewed it; any brewing stands that generate with potions inside it (such as in the End Ship) will fulfill this trigger. The player can repeatedly place a potion into a brewing stand and remove it to constantly fulfill this trigger.
For example, the following will trigger if the player removes any item from a brewing stand:
The "potion" string allows you to specify a default brewed potion ID (stored in the "Potion" string tag on the item) that the removed item must contain. The wiki contains a list of those here. If the item removed does not have a "Potion" string tag, the trigger will assume the ID is "minecraft:empty".
The following only triggers if the player removes an extended Invisibility potion from the brewing stand's output slots.
There are 2 conditions for this trigger: "to" and "from".
1. "to"
The "to" string specifies the dimension the player is traveling to, accepting values "overworld", "the_nether", and "the_end". The following triggers if the player travels to the end (regardless of their original dimension).
The "from" string specifies the dimension the player traveled from, accepting values "overworld", "the_nether", and "the_end". The following triggers if the player travels to the end, though specifically from the nether.
This triggers every time the player receives an effect update from a beacon, not when physically constructing a beacon pyramid. The beacon does not need to have any effects selected for this update to occur, but the player does need to be in range as usual. The beacon does not need to be placed on a valid pyramid structure!
For example, the following will trigger if the player is close enough to a beacon to receive its effect, regardless of an effect is selected or even if there is a valid pyramid beneath the beacon.
The "level"range specifies the number of levels the beacon pyramid has, up to 4. For example, the following checks if the beacon pyramid has at least 2 levels when the player receives an effect update.
The "item"item object specifies item data about the item before it was consumed. For example, the following activates if the player had 2 golden apples in the stack and ate 1 of them.
This triggers whenever a zombie villager completes its conversion into a villager. The player that had cured it will be the one fulfilling the trigger.
There are 2 conditions for this trigger: "zombie" and "villager".
1. "zombie"
The "zombie"entity object specifies entity data about the zombie that was converted. The "type" string is essentially useless here as it will always be "minecraft:zombie_villager".
The origin for the "distance"range for the entity will be the zombie's location. That is, the value will describe the distance between the cured zombie and the player. The following checks if the player cured a zombie but was 50+ blocks away from it when the conversion was completed.
The "villager"entity object specifies entity data about the villager that was created as a result of converting. The "type" string is essentially useless here as it will always be "minecraft:villager".
The origin for the "distance"range for the entity will be the villager's location. That is, the value will describe the distance between the new villager and the player. The following checks if the player cured a zombie but was 50+ blocks away from it when the conversion was completed.
A status effects object that checks the player's whole list of effects whenever any effect is applied or lost. However, keep in mind that if the player lost an effect to trigger this advancement, it cannot be detected. The following checks if the player has Levitation.
This triggers whenever the player enchants an item in an enchanting table. The player does not have to remove the item, as it's triggered when selecting which enchantment to apply. The following triggers upon enchanting.
There are 2 conditions for this trigger: "item" and "levels".
1. "item"
The "item"item object matches the enchanted item against the provided data. Note that this check occurs after enchanting, which means that you can make use of the "enchantments" list to only fulfill the trigger if a specific enchantment was received. The following will trigger if the item that was enchanted is a diamond pickaxe, and received any level of Fortune.
The "levels"range specifies the number of levels spent to receive the enchantment. For example, with 15 bookshelves, selecting the third option requires 30 levels and costs 3 levels. This condition checks that cost of 3 levels. This does mean that you can't ensure the player had to have 30 levels from the advancement alone, but could use in-game command blocks to help detect that.
The following will trigger if the player spends 3 levels on an enchantment.
This triggers whenever the player's hitbox intersects with a block, including air, as well as the block at the location an enderpearl had landed at. As such, the following triggers constantly because the player is always in a block.
A damage object that describes the damage the player has taken, complete with entity source that dealt the damage. For example, the following checks if the player had taken 10+ health damage from an explosion caused by a creeper.
The origin for the "distance"range for the source entity will be the mob's location. That is, the value will describe the distance between the entity causing the damage and the player taking the damage. The following checks if the player had taken damage from a skeleton while being within 3 blocks of that skeleton.
The origin for the "distance"range for the entity will be the mob's location. That is, the value will describe the distance between the player and the mob that killed them. The following checks if the player was killed by a skeleton while being within 3 blocks of it.
A damage flags object checking various flags for the damage the player had dealt for the killing blow. The following triggers if the player is killed by a skeleton that didn't deal projectile damage.
This does not trigger naturally. The only way to trigger this is in vanilla to use the /advancement command. This greatly supplements command mechanisms as it allows more complex requirements that can be met with in-game commands.
For example, given the following advancement, assuming resource location "custom:missions":
The following commands will individually trigger each specific criterion, completing the advancement, but only for players that have the "winner" tag:
/advancement grant @a[tag=winner] custom:missions mission1
/advancement grant @a[tag=winner] custom:missions mission2
There are 0 conditions for this trigger.
inventory_changed
This triggers whenever the player's inventory is updated, such as from removing an item or adding an item. Note that spreading items through the inventory by holding left or right-click will count as multiple actions, though is only relevant if the advancement is revoked by a function reward during that tick. The following will trigger from any addition or removal of items from the player's inventory:
There are 2 conditions for this trigger: "slots" and "items".
1. "slots"
The "slots" object contains generic information about all slots in the inventory. Within it are three possible ranges to specify: "occupied", "full", and "empty". The armor and offhand slots are included in these checks.
The "occupied" range indicates the number of slots that have an item in it. The "full" range indicates the number of slots that have the highest number of items possible for that slot (such as 1 diamond pickaxe or 64 stone blocks). The "empty" range indicates the number of empty slots.
For example, the following will trigger when the player has exactly 10 empty slots in their inventory at the time that their inventory gets updated.
The "items"item object list matches the player's inventory against each item provided in the list. The inventory must match all items specified. The following checks if the player has both stone and dirt in their inventory at the time their inventory gets updated.
This triggers whenever an item in the player's inventory has resulted in a loss of durability. The following will trigger whenever any item in the player's inventory takes damage:
There are 3 conditions for this trigger: "item", "durability", and "delta".
1. "item"
The "item"item object matches the damaged item with the data provided. This specifically checks the item before it was damaged, allowing you to check its durability and other data prior to durability loss. The following checks if the player used a diamond sword that had 1540 or more durability remaining before being damaged.
The "durability"range checks the item's remaining durability after the item was damaged. The following checks if a shield had at most 10 durability remaining after being damaged.
The "delta"range checks the change in durability of the item. For example, the following checks if the item had a change of -2 durability or more (took 2+ points of damage).
There are 2 conditions for this trigger: "duration" and "distance".
1. "duration"
The "duration"range checks how the number of ticks the player has been levitating (not how long the effect itself was set to last). Note that this internal timer will not reset until the Levitation effect is removed, thus revoking the advancement after it was achieved will simply cause it to be achieved immediately after if the player is still under the Levitation effect. The following triggers when the player has been under the Levitation effect for 40 or more ticks.
The "distance"distance object checks how the number of blocks away the player has traveled from the moment they received the effect. The following checks if the player has is still within 10 blocks (regardless of direction) of where they received the effect.
This triggers every second (every 20 ticks) at all times, essentially requiring the use of conditions despite them being optional for this trigger. However, this activation can be useful if needing pre-finished advancements. The following will always activate every second.
This triggers every second (every 20 ticks) at all times, essentially requiring the use of conditions despite them being optional for this trigger. However, this activation can be useful if needing pre-finished advancements. The following will always activate every second.
There are 3 conditions for this trigger: "entered", "exited", and "distance".
This trigger uses only the location object to check various data. The origin of the location is the player's coordinates.
1. "entered"
A location object checking the location of the nether portal that the player entered the nether through. The following checks if that nether portal was in a desert biome.
A location object checking the location of the nether portal that the player arrived to in the overworld after leaving the nether through a portal. The following checks if that nether portal was in the positive X and Z coordinates.
A distance object checking the distance between the two nether portals positioned in the overworld. The following checks if they are horizontally 500 blocks apart.
An item object that checks information concerning the corresponding item that the player used to place the block, before the item was consumed. The following checks if the player placed an unpowered repeater block (where the corresponding item is "minecraft:repeater") that was the last item in the stack at the time of placing.
A location object that checks various location data about where the block was placed. For example, the following checks if glass block was placed anywhere at Y128 or higher.
There are 2 conditions for this trigger: "damage" and "entity".
1. "damage"
A damage object that describes the damage the entity had taken by the player, complete with entity source to check information about the player. The "type" string in that case is essentially useless because it will always be "minecraft:player". The following checks if the player dealt at least 10.0 raw projectile damage before damage reduction from the entity's gear, allowing for only up to 10% damage reduction.
The origin for the "distance"range for the source entity will be the player's location. That is, the value will describe the distance between the player and.. the player. This renders the option essentially useless. For example, the following checks if the player was within 3 blocks of themselves after damaging an entity, which is always true.
An entity object that checks information concerning the entity that the player had damaged. The following checks if the player dealt projectile damage to a zombie.
The origin for the "distance"range for this entity will be the entity's location. That is, the value will describe the distance between the entity taking the damage and the player dealing the damage. The following correctly checks if the player was within 3 blocks of the entity they damaged.
The origin for the "distance"range for the entity will be the mob's location. That is, the value will describe the distance between the entity that died and the player that killed it. The following checks if the player had killed a skeleton with a projectile while being 50+ blocks away from it.
A damage flags object checking various flags for the damage the player had dealt for the killing blow. The following triggers if the player kills a creeper without projectile damage.
This triggers when the player unlocks a recipe. There is 1 required condition for this trigger: "recipe", which specifies the resource location to the desired recipe that must be unlocked. Note that this check only occurs at the time of receiving the recipe; if the player unlocked it before the advancement exists, the advancement will not take that into consideration. As the recipe is only detected at the moment of unlocking it, you must revoke the recipe from the player using the /recipe command before it can be detected again.
The following will trigger when the player unlocks the "minecraft:redstone" recipe, in whatever way they unlock it (including as a reward for another advancement).
This trigger uses only the location object to check various data. The origin of the location is the player's coordinates after getting in the bed, which would be just above the bed's head.
1. "position"
The following checks if the player is below Y10 once they get in a bed.
The following will trigger when the player sleeps in a bed while their position indicates the biome their new position is in, being where the head of the bed is. While this was seemingly implemented as a way to detect the player sleeping in the nether, the bed exploding will not cause the trigger to be fulfilled. The following checks if the player slept in a desert biome.
This triggers when the player creates an entity in specific manners. Valid methods are: constructing a wither, constructing a snow golem, constructing an iron golem, and respawning the ender dragon. In the case of the ender dragon, all players able to view the boss bar will fulfill the trigger. The following triggers when the player summons any of the valid entities.
The origin for the "distance"range for the entity will be the summoned mob's location. That is, the value will describe the distance between the entity that was summoned and the player that summoned it, or between the ender dragon and all elligible players. The following checks if the player is within 10 blocks of the ender dragon when the summoning ritual is complete, which would be very high in the air.
This simply triggers every tick. This can be used to help simulate command block systems or automatically unlock advancements. The following activates every tick, revoking the same advancement as a reward so that it may activate in the next tick.
There is 1 condition for this trigger: "distance".
1. "distance"
The "distance"range specifies the number of blocks away the player (not the Eye of Ender) is to the nearest stronghold's center. It only takes into consideration the X and Z coordinate, ignoring the Y coordinate.
The formula for determining the number of blocks is:
For example, if the player was at (40, 64, 10) and the stronghold was at (120, 25, 400), the resulting distance needed to encompass the player is at least 398:
sqrt((40 - 120) + (10 - 400)) = 398
And the following will trigger if the player is standing at (40, 64, 10) with the stronghold at (120, 25, 400). If the player moves one block further away, they will no longer be detected.
The "item"item object specifies item data about the item before it was consumed. For example, the following activates if the player had 5 totems of undying in the stack before one was consumed to save them.
This triggers whenever the player completes a trade with a villager. Note that shift-clicking to complete a trade multiple times will only trigger this for the first trade that tick.
There are 2 conditions for this trigger: "villager" and "item".
1. "villager"
The "villager"entity object describes information about the villager that was traded with. In this case, the "type" string is useless as it will always be "minecraft:villager".
The origin for the "distance"range for the entity will be the villager's location. That is, the value will describe the distance between the villager being traded with and the player that traded with it. The following checks if the player is within 1 block of the villager when completing a trade.
The "item"item object describes information about the item that was purchased. In terms of the count, keep in mind that this only accounts for one trade. If a villager was selling 2 sugar per emerald, shift-clicking to receive 10 sugar would still only count as 2 sugar as far as the advancement goes, as the first completed trade of the bunch was for 2 sugar. The following checks if the purchased item was sugar.
Wow, Skylinerw! Great guide yet again, thank you so much for documenting this stuff in-depth.
Quick point-out and question:
1. You have "/advancements" instead of "/advancement" near the top of the guide.
2. You said the "enchantments" item property looks at "ench." Does that mean enchanted books would fail the check?
1. Fixed, thanks!
2. Looked into it: the "enchantments" condition checks "ench" NBT list for all items except books, while it checks "StoredEnchantments" NBT list but only for books. So a book that contains "ench" will not be detected, but a book with "StoredEnchantments" will be.
Hmm, good guide! I'm currently working on a command block modpack, and I'll certainly refer back to this once I update to 1.12 (which will be once we get a stable version).
how do you make the root.json file it's not working in the 17w13b snapshot
There's currently an issue (MC-115064) where the namespace is "minecraft" despite the files being in its own folder, so it's a bit odd to explain. I've omitted it from the main post until the bug is resolved, but I'll explain here how to work with the files for the time being.
Assuming you have the following files:
/world/data/advancements/custom/root.json:
The root advancement for a tab doesn't have to be called "root", but it does work as a clear indicator and would be consistent to do so. The root must not have a "parent" tag, but must have a proper "display" tag.
{
"display": {
"icon": "minecraft:gold_block",
"title": "A new tree in its own tab",
"background": "minecraft:textures/gui/advancements/backgrounds/stone.png"
},
"criteria": {
"crafting_table": {
"trigger": "minecraft:player_damaged"
}
}
}
A new tab in the "Advancements" menu will not show up until at least one advancement in the tree is fulfilled. If you've got a valid root file but haven't completed any advancements in that tree, you won't see the tab. However, you could have a child advancement extending the root, while not giving that child a display. It will then act as a hidden method of forcing the tab to show up without having to complete any real advancements:
However, to interact with those files (whether with /advancement or to specify a parent in advancement files), the namespace is not "custom" as would be expected, but is "minecraft" (being the bug, as the namespace should be the name of the root folder in "/data/advancements/"). To refer to the above files, you would use:
1. Fixed, thanks!
2. Looked into it: the "enchantments" condition checks "ench" NBT list for all items except books, while it checks "StoredEnchantments" NBT list but only for books. So a book that contains "ench" will not be detected, but a book with "StoredEnchantments" will be.
I have another question based on this. What if I did:
/give @p enchanted_book 1 0 {ench:[{id:0,lvl:10}],StoredEnchantments:[{id:16,lvl:32767}]}
Which will it look at then? Or will it look at both?
Edit: nvm "So a book that contains "ench" will not be detected," Im blind...
I have another question based on this. What if I did:
/give @p enchanted_book 1 0 {ench:[{id:0,lvl:10}],StoredEnchantments:[{id:16,lvl:32767}]}
Which will it look at then? Or will it look at both?
Edit: nvm "So a book that contains "ench" will not be detected," Im blind...
Sorry, it will looks at what's relevant. If it's a book it looks for "StoredEnchantments" instead of "ench". If the book doesn't have "StoredEnchantments" then it won't be detected, not that it's disregarded if it has "ench". So yes, that book will be detected because it has "StoredEnchantments".
Is there a way to give the display items a data value? I'm trying to use colored wools as display Items for tasks!
It's currently not possible. We most likely won't get that ability though, as instead all items with a Damage value (excluding items with durability) will be split into their own IDs. For example, red wool would be "red_wool" instead of "wool" with a Damage value of 14. More info here on that upcoming change: https://bugs.mojang.com/browse/MC-105922
The jar != a resource pack, advancements and loot tables are part of the data of minecraft, but are not editable by resource packs because they are handled server side (as the progress/loot needs saving).
So I have two files to test with root.json and beach.json.
So in root.json
This is the root.json
{
"display": {
"icon": "minecraft:writeable_book",
"title": "Little's Challenges!",
"background": "minecraft:textures/blocks/dragon_egg.png"
},
"criteria": {
"biome_1": {
"trigger": "minecraft:location",
"conditions": {
"biome": "minecraft:hell"
}
}
}
}
This is the beach.json
{
"display": {
"icon": "minecraft:sand",
"title": "The Nether"
},
"parent": "minecraft:littleschallenges/root",
"criteria": {
"biome": {
"trigger": "minecraft:location",
"conditions": {
"biome": "minecraft:hell"
}
}
}
}
I have the criteria for the file which is detecting if the player is in the nether. I also have to put the same criteria in the beach.json file as well, but what is the difference between putting the triggers and junk in the root and child files?
You also said below about the child advancement, but you don't list what the "custom/root" advancement was, could you edit the post to show what the "custom/root" advancement was so we can get a better understanding into how it's related?
Minecraft uses the root for actual triggers and rewards, but you don't have to do that. You can have whatever criteria you want in the root; what makes it the "root" is not having a parent and having a display. It doesn't even need children, but would be ideal to have since otherwise you'd have a lot of tabs to work with that only contain single-advancement trees.
A parent also doesn't need to be fulfilled for a child to be fulfilled. You could leave a "minecraft:impossible" criteria and not touch it at all, or you could have a criteria that will automatically be fulfilled, such as "minecraft:location". The tab itself only shows up if at least one criteria in the tree is fulfilled, so that automation may be desired if you want the player to know that those advancements exist.
This is all very subject to change though, and may not work that way in the future. That is primarily why I've avoided adding much information in the way of manipulating the trees for now, but I have a separate post here about a root and child. I won't be adding this to the main thread until the namespace bug is fixed, since that fix would change how you reference the advancements (thus invalidating my other post).
EDIT: Oh, just noticed a small typo in your root: you have "minecraft:writeable_book" for the icon which needs to be "minecraft:writable_book" instead.
EDIT: Oh, just noticed a small typo in your root: you have "minecraft:writeable_book" for the icon which needs to be "minecraft:writable_book" instead.
In related to the -snipped- part, I realized my mistake, and noticed the namespace bug as well.
In relation to the EDIT, yeah I noticed that. That was also my problem lol
Rollback Post to RevisionRollBack
"It's what you do with the gift of life that determines who you are." ~Mewtwo
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
Starting in 1.12, achievements, now referred to as "advancements", have become data-driven via modifiable JSON files rather than hard-coded. This allows map makers, modders, and server owners to modify and add advancements to their liking.
Advancements have a multitude of options, ranging from triggers based on the player's inventory to what biome they're in. Rewards can optionally be given, such as unlocking a recipe, providing an item, or providing experience. A new command, /advancement, has been introduced to supplement the files.
Advancements use the JSON format to store the advancement information in external files.
Errors
When an advancement fails for whatever reason, you can find failure messages in the Game Output window in the log files.
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:
If you need assistance with your advancements, please post relevant advancement(s), as well as the error and stacktrace if applicable, in the following format:
File editing
File location
Advancements are saved within the world folder to be distributed with the world itself. More specifically, inside the /data/advancements/ folder. Here is an example structure within the world folder, where "New World" is the name of the world folder:
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
When referencing an advancement, whether it's from a parent or in a command, you must follow the following format excluding the .json extension:
Example, targeting the file /data/advancements/anothermod/challenges/kill_creepers.json:
By excluding the namespace, it will automatically assume it's meant to be "minecraft":
Replacing default advancements
You can create an advancement within the "minecraft" namespace with the same name as a default advancement. Anything that uses the default advancement will then use your custom one.
For example, given the filepath /data/advancements/minecraft/story/elytra.json, the following advancement will replace the default advancement that triggers by having any elytra in the inventory, and instead triggers by having an elytra slightly damaged in the inventory (which can trigger when starting to fly):
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
You will need to use a UTF-8 compliant text editor when creating and saving advancements that use unicode characters (such as the section symbol). By not encoding in UTF-8, special characters may not be saved correctly and Minecraft may fail to parse the data.
File/folder names must all be lowercase to circumvent issues with differing operating system file structures.
1. Windows Notepad is capable of saving as UTF-8, though will default to ANSI. Instructions for saving a .json in UTF-8:
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
The following is a list of all possible keys for advancements.
Shared: range
A large number of advancement features make use of a "range" object, which is a comparison of the incoming number (such as the number of occupied inventory slots) to the specified range of numbers.
To check for an exact value, simply declare the range as a number. The following checks if the compared value is exactly 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.
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.
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.
Shared: location object
A location object contains a small amount of data to specify an origin, biome, or generated structure. All options are available anywhere that this location object is used.
1. "position"
The "position" object contains "x", "y", and "z" ranges to check the global position of the player in the world. You do not need to specify all of the axes. For example, the following checks if the player is at Y62 or lower.
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.
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.
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.
Shared: distance object
The distance object contains information about the distance between the advancement-earning player and an unspecified origin. The origin cannot be directly defined but changes depending on the trigger; see each trigger that uses this for specific information. All options are available anywhere that this location object is used.
1. "x", "y", "z"
The "x", "y", and "z" ranges each check if the player is a number of blocks in either direction of the origin in the specified axis. You do not need to specify all of the axes. For example, the following checks if the player is within 40 blocks in either the positive or negative X direction of the origin.
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.
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.
Shared: status effects object
A status effect object contains nested objects, whose key names reflect status effect IDS. All options are available anywhere that this item object is used.
1. "amplifier"
The "amplifier" range checks the amplifier of the specified effect. The following checks if the amplifier is 10 or higher.
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.
3. "ambient"
The "ambient" boolean checks if the effect has the "ambient" flag set to true.
4. "visible"
The "visible" boolean checks if the effect has the "visible" flag set to true.
Shared: item object
An item object contains a handful of data to compare to an incoming item stack. All options are available anywhere that this item object is used.
1. "item"
The "item" string specifies a base item ID to compare the item to. The following checks if the item is redstone.
2. "data"
The "data" integer specifies a metadata of the item. The following checks if the item is a polished granite block.
3. "durability
The "data" range specifies the remaining durability of an item. The following checks if the item has 400 or more durability remaining.
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.
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.
The item does not have to be a potion. As long as the item has the Potion NBT string, it will match:
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.
The "enchantment" string will specify the enchantment ID to look for. The following checks the item for the Sharpness enchantment.
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.
And combining it with an ID, the following checks if the player has Sharpness 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.
Shared: entity object
An entity object contains a handful of data to compare to an incoming entity. All options are available anywhere that this entity object is used.
1. "type"
The "type" string specifies the entity ID to match against. For example, the following checks if the incoming entity is a 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.
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.
4. "effects"
The "effects" status effects object checks data concerning the entity's status effects. The following checks if the entity has Speed 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.
Shared: block object
A block object contains a handful of data to compare to an incoming block. All options are available anywhere that this entity object is used.
1. "block"
The "block" string specifies a base block ID to detect the player in. For example, the following checks if the block has the base ID of "minecraft:tallgrass" (includes grass, fern, and double 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.
Shared: damage object
A damage object contains a large amount of information about the incoming or outgoing damage. All options are available anywhere that this damage object is used.
1. "dealt"
A range checking the raw incoming damage before damage reduction. For example, the following checks the damage of an un-owned arrow (via /summon) before that damage was either reduced or blocked with a shield entirely.
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.
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).
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).
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.
Shared: damage flags object
A damage flags object checks different flags concerning the incoming or outgoing damage. All options are available anywhere that this damage flags object is used.
1. "bypasses_armor"
Checks the "unblockable" flag for the incoming damage. This is true for: fire, suffocation (blocks & world border), entity cramming, drowning, starving, falling, flying into a wall, void (the Void & /kill), health recalcuation, magic damage, and wither effect damage. The following checks if the damage is caused by any damage that cannot be blocked.
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.
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.
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.
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.
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.
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.
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.
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.
Shared: death object
The death object contains information about both the killer/killed entity (changing depending on the trigger) and the killing blow. All options are available anywhere that this death object is used.
1. "entity"
An entity object that will either describe the entity that was killed or the killer itself, depending on the trigger being used; see each trigger that uses this for specific information. To be clear: this does not always describe the entity that died. The following checks if the killed entity or killer was a 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.
Customizing advancements
Criteria
An advancement must include a set of rules that activate the advancement, specified in the "criteria" object. Each object nested within will contain a custom name of your choosing, to later be used with the optional "requirements" list or the /advancement command. When the player matches a criterion at any point, that fulfillment will be remembered, allowing the player to fulfill all criteria over time rather than all at the same time.
Within each criterion there must be a trigger, specified by the "trigger" string.
If "requirements" is not specified, then all criteria must be met for the advancement to be granted.
The following advancement is granted provided both the "custom_test_name" and "take_damage" criteria succeeds, where the names can be anything you want. The player can breed animals together, and then at any point in the future take damage to complete the advancement (or vice versa). As "requirements" is not specified, both criteria must be fulfilled.
While the following advancement is granted provided either the "custom_test_name" and "take_damage" criteria succeeds. See the Requirements section for more details.
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
The "requirements" list specifies a Conjunctive Normal Form structure to accompany criteria. It essentially allows boolean logic to determine when the advancement is granted based on the accompanying criteria. The list contains more lists, which in turn contains strings that equal the names of the criteria. You would use this if you want to use an OR operation. Each new list is a new AND operation, while each comma-separated string within the list is an OR operation.
If "requirements" is not specified, then all criteria must be fulfilled. If this list is specified, then every criteria must be included in "requirements" to determine which ones need to be fulfilled.
Given the following advancement:
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:
Modifying the requirements list slightly, which joins "trigger_2" with "trigger_1":
Now either "trigger_1" or "trigger_2" must be completed to be granted the advancement. Using logical operators, this can be viewed as:
Given the following advancement:
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:
And modifying the requirements slightly:
The advancement is granted if any of the criteria are met. Using logical operators, this can be viewed as:
Display
The optional "display" object contains information about the display in the "Advancements" menu. If this object does not exist, the advancement will be hidden from the "Advancements" menu and popup notifications will not appear.
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:
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):
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:
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):
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
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:
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.
The following advancement makes use of the "goal" frame.
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.
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.
The announceAdvancements gamerule can globally disable fulfillment messages, overriding the value of "announce_to_chat" for individual advancements.
Hidden
An optional "hidden" boolean can be specified in order to prevent child advancements from displaying in the "Advancements" menu until they are completed.
Rewards
The "rewards" object specifies multiple types of rewards to provide the player upon completing the advancement.
"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.
"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".
"experience"
This number (not range) specifies the amount of experience (not levels) to reward the player with.
"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).
All rewards can be used at the same time.
Tree display
When an advancement has a display, it will be shown in the "Advancements" menu under a relevant tab. Root advancements will be the "owner" of a tab, with new tabs appearing for each unique root:
Any advancements referring to the root will be its children and are displayed in a branching tree:
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:
While the following is an invisible root, as it has neither a display nor a parent:
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
/custom/branch_a.json
/custom/branch_b.json
Visual:
Changing /custom/branch_b.json to the following will cause it to branch off of "custom:branch_a" rather than the root:
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
Coming soon...
External links
- Generic JSON Validator
- Minecraft Wiki: Advancements
Translations:
- Chinese
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
Triggers
Certain triggers make use of subcriteria, specified in the "conditions" object. The data stored within is dependent on the type of trigger, and not all triggers need or use it.
The following is a list of all possible triggers that can be used, along with any extra applicable data. Open the spoiler before clicking a link to be taken to the description.
bred_animals
This triggers when the player successfully breeds two animals. If two players cause a pair of animals to breed, the animal that "births" the baby will trigger the advancement for whoever fed that animal. For example, the following succeeds if the player breeds any two animals together:
There are 3 conditions for this trigger: "parent", "partner", and "child".
1. "parent", "partner"
Both the "parent" and "partner" entity objects describe either of the parents. Both entities in the taming process could be the parent or the partner. For example, all of the following triggers checks if either parent is a cow.
A time that you'd use both "parent" and "partner" is when you want to check to see if the entity types are a specific pairing, whether it be two of the same entity or two different entities. The following will trigger only if the parents are a mix of a cow and a sheep, which cannot be fulfilled in vanilla.
The only animal pairing that can have different parents are horses and donkeys, which create a mule. If you wanted to check if the player bred a horse and a horse together, you must specify both the parent and partner as a horse because otherwise it would trigger if the player bred a horse and a donkey.
But if you wanted to check if a mule is being created, you'd look for a donkey and a horse (the order does not matter).
2. "child"
The "child" entity object will match against the newborn animal. The following will trigger only if the child is a cow.
You can also specify the parents and child. For example, the following triggers if the parents include a horse and a donkey, while the child is a mule (although that makes the check for parents useless as that's the only way to get a mule).
brewed_potion
This triggers when the player removes any item from the output slots of a brewing stand. Note that this doesn't mean the player has to have brewed it; any brewing stands that generate with potions inside it (such as in the End Ship) will fulfill this trigger. The player can repeatedly place a potion into a brewing stand and remove it to constantly fulfill this trigger.
For example, the following will trigger if the player removes any item from a brewing stand:
There is 1 condition for this trigger: "potion".
1. "potion"
The "potion" string allows you to specify a default brewed potion ID (stored in the "Potion" string tag on the item) that the removed item must contain. The wiki contains a list of those here. If the item removed does not have a "Potion" string tag, the trigger will assume the ID is "minecraft:empty".
The following only triggers if the player removes an extended Invisibility potion from the brewing stand's output slots.
changed_dimension
This triggers whenever the player switches to another dimension.
There are 2 conditions for this trigger: "to" and "from".
1. "to"
The "to" string specifies the dimension the player is traveling to, accepting values "overworld", "the_nether", and "the_end". The following triggers if the player travels to the end (regardless of their original dimension).
2. "from"
The "from" string specifies the dimension the player traveled from, accepting values "overworld", "the_nether", and "the_end". The following triggers if the player travels to the end, though specifically from the nether.
construct_beacon
This triggers every time the player receives an effect update from a beacon, not when physically constructing a beacon pyramid. The beacon does not need to have any effects selected for this update to occur, but the player does need to be in range as usual. The beacon does not need to be placed on a valid pyramid structure!
For example, the following will trigger if the player is close enough to a beacon to receive its effect, regardless of an effect is selected or even if there is a valid pyramid beneath the beacon.
There is 1 condition for this trigger: "level".
1. "level"
The "level" range specifies the number of levels the beacon pyramid has, up to 4. For example, the following checks if the beacon pyramid has at least 2 levels when the player receives an effect update.
While the following checks if the player is receiving an update from a beacon that does not have a pyramid associated with it.
consume_item
This triggers whenever the player eats food, drinks milk, or drinks a potion/water bottle.
There is 1 conditions for this trigger: "item".
1. "item"
The "item" item object specifies item data about the item before it was consumed. For example, the following activates if the player had 2 golden apples in the stack and ate 1 of them.
cured_zombie_villager
This triggers whenever a zombie villager completes its conversion into a villager. The player that had cured it will be the one fulfilling the trigger.
There are 2 conditions for this trigger: "zombie" and "villager".
1. "zombie"
The "zombie" entity object specifies entity data about the zombie that was converted. The "type" string is essentially useless here as it will always be "minecraft:zombie_villager".
The origin for the "distance" range for the entity will be the zombie's location. That is, the value will describe the distance between the cured zombie and the player. The following checks if the player cured a zombie but was 50+ blocks away from it when the conversion was completed.
2. "villager"
The "villager" entity object specifies entity data about the villager that was created as a result of converting. The "type" string is essentially useless here as it will always be "minecraft:villager".
The origin for the "distance" range for the entity will be the villager's location. That is, the value will describe the distance between the new villager and the player. The following checks if the player cured a zombie but was 50+ blocks away from it when the conversion was completed.
effects_changed
This triggers whenever the player receives or loses an effect.
There is 1 condition for this trigger: "effects".
1. "effects"
A status effects object that checks the player's whole list of effects whenever any effect is applied or lost. However, keep in mind that if the player lost an effect to trigger this advancement, it cannot be detected. The following checks if the player has Levitation.
enchanted_item
This triggers whenever the player enchants an item in an enchanting table. The player does not have to remove the item, as it's triggered when selecting which enchantment to apply. The following triggers upon enchanting.
There are 2 conditions for this trigger: "item" and "levels".
1. "item"
The "item" item object matches the enchanted item against the provided data. Note that this check occurs after enchanting, which means that you can make use of the "enchantments" list to only fulfill the trigger if a specific enchantment was received. The following will trigger if the item that was enchanted is a diamond pickaxe, and received any level of Fortune.
2. "levels"
The "levels" range specifies the number of levels spent to receive the enchantment. For example, with 15 bookshelves, selecting the third option requires 30 levels and costs 3 levels. This condition checks that cost of 3 levels. This does mean that you can't ensure the player had to have 30 levels from the advancement alone, but could use in-game command blocks to help detect that.
The following will trigger if the player spends 3 levels on an enchantment.
enter_block
This triggers whenever the player's hitbox intersects with a block, including air, as well as the block at the location an enderpearl had landed at. As such, the following triggers constantly because the player is always in a block.
This trigger uses only the block object to check various data.
1. shared block object
The following checks if the player is standing in a fern.
entity_hurt_player
This triggers whenever the player takes any amount of damage (including 0), even when blocking.
There is 1 condition for this trigger: "damage".
1. "damage"
A damage object that describes the damage the player has taken, complete with entity source that dealt the damage. For example, the following checks if the player had taken 10+ health damage from an explosion caused by a creeper.
The origin for the "distance" range for the source entity will be the mob's location. That is, the value will describe the distance between the entity causing the damage and the player taking the damage. The following checks if the player had taken damage from a skeleton while being within 3 blocks of that skeleton.
entity_killed_player
This triggers when any mob (not other players) kills the player.
This trigger uses only the death object to check various data.
1. "entity"
Matches the mob that killed the player against the specified entity object. The following triggers if the player was killed by a creeper.
The origin for the "distance" range for the entity will be the mob's location. That is, the value will describe the distance between the player and the mob that killed them. The following checks if the player was killed by a skeleton while being within 3 blocks of it.
2. "killing_blow"
A damage flags object checking various flags for the damage the player had dealt for the killing blow. The following triggers if the player is killed by a skeleton that didn't deal projectile damage.
impossible
This does not trigger naturally. The only way to trigger this is in vanilla to use the /advancement command. This greatly supplements command mechanisms as it allows more complex requirements that can be met with in-game commands.
For example, given the following advancement, assuming resource location "custom:missions":
The following commands will individually trigger each specific criterion, completing the advancement, but only for players that have the "winner" tag:
There are 0 conditions for this trigger.
inventory_changed
This triggers whenever the player's inventory is updated, such as from removing an item or adding an item. Note that spreading items through the inventory by holding left or right-click will count as multiple actions, though is only relevant if the advancement is revoked by a function reward during that tick. The following will trigger from any addition or removal of items from the player's inventory:
There are 2 conditions for this trigger: "slots" and "items".
1. "slots"
The "slots" object contains generic information about all slots in the inventory. Within it are three possible ranges to specify: "occupied", "full", and "empty". The armor and offhand slots are included in these checks.
The "occupied" range indicates the number of slots that have an item in it. The "full" range indicates the number of slots that have the highest number of items possible for that slot (such as 1 diamond pickaxe or 64 stone blocks). The "empty" range indicates the number of empty slots.
For example, the following will trigger when the player has exactly 10 empty slots in their inventory at the time that their inventory gets updated.
2. "items"
The "items" item object list matches the player's inventory against each item provided in the list. The inventory must match all items specified. The following checks if the player has both stone and dirt in their inventory at the time their inventory gets updated.
item_durability_changed
This triggers whenever an item in the player's inventory has resulted in a loss of durability. The following will trigger whenever any item in the player's inventory takes damage:
There are 3 conditions for this trigger: "item", "durability", and "delta".
1. "item"
The "item" item object matches the damaged item with the data provided. This specifically checks the item before it was damaged, allowing you to check its durability and other data prior to durability loss. The following checks if the player used a diamond sword that had 1540 or more durability remaining before being damaged.
2. "durability"
The "durability" range checks the item's remaining durability after the item was damaged. The following checks if a shield had at most 10 durability remaining after being damaged.
3. "delta"
The "delta" range checks the change in durability of the item. For example, the following checks if the item had a change of -2 durability or more (took 2+ points of damage).
levitation
This triggers whenever the player is under the Levitation potion effect.
There are 2 conditions for this trigger: "duration" and "distance".
1. "duration"
The "duration" range checks how the number of ticks the player has been levitating (not how long the effect itself was set to last). Note that this internal timer will not reset until the Levitation effect is removed, thus revoking the advancement after it was achieved will simply cause it to be achieved immediately after if the player is still under the Levitation effect. The following triggers when the player has been under the Levitation effect for 40 or more ticks.
2. "distance"
The "distance" distance object checks how the number of blocks away the player has traveled from the moment they received the effect. The following checks if the player has is still within 10 blocks (regardless of direction) of where they received the effect.
location
This triggers every second (every 20 ticks) at all times, essentially requiring the use of conditions despite them being optional for this trigger. However, this activation can be useful if needing pre-finished advancements. The following will always activate every second.
This trigger uses only the location object to check various data. The origin of the location is the player's coordinates.
1. "position"
The following checks if the player is between Y0 and Y30.
2. "biome"
The following will trigger once the player eventually visits both the "desert" and "plains" biomes.
nether_travel
This triggers every second (every 20 ticks) at all times, essentially requiring the use of conditions despite them being optional for this trigger. However, this activation can be useful if needing pre-finished advancements. The following will always activate every second.
There are 3 conditions for this trigger: "entered", "exited", and "distance".
This trigger uses only the location object to check various data. The origin of the location is the player's coordinates.
1. "entered"
A location object checking the location of the nether portal that the player entered the nether through. The following checks if that nether portal was in a desert biome.
2. "exited"
A location object checking the location of the nether portal that the player arrived to in the overworld after leaving the nether through a portal. The following checks if that nether portal was in the positive X and Z coordinates.
3. "distance"
A distance object checking the distance between the two nether portals positioned in the overworld. The following checks if they are horizontally 500 blocks apart.
placed_block
This triggers whenever the player places a block from their inventory.
This trigger makes use of the shared block object, and has 2 extra conditions for this trigger: "location" and "item".
1. shared block object
The block to be checked. The following checks if the player placed down smooth andesite.
2. "item"
An item object that checks information concerning the corresponding item that the player used to place the block, before the item was consumed. The following checks if the player placed an unpowered repeater block (where the corresponding item is "minecraft:repeater") that was the last item in the stack at the time of placing.
3. "location"
A location object that checks various location data about where the block was placed. For example, the following checks if glass block was placed anywhere at Y128 or higher.
player_hurt_entity
This triggers whenever the player deals any amount of damage to an entity, including 0 (e.g. snowballs).
There are 2 conditions for this trigger: "damage" and "entity".
1. "damage"
A damage object that describes the damage the entity had taken by the player, complete with entity source to check information about the player. The "type" string in that case is essentially useless because it will always be "minecraft:player". The following checks if the player dealt at least 10.0 raw projectile damage before damage reduction from the entity's gear, allowing for only up to 10% damage reduction.
The origin for the "distance" range for the source entity will be the player's location. That is, the value will describe the distance between the player and.. the player. This renders the option essentially useless. For example, the following checks if the player was within 3 blocks of themselves after damaging an entity, which is always true.
2. "entity"
An entity object that checks information concerning the entity that the player had damaged. The following checks if the player dealt projectile damage to a zombie.
The origin for the "distance" range for this entity will be the entity's location. That is, the value will describe the distance between the entity taking the damage and the player dealing the damage. The following correctly checks if the player was within 3 blocks of the entity they damaged.
player_killed_entity
This triggers when the player kills any entity extending the "Living" class (only mobs, not other players).
This trigger uses only the death object to check various data.
1. "entity"
Matches the entity killed against the specified entity object. The following triggers if the player kills a cow.
The origin for the "distance" range for the entity will be the mob's location. That is, the value will describe the distance between the entity that died and the player that killed it. The following checks if the player had killed a skeleton with a projectile while being 50+ blocks away from it.
2. "killing_blow"
A damage flags object checking various flags for the damage the player had dealt for the killing blow. The following triggers if the player kills a creeper without projectile damage.
recipe_unlocked
This triggers when the player unlocks a recipe. There is 1 required condition for this trigger: "recipe", which specifies the resource location to the desired recipe that must be unlocked. Note that this check only occurs at the time of receiving the recipe; if the player unlocked it before the advancement exists, the advancement will not take that into consideration. As the recipe is only detected at the moment of unlocking it, you must revoke the recipe from the player using the /recipe command before it can be detected again.
The following will trigger when the player unlocks the "minecraft:redstone" recipe, in whatever way they unlock it (including as a reward for another advancement).
slept_in_bed
This triggers when the player successfully sleeps in a bed. If the bed explodes, such as from trying to sleep in the nether, this will not trigger.
This trigger uses only the location object to check various data. The origin of the location is the player's coordinates after getting in the bed, which would be just above the bed's head.
1. "position"
The following checks if the player is below Y10 once they get in a bed.
2. "biome"
The following will trigger when the player sleeps in a bed while their position indicates the biome their new position is in, being where the head of the bed is. While this was seemingly implemented as a way to detect the player sleeping in the nether, the bed exploding will not cause the trigger to be fulfilled. The following checks if the player slept in a desert biome.
summoned_entity
This triggers when the player creates an entity in specific manners. Valid methods are: constructing a wither, constructing a snow golem, constructing an iron golem, and respawning the ender dragon. In the case of the ender dragon, all players able to view the boss bar will fulfill the trigger. The following triggers when the player summons any of the valid entities.
There is 1 condition for this trigger: "entity".
1. "entity"
Matches the entity summoned against the specified entity object. The following triggers if the player resummons the ender dragon.
The origin for the "distance" range for the entity will be the summoned mob's location. That is, the value will describe the distance between the entity that was summoned and the player that summoned it, or between the ender dragon and all elligible players. The following checks if the player is within 10 blocks of the ender dragon when the summoning ritual is complete, which would be very high in the air.
tame_animal
This triggers when the player tames any animal.
There is 1 condition for this trigger: "entity".
1. "entity"
The "entity" entity object specifies the entity that the player tamed. The following checks if the player tamed a wolf.
tick
This simply triggers every tick. This can be used to help simulate command block systems or automatically unlock advancements. The following activates every tick, revoking the same advancement as a reward so that it may activate in the next tick.
There are 0 conditions for this trigger.
used_ender_eye
This triggers when the player uses an Eye of Ender.
There is 1 condition for this trigger: "distance".
1. "distance"
The "distance" range specifies the number of blocks away the player (not the Eye of Ender) is to the nearest stronghold's center. It only takes into consideration the X and Z coordinate, ignoring the Y coordinate.
The formula for determining the number of blocks is:
For example, if the player was at (40, 64, 10) and the stronghold was at (120, 25, 400), the resulting distance needed to encompass the player is at least 398:
And the following will trigger if the player is standing at (40, 64, 10) with the stronghold at (120, 25, 400). If the player moves one block further away, they will no longer be detected.
used_totem
This triggers when the player uses a Totem of Undying.
There is 1 condition for this trigger: "item".
1. "item"
The "item" item object specifies item data about the item before it was consumed. For example, the following activates if the player had 5 totems of undying in the stack before one was consumed to save them.
villager_trade
This triggers whenever the player completes a trade with a villager. Note that shift-clicking to complete a trade multiple times will only trigger this for the first trade that tick.
There are 2 conditions for this trigger: "villager" and "item".
1. "villager"
The "villager" entity object describes information about the villager that was traded with. In this case, the "type" string is useless as it will always be "minecraft:villager".
The origin for the "distance" range for the entity will be the villager's location. That is, the value will describe the distance between the villager being traded with and the player that traded with it. The following checks if the player is within 1 block of the villager when completing a trade.
2. "item"
The "item" item object describes information about the item that was purchased. In terms of the count, keep in mind that this only accounts for one trade. If a villager was selling 2 sugar per emerald, shift-clicking to receive 10 sugar would still only count as 2 sugar as far as the advancement goes, as the first completed trade of the bunch was for 2 sugar. The following checks if the purchased item was sugar.
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
Wow, Skylinerw! Great guide yet again, thank you so much for documenting this stuff in-depth.
Quick point-out and question:
1. You have "/advancements" instead of "/advancement" near the top of the guide.
2. You said the "enchantments" item property looks at "ench." Does that mean enchanted books would fail the check?
This is great! Really appreciate the amount of work you must be putting in to discover every tag that does something in these advancements.
1. Fixed, thanks!
2. Looked into it: the "enchantments" condition checks "ench" NBT list for all items except books, while it checks "StoredEnchantments" NBT list but only for books. So a book that contains "ench" will not be detected, but a book with "StoredEnchantments" will be.
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
how do you make the root.json file it's not working in the 17w13b snapshot
Hmm, good guide! I'm currently working on a command block modpack, and I'll certainly refer back to this once I update to 1.12 (which will be once we get a stable version).
There's currently an issue (MC-115064) where the namespace is "minecraft" despite the files being in its own folder, so it's a bit odd to explain. I've omitted it from the main post until the bug is resolved, but I'll explain here how to work with the files for the time being.
Assuming you have the following files:
/world/data/advancements/custom/root.json:
The root advancement for a tab doesn't have to be called "root", but it does work as a clear indicator and would be consistent to do so. The root must not have a "parent" tag, but must have a proper "display" tag.
A new tab in the "Advancements" menu will not show up until at least one advancement in the tree is fulfilled. If you've got a valid root file but haven't completed any advancements in that tree, you won't see the tab. However, you could have a child advancement extending the root, while not giving that child a display. It will then act as a hidden method of forcing the tab to show up without having to complete any real advancements:
/world/data/advancements/custom/test.json:
You should then see:
However, to interact with those files (whether with /advancement or to specify a parent in advancement files), the namespace is not "custom" as would be expected, but is "minecraft" (being the bug, as the namespace should be the name of the root folder in "/data/advancements/"). To refer to the above files, you would use:
When the bug is fixed, you'd refer to them as:
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
Could you also use the data:image/png,base64,string thing as icons/backgrounds?
YouTube: https://www.youtube.com/channel/UCzGDRYWcrGreMmQFo_d5N5Q
Facebook:https://goo.gl/s0r12d
Website:https://theusaf.weebly.com
JavaScript Projects: https://theusaf.github.io
Link Shortener: https://shortr.github.io
Twitter:https://www.twitter.com/theusafyt
I have another question based on this. What if I did:
/give @p enchanted_book 1 0 {ench:[{id:0,lvl:10}],StoredEnchantments:[{id:16,lvl:32767}]}
Which will it look at then? Or will it look at both?
Edit: nvm "So a book that contains "ench" will not be detected," Im blind...
YouTube: https://www.youtube.com/channel/UCzGDRYWcrGreMmQFo_d5N5Q
Facebook:https://goo.gl/s0r12d
Website:https://theusaf.weebly.com
JavaScript Projects: https://theusaf.github.io
Link Shortener: https://shortr.github.io
Twitter:https://www.twitter.com/theusafyt
No, the icon must be an item ID and the background must point to a resource pack image.
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
Sorry, it will looks at what's relevant. If it's a book it looks for "StoredEnchantments" instead of "ench". If the book doesn't have "StoredEnchantments" then it won't be detected, not that it's disregarded if it has "ench". So yes, that book will be detected because it has "StoredEnchantments".
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
It's currently not possible. We most likely won't get that ability though, as instead all items with a Damage value (excluding items with durability) will be split into their own IDs. For example, red wool would be "red_wool" instead of "wool" with a Damage value of 14. More info here on that upcoming change: https://bugs.mojang.com/browse/MC-105922
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
If nbt is/will be possible on the displayed item, we could use the durability, as well as custom player heads.
so I hope that will happen.
It only seems to work when placing the advancements in the World Data folder, whats the us of the Advancements folder in the resource packs?
My Youtube Channel: https://www.youtube.com/channel/UCd_JoIjCmRRjG7S5vR4hYig/
The jar != a resource pack, advancements and loot tables are part of the data of minecraft, but are not editable by resource packs because they are handled server side (as the progress/loot needs saving).
So I have two files to test with root.json and beach.json.
So in root.json
I have the criteria for the file which is detecting if the player is in the nether. I also have to put the same criteria in the beach.json file as well, but what is the difference between putting the triggers and junk in the root and child files?
You also said below about the child advancement, but you don't list what the "custom/root" advancement was, could you edit the post to show what the "custom/root" advancement was so we can get a better understanding into how it's related?
"It's what you do with the gift of life that determines who you are." ~Mewtwo
Minecraft uses the root for actual triggers and rewards, but you don't have to do that. You can have whatever criteria you want in the root; what makes it the "root" is not having a parent and having a display. It doesn't even need children, but would be ideal to have since otherwise you'd have a lot of tabs to work with that only contain single-advancement trees.
A parent also doesn't need to be fulfilled for a child to be fulfilled. You could leave a "minecraft:impossible" criteria and not touch it at all, or you could have a criteria that will automatically be fulfilled, such as "minecraft:location". The tab itself only shows up if at least one criteria in the tree is fulfilled, so that automation may be desired if you want the player to know that those advancements exist.
This is all very subject to change though, and may not work that way in the future. That is primarily why I've avoided adding much information in the way of manipulating the trees for now, but I have a separate post here about a root and child. I won't be adding this to the main thread until the namespace bug is fixed, since that fix would change how you reference the advancements (thus invalidating my other post).
EDIT: Oh, just noticed a small typo in your root: you have "minecraft:writeable_book" for the icon which needs to be "minecraft:writable_book" instead.
Minecraft-things: http://skylinerw.com
More Minecraft-things: https://sourceblock.net
Guides for command-related features (eventually moving to Source Block): https://github.com/skylinerw/guides
I primarily hang out in the /r/MinecraftCommands discord, where there's a lot of people that help with commands: https://discord.gg/QAFXFtZ
Their corresponding subreddit: https://www.reddit.com/r/MinecraftCommands/
In related to the -snipped- part, I realized my mistake, and noticed the namespace bug as well.
In relation to the EDIT, yeah I noticed that. That was also my problem lol
"It's what you do with the gift of life that determines who you are." ~Mewtwo
Yep, fixed for the next snapshot