16

Minecraft Advancements and Functions Tutorial [1.12-pre3]

Collectable

Get Embed Codes

Forum:
HTML:
Link:
avatar
Pepijn
Level 52 : Grandmaster Cyborg
336
Advancements (which will replace achievements in 1.12) are one of the biggest changes so far for Minecraft 1.12, they can be found in the 1.12 snapshots which you can access through the Minecraft launcher. Snapshots can be unstable and they can corrupt your world! Make backups and possibly launch the snapshots from a different directory!

Functions are simple text files filled with commands. They can be run from "/gamerule gameLoopFunction", "/function" and as rewards for advancements.

If you encounter any problems, feel free to send me a PM!


Enable Snapshots


Introduction
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 at ".../.minecraft/saves/WORLDNAME/data/advancements/"
and custom functions at
".../.minecraft/saves/WORLDNAME/data/functions/"
You can make folders inside the advancement folder as well, to organize things a bit better. The root folder is what we call the namespace of advancement or function. For example:

".../.minecraft/saves/WORLDNAME/data/advancements/custom1/stuff/advancement.json"
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.

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.


https://pastebin.com/JckTwwZY

Above you will see the basic format of a custom advancement. 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.


https://pastebin.com/DmwKdUxV

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 both criteria have to be full-filled for the advancement to be completed (this is also the default behavior for when you just leave out the requirement parameter, so you don't always need to add it!).


https://pastebin.com/aTiGexM7

You can also make the advancement get completed when either criteria is met by listing the criteria separately. By using this system you can create more advanced logic with multiple criteria.


https://pastebin.com/M4qdM0Eu

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

Triggers and Conditions
Table provided by Gamepedia (which is being updated partially by me).

Trigger NameTriggered when:Available Conditions
minecraft:bred_animalsPlayer breeds 2 animals."parent", "partner", "child"
minecraft:brewed_potionPlayer brews a potion."potion"
minecraft:changed_dimensionPlayer travels to or from a dimension."to", "from"
minecraft:construct_beaconPlayer changes the structure of a beacon. (When the beacon updates itself)."level"
minecraft:consume_itemPlayer consumes an item."item"
minecraft:cured_zombie_villagerPlayer cures a zombie villager."zombie", "villager"
minecraft:effects_changedPlayer gets a potion effect applied or taken from them."effects"
minecraft:enchanted_itemPlayer enchants an item through an enchanting table (does not get triggered through an anvil, or through commands)."item", "levels"
minecraft:enter_blockPlayer enters a block (such as a portal), player needs to be standing in the same block space as the block. Checks every tick but if the advancement is revoked immediatly using a reward command, it will trigger for each successful match in one tick. This means it can trigger between 1 and 8 times each tick."block", "state"
minecraft:entity_hurt_playerEntity hurts a player."damage"
minecraft:entity_killed_playerEntity kills a player."entity"
minecraft:impossibleOnly using commands.
minecraft:inventory_changedAny changes happen to the player's inventory."items", "slots"
minecraft:item_durability_changedAny item being damaged in any form."item", "durability", "delta"
minecraft:levitationPlayer having the levitation status effect."duration", "distance"
minecraft:locationChecks every 20 ticks (1 second) where the player is."position", "biome", "feature"
minecraft:nether_travelPlayer travels to the Nether and then returns to the Overworld."distance"
minecraft:placed_blockPlayer placed a block."location", "block", "state"
minecraft:player_hurt_entityPlayer hurts an entity (including itself)."damage", "entity"
minecraft:player_killed_entityPlayer kills an entity."entity", "killing_blow"
minecraft:recipe_unlockedPlayer unlocks a recipe (using a knowledge book for example)."recipe"
minecraft:slept_in_bedPlayer enters a bed."location"
minecraft:summoned_entityPlayer summons an entity through for example summoning the wither using soul sand and wither skulls. Works with iron golems, snow golems and the ender dragon (using ender crystals) as well. Using dispensers to place the wither skulls or pumpkins will still activate this trigger. Spawn eggs, commands and mob spawners will not work however."entity"
minecraft:tame_animalPlayer tames an animal."entity"
minecraft:tickTriggers every tick (20 times a second).
minecraft:used_ender_eyePlayer uses an ender eye (in a world where strongholds generate)."distance"
minecraft:used_totemPlayers uses a totem."item"
minecraft:villager_tradePlayer trades with a villager."villager", "item"

A full list of conditions and their formatting can be found here.

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


https://pastebin.com/5tcF4Cjc

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 point (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/or 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.

custom/otherstuff/BranchA_advancement.json

https://pastebin.com/r4cAJGwU

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 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. As of now, 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 also 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 they have been completed. This has no effect on root advancements them self but will still effect all their children. Once a "hidden": true value has been inherited from a parent advancement, it can't be overwritten to false. Defaults to false.

For example:

custom/stuff/root.json

https://pastebin.com/yBqjrVhn

custom/otherstuff/BranchA_advancement.json

https://pastebin.com/BmGbkq8D

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 description 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:
https://www.dropbox.com/sh/aolacnqfttrmwhv/AAB0PP5Q6xKFvdzNkrvsrWhfa?dl=0 

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 or location).
The third way of running functions is by giving them as a reward for advancements, which runs the commands as it 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 since you can use the /function command in a function file. 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 the amount of commands that can run within one tick is limited by "/gamerule maxCommandChainLength".

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 @a ~ ~5 ~setblock ~ ~-1 ~ emerald_blockexecute @a ~ ~ ~ setblock ~ ~-1 ~ diamond_block
These 3 commands will teleport all players 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.

Commands
Advancements
There are 3 main commands associated with advancements:

- /advancement <grant|revoke> <only|until|from|through|everything> [advancement] [criterion]
This command can either grant (give) or revoke (remove) advancements or advancement criteria.
"only" -> grant only the specified advancement/criterion. Needs [advancement] but [criterion] is optional.
"until" -> grant the specified advancement, its parent, it parent parent, etc. till the root advancement. Needs [advancement].
"from" -> grant the specified advancement and all it's branched advancements. Needs [advancement].
"through" -> combination of "until" and "from". Needs [advancement].
"everything" -> grants every advancement.

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

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

Functions
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. Currently the if argument only succeeds upon matching 1 target (beyond which the function will be skipped), and the unless argument with 0 or 2+ targets (with only 1, the function will be skipped), although this behavior is likely unintended.

- /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.

Tags:Tutorial, Guide, How, Advancement, Advancements, Function, Functions, Goal, Challenge, Task, Custom, 112, Snapshot, Snapshots, 17w16a, 17w16b, 17w17a, 17w17b, 17w18a, 17w18b, Achievement, Map, Reward, Criteria, Trigger, Display, Condition, Requirement
Credit:Gamepedia, Mojang

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.

  • 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 : 12

Join us to post comments.

Show Comments

1 - 12 of 12

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 52
  • 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 52
  • 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
  • Drostik
  • Level 28
  • Expert Architect
  • 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 52
  • 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 52
  • 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 52
  • 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 - 12 of 12

Show Comments