Tutorials/Creating a data pack

From Minecraft Wiki
Jump to: navigation, search
Information icon.svg
This feature is exclusive to Java Edition.

This tutorial shows how to create a data pack.

Getting started[edit]

Data packs can be used to add or modify functions, loot tables, world structures, advancements, recipes, and tags.

What not to do[edit]

There are some things that you should not do before creating a data pack. Here is a list of "don'ts":

  • Anything that violates Mojang's terms of use for Minecraft.
  • Release Minecraft versions or modifications that allow players to play without having bought Minecraft from Mojang.
  • Release the decompiled source code of Minecraft in any way.

Creating a data pack[edit]

To create a data pack, start off by navigating to the datapacks folder inside the world folder.

To find the world folder, locate the saves folder inside your game directory, which is .minecraft by default.

  • In singleplayer, you can select your world, click on “Edit”, then “Open world folder”.
  • On a server, you can navigate to its root directory (where server.properties is located), then enter the world directory.

Once you are in the datapacks folder, create a folder with a name of your choice. It will be your data pack's name. Enter the data pack folder.

The first thing to do after you are in the folder is to create a pack.mcmeta file. This lets Minecraft identify your data pack.

Creating an MCMETA file[edit]

To create an MCMETA file, right click within your data pack folder and create a new text document. Name this file “pack.mcmeta”.

Note

Make sure the file extension is .mcmeta and not .txt when you rename it! In other words, remove your old file extension. You may be warned that changing a file name extension could make the file unusable. However, this actually indicates that you have renamed the pack.mcmeta file correctly.

If you are using Microsoft Windows and can’t see file extensions, you can turn them on by going to the View menu of the file explorer and checking the check box for file name extensions.

FileExtensions.png

Text editor[edit]

Any text editor should work. It is recommended that the chosen text editor supports JSON, which is the format used by files of mcmeta extension and most other files in a data pack. Note that most text editors do not recognize mcmeta extension as JSON. Thus, you need to configure the editors manually.

pack.mcmeta content[edit]

Open pack.mcmeta in your text editor and paste or type the following:

{
  "pack": {
    "pack_format": 1,
    "description": "Tutorial Data Pack"
  }
}

The  pack_format can be any number as it's currently not enforced. The  description can be any string or a raw JSON text. It will show up when you hover over your data pack in the output from /datapack list.

Note

This file is written in JSON! This tutorial does not go into specifics about the format now, but be aware about how things are laid out. Be very careful not to forget quotation marks, colons, and curly or square brackets. Missing one of these can lead to your data pack not working correctly! To check your files you can use a JSON validator, such as the one found on JSONLint.

Testing your Pack[edit]

Once you have created your pack.mcmeta, try testing it out in-game! Open the world or, if you are already in the world, type /reload, then type /datapack list. It should list two entries. One should be [vanilla], the second one should be named like [file/(your data pack's name)], where your data pack's folder name goes at (your data pack's name). When you hover over your data pack's entry, you should see the description of your data pack as you have written in  description of your pack.mcmeta.

When your pack shows up, you are ready to move on.

Troubleshooting[edit]

If you don’t see your pack in the list, make sure your pack.mcmeta file is correct. Look for any missing curly brackets {}, commas ,, colons :, quotation marks "", or square brackets []. Remember that for each open brace, quotation, or square bracket, you must have a closing bracket, quotation, or square brackets.

Naming[edit]

Make a folder called data in your data pack folder, where you have placed the pack.mcmeta file in. In this data folder you have to create another folder which will act as your namespace.

Entries in data packs have namespaced IDs in a fashion of namespace:path. The corresponding file would be located at data/namespace/(data_type)/path.(suffix). Note that / characters in the path will be translated into directory separators.

A few examples:

  • an item tag of ID dummy:foo_proof/bar would be located at data/dummy/tags/item/foo_proof/bar.json
  • a function of ID foo:handler/bar_call would be located at data/foo/functions/handler/bar_call.mcfunction

Legal characters[edit]

Namespaces, paths and other folder and file names in the data pack should only contain the following symbols:

0123456789 Numbers

abcdefghijklmnopqrstuvwxyz Lowercase letters

_ Underscore

- Hyphen/minus

/ Forward Slash/Directory separator (Can't be used in namespace)

. Period (Can't be used in namespace)

The preferred naming convention is lower_case_with_underscores, called lower snake case.

Namespace[edit]

Most objects in the game have a namespaced ID to prevent potential content conflicts or unintentional overrides.

For example, if two data packs add two new minigame mechanisms to Minecraft and both have a function named start. Without namespaces, these two functions would clash and the minigames would be broken. But if they have different namespaces of minigame_one and minigame_two, the functions would become minigame_one:start and minigame_two:start, which no longer conflict.

Most of the time when Minecraft requires an ID, such as for /function, you should provide the namespace in addition to the path. If you don't specify the namespace, it will fallback to minecraft.

Make sure to always use your own namespace for anything new that you add, and only use other namespaces if you're explicitly overriding something else, or, in the case of tags, appending to something else.

For example, Minecraft uses the minecraft namespace, which means that this namespace should only be used when the data pack needs to overwrite existing Minecraft data or to add its entries to vanilla tags.

Functions[edit]

Functions are a set of commands that can be run in order.

To add functions, first create a folder named functions inside the namespace folder. Then, create a file named (function_name).mcfunction in this folder or in any of its subfolders. This will be your function file. Your function will be named in the game as (namespace):(name) or (namespace):(subfolder1)/(subfolder2)/.../(name) when the function file is located in a subfolder.

Loot tables[edit]

Loot tables will tell Minecraft what should be dropped when a mob dies or what should be generated inside containers, like chests, when opened for the first time.

To add loot tables, first create a folder named loot_tables inside the namespace folder. Then, create a file named (loot_table_name).json in this folder or in any of its subfolders. This will be your loot table file. Your loot table will be named in the game as (namespace):(name) or (namespace):(subfolder1)/(subfolder2)/.../(name) if the file is located in a subfolder.

Here is an example of a cow's loot table, it can be used as a reference:

    {
        "pools": [
            {
                "rolls": 1,
                "entries": [
                    {
                        "type": "item",
                        "name": "minecraft:leather",
                        "weight": 1,
                        "functions": [
                            {
                                "function": "set_count",
                                "count": {
                                    "min": 0,
                                    "max": 2
                                }
                            },
                            {
                                "function": "looting_enchant",
                                "count": {
                                    "min": 0,
                                    "max": 1
                                }
                            }
                        ]
                    }
                ]
            },
            {
                "rolls": 1,
                "entries": [
                    {
                        "type": "item",
                        "name": "minecraft:beef",
                        "weight": 1,
                        "functions": [
                            {
                                "function": "set_count",
                                "count": {
                                    "min": 1,
                                    "max": 3
                                }
                            },
                            {
                                "function": "furnace_smelt",
                                "conditions": [
                                    {
                                        "condition": "entity_properties",
                                        "entity": "this",
                                        "properties": {
                                            "on_fire": true
                                        }
                                    }
                                ]
                            },
                            {
                                "function": "looting_enchant",
                                "count": {
                                    "min": 0,
                                    "max": 1
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }

To learn what each tag means, see Loot tables. There are also a list of vanilla loot tables on that page.

Structures[edit]

Structures can be used with structure blocks and jigsaw blocks and/or can overwrite how certain vanilla structures look in Minecraft. It is saved in an NBT format. You can create an NBT file by using a structure block or by exporting a build using a third party program like MCEdit.

To add structures to a data pack, first create a folder named structures inside the namespace folder. Then, put your structure file in this folder or in any of its subfolders. Your structure will be named in the game as (namespace):(name) or (namespace):(subfolder1)/(subfolder2)/.../(name) if the file is located in a subfolder.

Advancements[edit]

Advancements can be completed by players and give various rewards.

To add advancements, first create a folder named advancements inside the namespace folder. Then, create a file named (advancement_name).json (You can't put spaces in the file name). in this folder or in any of its subfolders. This will be your advancement file. Your advancement will be named in the game as (namespace):(name) or (namespace):(subfolder1)/(subfolder2)/.../(name) if the file is located in a subfolder.

Recipes[edit]

Recipes are used to let players craft items.

To add recipes, first create a folder named recipes inside the namespace folder. Then, create a file named (recipe_name).json in this folder or in any of its subfolders. This will be your recipe file. Your recipe will be named in the game as (namespace):(name) or (namespace):(subfolder1)/(subfolder2)/.../(name) if the file is located in a subfolder.

Shaped crafting[edit]

The first common type of crafting is shaped crafting.

    {
        "type": "crafting_shaped",
        "pattern": [
            "123",
            "231",
            "312"
        ],
        "key": {
            "1": {
                "item": "<item ID>"
            },
            "2": {
                "item": "<item ID>"
            },
            "3": {
                "item": "<item ID>"
            }
        },
        "result": {
            "item": "<item ID>",
            "count": 5
        }
    }

This is a rough example of a shaped crafting recipe, as specified by the crafting_shaped type. pattern is a list used to specify the shape of the crafting recipe. It contains a maximum of 3 strings, each string standing for one row in the crafting grid. These strings then contain a maximum of 3 single characters next to each other, each character standing for one spot in the crafting grid. You don't need all 3 strings, nor do you need to have 3 characters in each string. But each string should contain the same amount of characters. You can use spaces to indicate empty spots.

key is a compound used to specify what item should be used for which character in pattern. This can either be specified using item followed by an item ID or tag followed by an item datapack tag.

The result compound speaks for itself, it specified what the resulting item should be. count is used to specify how many of the item should be given.

This is the original recipe for a piston (can be used as a reference):

    {
        "type": "crafting_shaped",
        "pattern": [
            "TTT",
            "#X#",
            "#R#"
        ],
        "key": {
            "R": {
                "item": "minecraft:redstone"
            },
            "#": {
                "item": "minecraft:cobblestone"
            },
            "T": {
                "tag": "minecraft:planks"
            },
            "X": {
                "item": "minecraft:iron_ingot"
            }
        },
        "result": {
            "item": "minecraft:piston"
        }
    }

Shapeless crafting[edit]

There's another common type of recipes, a shapeless recipe.

    {
        "type": "crafting_shapeless",
        "ingredients": [
            {
                "item": "<item ID>"
            },
            {
                "item": "<item ID>"
            },
            [
                {
                    "item": "<item ID>"
                },
                {
                    "item": "<item ID>"
                }
            ]
        ],
        "result": {
            "item": "<item ID>",
            "count": 5
        }
    }

As specified by the crafting_shapeless type, this is a recipe without a pattern. The ingredients can be put in the crafting grid in any shape or form. In the example, there's a list inside the ingredients compound. This means any of the items in this list can be used.

This is the original recipe for Fire Charge (can be used as a reference):

    {
        "type": "crafting_shapeless",
        "ingredients": [
            {
                "item": "minecraft:gunpowder"
            },
            {
                "item": "minecraft:blaze_powder"
            },
            [
                {
                    "item": "minecraft:coal"
                },
                {
                    "item": "minecraft:charcoal"
                }
            ]
        ],
        "result": {
            "item": "minecraft:fire_charge",
            "count": 3
        }
    }

Smelting It is also possible to create new smelting recipies.

{
    "type": "smelting",
    "ingredient": {
        "item": "<item ID>"
    },
    "result": "<item ID>",
    "experience": 0.35,
    "cookingtime": 200
}

This is a rough example of a smelting recipie. "ingredient" is used to specify the item you are going to smelt. "result" is going to specify the result. In "experience", you are able to choose the amount of xp gained for smelting, and in "cookingtime" the amount of time that it will take for the item to smelt, which in this case is 10 seconds (200 ticks = 10 seconds). This is the default smelting recipie for a diamond ore:

{
    "type": "smelting",
    "ingredient": {
        "item": "minecraft:diamond_ore"
    },
    "result": "minecraft:diamond",
    "experience": 1,
    "cookingtime": 200
}

Tags[edit]

Tags are used to group blocks, items, or functions together. Additionally, the minecraft:tick function tag is used to run functions every tick and the minecraft:load function tag is used to run functions every time the world is (re)loaded.

To add tags, first create a folder named tags inside the namespace folder. Inside this folder, create folders named blocks, items and functions. Then, create a file named (tag_name).json in one of these folders or in any of their subfolders. This will be your tag file. Your tag will be named in the game as (namespace):(name) or (namespace):(subfolder1)/(subfolder2)/.../(name) if the file is located in a subfolder.

See also[edit]