Minecraft Datapack

Minecraft Datapack Skill

Skill Scope

Routing Boundaries

• Use when: the deliverable is datapack files (pack.mcmeta, data/...) and .mcfunction/JSON content.
• Do not use when: the request is command-only snippets not tied to a datapack file tree (minecraft-commands-scripting).
• Do not use when: the request requires loader APIs, Java code, or runtime mod behavior (minecraft-modding).

Pack Metadata (1.21.x)

Use pack_format through 1.21.8. Starting in 1.21.9, Mojang replaced that single field with explicit min_format / max_format values.

Keep pack.mcmeta exact for the patch you target instead of trying to span the entire 1.21.x line with one metadata block.

Directory Layout

my-datapack/
├── pack.mcmeta
└── data/
    └── <namespace>/           ← use your pack's name (e.g., mypack)
        ├── function/
        │   ├── main.mcfunction
        │   └── tick.mcfunction
        ├── advancement/
        │   └── custom_advancement.json
        ├── recipe/
        │   └── custom_recipe.json
        ├── loot_table/
        │   └── custom_loot.json
        ├── predicate/
        │   └── is_night.json
        ├── item_modifier/
        │   └── add_name.json
        └── tags/
            ├── block/
            │   └── climbable.json
            ├── entity_type/
            │   └── bosses.json
            └── function/
                ├── load.json     ← runs on /reload
                └── tick.json     ← runs every game tick

pack.mcmeta

1.21.8 and earlier

{
  "pack": {
    "pack_format": 81,
    "description": "My Custom Datapack v1.0"
  }
}

1.21.9 and newer

{
  "pack": {
    "min_format": 94.1,
    "max_format": 94.1,
    "description": "My Custom Datapack v1.0"
  }
}

Function Tags (load / tick)

data/<namespace>/tags/function/load.json

{
  "values": [
    "<namespace>:setup"
  ]
}

data/<namespace>/tags/function/tick.json

{
  "values": [
    "<namespace>:tick"
  ]
}

data/<namespace>/function/setup.mcfunction

# Runs once on /reload
scoreboard objectives add deaths deathCount
scoreboard objectives add kills playerKillCount
tellraw @a {"text":"[MyPack] Loaded!","color":"green"}

data/<namespace>/function/tick.mcfunction

# Runs every tick — KEEP THIS SHORT
# Only put fast, targeted operations here
execute as @a[scores={deaths=1..}] run function mypack:on_death_check

Commands and Function Syntax

Execute subcommands (datapack-specific patterns)

# Chained execute — common datapack pattern for conditional per-player logic
execute as @a[gamemode=!spectator] at @s if block ~ ~-1 ~ #minecraft:logs run give @s minecraft:apple

# store result into score (bridge between NBT world and scoreboard state)
execute store result score @s mypack.health run data get entity @s Health

# in: run logic in another dimension
execute in minecraft:the_nether run say This runs in the Nether

Storage NBT (datapack-specific global state)

# Storage is the datapack-native key-value store — persists across /reload
data modify storage mypack:data config.difficulty set value "hard"
data get storage mypack:data config.difficulty

# Copy live entity data into storage for macro use or cross-function state
data modify storage mypack:log last_player_pos set from entity @s Pos

For full command syntax, selectors, and scoreboard operations see the Minecraft Wiki — Commands reference. The minecraft-commands-scripting skill covers command-only work in depth.

Macros (1.20.2+)

Macro functions let you pass dynamic arguments to a function.

Define a macro function (data/mypack/function/greet.mcfunction)

# Macro argument: $(name)
$tellraw @a {"text":"Welcome $(name)!","color":"gold"}
$scoreboard players set $(name) points 0

Call with run function + with

# Pass values from storage
data modify storage mypack:tmp input set value {name:"Steve"}
function mypack:greet with storage mypack:tmp input

# Pass values from entity NBT
function mypack:greet with entity @p {}

# Pass value from block NBT
function mypack:greet with block 0 64 0 {}

Advancements

data/<namespace>/advancement/my_advancement.json

{
  "display": {
    "icon": {
      "id": "minecraft:diamond"
    },
    "title": {"text": "Diamond Hunter"},
    "description": {"text": "Mine your first diamond"},
    "frame": "task",
    "show_toast": true,
    "announce_to_chat": true,
    "hidden": false
  },
  "criteria": {
    "mined_diamond": {
      "trigger": "minecraft:item_picked_up",
      "conditions": {
        "item": {
          "items": ["minecraft:diamond"]
        }
      }
    }
  },
  "rewards": {
    "function": "mypack:on_diamond_obtained",
    "experience": 10
  }
}

Common advancement triggers

Custom Recipes

Shaped crafting (data/<namespace>/recipe/shaped.json)

{
  "type": "minecraft:crafting_shaped",
  "pattern": [
    "DDD",
    "D D",
    "DDD"
  ],
  "key": {
    "D": { "item": "minecraft:diamond" }
  },
  "result": {
    "id": "minecraft:diamond_block",
    "count": 1
  }
}

Shapeless crafting

{
  "type": "minecraft:crafting_shapeless",
  "ingredients": [
    { "item": "minecraft:wheat" },
    { "item": "minecraft:wheat" },
    { "item": "minecraft:wheat" }
  ],
  "result": {
    "id": "minecraft:bread",
    "count": 2
  }
}

Smelting / blasting / smoking / campfire

{
  "type": "minecraft:smelting",
  "ingredient": { "item": "minecraft:beef" },
  "result": { "id": "minecraft:cooked_beef" },
  "experience": 0.35,
  "cookingtime": 200
}

Disable a vanilla recipe (override with empty file)

To remove a vanilla recipe, create a file at the same path under data/minecraft/recipe/ in your datapack with just {} as the content:

{}

For example, to disable the piston recipe, create:
data/minecraft/recipe/piston.json containing only {}.

Get the exact filename from the vanilla jar:
jar xf minecraft.jar data/minecraft/recipe/

Smithing transform

{
  "type": "minecraft:smithing_transform",
  "template": { "item": "minecraft:netherite_upgrade_smithing_template" },
  "base": { "item": "minecraft:diamond_sword" },
  "addition": { "item": "minecraft:netherite_ingot" },
  "result": { "id": "minecraft:netherite_sword" }
}

Loot Tables

data/<namespace>/loot_table/custom_chest.json

{
  "type": "minecraft:chest",
  "pools": [
    {
      "rolls": { "type": "minecraft:uniform", "min": 3, "max": 8 },
      "entries": [
        {
          "type": "minecraft:item",
          "name": "minecraft:diamond",
          "weight": 5,
          "functions": [
            {
              "function": "minecraft:set_count",
              "count": { "type": "minecraft:uniform", "min": 1, "max": 3 }
            }
          ]
        },
        {
          "type": "minecraft:item",
          "name": "minecraft:gold_ingot",
          "weight": 20
        },
        {
          "type": "minecraft:empty",
          "weight": 30
        }
      ]
    }
  ]
}

Predicates

data/<namespace>/predicate/is_daytime.json

{
  "condition": "minecraft:time_check",
  "value": { "min": 0, "max": 12000 }
}

data/<namespace>/predicate/player_has_diamond.json

{
  "condition": "minecraft:entity_properties",
  "entity": "this",
  "predicate": {
    "inventory": {
      "items": [
        { "items": ["minecraft:diamond"] }
      ]
    }
  }
}

Using predicates in functions

execute if predicate mypack:is_daytime run say It is daytime!
execute unless predicate mypack:player_has_diamond run tell @s You need a diamond!

Tags

Block tag (data/minecraft/tags/block/climbable.json — override vanilla)

{
  "replace": false,
  "values": [
    "minecraft:ladder",
    "minecraft:vine",
    "#minecraft:wool"
  ]
}

Item tag (data/<namespace>/tags/item/my_fuel.json)

{
  "replace": false,
  "values": [
    "minecraft:coal",
    "minecraft:charcoal",
    "minecraft:blaze_rod"
  ]
}

Use "replace": false to append to existing tags. Use "replace": true to completely override (use with care for vanilla tags).

Worldgen Overrides

Override biome noise (data/minecraft/worldgen/noise_settings/overworld.json)

Edit inside an existing copy — do NOT create from scratch without the full JSON. Get the vanilla version from the Minecraft jar: jar xf minecraft.jar data/.

Override a biome's spawn costs

{
  "spawn_costs": {
    "minecraft:zombie": {
      "energy_budget": 0.12,
      "charge": 0.7
    }
  }
}

Installation & Testing

# Place datapack in world folder
/datapacks/my-datapack/

# Or as a zip
/datapacks/my-datapack.zip

# In-game commands
/datapack list               # see all datapacks
/datapack enable "file/my-datapack"
/datapack disable "file/my-datapack"
/reload                      # hot-reload all datapacks without restart

Development workflow

1. Edit .mcfunction or .json files
2. Run the bundled validator to catch JSON and path errors before loading:

   ./scripts/validate-datapack.sh --root /path/to/datapack
   

3. If errors, fix and re-validate until clean
4. Run /reload in-game (or /minecraft:reload if a mod intercepts it)
5. Test with target command (e.g., /function mypack:setup, trigger an advancement)
6. Check latest.log for runtime errors (missing references, bad selectors)

Common Errors

Validator Script

Use the bundled validator script before shipping a datapack update:

# Run from the installed skill directory (for example `.codex/skills/minecraft-datapack`):
./scripts/validate-datapack.sh --root /path/to/datapack

# Strict mode treats warnings as failures:
./scripts/validate-datapack.sh --root /path/to/datapack --strict

What it checks:

• JSON validity for pack.mcmeta and data/**/*.json
• Legacy pluralized path mistakes for loot tables and block/item tags
• tags/function/load.json and tags/function/tick.json references resolve to real .mcfunction files

References

• Minecraft Wiki — Data Pack: https://minecraft.wiki/w/Data_pack
• Minecraft Wiki — Function: https://minecraft.wiki/w/Function_(Java_Edition)
• Minecraft Wiki — Commands: https://minecraft.wiki/w/Commands
• Pack format history: https://minecraft.wiki/w/Pack_format
• NBT format: https://minecraft.wiki/w/NBT_format
• Predicate conditions: https://minecraft.wiki/w/Predicate
• Loot table format: https://minecraft.wiki/w/Loot_table