Minecraft Blogs / Tutorial

Minecraft Datapack Tutorial [1.16]

  • 19,939 views, 12 today
  • 35
  • 19
  • 43
Pepijn avatar Pepijn
Level 56 : Grandmaster Cyborg
374
If you encounter any problems, feel free to send me a PM!

Introduction
Data packs in Minecraft could be described as resource packs but for game logic. To be more precise, resource packs are for the client and data packs are for the (integrated) server. But don't worry too much about the definition, what mostly matters is what you can do with it.
Just like resource packs are a collection of "resources" for the game (textures, models, sounds, etc), data packs are a collection of "data" for the game. This "data" includes advancements, functions, loot tables, structures, recipes, tags, and predicates. Each of these will be discussed in their own section further along, but for now let's focus on actually setting up an empty data pack. First you must find the installation location of Minecraft, which by default will be the .minecraft folder. Since data packs deal with in game data (the integrated server) they are always attached to a minecraft world and as such it's easiest to create one directly where it belongs. First thing to do is create a folder here:.../.minecraft/saves/<world name>/datapacks/<data pack name>/This is where we will start to make your data pack. For the game to recognize that this folder is indeed a data pack that it can use, we have to add a file called "pack.mcmeta" with the following contents:{
  "pack": {
    "description": "",
    "pack_format": 5
  }
}
Save the file and you have now made your first data pack. Of course it doesn't do anything yet so let's hurry along.Create a folder called "data" within your main data pack folder. Inside this "data" folder is where you have to create another folder with a name referred to as the "namespace". This namespace is what helps the game differentiate between your data pack and someone else's data pack that also might be installed in the same world. Namespaces can only contain the following characters:
  • 0123456789
  • abcdefghijklmnopqrstuvwxyz
  • _
  • -
Advancements go in:.../datapacks/<data pack name>/data/<namespace>/advancements/Functions go in:.../datapacks/<data pack name>/data/<namespace>/functions/Loot tables go in:.../datapacks/<data pack name>/data/<namespace>/loot_tables/Predicates go in:.../datapacks/<data pack name>/data/<namespace>/predicates/Structures go in:.../datapacks/<data pack name>/data/<namespace>/structures/Recipes go in:.../datapacks/<data pack name>/data/<namespace>/recipes/Tags go in:.../datapacks/<data pack name>/data/<namespace>/tags/

Advancements
Advancements are simply put a way to check certain conditions and give the player who fulfills these something in return. You specify the conditions with one or more "criteria", when met they will grant that player the advancement and possibly a "reward" if you choose to include one.

To start, make a new text file in any text editor and save it as .json.

Criteria
Criteria are used to specify when an advancement is completed by a player. They consist of two parts: triggers and conditions. Triggers are used to detect certain events happening in the game, for example the inventory changing or the player breeding two animals. The conditions can then be used to specify certain details, so instead of the advancements being granted for breeding whatever animal you can tell the game to only grant it when the player breeds two wolves.

{
  "criteria": {
    "Criteria_Name": {
      "trigger": "minecraft:TRIGGERNAME"
    },
    "Another_Criteria_Name": {
      "trigger": "minecraft:TRIGGERNAME",
      "conditions": {
        "CONDITIONNAME": "VALUE"
      }
    }
  }
}

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 coded into the game. An example is given below.

{
  "criteria": {
    "Criteria_Name": {
      "trigger": "minecraft:bred_animals",
      "conditions": {
        "parent": {
          "type": "minecraft:cow"
        }
      }
    },
    "Another_Criteria_Name": {
      "trigger": "minecraft:location",
      "conditions": {
        "biome": "minecraft:desert"
      }
    }
  }
}

This advancement will be granted 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 any 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 be granted basically immediately.

This is not everything however, since you can have some more optional control over criteria using the "requirements" parameter. This is a list of lists. In the code below, the requirement list includes one list, which then contains the two criteria. Having criteria in the same list means either one of them has the be completed for that whole list to count as completed. In more technical terms, the requirements are in conjuctive normal form.
{
  "criteria": {
    "Criteria_Name": {
      "trigger": "minecraft:bred_animals",
      "conditions": {
        "parent": {
          "type": "minecraft:cow"
        }
      }
    },
    "Another_Criteria_Name": {
      "trigger": "minecraft:location",
      "conditions": {
        "biome": "minecraft:desert"
      }
    }
  },
  "requirements": [
["Criteria_Name", "Another_Criteria_Name"]
]
}

To see how this truly works a more complex example might help clear things up.
"requirements": [
  ["A", "B", "C"],
["D"],
["E", "F"]
]
In this example above, the advancement will be granted when a player has completed (A or B or C) and (D) and (E or F). So they can complete A, D, and F to get the advancement, but also C, D, and E (and many other combinations). This jumble of ands and ors also gave rise to another common name for this logic, an "AND of ORs". The simplest way to think about it is by realizing a player just needs to complete each list which can be done by completing any of its criteria.

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

Rewards
Rewards are an optional part of advancements. As the name suggests they reward the player for completing the advancement. They are 4 different types of rewards, all of which are shown here:
{
  "criteria": {
    "Criteria_Name": {
      "trigger": "minecraft:bred_animals",
      "conditions": {
        "parent": {
          "type": "minecraft:cow"
        }
      }
    },
    "Another_Criteria_Name": {
      "trigger": "minecraft:location",
      "conditions": {
        "biome": "minecraft:desert"
      }
    }
  },
  "rewards": {
   "recipes": [],
"loot": "",
"experience": 0,
"function": ""
}
}

Recipes will grant the player certain recipes for in their recipe book. It's a list containing the namespace and name of the recipes you want to give the player.
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 you specified.

As always you do not need to specify something you're not using. If you only want to grant the player experience you only have to include the "experience" reward.

Display
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" or "start" of an advancement tree is the first advancement in branching 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/<world name>/datapacks/<data pack name>/data/custom/advancements/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.

data/custom/advancements/stuff/BranchA_advancement.json
Minecraft Datapack Tutorial [1.16]
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. You can even have an advancement in a one folder be the parent of an advancement in another folder (even an entirely different namespace)!

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 themselves). This has no effect on root advancements since they are always hidden.

For example:

custom/advancements/stuff/root.json
Minecraft Datapack Tutorial [1.16]
https://pastebin.com/yBqjrVhn

custom/advancements/stuff/BranchA_advancement.json
Minecraft Datapack Tutorial [1.16]
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 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"}

Functions
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/<namespace>/functions/ in your data pack folder and contain commands (one command on each line without the usual forward slash!). Functions will execute all of their commands in one single game 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/example/functions/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 way is using the /function command explained in an upcoming section. Note that the /function command runs the commands as if they were run by the player or commandblock who ran the /function command.

The second way is by adding the function to either the "minecraft:tick" or "minecraft:load" function tags. Tags will be explained in a later section but simply put they're a way to group things like functions together. These 2 tags in the "minecraft" namespace are special and coded to either run functions in them every game tick or upon (re)load.

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 at @s run 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.

Loot Tables
TBA

Predicates
TBA

Structures
TBA

Recipes
TBA

Tags
TBA

Commands
Advancements
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.

Functions
There are 2 main commands associated with functions:

- /function <function>
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/example/functions/pep/test.mcfunction
- /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 file has the proper JSON formatting. Very useful for debugging.

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

CreditGamepedia
Tags

9 Update Logs

Update #9 : 12/01/2019 9:14:41 amDec 1st, 2019

- Updated introduction to 1.13
LOAD MORE LOGS

Create an account or sign in to comment.

1
07/24/2020 1:49 pm
Level 29 : Expert Miner
gwzyoutube
gwzyoutube avatar
Why does it show "TBA" when I open predicted, structures, etc.?
1
07/24/2020 4:35 pm
Level 56 : Grandmaster Cyborg
Pepijn
Pepijn avatar
Stands for "To be added". I'm not very active on PMC anymore and thus only slowly update this every so often.
2
03/04/2018 2:00 am
Level 22 : Expert Modder
Nevermind3476
Nevermind3476 avatar
Very useful and professional
1
06/20/2017 11:00 pm
Level 31 : Artisan Mage
Peashooter101
Peashooter101 avatar
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
1
06/21/2017 8:13 am
Level 56 : Grandmaster Cyborg
Pepijn
Pepijn avatar
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:
https://pastebin.com/r5qkMGnH

For having a stack of items in a slot you can use this:
https://pastebin.com/G2QJGc5K
1
06/22/2017 5:02 pm
Level 31 : Artisan Mage
Peashooter101
Peashooter101 avatar
How would you do this tracking items with a specific name (even if colored or formatted) or lore?




~ Peashooter101
1
06/22/2017 5:14 pm
Level 56 : Grandmaster Cyborg
Pepijn
Pepijn avatar
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.
1
06/23/2017 3:16 pm
Level 31 : Artisan Mage
Peashooter101
Peashooter101 avatar
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
1
06/23/2017 4:49 pm
Level 56 : Grandmaster Cyborg
Pepijn
Pepijn avatar
Yes, just make sure to escape quotes and you should be fine.
1
06/21/2017 9:33 pm
Level 31 : Artisan Mage
Peashooter101
Peashooter101 avatar
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
1
06/14/2017 2:35 am
Level 1 : New Miner
jstro69
jstro69 avatar
please help, i did everything right (I promise) im 112 full release but the function command is broken... yes, i did do /reload
Planet Minecraft

Website

© 2010 - 2021
www.planetminecraft.com

Welcome