datapack-py — Minecraft 26.1-26.2 Datapack compiler

Editor

Output

Edit the code, then click "Run" to compile and download datapack.zip.

Click a function to see how to use it.

What is this?

A datapack adds custom behavior to a Minecraft world — give items, spawn mobs, react to where players stand — with no mods. Normally you write that in Minecraft's command language, which is picky and verbose. This tool lets you write the same thing in simple Python-like code and turns it into a ready-to-use datapack for you.

You don't need to know Minecraft commands or real Python. If you can copy the examples below and change a few words, you can build a pack.

Make your first datapack

Type code in the Editor on the left. A starter example is already loaded, so you can just use that the first time.
Click Run (top of the page). Your browser saves a file called datapack.zip.
Find your world's save folder and open its datapacks folder. Drop datapack.zip inside — no need to unzip it.
Back in the game, run /reload in the chat.
Done — your code is now running in that world.

Edit the code, compile again, copy the new zip over the old one, and /reload to see changes. Your work autosaves in this browser, so it's still here when you come back.

The buttons and panels

Run compiles your code and builds the zip. Fix Indentation tidies up spacing if you pasted code and it looks crooked. Reset to Example brings back the starter script (this erases your current code). Use the project dropdown to keep several packs and switch between them.

Editor — where you write code. Functions — a searchable list of everything you can call; click a name to see how to use it. Guide — this help (use the tabs above to switch between Functions and Guide). Output — shows "success" or points to the line with a mistake after you compile.

When does my code run?

Two simple rules:

Code that is not inside a def runs every tick (20 times a second) — use it for things that should keep checking, like "if a player stands on gold, do X".
Code inside def init(): runs once when the pack loads — use it for one-time setup, like starting a score at 0.

def init():
    say("Pack loaded!")     # once, on /reload

say("tick")                 # every tick (very spammy!)

Indentation (the spaces at the start of a line) is how the tool knows what belongs inside a def, with, or if — just like Python. Keep it consistent; Fix Indentation can help.

Values: who, where, what

Most actions need to know who to affect, where in the world, or what item/block. These are the words you fill in:

Who: me, players, all, nearest, or near(zombie, distance=8).
Where: here, below, above, rel(0,-1,0), offset(here,0,1,0), pos(10,64,0).
What: write ids directly. diamond_block compiles as minecraft:diamond_block.

Actions (do something)

An action is a single thing to do. You call it by name with details in the brackets:

give(me, diamond, 3)
title(me, "Wave 1")
effect(me, speed, seconds=10)
summon(zombie, here, name="Tank", health=80, damage=8)

Don't remember them all — search the Functions panel and click any name for its example.

Blocks: with / if (only sometimes)

Use with and if to control who runs the action and when. Put the affected lines underneath, indented. This example tells every player standing on gold a message:

with as_players():
    if block_is(below, gold_block):
        tell(me, "on gold!")

Raycast

raycast is built in. It casts from eyes or feet. Inside the block, here is the block position being aimed at; use offset to move along the look ray. through can be one block, a tag, or a list.

with as_players():
    with raycast(max=40, offset=-1,
                 through=[air, cave_air, water]):
        setblock(here, glowstone)

raycast_miss runs only if no solid block is hit before max range.

with as_players():
    with raycast_miss(max=20):
        summon(lightning_bolt, here)

raycast_entity finds the first matching entity near the ray. Inside the block, me is the hit entity and here is the ray position. Set stop_at_blocks=false for through-wall checks.

with as_players():
    with raycast_entity(entities(zombie), radius=1):
        effect(me, glowing, seconds=2)

raycast_entity_miss runs at max range when no entity is found.

Waiting (non-blocking)

sleep(20) waits 20 ticks. sleep("3s") waits 3 seconds. It schedules the rest of the function for later, so the game keeps running. Use it at top level, in def, or in with; avoid it inside if.

Variables

Assign values with normal Python-style syntax:

points = 0          # int   - LIVE
ready  = true       # bool  - LIVE
pi     = 3.14       # float - constant
name   = "Hero"     # string- constant
spawn  = vec3(0,64,0) # vec3 - constant

Live int/bool variables use scoreboards and can change while the pack runs:

points = points + 10
points = points * 2

Constants are fixed when you compile. Use them for config, names, and positions:

setblock(spawn, beacon)
greeting = "Hi " + name

A plain variable like points has one shared value for the whole pack. If you want a value that each player or mob keeps separately, use a per-entity variable (next).

Per-entity variables (each entity has its own)

Write who.name to give every entity or player its own copy of a value. me is the current entity, so me.levels is this entity's levels — a different number for each one:

with as_players():
    me.levels = me.levels + 1
    actionbar(me, f"Level: {me.levels}")
    if me.levels >= 10:
        give(me, diamond)
        me.levels = 0

The left side is who dot name. who can be any selector:

me.score = 5                       # just this entity
near(zombie, limit=1).anger = 100  # one nearby zombie
boss = near(zombie, limit=1)       # save a target...
boss.anger = 100                   # ...and reuse it

To set the value for everyone at once, point at a group selector — all (every entity) or players (every player):

all.levels = 0        # reset levels on every entity
players.coins = 100   # give every player 100 coins

Declare a per-entity value with persist mana or persist all.mana when it should survive reloads. Per-entity values that are not marked persistent are cleared on reload.

if supports elif and else; only the first matching branch runs.

if me.levels >= 10:
    title(me, "Max")
elif me.levels >= 5:
    actionbar(me, "Halfway")
else:
    actionbar(me, "Starting")

Use them anywhere a number works — math, if comparisons (including between entities, like if me.score > nearest.score), and f-strings. Player values are saved across reloads automatically. Reading me.x means "the current entity," so read inside a with as_players()/as_each() block (or a limit=1 selector) where there is exactly one. These hold whole numbers only; blocks can't store them.

Queues

Plain lists are still useful for fixed values because they compile directly into commands:

pass_blocks = [air, cave_air, water]
with as_players():
    with raycast(through=pass_blocks):
        setblock(here, glowstone)

If you call a mutating method, the value becomes a dynamic queue in storage. Dynamic queues are intentionally simple: add to the back, read the front, pop the front, clear, or read the whole queue. Dynamic setup usually belongs in def init():

def init():
    spots = []
    spots.append(pos(8, 65, 9))
    spots.append(here)
    setblock(spots.front, light, state={level:15})
    spots.pop()

Use persist before the name when a dynamic queue should survive reloads. Put the starting value in def init(); it is only applied the first time.

persist spots
def init():
    spots = []
with as_players():
    if block_is(below, gold_block):
        spots.append(here)
        tell(me, f"{spots.all}")

To drain a queue, use a top-level function that calls itself after popping one item. The empty check is len(queue) > 0:

def clear_spots():
    if len(spots) > 0:
        setblock(spots.front, air)
        spots.pop()
        clear_spots()

clear_spots()

For a queue per player or per entity, make an entity queue reference. The queue name is shared, but the stored items are keyed by that entity's UUID:

with as_players():
    lights = entity_queue(me, light_sources)
    lights.append(offset(here, 0, 1, 0))
    if len(lights) > 0:
        setblock(lights.front, air)
        lights.pop()

Use queue.all or a bare queue in an f-string to inspect the whole stored queue. Top-level assignments run every tick and will reset a dynamic queue every tick, just like other top-level code.

Showing variables (f-strings)

Use f"..." strings when a message needs a variable value:

tell(me, f"Score: {points}")
actionbar(me, f"{name} has {points}!")

say() cannot show live variables; use tell() or actionbar().

Text colors & styles

Put color and style tags inside an f"..." string before the text they should affect:

tell(me, f"{gold}{bold}Score: {points}")
actionbar(me, f"{red}Low HP! {reset}{hp}/20")
title(me, f"{aqua}Wave {wave}")

Works in tell, title, actionbar, and item name/lore.

give(me, diamond_sword,
     name=f"{aqua}{bold}Frostbite",
     lore=[f"{gray}Frozen blade", f"{gold}+5 style"])

Colors: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white.

Styles: bold, italic, underlined, strikethrough, obfuscated. Aliases: underline, strike, magic. Use {reset} to go back to the command's default style.

Persistence

Live variables reset on reload unless you mark them with persist before first use:

persist coins      # kept across reloads
def init():
    coins = 0      # first load only
    tries = 0      # resets on reload
with as_players():
    if block_is(below, gold_block):
        coins = coins + 1

Plain persisted variables must be int/bool values or dynamic queues. Per-entity scores can also be declared with persist mana before using me.mana, or explicitly with persist all.mana. Each player/entity keeps its own value; numeric += and -= start missing scores from 0.

persist mana
persist all.energy

with as_players():
    me.mana += 5
    all.energy += 1

Items & blocks

give and custom_item accept common item fields directly: name, color, lore, enchant, unbreakable, model, cooldown, attributes, and more. Use components={...} for raw item components.

give(me, diamond_sword,
     name="Frostbite", enchant={sharpness:5},
     model="my_pack:frostbite", unbreakable=true)

custom_item defines a reusable item, then give_custom gives it later. Use unbreakable=true for the real item component; data={...} is custom marker data used to identify your item.

custom_item(gun, iron_hoe,
     name=f"{gold}Gun", unbreakable=true,
     data={kind:"gun"})
give_custom(me, gun)

For right-click abilities, add cooldown=1 to wait 1 second before the block can run again. Numbers are seconds by default; use cooldown=10t for ticks. You can put the cooldown on the item or override it on the event. The compiler enforces custom ability cooldowns with scoreboards; custom items use a non-completing use action so survival stacks are not eaten.

custom_item(wand, stick, name="Blink Wand", cooldown=1)
on_right_click(wand):
    particle("flame", pos=here, count=8)

on_right_click(wand, cooldown=10t):
    actionbar(me, "quick pulse")

Use clear_cooldowns(me) to reset generated right-click cooldown scores for a player, or omit the target to clear them for all players.

Quote sound and particle names. Use at=me to emit at an entity, pos=here for a position, spread=vec3(...) for an area, and mode=force for long-range particles.

playsound("entity.player.levelup", target=me)
particle("happy_villager", at=players,
     spread=vec3(0.4,0.8,0.4), count=12)

Use cooldown_group to make native item uses share the same vanilla visual cooldown group.

give(me, ender_pearl,
     cooldown=5, cooldown_group="magic_items")

model sets the modern item_model component, which is the normal way to give an item a custom model in 26.1-26.2. For advanced item model predicates, use structured custom_model_data with strings, floats, flags, or colors:

give(me, stick,
     custom_model_data={strings:["wand"]})

setblock accepts state={...} for block states, data={...} for block entity data, and command= for command blocks.

setblock(below, chest,
  data={Items:[{slot:0, id:"minecraft:diamond", count:5}]})

Raw commands

raw_command("...") emits a Minecraft command unchanged, without the leading slash. It is a fallback, not the recommended way to write packs. If you need it because a command is missing, comment on the Reddit feedback post.

raw_command("weather clear")

Tips

Edits autosave in this browser.
Reset to Example restores the starter script.
Fix Indentation cleans pasted code across the whole file.
Function calls can span multiple lines when wrapped in (...), [...], or {...}.
Start typing for autocomplete; use the arrow keys and Enter.
Click a function for its signature and an example.