Tutorial:Creating a data pack

This feature is exclusive to Java Edition.

 

This tutorial shows how to create a data pack. Data packs can be used to add or modify functions, loot tables, structures, advancements, recipes, tags, dimensions, predicates and world generation.

Setting up your data pack

To create a data pack, start by navigating to the datapacks folder of your world. The location of the folder varies depending on your operating system and the type of world:

Finding the world directory

To create a data pack, you will need to find the datapacks folder of your world. The location of the world folder depends on your operating system and the type of world:

• In Singleplayer:
  • For Windows, press Alt + D in File Explorer (or ⊞ Win + R) and navigate to %APPDATA%\.minecraft\saves\(your world).
  • For macOS, press ⌘ Cmd + ⇧ Shift + G in Finder and navigate to ~/Library/Application Support/minecraft/saves/(your world).
  • For Linux, press Ctrl + L in Files and navigate to ~/.minecraft/saves/(your world).

• In Multiplayer:
  • Find the root directory of your server (where server.properties is located), then navigate to world.

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

Folder structure

A data pack needs to follow a specific folder structure. Every content in your data pack has its own place.

Creating a pack.mcmeta file

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

Note: Make sure that the file extension is .mcmeta and not .txt when you rename it, as otherwise the data pack will not be readable by Minecraft! 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 cannot see file extensions, you will have to turn them on. For Windows 11, you can turn them on by open the "View" dropdown menu, then hover over the "Show" option, then turn on the "File name extensions" option. For Windows 10, you can turn them on by going to the View menu of the file explorer and checking the check box for file name extensions. For Windows beneath Windows 10, you can uncheck "hide extensions" in folder settings.

Formatting pack.mcmeta

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

{
  "pack": {
    "description": "This is the description of your data pack",
    "pack_format": 71,
    "supported_formats": [71,71]
  }
}

Be very careful not to forget any braces {}, commas ,, colons :, quotation marks "", or square brackets []. Missing one of these can lead to your data pack not being readable by Minecraft.

Description

The text following description is required and can be any string or a raw JSON text. It will be displayed in game when hovering over the data pack in the output from /datapack list, as well as under the pack title in the data pack selection screen when creating a new world. In pack.mcmeta, it is possible to use the § symbol (see Minecraft Formatting codes) in the description of pack.mcmeta and the data pack name.

Pack format

The number next to pack_format is required and tells Minecraft what release the data pack is designed for. All valid data pack formats with their corresponding Java Edition versions that can be used for this pack_format property are presented in the table below.

Starting with Minecraft 1.20.2, in addition to this property, a data pack can also specify a range of pack formats it is compatible with. For more information on this topic, see the "Pack format range" section.

Pack format range (optional)

The supported_formats property introduced in Minecraft 1.20.2 is optional and was designed to be used to specify a range of pack formats that the data pack is compatible with, something that was not possible with the legacy pack_format property. All valid data pack formats with their corresponding Java Edition versions that can be used for this supported_formats property are presented in the table below.

This property can be represented in one of the following three forms:

• a single number (example: 18)
• a list that contains two numbers, where the first one denotes the start of the range and the second one the end, both inclusive (example: [18, 48])
• an object that contains two children — min_inclusive and max_inclusive — to specify the start and end of the range, similarly to the list above (example: { "min_inclusive": 18, "max_inclusive": 48 }).

Note: Even though this property somewhat replaces pack_format, the latter is still required and has to be specified in order for the data pack to be read correctly by Minecraft. Also, if supported_formats is present, it must contain the value declared in pack_format.

UPDATE: New Table listing "pack_format":

Wiki Page: Pack format – Minecraft Wiki^[1]

Pack icon

If an icon is not specified, a generic cobblestone icon appears next to the data pack in the data pack selection screen in game when creating a new world. If you would like to use your own pack icon instead, you need to name it pack.png and place it inside your data pack folder right next to the pack.mcmeta file.

The file must be in the PNG format in any resolution and with a 1:1 aspect ratio (in other words, square-shaped), but a resolution of 128×128 px is recommended, as this is what Mojang itself uses in the default built-in resource and data packs.

Testing your pack

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 of the two should appear as [file/(your data pack's name) (world)], 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 [String][NBT Compound / JSON Object] description of your pack.mcmeta.

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

Troubleshooting

If you don't see your pack in the list, make sure your pack.mcmeta file is correct and saved. Look for any missing braces {}, commas ,, colons :, quotation marks "", or square brackets []. Remember that for each open brace, quotation mark, or square bracket, you must have a corresponding closing bracket, quotation mark, or square bracket respectively. If you still don't see your pack, make sure it's in the right folder.

Adding content to your pack

Naming

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 one or more folders which will act as your namespaces.

Entries in data packs have resource locations 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/function/handler/bar_call.mcfunction

Legal characters

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

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

Namespaces

Most objects in the game use namespaced resource locations 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 (remember, no spaces!) 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

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

To add functions, first create a folder named function 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

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, they can also be called by the /loot command.

To add loot tables, first create a folder named loot_table 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. All the vanilla loot tables are in the minecraft namespace.

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

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

Structures

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 such as MCEdit.

To add structures to a data pack, first create a folder named structure 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.

World generation

Custom world generation allows your pack to change how the world generates. This is particularly useful in conjunction with custom worlds.

To change world generation, first create a folder named worldgen inside the namespace folder. Then, put your noise_settings file in this folder or in any of its subfolders. Your changes will be named in the game as (namespace):(name) or (namespace):(subfolder1)/(subfolder2)/.../(name) if the file is located in a subfolder.

Advancements

Advancements can be completed by players and give various rewards.

To add advancements, first create a folder named advancement inside the namespace folder. Then, create a file named (advancement_name).json. (Note: You can't put spaces in the file name. Use lowercase letters 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.

Enchantments

An Enchantment is a set of core properties like level ranges and cost together with some effects. Most effect types also support a set of conditions, making it possible to apply them only when certain criteria are met.

Enchantments can be added in the registry enchantment. All Vanilla Enchantments can be found in the vanilla datapack in the client and server jar files.

Recipes

Recipes are used to let players craft items.

To add recipes, first create a folder named recipe 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.

ATTENTION: Prior to Java Edition 1.21 the folder recipe was named recipes! Data packs written prior to this may need to be updated to still work properly.

Also recently the string required after result was changed from "result": {"item": to "result": {"id":! Data packs written prior to the release of Java Edition 1.20.5 may need to be updated to still work properly.

Shaped crafting

The first common type of crafting is shaped crafting.

{
  "type": "minecraft:crafting_shaped",
  "pattern": [
    "123",
    "231",
    "312"
  ],
  "key": {
    "1": "Resource location of the item",
    "2": "Resource location of the item",
    "3": "Resource location of the item"
  },
  "result": {
    "id": "Resource location of the item",
    "count": Number of items produced
  }
}

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 as an item ID or a hash-prefixed item tag.

The result compound speaks for itself, it specifies 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 for reference:

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

Shapeless crafting

This section needs expansion.

 

You can help by expanding it.

There's another common type of recipes, a shapeless recipe. The list with multiple items allows alternatives for the given slot such as Oak Plank and Birch Plank.

{
  "type": "crafting_shapeless",
  "ingredients": [
    "<item ID>",
    "<item ID>",
    [
      "<item ID>",
      "<item ID>"
    ]
  ],
  "result": {
    "id": "<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 for reference:

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

It is also possible to create new smelting recipes.

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

This is a rough example of a smelting recipe. "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 recipe for a diamond ore:

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

Tags

Tags are used to group blocks, items, entities, 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 block, item and function. 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.

Predicates

Predicates are technical JSON files that represent the conditions for loot tables, /execute if predicate command, or predicate target selector argument.

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

Dimensions

Dimensions are JSON files used to specify all the dimensions a world contains.

To add dimensions, first create a folder named dimension inside the namespace folder. Then, create a file named (dimension_name).json (You can't put spaces in the file name. Use lowercase letters in the file name). in this folder. This will be your dimension file.

Custom dimensions can be accessed in game using /execute in (namespace):(dimension_name)

Utilities

Many utilities have been created in order to make programming data packs easier. This is a reference list for utilities such as transpilers or syntax highlighting plugins. Please exercise caution when installing third-party programs onto your computer, as they are not actively monitored and may contain malware.

See also

• Resource pack
• Tutorials/Creating a resource pack
• Tutorials/Installing a data pack

Navigation

v t e Tutorials
Introductory Basics Menu screen Java Edition Bedrock Edition Game terms Playing with a controller Newcomer survival Beginner's guide First ten minutes Second day Third day Best biomes to use Hunger management Things to do Things not to do Simple tips and tricks Survival mode progression Shelters Best biomes for homes Best building materials Building and construction Navigation Shelters Types
General General Achievement guide Advancement guide Minecraft Nether The End Adventure Husbandry Adventuring Best enchantments guide Breaking a fall Breaking bedrock Chunk loader Combat Complete main adventure Creating a village Dual wielding Desert survival End survival Exploring caverns Gathering resources on peaceful difficulty Getting food quickly Getting max gear Headless pistons Hitboxes Horses Indestructible end crystals Managing slimes in superflat mode Mapping Measuring distance Minecraft in education Mining Ancient Debris Diamonds Fossils Nether hub Nether portals Nether survival Organization Pillar jumping Phantom-proofing Spawn-proofing Summoning jockeys Things to do when bored The Void Thunderstorm survival Time-saving tips Transportation methods Units of measure Village mechanics Trading X-ray glitches Zombie siege defense Enchanting and smelting Enchanting mechanics Anvil mechanics Automatic smelting Manual smelting
Challenges General Acquiring a conduit Archaeology Curing a zombie villager Conquering a mountain Defeating a bastion remnant Defeating an End city Defeating a monster room Defeating an ocean monument Defeating a Nether fortress Defeating a pillager outpost Defeating a stronghold Defeating temples Defeating trial chambers Defeating a woodland mansion Defeating a village raid Defeating the Ender dragon Defeating the Wither If it escapes Exploring an ancient city Locating a stronghold Obtaining every music disc Obtaining every block Non-standard survival Adventure mode survival Custom maps Half hearted hardcore Hardcore mode Surviving in a single area indefinitely Infinite desert survival Island survival Manhunt Mob switch Nomadic experience Trapping every mob Skyblock survival Skywars survival Speedrunning Starting in the Nether Starting in the End Superflat survival Java Edition Bedrock Edition Ultra hardcore survival The World Starts With One Getting to the world border Village only survival Challenge maps Beating a challenge map Creating a challenge map
Constructions Constructions Adding beauty to constructions Airlock Architectural terms Building a cruise ship Building a metropolis Building a rollercoaster Building micro shelters Building safe homes Building water features Chunk ban Color palette Creating shapes Defense Elevators Endless circling pool Furniture Glazed terracotta patterns Hiking trail Making nice floors Pixel art Ranches Roof types Curved roofs Roof construction guidelines Roof decorations Secret door Settlement guide Underwater home Walls and buttresses Water gate Water-powered boat transportation Block breaking Blast chamber Igniting TNT underwater Wither cage
Farming Blocks and items Amethyst Armor Azalea Bamboo Basalt Bedrock Blaze Rod Bone Meal Cactus Cat gift Chorus Fruit Clay & Mud Cobblestone Cocoa Beans Copper, Nautilus Shell & Trident Crops (Beetroot, Carrot, Potato, Wheat) Dirt Dragon's breath Dripstone Egg Enchanted Golden Apple Experience Fern Fish Flower Froglight Ghast Tear Glow Berries Glow Ink Sac Glow Lichen Goat Horn Gold Hanging Roots Honey Ice Iron Kelp Lava Meat Moss Mushroom Music Disc Nether growth Nether vine Nether Wart Obsidian Ominous Bottle Powder Snow Pumpkin, Melon Rooted Dirt Sculk Turtle Scute Seagrass Sea Pickle Snow Soul Soil Sugar Cane Sweet Berries Tree Vine Villager trading hall Wither Rose Wool Duplication Mobs Mob farming Mob grinding Monster spawner traps Allay Animals Axolotl Bee Blaze Breeze Cat Cave Spider Chicken Creeper Drowned Ender Dragon Enderman Fox Frog Ghast Glow squid Goat Guardian Hoglin Iron golem Magma cube Phantom Piglin bartering Pillager Raid Shulker Skeleton horse Slime Squid Turtle Villager Wandering trader Warden Witch Wither Wither Skeleton Wolf Zombie Zombie villager Zombified piglin
Mechanisms Various devices Redstone Circuits Components Dust Mechanics Tips Automatic respawn anchor recharger Combination locks Command block Crafter Flying machines Hopper TNT Item sorting Item transportation Mechanisms Observer stabilizer Randomizers Redstone music Doorbell Rube Goldberg machine Shulker box storage Detectors Block update detector Comparator update detector Daylight detector Minecarts Train station Minecarts Storage Storage system Traps Snow golems TNT cannons Trapdoor uses Trap design Traps Pistons Piston uses Piston circuits Quasi-Connectivity Zero-ticking Instant repeaters Tripwire Tripwire techniques Advanced redstone Advanced redstone circuits Arithmetic logic Calculator Command stats Hourly clock Morse code Printer Redstone computers Redstone telegraph
Multiplayer General Griefing prevention Hiding chests Multiplayer Survival Spawn jail Playing on servers PvP Bases Joining a LAN world with alternate accounts Server setup Setting up a Java Edition server Forge server Hamachi server Setting up a Bedrock Edition server Server maintenance Setting up a LAN world Server startup script FreeBSD OpenBSD Ubuntu Ramdisk enabled server
Technical General Creating Forge mods Moving structures using structure blocks from world to world Improving frame rate Minecraft help FAQ Note Block Studio Programs and editors Running the data generator Update Java See Minecraft's code Downgrading Restoring a hardcore world Maps Custom maps Map downloads Command NBT tags Falling blocks Updating old terrain using MCEdit Resource packs Creating a resource pack Loading a resource pack Models Sound directory Data packs Adding a new dimension Adding custom enchantments Adding custom paintings Adding custom trims Custom structures Installing a data pack Repairing a world corrupted by a data pack Creating Minecraft media Creating videos Livestreaming Hide Server IP Game installation Installing snapshots Installing Minecraft Preview and beta versions How to get a crash report Installing Forge mods Custom Minecraft directory Playing and saving Minecraft on a thumb drive Playing and saving Minecraft on a thumb drive with the old launcher Recover corrupted saved world data Run Minecraft through Google Drive Save game data to Dropbox (world data only) Saved data Dropbox guide Create a Mac OS X startup daemon Playing Java Edition on ChromeOS
Outdated Farming Potion farming End of light mob farms Door-based iron golem farming Villages Legacy Console village mechanics Pre-1.14 village mechanics Village chaining Glitches Duplication Far Lands Contraptions Minecart booster Repeater reboot system Instant wire Water ladder Water tram Challenges Survival with no enabled data packs Construction Man-made lake Other Custom texture packs How to get a crash report (old) Installing mods Setting up a Spigot server Update LWJGL Update Minecraft Custom world generation