Minecraft Datapack Skill

What Is a Datapack?

A datapack is a folder (or

.zip

datapacks/

.mcfunction

Datapacks can:

• Add custom advancements, recipes, loot tables, and tags
• Override vanilla worldgen (biomes, structures, noise settings)
• Add functions executed by command blocks, other functions, or triggers
• Add predicates for conditional logic
• Add item modifiers (rename, enchant, etc. via loot table mechanics)

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 Format Numbers (1.21.x)

pack_format

Always use the exact format for your target version. Use

supported_formats

"supported_formats": { "min_inclusive": 48, "max_inclusive": 71 }

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

{
  "pack": {
    "pack_format": 71,
    "supported_formats": { "min_inclusive": 48, "max_inclusive": 71 },
    "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

# as: change execution entity
execute as @a run say Hi from each player

# at: change execution position to entity's location
execute as @a at @s run particle flame ~ ~ ~ 0 0 0 0 1

# positioned: change position without changing executor
execute positioned 0 64 0 run setblock ~ ~ ~ stone

# if/unless conditions
execute if block ~ ~-1 ~ minecraft:grass_block run say Standing on grass
execute unless entity @a[tag=vip] run say No VIPs online

# store result into score
execute store result score @s mypack.health run data get entity @s Health

# Chained
execute as @a[gamemode=!spectator] at @s if block ~ ~-1 ~ #minecraft:logs run give @s minecraft:apple

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

Scoreboard

# Create objectives
scoreboard objectives add kills playerKillCount
scoreboard objectives add points dummy
scoreboard objectives setdisplay sidebar points

# Modify scores
scoreboard players set @s points 0
scoreboard players add @s points 10
scoreboard players remove @s points 5
scoreboard players operation @s points += @s kills

# Test scores
execute if score @s points matches 100.. run say Reached 100 points!
execute if score @s points matches ..0 run say Score is zero or negative
execute if score PlayerA points < PlayerB points run say A has fewer points than B

NBT and storage

# Read entity NBT
data get entity @s Health
data get entity @s Inventory[0]

# Modify entity NBT
data modify entity @s Health set value 20.0f
data modify entity @s CustomName set value '{"text":"Boss","color":"red"}'

# Storage (global key-value store)
data modify storage mypack:data config.difficulty set value "hard"
data get storage mypack:data config.difficulty

# Copy from entity to storage
data modify storage mypack:log last_player_pos set from entity @s Pos

Selectors

@a                          # all players
@p                          # nearest player
@r                          # random player
@e                          # all entities
@s                          # executing entity
@n                          # nearest entity (1.21+)

# Selector arguments
@a[gamemode=survival]
@a[gamemode=!spectator]
@e[type=minecraft:zombie,distance=..10]
@e[type=minecraft:player,tag=vip]
@a[scores={kills=1..10}]
@a[nbt={playerGameType:0}]
@e[sort=nearest,limit=1,type=!minecraft:player]
@a[x=0,y=64,z=0,dx=10,dy=10,dz=10]   # AABB selection
@a[team=red]
@a[level=30..]
@a[name=Steve]

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

minecraft:impossible

minecraft:tick

minecraft:player_killed_entity

minecraft:entity_killed_player

minecraft:item_picked_up

minecraft:placed_block

minecraft:inventory_changed

minecraft:changed_dimension

minecraft:consume_item

minecraft:location

minecraft:recipe_unlocked

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/

{}

{}

For example, to disable the piston recipe, create:

data/minecraft/recipe/piston.json

{}

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

"replace": true

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

   /reload

   in-game (or

   /minecraft:reload

   if a mod intercepts it)
3. Test with target command
4. Check

   latest.log

   for syntax errors

Common Errors

Unknown or invalid command

Datapack did not load

jq . < file.json

pack_format mismatch

pack_format

pack.mcmeta

tags/function/tick.json

$

with

with storage/entity/block

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