Minecraft / Blogs

Minecraft Advancements and Functions Tutorial [1.12+]


Get Embed Codes

Level 53 : Grandmaster Cyborg
If you encounter any problems, feel free to send me a PM!

Besides the standard advancements provided by the Mojang developers, it is possible to add custom advancements and also functions to a Minecraft world. You can place custom advancements in a top-level folder at ".../.minecraft/saves/WORLDNAME/data/advancements/"
and custom functions in a top-level folder at
These top-level folders act as a "namespace" and are always required. For example:

The custom advancement named "advancement.json" has a namespace called "custom1". Naming the advancement after a default Minecraft advancement and setting its namespace to "minecraft" will make it override that default advancement. If you don't want this to happen, simply don't use the "minecraft" namespace.

The default namespace is called "minecraft", which can be used to overwrite default advancements. In any other case the use of this namespace should be avoided.

Custom advancements
Criteria - necessary
To make a custom advancement, make a new text file in any text editor and save it as .json (I personally use Notepad++, a free program which can be downloaded here). Advancements consist of certain elements, one necessary and others optional. Let's start with the necessary one: the criteria. Criteria are used to specify when an advancement is completed by a player.


Above you will see the basic format of a custom advancement with two criteria. You can replace "Criteria_Name" and "Another_Criteria_Name" with whatever text you want, but "TRIGGERNAME" and "CONDITIONNAME" must be picked from a list of available criteria which are provided by Mojang (a list of triggers and their available conditions can be found further ahead). An example is given below.


This advancement will trigger when the player has both bred a cow and has visited the desert, doing them simultaneously is NOT necessary however. So you can visit the desert and leave it, then breed a cow and still obtain the advancement. You don't necessarily have to specify the conditions, in which case the criteria will be full-filled when its trigger has been activated. For triggers like "enter_block" and "location" this means that they will trigger basically immediately.

This is not everything however, since you can have some more optional control over criteria using the "requirements" parameter. The image below shows the requirement tag with both criteria listed together, which means that either criteria have to be full-filled for the advancement to be completed instead of both the criteria.


You can also make the advancement get completed when both the criteria have been met by listing the criteria separately (this is also the default behavior for when you just leave out the requirement parameter, so you don't always need to add it!). By using this system you can create more advanced logic with multiple criteria.


You hopefully have a working advancement now, but it's not doing anything. For this we need some other elements.

Triggers and Conditions
A full list of all available triggers and their corresponding conditions can be found here. This page is hosted on Gamepedia to make use of their templates, the content of the page was written mostly by me.

Rewards - optional
If you want your advancement to give rewards we can specify that in the advancement json file as well.


Here you see the 4 different ways of giving a reward:
Recipes will grant the player certain recipes for in their recipe book (a new 1.12 feature) and it's a simple list of Minecraft items (in the future custom recipes will be a thing as well!).
Loot will give the player items based on loot tables from mob drops and chests spawned in structures (this will completely mimic the behavior of loot, including randomization). Custom loot tables are also a thing so giving items is extremely customizable.
Experience is pretty straight forward, it will grant experience points (NOT levels) to the player.
Function will run the commands from the function text file you specified. In the example above it will run the function located at .minecraft\saves\XXXX\data\functions\example\test.mcfunction
If you only want to give for example experience, you can just leave the other 3 options away. You only have to list the things you want to use.

Branching and Display - optional
You have a pretty nice custom advancement now, but to make it even nicer we can make your advancements display in the actual Minecraft advancement list and make them pop up when a player has completed them.
Before we do this we need to talk about how to structure multiple advancements together, which is actually pretty easy. The "root" of an advancement is the first advancement in a tree branch of multiple advancements and is defined by NOT having a "parents" parameter in the json file. So the advancement we made previously is a root advancement (with a path file of for example: .minecraft/saves/WORLDNAME/data/advancements/custom/stuff/root.json which means its namespace is "custom") , but with no other advancements after it yet. So let's make another advancement to branch of the root advancement now.



This advancement has its parent defined as "custom:stuff/root". "custom" being the namespace and stuff/root being the remaining path to the root advancement. Keep in mind that these names are arbitrary and can be changed to your liking. Also note that the folder structure of your advancements has nothing to do with the in game structure. You can have a file in a different folder be the parent of an advancement in another file, as long as they're in the same WORLDNAME/data/advancement folder of course.

You can have multiple advancements referring to the same parent, making different branches. Or you can make a line of advancements each having the previous one as a parent. Having multiple parent advancements is however not possible. Keep in mind that parents don't prevent other advancements from being achievable. So you can complete a branched advancement without achieving its parent.

Now that you can link advancements together, let's actually make them display. To make an advancement tree branch display in the advancement list, you need to add the display parameter to the root files and all its branches. You must specify icons, titles and descriptions for each advancement. For the root advancement you can also specify the background for the advancement tab. You can set the frame of the advancement to 3 different shapes: "task", "challenge" and "goal" ("task" being the default when not specified). On top of that, you can specify if you want the advancement to be announced in chat or pop up on screen using "announce_to_chat": true/false and "show_toast": true/false respectively (they both default to true when not specified).
You can also use "hidden": true/false. This determines whether or not to hide this advancement and all its children from the advancement screen until the hidden advancement have been completed (after which all its children will also become visible as long as they're not set to be hidden themself). This has no effect on root advancements since they are always hidden.

For example:





This will produce an advancement tab like this once one of the two advancements has been completed. Adding the display parameter for an advancement will also make it pop up when it has been completed (unless "show_toast" is set to false). If you want branched advancements to pop up but you don't want them to display on the advancement screen, simple remove the display parameter from the root advancement, but keep it on the branched advancements.

As you saw, for titles and descriptions you can simply provide a string of text but you can also add some text formatting the same as you would with text components from /tellraw and /title commands (except for event listeners, scores and selectors). An example:

"title": {"text":"Hello World","obfuscated":true,"italics":true,"bold":true,"color":"dark_red"}

In-game advancement files
A full list of the in-game advancement files made by Mojang can be found here:

You will see the use of "translate" in titles and descriptions. Keep in mind that this does NOT work with normal text, it functions through the Minecraft language files.

Functions - the new way of executing commands
I've mentioned functions before in the reward section of advancements. They sound pretty complicated, but they're actually quite easy to use. Function files are just text files with the ".mcfunction" file extension located at \data\functions\ in your world folder. They can contain commands (one command on each line without the usual forward slash!). Functions will execute all of their commands in one single tick. An example of a function text file:

You can also add "comments" by using "#" before the text. Comments are just used for organization and are ignored by Minecraft when running the function.

Now let's say we place these commands in \data\functions\example\pep\test.mcfunction. Make sure the file extension is correct. As before with advancements, it's important to remember that this function file now has a so-called namespace of "example" and a remaining path of "pep/test".

There are 3 ways to use function files. The first 2 ways are using the commands explained in the upcoming section (/function and /gamerule gameLoopFunction).
Note that the /function command runs the commands as if they were run by the player or commandblock who ran the /function command and that the /gamerule gameLoopFunction runs the commands through the "server" (or through the world if you prefer to call it that, so you don't get confused with the usual meaning of "server". It's just important to know that the commands aren't run from a specific entity). The "server" will run the function at the coordinates 0,0,0.
The third way of running functions is by giving them as a reward for advancements, which runs the commands as if they were run by the player who completed the advancement. In all these 3 cases, you need to specify the function you want to run using "namespace:path/to/function/file". For our example this would be "example:pep/test".

You might have thought of this already, but you can use the /function command in a function file. When doing so, Minecraft will run all the commands from that called function in the same tick as the function that called it. This means you can create one piece of command "code", place it in its own function file and just use the /function command in your main function file to "call" this function whenever you need it. This makes writing complex command creations way easier and more organized! Keep in mind that individual commands in functions can be longer than the 32 500 character limit in command blocks but the total number of commands run inside a function will still obey /gamerule maxCommandChainLength, which is 65 536 commands by default; any commands beyond this limit will not be run.

One last note is that position changes that happen within a function will not affect the relative coordinates used in other commands within that function (or other functions called within the function) till the next iteration regardless of the order of commands, the /execute command circumvents this. For example:

tp @s ~ ~5 ~setblock ~ ~-1 ~ emerald_blockexecute @s ~ ~ ~ setblock ~ ~-1 ~ diamond_block
These 3 commands, when in a function ran through a player, will teleport that player 5 blocks up, place an emerald_block one block below their original position before the teleport and place a diamond block one block below their new position after the teleport. This behavior does not affect position arguments within selectors, which will always test for the current position at the time of execution.

There are 3 main commands associated with advancements:

- /advancement <grant|revoke> <player> <only|until|from|through|everything> [advancement] [criterion]
This command can either grant (give) or revoke (remove) advancements or advancement criteria.
"only" -> Grants/revokes only the specified advancement from the player.
"until" -> Grants/revokes the specified advancement, its parent advancement, its parent's parent advancement, etc. from the player. From the start until the specified advancement. The exact order of granting/revoking is "parent" > "parent's parent" > ... > "start" > "specified advancement".
"from" -> Grants/revokes the specified advancement, its children advancements, its children's children advancements, etc. from the player. All the way forward from the specified advancement. The exact order of granting/revoking is "specified advancement" > "child" > "child's child", when a branch is found it will iterate through the top branch entirely before going through the other branches. Because the order of branches depends on how the operating system reads the files, this order will be inconsistent across different operating systems.
"through" -> Acts as until and from combined; all advancements through the specified advancement, going both backwards and forwards. The exact order of granting/revoking is the same as for until and from, until being done before from.
"everything" -> Grants/revokes every loaded advancement from the player.

- /advancement test <player> <advancement> [criterion]
This command will test if a player has completed an advancement or one of its criteria.

- /reload
This command will reload all advancement, function and loot table files from the disk in case they have been updated during a session.

There are 3 main commands associated with functions:

- /function <function> [if|unless] [selector]
This command will execute all commands from the function file you specify through the player or commandblock that uses this command. An example: /function example:pep/test will run the function file located at \data\functions\example\pep\test.mcfunction
The optional arguments "if" and "unless" will make the function only run when the selector was found or not found in the world respectively.

- /gamerule gameLoopFunction <function>
This command will execute all commands from the function file you specify through the "Server" once every tick.

- /reload
This command will reload advancement, functions and loot table files from the disk in case they have been updated during a session.

Useful links
  • Gamepedia: Advancements | Function
    • For more information you can go here, although I covered most, if not all, of it here. Similarities may occur because I am one of the people editing these 2 Gamepedia pages.

  • JSON validator
    • A tool to check whether your advancement file has the proper JSON formatting. Very useful for debugging your advancements!

  • In-game advancements
    • These are the advancements made by Mojang that are standard in the game. I did not make these and they are purely listed here so people can have a look at them to understand the formatting better.

  • Mojang bug tracker
    • Search or report bugs here. Make sure your issue hasn't been reported before and add as much relevant information as possible to help speed up the process.

Credit:Gamepedia, Mojang

Update #8 : 07/19/2017 9:35:34 am7/19/17

  • Added more information to both the advancement and function section.
    • Explained namespaces better and when (not) to use the "minecraft" namespace.
    • Fixed the advancement commands.
    • Explained calling functions from within other functions better.

Update #7 : 06/08/2017 11:02:40 am6/08/17

  • Completely redid the triggers and condition section and moved it to Gamepedia to make use of their templates.
  • Updated the "requirements" tag behavior which was changed in a snapshot but overlooked by me initially.

  • Updated the "hidden" tag behavior which was changed in a snapshot but overlooked by me initially.
  • Updated the page to 1.12
    • Removed "Enable Snapshots" section

  • Some minor edits.

Update #6 : 05/22/2017 11:05:30 am5/22/17

  • 1.12-pre4 stuff:
    • Updated the /function command to include "if" and "unless".

  • 1.12-pre5 stuff:
    • Updated the function section to include function behavior with relative coordinates.

  • 1.12-pre6 stuff:
    • Removed text about bugged behavior which was fixed in 1.12-pre6.

  • 1.12-pre7 stuff:
    • Updated list of in-game advancements.

  • Added a link to the Mojang bug tracker.

Update #5 : 05/17/2017 2:48:26 pm5/17/17

  • 1.12-pre3 stuff:
    • Updated list of in-game advancements.
    • Updated the function section.

  • Updated list of conditions.

Update #4 : 05/10/2017 9:49:19 am5/10/17

  • 1.12-pre1 stuff:
    • Updated list of triggers. Added "effects_changed", "nether_travel" and "used_totem". Removed "arbitrary_player_tick".
    • Updated list of conditions.
    • Updated list of in-game advancements.
    • Updated reward section. Added "function". Removed "commands".
    • Updated display section. Added "hidden".
    • Updated command section. Added commands for using functions.
    • Changed scripting section to a function section.

  • 1.12-pre2 stuff:
    • Updated list of ingame advancements.

Update #3 : 05/04/2017 5:29:44 pm5/04/17

  • 17w18b stuff:
    • Updated list of triggers. Added "consume_item", "placed_block" and "arbitrary_player_tick".
    • Updated list of in-game advancements.
    • Updated the scripting section to use the new "arbitrary_player_tick" trigger.

  • Added an "Enable Snapshot" section, use backups when playing on snapshots!
  • A new layout.

Update #2 : 05/03/2017 5:21:32 pm5/03/17

  • 17w18a stuff:
    • Added "show_toast" and "announce_to_chat" options.
    • Added /reload and /gamerule announceAdvancements commands.
    • Updated scripting API to use the new "minecraft:tick" trigger.

  • Added a full list of triggers, including a description and available conditions. From Gamepedia (which is being updated partially by me).
  • Added a list of conditions and options in their appropriate formatting.
  • Added a download link to all in-game advancements which were made entirely by Mojang. To help understand formatting better.

Update #1 : 05/02/2017 4:26:31 pm5/02/17

  • Added a "Requirements" parameter explanation.
  • Added frame options and text formatting explanation.
  • Added /advancement commands explanations.
  • Added a scripting explanation.
  • Made some minor edits.

Comments : 40

Join us to post comments.

Show Comments

1 - 40 of 40

So say for instance I wanted to have an advancement for killing or harming a specific player. How would I go about that? Also, how would I go about merging the item and item stack criteria so that I have requirements like "Obtain 64 of this item"?

Thank you, Much Obliged...

~ Peashooter101
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 21, 2017, 4:13 am
For a player harming a specific player you can use this (using a scoreboard tag to specify which player). This will also activate when a player kills that specific player:

For having a stack of items in a slot you can use this:
How would you do this tracking items with a specific name (even if colored or formatted) or lore?

~ Peashooter101
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 22, 2017, 1:14 pm
You can use the "nbt" option for that. An example: https://pastebin.com/4me49LHi
The nbt data is the same as that for commands like /give, except that you need to make sure to properly escape quotes (so you need to use \" instead of just " so Minecraft doesn't get confused with multiple quotes).

In the blog you can find a link to https://minecraft.gamepedia.com/User:PepijnMC/Triggers, which is a page made by me with a pretty detailed example for every trigger.
So if the Item is a Skull, per say, and it contains the NBT Tag to give it its texture, would I just use the "texture": argument in the same manner as the NBT Args? Just asking to verify, I will try it sometime soon myself. I have xisumavoid's skulls and if there is a way for me to read each skull, I am adding that to Advancements.

~ Peashooter101
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 23, 2017, 12:49 pm
Yes, just make sure to escape quotes and you should be fine.
How would I apply this to the use of Teams in the Scoreboard, will I test for "team": instead of "nbt":?
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 26, 2017, 9:49 am
No. It only allows you to search for stuff that Mojang has coded in and "team" is not. Again, you can find all available keys for each trigger here: https://minecraft.gamepedia.com/User:PepijnMC/Triggers

A key "team" is not listed anywhere and thus not available. There is a Team key within NBT data of a mob, but it's not actually used dynamically (it's only a tag you can use when summoning a mob, it won't change when you add the mob to a team manually). So you can't use that either.

My suggestion is to tag everything that is in a team and then just test for the tag.
I appreciate it, I wasn't sure if that would actually work. Most of my custom advancements are made using a website but the website is very buggy and what not so to simplify some of the processes, I use it as a base then go through it myself to see what I can do with it. I appreciate the extra info regarding NBT Tagging using the Scoreboard.

~ Peashooter101
  • jstro69
  • Level 1
  • New Miner
  • June 13, 2017, 10:35 pm
please help, i did everything right (I promise) im 112 full release but the function command is broken... yes, i did do /reload
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 14, 2017, 2:04 am
I'm going to need some more information before I can help you, could you zip your data file, upload it to a site like mediafire/dropbox and send me the download link?
  • WindBound
  • Level 8
  • Apprentice Warrior
  • June 11, 2017, 12:08 am
I understand very few of this, there should really just be a generator for this that allows us to easily do any of this xD
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 11, 2017, 3:23 am
There probably will be/is one already :p. But it's nice to understand what the generator does so you can easily fix small problems you're having.
  • WindBound
  • Level 8
  • Apprentice Warrior
  • June 11, 2017, 12:28 am
After a bit of testing, there is NO example for the kind of thing I'd like to do. I click the example button and nothing shows up like any of the other examples.

  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 11, 2017, 3:21 am
I'm still working on that page. I will see if I can get all examples in there today.
  • WindBound
  • Level 8
  • Apprentice Warrior
  • June 11, 2017, 1:33 pm
Could you please like, do one for me? Nothing crazy, just that it triggers once it notices an item or block has entered the inventory. Plus maybe give it its own tab.

For example, I'd like to trigger an achievement when the DIRT block first enters the inventory and then after that I'd like to detect the OAK LOG when it enters the inventory. I could probably figure it out if I have a live example of what I'd like.
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 11, 2017, 2:57 pm
I updated the page and provided basic examples for each trigger now (https://minecraft.gamepedia.com/User:PepijnMC/Triggers). You can also take a look at all the standard advancements from Minecraft if you need more basic examples to start with (I included a download link to all of them in the blog).

Here is a full example (with a display and everything) of the 2 advancements you mentioned:
Instead of letting them have their own tab, I included them in the main Minecraft tab in front of the crafting table advancements.
  • WindBound
  • Level 8
  • Apprentice Warrior
  • June 11, 2017, 5:42 pm
I still have a problem, I have the oak log one in too, but it doesn't show or interact at all.

This is what I have:

he folders have the files you have linked in them (Respectively in the titled folders)

How about you give me a step by step visualization of how to install them lol
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 11, 2017, 5:53 pm
Don't put them in separate files, keep the file structure from the download link I have.
So put all 3 json files in:
  • WindBound
  • Level 8
  • Apprentice Warrior
  • June 11, 2017, 6:31 pm
I have this and it still won't work:

saves/Worldname/data/advancements/minecraft/story (The minecraft is the exact thing you linked) and it will not load the oak log at all. It loads the dirt perfectly fine, but if I try obtaining the log it doesn't register.

Can you show me that you have it working?
  • WindBound
  • Level 8
  • Apprentice Warrior
  • June 11, 2017, 7:00 pm
OH! It finally clicked on in my mind on how to install it.

I don't need any help anymore, tested making my own few to see if I knew the basics, got everything working :D
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 11, 2017, 7:13 pm
That's great! Good luck with your endeavors.
  • HZServers
  • Level 11
  • Journeyman Engineer
  • June 9, 2017, 2:04 am
Thank you. This is sooo useful
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 9, 2017, 4:31 am
Nice to hear! Good luck with whatever you're making.
  • HZServers
  • Level 11
  • Journeyman Engineer
  • June 9, 2017, 11:45 am
I am planning on recreating one of my old minecraft servers. It was a casino, but everything was command blocks. Spigot wasn't even installed.
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • June 10, 2017, 1:18 pm
Sounds interesting, good luck with it! If you have any questions regarding commands, functions, etc just let me know.
  • zack909
  • Level 7
  • Apprentice Miner
  • June 8, 2017, 12:07 pm
there's a challenge completed sound now
here it is:
click me pls
Is it possible (in the criteria abot breding cows and being in the desert) to make it so that both are required simultaneously?
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • May 30, 2017, 5:27 am
Just a note, they've added a location sub-condition to all entity conditions. So you can do this now:


It's of course not exactly the same as requiring two separate criteria to be obtained simultaneously, but it solves this specific example.
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • May 4, 2017, 1:27 am
I could not find a build in option for this, it might come in the future.
Oh okay.... BTW I noticed (a minecraft Bug) that you can't post unlimited advancements (if they're custom), unless you place them in story, adventure, nether or end.
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • May 4, 2017, 4:53 am
Well, you can't place unlimited advancements either way. It's both physically impossible and your pc can't handle it. But do you mean in the advancement screen due to the limited amount of free space for tabs?
No, I mean that in only 1 tab, you can only put a maximum of 7 or 8 advancements, but some won't show up, even if they're correctly written, but if you use the Vanilla ones, such as story, It will be perfectly fine, even the screen will scroll up and down
  • LimeFox
  • Level 32
  • Artisan Fox
  • May 2, 2017, 10:39 am
Wow thanks so much. I now see what they are made for. Seems like its gonna be great fot multiplayer servers such as rpg ones. Am i right?
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • May 2, 2017, 10:42 am
Yup, plugins could already do a lot but this gives has a nice display for it (and it's build-in, which is often better).
After this I'll make my custom advancements!
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • May 2, 2017, 8:22 am
\o/ Good luck! If you encounter any problems just let me know.
i woulldd do this on my minecraft world but im to lazy. but it sounds like fun ^^ might have my command friend do it =3 he owes me for the spam kill command he did on me a while back huehuehue >;3
Yea x3
  • Pepijn
  • Level 53
  • Grandmaster Cyborg
  • May 1, 2017, 2:27 pm
Haha. It's awesome to have custom advancements in a survival world, gives you some more motivation for doing certain tasks.

1 - 40 of 40

Show Comments




© planetminecraft.com