Minecraft Data Packs: A Complete Guide

Building anything in Java Edition with data packs — from your first command to custom worlds

Java Edition 26.2

About This Book

Modern Minecraft is a data-driven game: items, recipes, enchantments, world generation, even mob variants are defined by JSON files the game reads on load. A data pack is how you add your own files to that system. This book gets you there the way the game itself does: you start by typing commands and watching them work, wire them into command blocks, then learn to save and share them as data packs, building project by project all the way to custom dimensions and world generation.

It assumes no prior programming experience and is written for readers aged 12 and up. Parts I–IX are the core path, taught in order. Parts X–XI are advanced material you can approach à la carte once the core is comfortable, and Part XII covers polishing and sharing what you’ve made.

Everything is hands-on and every example traces to current Java Edition behavior: you begin in the chat box on the very first page and end with data packs you can share.

Note. Screenshots are still being captured; figures appear as “Figure (to be captured)” callouts for now. Want to help capture them? See how to contribute.

Chapter 1 — Your First Commands

What You’ll Build

This is the most important five minutes in the whole book, because it’s the moment Minecraft stops feeling like a finished thing you play and starts feeling like a thing you can talk to. You’re going to open a world, type a short instruction into the chat box, press Enter, and watch the game do exactly what you said: hand you a diamond sword, drop a cow at your feet, whisk you across the map. No files, no setup beyond ticking one box. Just you and the game, having a conversation.

By the end of this chapter you’ll know the handful of commands that do the most useful “just make something happen” jobs: making the game talk (/say), handing yourself items (/give), spawning mobs and other entities (/summon), and moving things around (/teleport, which you can also write /tp). You’ll learn to read the little feedback line a command prints, so you can tell “it worked” from “it failed,” and you’ll meet the three simplest ways to point a command at someone: @s, @p, and @a. Everything in this chapter is typed straight into the chat box and happens the instant you press Enter.

Setting up a world to play in

Commands are powerful, so Minecraft only lets you use them in a world where cheats are turned on. (“Cheats” is just Minecraft’s word for “commands allowed.” There’s nothing sneaky about it; it’s the switch that hands you the controls.) Make yourself a world to experiment in:

1. Click Create New World.
2. Set the Game Mode to Creative (you get every block, you can fly, and nothing can kill you, perfect for tinkering).
3. Open the More tab and turn Allow Cheats on.
4. Create the world and drop in.

That’s your test world: a safe sandbox where a mistake costs you nothing. Do all your experimenting here, not in a survival world you care about. (When you start building real projects later in the book, you’ll keep using a world set up exactly like this one.)

Try It! Press T to open the chat box. A line opens at the bottom of the screen with a / already waiting. Type time set day and press Enter. If it’s night, the sun jumps up. You just ran your first command. Figure (to be captured). the chat box open with /time set day typed in, ready to press Enter

Concepts

A command is a single instruction to the game: “give this player a sword,” “spawn a zombie here,” “send everyone a message.” You open the chat box with T, and every command starts with a slash (/). The slash is how the game knows you’re giving an order instead of just chatting. Type the command, press Enter, and it happens immediately.

Most commands need to know who or what they act on. Instead of typing a player’s exact name every time, Minecraft gives you target selectors: short codes that stand for “some players or entities.” This chapter uses only the three simplest ones:

• @s is yourself, the one running the command. When you type a command in chat, @s is you.
• @p is the nearest player to where the command runs.
• @a is all players online.

(There are more, like @e for all entities, @r for a random one, and @n for the nearest entity, but they come with filters and fine print that we save for Chapter 3. Three is plenty for now.)

Finally, almost every command prints a line of feedback after it runs: a short message telling you it worked, or a red message telling you it didn’t and roughly why. Learning to glance at that line is the fastest debugging habit there is, and we’ll lean on it at the end of the chapter.

Modern Minecraft Typing commands one at a time in chat is the fastest way to learn them, and that’s exactly what this chapter is for. Later you’ll discover two ways to save commands so you don’t retype them: putting them in a command block inside the world (Chapter 6), and saving whole lists of them in a data pack (Part III), which is how real creations are built and shared. For now, the chat box is your workbench.

Making the game talk: /say

The simplest “make something happen” command is /say. Its job: broadcast a plain-text message in the chat to everyone in the world. The syntax is just:

/say <message>

The <message> is everything after the word say. You don’t put it in quotes, you just type it. Open the chat box and try:

/say Welcome to my world!

Press Enter, and everyone in the world (in single-player, that’s you) sees [<your name>] Welcome to my world! in chat. That’s /say in full: plain, unstyled, broadcast to all.

/say is great for a quick “did that work?” check. The text is always plain, though: you can’t color it or make it clickable. When you want a styled, colored, or clickable message, there’s a fancier command called /tellraw. It’s genuinely useful, but it needs you to write the message in a small data format, and that format deserves a proper, gentle introduction rather than a surprise here on page one. So /tellraw gets its own chapter (Chapter 5), once you’ve got a few easy commands under your belt. For now, /say is all you need to make the game talk.

Figure (to be captured). chat showing a /say line broadcast to everyone, with the player-name prefix visible

Giving yourself items: /give

/give puts items straight into a player’s inventory. The syntax is:

/give <targets> <item> [<count>]

• <targets>: who gets the item (@s = you, @p = nearest player, @a = everyone).
• <item>: the item’s identifier, like minecraft:diamond (the minecraft: part can be left off for vanilla items, so diamond works too).
• [<count>]: optional how many. The square brackets mean “you can leave this out”; if you do, it defaults to 1.

Try giving yourself a few things. Type these one at a time, pressing Enter after each:

/give @s diamond_sword /give @s diamond_pickaxe /give @s cooked_beef 16 /give @s oak_planks 64

The first two leave out the count, so you get one of each. The last two ask for 16 steaks and a full stack of 64 planks. Your inventory fills up as you press Enter.

What Went Wrong? “Nothing went into my inventory.” Two usual causes. First, your inventory might be full: in Creative the extra is simply discarded; in Survival it drops on the ground. Second, you may have misspelled the item ID (diamnod_sword). A wrong ID makes the command fail with a red feedback line; read it (see “Reading feedback” below).

Under the Hood /give items can carry extra built-in data in square brackets after the ID (for example a custom name, a color, or enchantments), written like diamond_sword[...]. That square-bracket syntax is the data component system, and it’s the whole of Chapter 21. You don’t need it yet; plain item IDs are all this chapter uses. (Skippable.)

Spawning entities: /summon

/summon creates an entity: a mob, a dropped item, a lightning bolt, anything that moves or lives in the world. The syntax is:

/summon <entity> [<pos>] [<nbt>]

• <entity>: what to spawn, by identifier: minecraft:cow, minecraft:zombie, minecraft:lightning_bolt. (One catch: you can’t summon a player or a fishing bobber; those always fail.)
• [<pos>]: optional where to spawn it. The brackets mean you can leave it out, and if you do, the entity spawns right where you’re standing. That’s perfect for us right now.
• [<nbt>]: optional extra data describing the entity (its name, whether it’s a baby, effects on it, and so on). That’s a more advanced topic; we’ll spawn plain default mobs here.

Stand in an open spot, open chat, and try:

/summon cow /summon cow /summon zombie

Each press of Enter pops a mob into existence right on top of you: two cows and a zombie.

What Went Wrong? “I tried to put the mob at a specific spot and it failed / went somewhere weird.” To place a summon at an exact place you give it coordinates, and coordinates are the whole of the next chapter (Chapter 2). Until you’ve read it, the easy path is to leave the position out, which spawns the mob right where you stand. Walk to where you want it and summon there.

What Went Wrong? “Summoning a hostile mob did nothing.” On Peaceful difficulty the game refuses to summon hostile mobs like zombies. Open your world to Easy (or harder) and try again.

Moving things around: /tp and /teleport

To move a player or entity, use /teleport. It has a short alias, /tp, and they’re the same command, so tp and teleport do exactly the same thing; pick whichever you like to type. The two forms you’ll use most are:

/teleport <targets> <location> moves the target(s) to a set of coordinates. /teleport <targets> <destination> moves the target(s) to another entity’s position.

(If you give just one argument, /teleport <location> or /teleport <destination>, it moves you.)

A couple of examples to try:

• /tp @a @s teleports all players to you (@s). The first selector is who moves, the second is where they go (here, to you). In single-player this just keeps you put, a safe way to watch the command parse without error.
• Teleporting to exact coordinates is also possible, but coordinates are the next chapter; for now, teleporting to an entity (like @s) is the form to play with.

What Went Wrong? “Teleport sent me somewhere strange.” If you tried typing raw numbers, the order is always X Y Z, and a common mix-up is putting the height (Y) in the wrong slot, sending you underground or into the sky. Coordinates get their own chapter next (Chapter 2); until then, teleport to an entity rather than to numbers.

Reading feedback messages

Every command you run prints a small feedback line, and reading it is how you tell success from failure without guessing:

• On success, the game prints a confirming line. For example, after a /give it tells you the item was handed over; after a /summon it confirms something was created.
• On failure, the game prints a red line that names the problem: an argument that wasn’t filled in correctly, a target that matched nobody, a position the game couldn’t use.

A few common failures worth knowing as a checklist when a red line appears:

• /give fails if the targets don’t resolve to any online player, or the item can’t be given.
• /summon fails if you try to summon a player/fishing bobber, the spot is in an unloaded chunk, you summon a hostile mob on Peaceful, or the coordinates are out of the world’s huge legal range.
• /teleport fails if the targets or the destination entity don’t resolve, or the coordinates are out of range.

So the routine is always the same: run the command, glance at the feedback line, and if it’s red, match it against the command’s failure reasons. The exact wording changes from command to command, so rather than memorize a message string, read the actual words your game prints and map them to a cause.

Common mistakes

A quick field guide to the beginner trip-ups this chapter tends to produce:

• Forgetting the /. In the chat box, a command must start with a slash. Without it, the game thinks you’re just chatting and prints your text as a message instead of running it.
• Forgetting the target on /give or /teleport. Unlike /say (which always goes to everyone), these need you to say who: @s, @p, or @a. Leaving it out is an error.
• Misspelling an identifier. zombei, diamnod_sword, coww: a wrong ID fails the command with a red line. Type IDs carefully.
• Trying to summon hostiles on Peaceful. The command quietly fails. Set your world to Easy or harder.

Practice

Build a one-shot “test playground” by typing a sequence of commands: announce it, kit yourself out, and spawn a few mobs to experiment on. Stand in an open area in your test world and type these in order:

/say Setting up the test area... /give @s diamond_sword /give @s diamond_pickaxe /give @s bread 16 /give @s torch 64 /summon cow /summon pig /summon zombie /summon skeleton /say Test area ready!

You should get your kit, see four mobs appear, and read the “setting up” and “ready” messages in chat.

Figure (to be captured). the test world right after running the setup sequence — the player holding the kit, with a cow, pig, zombie, and skeleton spawned nearby, and the setup messages in chat

Typing all ten lines every time you want a fresh playground gets old fast, and that nagging feeling is exactly the itch the rest of the book scratches. In Chapter 6 you’ll wire a sequence like this into a command block so a button press runs it, and in Part III you’ll save it as a function you can trigger with a single command. For now, just notice the wish: “I’d love to run all of these at once.” Hold onto it.

Now make the playground yours:

1. Personalize the kit. Swap in items you like to test with, maybe bow and arrow 32, or a stack of tnt. Read each /give’s feedback to confirm it worked.
2. Pick your mobs. Replace one mob with another you want to experiment on (creeper, villager, armor_stand). Remember hostiles need a non-Peaceful difficulty.
3. Break one on purpose. Misspell an item or a mob (try /give @s diamnod_sword or /summon coww) and read the red feedback line it prints. Getting comfortable reading that red line now, when the mistake is harmless, is the single most useful habit you’ll carry through the whole book.

Try It! Here’s a wish you can’t grant yet: cleaning the playground back up. Removing only certain entities (say, just the zombies) needs target-selector filters like @e[type=zombie]. That’s Chapter 3, a good reason to keep reading.

What Can Go Wrong

• Nothing happens and my text shows up in chat. You forgot the leading /, so the game treated your command as a chat message. Open chat, start with the slash, try again.
• A command runs but seems to do nothing. Read its feedback line. A red line means it failed: match it to the command’s failure reasons (wrong ID, no matching target, Peaceful difficulty, a position the game can’t use). No red line plus no visible effect often means you weren’t looking where it happened (a mob summoned behind you, an item that overflowed a full inventory).
• Mobs spawn in the wrong place, or not at all. With no position, a /summon spawns where you stand, so face an open area first. Precise placement needs coordinates, which is the very next chapter.

What You Know Now

You can open the chat box and talk to Minecraft: make it broadcast with /say, give items with /give (with an optional count), summon entities with /summon (spawning where you stand when you omit the position), and teleport players or entities with /teleport / /tp. You can aim any of them at @s (yourself), @p (nearest player), or @a (all players), and you can read a command’s feedback line to tell success from a red failure. You also felt the first real itch of this whole book (“I wish I could run all of these at once”), which is the thread everything else pulls on. Next, in Chapter 2, you’ll unlock real positioning power: the X/Y/Z axes and the ~ and ^ coordinate shortcuts that let your commands aim anywhere in the world.

Chapter 2 — Coordinates and Building

What You’ll Build

So far your commands have talked to the game (/say), handed you items (/give), and spawned mobs (/summon). This chapter teaches your commands to shape the world. By the end you’ll be able to type a short sequence that builds a small house out of stone, hollows out the inside, cuts a doorway, lays a floor, decorates it, and finishes with a puff of particles and a little chime. To get there you first need the game’s address system: coordinates, the numbers that name a spot in the world. You’ll learn the three directions the world runs in, how to read your own position off the F3 screen, and three different ways to write a position: one exact, one measured from where you stand, and one measured from where you’re looking. Then you’ll meet the five “world-shaping” commands: /setblock, /fill, /clone, /particle, and /playsound.

Everything happens in your test world (Creative with cheats), the same one you’ve used since Chapter 1.

The three axes: how the world is laid out

Every spot in a Minecraft dimension has an address made of three numbers, written in the order X Y Z. Each number is a distance along one axis, an invisible measuring line that runs through the world. The three axes cross at one spot called the world origin, the place where all three numbers are zero (0 0 0). One step of any axis is exactly one block (one cubic meter), so the numbers are just “how many blocks from the origin.”

Here’s what each axis measures:

• The X-axis runs east–west. Travel east and your X number goes up (positive); travel west and it goes down (negative).
• The Z-axis runs north–south. Travel south and your Z number goes up (positive); travel north and it goes down (negative).
• The Y-axis runs up–down. Climb up and your Y number goes up; go down and it goes down. In the Overworld, Y ranges from -64 at the bottom of the world to 320 at the top, and sea level is Y=63.

So a position like 100 70 -40 means “100 blocks east of the origin, 70 blocks up, and 40 blocks north of the origin.” When you’re reading a set of coordinates, the trick is just to remember the order, X, then Y (the height), then Z, and that the middle number is always the height.

What Went Wrong? “I thought north was the positive direction, like ‘up’ on a graph.” A very natural guess, and a wrong one. Minecraft’s map is turned a quarter-turn from the math-class graph you may have seen: going north makes Z smaller (negative), not bigger. If a build keeps appearing on the wrong side of you, you’ve probably got a Z sign backwards. Face one direction, check F3, and walk a few blocks to see which way the number moves.

Under the Hood Your coordinates are actually the spot at the center of the bottom of your body. When F3 says you’re at Y=63, your feet are at 63.0 and your eyes are a bit higher (about 64.62). You don’t need this number for anything yet. It just explains why “your” Y and the block you’re standing on can differ by a hair. (Skippable.)

Reading your position with F3

To see your own position, press F3 (or Fn+F3 on a Mac or some laptops) to open the F3 debug screen, the overlay of technical text. Look at the upper-left: it shows your current coordinates (your XYZ) and which way you’re facing. It also lists your block position, your coordinates rounded down to whole numbers, which is the actual block you’re standing in (more on that just below).

The F3 screen also swaps your crosshair for a tiny set of colored arrows so you can see which way each axis points: +X is red (east), +Y is green (up), and +Z is blue (south). Whenever you lose track of which way is which, glance at that crosshair.

Figure (to be captured). F3 debug screen with the XYZ line and the colored +X red / +Y green / +Z blue crosshair annotated

Try It! Press F3, note your X, Y, and Z, then walk straight in one direction without turning. Watch which of the three numbers changes and whether it climbs or drops. You’ve just measured which axis you’re walking along. No memorizing required.

Block position: why coordinates round down

Your position can be a decimal, because you stand between whole blocks, but a block itself sits on the whole-number grid. The block position is the coordinates of the lower-northwest corner of a block: the whole numbers you get by rounding the decimal coordinates down. That’s the number the block-placing commands in this chapter use.

One quirk worth knowing because it bites people: rounding down behaves differently on each side of zero. For positive coordinates the block position starts at 0 (so the block from 0.0 up to 0.999… is block 0). For negative coordinates it starts at -1 (the block from -1.0 up to -0.001 is block -1). You don’t have to do this math by hand (F3 prints the block position for you), but it explains why a build can land one block off when you’re working in negative territory.

Three ways to write a position

Every command that takes a position will accept it in any of three styles. Learning all three now means the rest of the chapter (and the rest of the book) just works.

Absolute coordinates: the exact spot

Absolute coordinates are the plain numbers straight off F3: X Y Z measured from the world origin. 100 70 -40 always means that one exact spot in the world, no matter who runs the command or where they’re standing. Use absolute coordinates when you want something to appear in a fixed place: a build that always lands at the same spot.

Relative coordinates with ~ (tilde): “from where I am”

Often you don’t care about the exact spot. You want “right here” or “ten blocks that way from me.” That’s what relative coordinates are for. You write them in tilde notation: a ~ (tilde) before each number means “offset from the command’s current position along that axis.” A number after the tilde is the offset; a lone ~ with no number means an offset of 0 (i.e. “don’t move on this axis”).

• ~ ~ ~ means the command’s current position, exactly here.
• ~10 ~ ~-30 means 10 blocks east (+X) and 30 blocks north (–Z) of here, same height.
• ~ ~5 ~ means 5 blocks straight up from here.

You can even mix tildes with absolute numbers. For example, a teleport to ~ 64 ~ keeps your X and Z exactly where they are but sets your height to an absolute Y of 64.

Relative coordinates are the workhorse of building: type a command with ~ coordinates and it acts around wherever you’re standing right now, instead of one hard-coded spot.

Local coordinates with ^ (caret): “from where I’m looking”

The third style measures from your facing direction instead of the world’s compass. Local coordinates use caret notation: a ^ (caret) before each number. The three carets mean, in order, sideways, up, and forward relative to the way the executor is looking:

• The first ^ is left/right (left is positive),
• the second ^ is up/down (up is positive),
• the third ^ is forward/back (forward, the way you face, is positive).

So ^ ^ ^5 means “5 blocks straight ahead of where I’m looking,” wherever that is. Turn around and run it again and you end up back where you started, because “forward” flipped with you. This is perfect for “place something right in front of the player” effects.

Two rules to keep straight:

• You can’t mix carets and world coordinates in the same position. Writing something like ^ 0 ^ fails: the game tells you “Cannot mix world & local coordinates.” A position is all carets or no carets.
• When you have rotation 0 0 (looking due south, level), your local frame happens to line up with the world frame. A handy sanity check.

Under the Hood Pressing F3+B draws a blue ray out of every entity’s head showing its +Z-local (“forward”) direction. If you ever want to see which way “forward” points for a mob, that’s the toggle. (Skippable.)

Modern Minecraft If you’ve watched older build tutorials, you may have only ever seen absolute numbers typed into chat. Relative and local coordinates (~ and ^) are more powerful precisely because the same command works for any player at any location, well beyond the one spot you happened to test it. Think in relative and local coordinates and your builds become reusable: when you later save these commands into command blocks (Chapter 6) and functions (Part III), they’ll already work wherever they run.

/setblock: placing one block

The simplest building command places a single block. Its shape is:

setblock <pos> <block> [destroy|keep|replace|strict]

<pos> is a position (absolute, ~, or ^), <block> is the block to place, and the last word is an optional mode that says how to treat whatever block was already there. The modes are:

• replace: swap in the new block; the old block drops neither itself nor its contents, and no break sound plays. This is the default if you leave the mode off.
• destroy: the old block is broken as if a player mined it: it drops itself and its contents, and the breaking sound plays.
• keep: only place into air; if there’s already a non-air block there, leave it alone.
• strict: place the block as-is without triggering block updates. (You won’t need this until much later; it’s listed here only so the option isn’t a mystery when you see it.)

Here’s a command that drops a block of gold one space in front of where you’re looking:

/setblock ^ ^ ^1 minecraft:gold_block

Some blocks carry extra settings called block states, written in square brackets right after the block name (we’ll use them as we build from here on). For example, to place a chest already facing east at your feet:

/setblock ~ ~ ~ minecraft:chest[facing=east]

What Went Wrong? “/setblock says it failed and nothing happened.” A few honest reasons: the target spot is outside the loaded world; or you tried to place the same block that’s already there (the game skips a pointless no-op); or with keep mode the spot wasn’t air. None of these are bugs. Read the red message and adjust.

/fill: building whole regions at once

/setblock does one block; /fill does a whole rectangular box of them in a single command. You give it two opposite corners and it fills everything in between. Its shape is:

fill <from> <to> <block> [outline|hollow|destroy|strict|replace|keep]
fill <from> <to> <block> replace <filter> [outline|hollow|destroy|strict]

<from> and <to> are any two opposite corners of the box (it doesn’t matter which is which: 0 0 0 to 5 5 5 fills the same box as 5 5 5 to 0 0 0). <block> is what to fill with. The optional mode says how to handle the blocks already there:

• replace: replace every block in the box (including air) with your block, dropping nothing. This is the default.
• destroy: replace everything, but drop the old blocks and their contents as items, as if mined.
• hollow: fill only the outer shell of the box with your block and turn the inside to air. Great for making a room. (If the box is too small to have an inside, it acts like replace.)
• outline: fill only the outer shell with your block, but leave the inside untouched. Like hollow, but it doesn’t clear what’s already inside.
• keep: fill only the air blocks in the box, leaving existing blocks alone.
• strict: place blocks as-is without triggering block updates (an advanced option you can ignore for now).

There’s also a second form with a filter: fill <from> <to> <block> replace <filter> changes only the blocks that match <filter>, leaving the rest as they are. For example, in a 20x10x20 box near you, this turns only orange glazed terracotta into gold, leaving everything else:

/fill ~ ~ ~ ~19 ~9 ~19 minecraft:gold_block replace minecraft:orange_glazed_terracotta

A few worked examples straight from the way /fill is meant to be used. A solid 7x3x7 pool of water just below you:

/fill ~-3 ~-3 ~-3 ~3 ~-1 ~3 minecraft:water

A hollow stone box around you (a house-sized shell, inside cleared to air):

/fill ~-3 ~ ~-4 ~3 ~4 ~4 minecraft:stone hollow

A solid 31x31x31 cube of stone centered on you:

/fill ~-15 ~-15 ~-15 ~15 ~15 ~15 minecraft:stone

What Went Wrong? “/fill did nothing on a giant region.” There’s a size cap on how many blocks one command may change, and over-large fills are rejected. There’s a hard ceiling of 655360 blocks, and a gamerule that controls the limit as well. So rather than memorize one exact gamerule value, just know a limit exists: if a huge /fill or /clone refuses to run, break it into smaller boxes. To see the current name of that gamerule on your version, type /gamerule in chat and read it off the suggestion list; the in-game message is always the authority.

/clone: copying a region

/clone copies a box of blocks from one place to another, perfect for duplicating a build. The Java shape you’ll use is:

clone <begin> <end> <destination> [strict] [replace|masked|filtered <filter>] [force|move|normal]

<begin> and <end> are the two opposite corners of the region to copy (the source), exactly like /fill’s corners. <destination> is the lower-northwest corner where the copy is placed. Then come two optional choices:

What to copy (the “mask”):

• replace: copy all blocks, overwriting everything in the destination. This is the default.
• masked: copy only the non-air blocks, so the destination’s existing blocks show through where the source had air.
• filtered <filter>: copy only blocks that match <filter>.

How to treat the source (the “clone mode”):

• normal: copy and leave the source alone. This is the default.
• force: allow the copy even if the source and destination regions overlap.
• move: copy, then replace the source region with air (it “moves” the build).

There’s also a strict option (place as-is, no block updates) you can ignore for now.

A plain copy looks like this. It copies a 5x5x5 box next to you and pastes it 10 blocks east:

/clone ~ ~ ~ ~4 ~4 ~4 ~10 ~ ~

What Went Wrong? “/clone failed.” The usual causes: the source and destination overlap (use force if you meant to, or move the destination away); the region is too big (same size limit as /fill); or part of either region isn’t loaded. If you’re cloning right next to the original, overlap is almost always the culprit.

Under the Hood /clone can even copy between dimensions with from <dimension> and to <dimension> forms. That needs the idea of naming a dimension, which we don’t cover until Chapter 44. So for now, clone within one world. (Skippable.)

/particle: visual effects

/particle sprays visual effects (smoke, flames, hearts, sparkles) into the world. They’re purely cosmetic (no gameplay effect), which makes them perfect for marking a spot or celebrating a result. The basic shape is short:

particle <name> [<pos>]

<name> is the particle type (like minecraft:explosion_emitter or minecraft:white_smoke) and the optional <pos> is where to make it, defaulting to your position if you leave it off. So a single explosion ten blocks east of you (cosmetic only) is:

/particle minecraft:explosion_emitter ~10 ~ ~

There’s a longer form for finer control:

particle <name> <pos> <delta> <speed> <count> [force|normal] [<viewers>]

You can mostly read those four numbers as: <count> is how many particles to make, <delta> is how spread out they are around <pos> (bigger numbers = a wider cloud), and <speed> scales how they behave. There’s one neat special case: if <count> is 0, you get a single particle and <delta> becomes its motion (the direction it drifts), with <speed> as a multiplier. The trailing force|normal controls range: normal only shows to nearby players, force pushes the particle to players much farther away and shows it even on low particle settings.

One puff of smoke drifting downward (count is 0, so delta is its motion):

/particle minecraft:white_smoke ^ ^1 ^2 0 -1 0 0.1 0

A whole vertical cloud of smoke (count is 10, so delta is the spread):

/particle minecraft:white_smoke ^ ^1 ^2 0 -1 0 0.1 10

Under the Hood Local coordinates (^) are great for the position of a particle, but <delta> always gets converted to absolute directions internally, so putting ~ or ^ in the delta numbers doesn’t do anything special. Use plain numbers there. (Skippable.)

/playsound: sound effects

/playsound plays a sound for a player. Its Java shape has a lot of optional pieces, but most have sensible defaults:

playsound <sound> [<source>] [<targets>] [<pos>] [<volume>] [<pitch>] [<minVolume>]

• <sound>: the sound event to play, like entity.pig.ambient. (A sound event is a named entry the game already knows about; one event can pick randomly from several actual sounds, which is why pigs don’t all sound identical. Making your own sound events is a resource-pack topic for Chapter 30; here we use built-in ones.)
• <source>: the volume category the sound belongs to, which lets players mute it with the right audio slider. It must be one of: master, music, record, weather, block, hostile, neutral, player, ambient, voice, or ui. Defaults to master.
• <targets>: who hears it. Defaults to the player who ran the command. (We’ll cover picking targets properly in Chapter 3; @s, “me”, is enough here.)
• <pos>: where the sound comes from. <volume> sets how far it carries (1 ≈ a 16-block radius; bigger numbers widen the range). <pitch> raises or lowers it (above 1 = higher and faster, below 1 = lower and slower; values under 0.5 are treated as 0.5). <minVolume> is the volume for listeners outside the normal range, and defaults to 0.

A simple chime to yourself, a pig oink (source neutral, so the “Friendly Creatures” slider controls it):

/playsound entity.pig.ambient neutral @s

What Went Wrong? “/playsound failed even though I’m standing right there.” Two common causes: the target isn’t a player (sounds play to players, not mobs), or nobody could actually hear it: if the listener is outside the volume’s range and you didn’t set a <minVolume> above 0, the command reports failure. Move closer, raise the volume, or set a small minVolume.

Walkthrough: building a house

Now the payoff. You’ll type a short sequence that builds a small stone house around you, using relative ~ coordinates so it appears wherever you’re standing, then decorates it and signals that it’s done. Stand in an open spot in your test world, open chat, and type these lines in order, pressing Enter after each. Each one is described just before it.

The shell: a hollow stone box, 7 wide, 5 tall, 7 deep, with its floor at your feet. hollow fills the outer walls/roof/floor and clears the inside to air:

/fill ~-3 ~ ~-3 ~3 ~4 ~3 minecraft:stone hollow

A wooden floor inside, one layer, just above your feet:

/fill ~-2 ~ ~-2 ~2 ~ ~2 minecraft:oak_planks

Cut a doorway in the south wall, two air blocks tall:

/setblock ~ ~1 ~3 minecraft:air /setblock ~ ~2 ~3 minecraft:air

A glowing block in the ceiling so the room isn’t dark:

/setblock ~ ~4 ~ minecraft:glowstone

A chest in the corner, facing into the room:

/setblock ~2 ~1 ~2 minecraft:chest[facing=west]

A celebratory puff of particles at the center of the room:

/particle minecraft:white_smoke ~ ~2 ~

And a sound so you know the build finished:

/playsound entity.pig.ambient neutral @s

Type those in order and a stone hut springs up around you, floored, lit, with a door and a chest, finished off with a puff of smoke and an oink.

Figure (to be captured). the finished stone house built around the player, with the doorway, glowstone ceiling light, and chest visible

Try It! Change minecraft:stone in the first line to a flashier block (minecraft:quartz_block, minecraft:oak_planks, even minecraft:glass for a greenhouse) and run the sequence again. One word changes the whole look of your house.

Want a second house next door? Stand in the same spot you built the first one from and type this to copy the house you’re standing in and paste an identical one to the east:

/clone ~-3 ~ ~-3 ~3 ~4 ~3 ~5 ~ ~-3

Because the source box (~-3 ~ ~-3 to ~3 ~4 ~3) is exactly the box you filled for the shell, this copies the whole hut. The destination corner ~5 ~ ~-3 puts the copy a few blocks to the east, clear of the original so the regions don’t overlap.

Practice

1. Make it bigger. Retype the shell line, widening it from ~-3 ... ~3 to ~-5 ... ~5 and raising the roof from ~4 to ~6. Notice you have to widen the floor line to match, or you’ll have a stone rim around your wooden floor.
2. A window with the filter. Type a line that turns the front wall’s middle blocks into glass using the replace <filter> form, e.g. /fill ~-1 ~2 ~3 ~1 ~3 ~3 minecraft:glass replace minecraft:stone. Because it filters on minecraft:stone, it only changes wall blocks, never your doorway air.
3. Light it from the front. Type a line that places a torch-like block in front of you with local coordinates: /setblock ^ ^ ^2 minecraft:glowstone. Run it facing different directions and watch the block follow your gaze.
4. Clone a row of houses. Build a house, then run the clone line twice from the same spot but change the destination each time (~5 ~ ~-3, then ~13 ~ ~-3) to line up three identical huts.
5. Mark the center. Type a /particle line that drops minecraft:white_smoke particles at ~ ~3 ~ so you can spot the middle of a build at a glance.

What Can Go Wrong

• Coordinate order mix-ups. It’s always X, Y, Z, and Y is the height. If your build is buried or floating, you almost certainly swapped a number into the wrong slot. F3 prints them in the same X-Y-Z order, so compare directly.
• Mixing ^ with ~ or plain numbers. A single position must be all caret (^) or no caret. ^ ~2 ^ won’t parse: the game refuses it with a “can’t mix world & local coordinates” message. Pick one style per position.
• Forgetting hollow and getting a solid block of stone. /fill ... minecraft:stone with no mode defaults to replace, which fills the box solid. If you wanted a room, you need the hollow mode (and remember it clears the inside to air: put your floor and furniture in after).
• Region too large. Very big /fill or /clone commands are rejected by the block-modification limit. If a giant build silently does nothing, split it into smaller boxes.

What You Know Now

You can now describe the world’s address system: the X (east/west), Y (up/down), and Z (north/south) axes, the origin at 0 0 0, and the Overworld’s Y range from -64 to 320. And you can read your own position straight off the F3 screen. You can write any position three ways: absolute (exact, from the origin), relative with ~ (“from where I am,” a lone ~ meaning no offset on that axis), and local with ^ (“sideways, up, forward, from where I’m looking”). And you can shape the world from the chat box: place one block with /setblock (and its destroy/keep/replace modes), fill and hollow and outline regions with /fill (including the replace <filter> form), copy a build with /clone (replace/masked/filtered, force/move/normal), throw cosmetic /particle effects, and play a built-in sound with /playsound. Best of all, you’ve typed a sequence that constructs and decorates a whole house around you: the first time your commands have built something real in the world.

Chapter 3 — Target Selectors: Picking Who or What

What You’ll Build

Up to now, almost every command you’ve typed has acted on you, the player running it. But you’ll often want more than “just me.” You’ll want “every zombie near the player,” or “the closest other player,” or “all the armor stands I summoned.” This chapter teaches the tool that lets a command pick its victims without you ever typing a name: the target selector. By the end you’ll know the five selectors you’ll reach for every day (@s, @p, @a, @e, @r) and how to bolt on square-bracket filters to narrow a crowd down to exactly the entities you mean, like @e[type=minecraft:zombie,distance=..10] for “every zombie within ten blocks.” Then you’ll type a short sequence of commands that rounds up nearby mobs, teleports them to you, and slaps an effect on them. Selectors are the single most reused idea in the rest of this book: every command from here on picks its targets this way.

This chapter builds on the chat commands from Chapter 1 and the coordinate ideas from Chapter 2. Everything here is typed straight into the chat box in your test world.

The problem selectors solve

A target selector is a shorthand for picking players or entities in a command without naming them or knowing their hidden ID: you write a short code and the game figures out who matches. You’ve actually already met one: every time you typed @s in Chapters 1–2, that was a selector meaning “myself, the one running this command.” @s is just the simplest member of a small family.

Here’s why this matters. Imagine you want a command to heal every player on the server. You could try to type out everyone’s name, but names change, players join and leave, and a data pack can’t know them ahead of time. A selector sidesteps all of that. You write @a (“all players”) once, and it resolves to whoever happens to be online when the command runs. Selectors turn “I have to know who specifically” into “I describe the kind of target I want, and the game finds them.”

The five selector variables

The first part of a selector is its variable: the @-something that names the broad category of targets. There are five you’ll use constantly. (There’s actually a sixth in Java Edition, covered in the Under the Hood box below.)

• @s — yourself. Selects the entity that the command was executed as, usually you. It picks the executor whether they’re alive or not. If a command wasn’t run as an entity at all (say, from the server console), @s selects nothing. This is the one you’ve been using.
• @p — the nearest player. Selects the nearest player to where the command runs. If two players are tied for closest (exactly the same distance), the one who most recently joined the server wins.
• @a — all players. Selects every online player, alive or dead.
• @e — all entities. Selects all alive entities in loaded chunks, plus all alive online players. “Entity” here means everything that lives in the world: mobs, dropped items, armor stands, arrows, you name it, not just players.
• @r — a random player. Selects a random online player.

A quick but important caution about @r: in Java Edition it picks a random player, not a random mob. If you want a random entity (say, one random zombie), write @e[sort=random,limit=1] instead. You’ll understand exactly what that means by the end of this chapter.

You can type any of these into chat on its own. Here are a few one-liners:

/say Hello from @s /effect give @a minecraft:glowing 10 0 /kill @e[type=minecraft:arrow]

The first makes you say hello. The second gives every online player ten seconds of Glowing. The third, using a filter you’ll meet shortly, removes every stray arrow in loaded chunks. (We’ll come back to effect give and how its arguments work when we build the practice function.)

Under the Hood Java Edition actually has six selector variables, not five. The sixth is @n, the nearest alive entity (any entity, not just a player, unlike @p). It works just like the others and you’re free to use it, but this book leans on the five above because they cover almost everything a beginner needs, and @n is easy to mimic with @e[limit=1,sort=nearest] once you’ve learned filters. Skip this box if it’s more than you want right now.

Modern Minecraft If you’ve watched older tutorials or Bedrock (phone/console) videos, you may have seen extra selectors like @c, @v, or @initiator. Those are specific to Bedrock Edition or the Education Edition. They don’t exist in the Java Edition this book teaches. Stick to the Java five (plus @n) and you’ll never be surprised.

Filtering: narrowing the crowd

A bare @e is a fire hose: it grabs everything. The real power of selectors is filter arguments (the wiki calls them “target selector arguments”): extra conditions you list in square brackets to keep only the targets that match. The shape is always the same: the variable, then square brackets holding argument=value pairs separated by commas:

@e[type=minecraft:zombie,distance=..10]

Read that as: “all entities, but only the ones that are zombies and within ten blocks.” A few rules worth burning in now:

• Multiple filters are AND-ed together. Every pair must be true for a target to make the cut. The example above keeps something only if it’s both a zombie and close enough.
• Filters change how @p, @r, and @s behave, too. With @a or @e, filters narrow the full list. With @p or @r, the nearest/random target is chosen from the filtered group. With @s, you’re kept only if you would land in that group, so @s[type=minecraft:zombie] selects nothing when you run it (you’re a player, not a zombie).
• Case matters. In Java Edition, argument names and values are case-sensitive. type=Zombie won’t match minecraft:zombie.
• No space before the first bracket. You can put spaces around the equals signs and commas if you like, but not between the variable and its opening [.

Let’s walk through the filters you’ll use most.

type= — filter by entity type

The type= argument keeps only entities of a given kind, named by their identifier (the namespace:path name you’ll meet properly in Chapter 8). The minecraft: namespace can be left off, so type=zombie and type=minecraft:zombie mean the same thing.

@e[type=minecraft:zombie]
@e[type=creeper]

Put a ! in front of the value to mean “everything except this type”:

@e[type=!minecraft:player]

That selects every entity that isn’t a player, handy for “all the mobs and items, but leave the people alone.” Two rules to be strict about:

• A plain type=<something> (no !) can appear only once, and you can’t mix it with a ! exclusion. So @e[type=creeper,type=pig] is an invalid selector (an entity can’t be two types at once anyway). If you want creepers or pigs, that’s what entity tags are for: previewed below under tag=, taught fully in Chapter 13.
• You can stack several exclusions: @e[type=!creeper,type=!pig] means “everything except creepers and pigs.”
• You can’t use type= with @a, @p, or @r in Java Edition, because those already mean “players,” and a type filter would either be redundant or contradictory.

distance= — filter by range

The distance= argument keeps only targets within (or beyond) a distance of the point the command runs from. This is where you meet range syntax, a little notation Minecraft uses all over the place: two dots .. mean “a range,” and which side the number is on says whether it’s a maximum or a minimum:

@e[distance=..10]      all entities LESS than (up to) ten blocks away
@e[distance=10..]      all entities MORE than ten blocks away
@e[distance=8..16]     all entities between eight and sixteen blocks away (inclusive)
@e[distance=10]        all entities EXACTLY ten blocks away

So ..10 is “no more than 10,” 10.. is “at least 10,” and 8..16 is the band in between. Distances are measured to the target’s feet, and only positive (unsigned) values are allowed; there’s no such thing as a negative distance. Distance also limits the search to the dimension the command runs in.

You’ll use distance=..N constantly: “do something to everything near here” is one of the most common things a data pack ever asks for.

name= — filter by name

The name= argument keeps only targets whose name matches exactly. If the name has spaces in it, wrap it in quotes.

@e[name=Rover]
@e[name="Sir Barksalot"]
@a[name=!Steve]

The last one, with !, means “every player except the one named Steve.” Names are how you single out a specific mob you’ve named with a name tag, or a particular player. But remember names can change and aren’t unique, so they’re a blunt tool compared to the next one.

tag= — filter by a label you put on entities

The tag= argument keeps only entities carrying a particular scoreboard tag, a simple text label you can stick on any entity to mark it. You haven’t learned how to add tags yet (that’s the /tag command, coming in Chapter 13), but you’ll see tag= in selectors everywhere, so meet it now:

@e[tag=is_boss]
@e[tag=!frozen]

The first selects every entity wearing the is_boss label; the second selects everything without the frozen label. Tags are the cleanest way to mark “these specific entities are special”: for example, tagging the three zombies your pack summoned so a later command can find just those three and ignore every other zombie in the world. We’ll build real tag-based systems in Chapter 13. For now, just know that tag= reads a label, and ! flips it.

limit= and sort= — how many, and which ones

By default, @a and @e grab every match. Often you want only one, or only the closest few. Two arguments control that together:

• limit=<number> caps how many targets come back.
• sort=<order> decides which ones survive the cap, by setting the order before the limit applies. The four orders are:
  • sort=nearest: closest first (this is the default for @p)
  • sort=furthest: farthest first
  • sort=random: shuffled (this is the default for @r)
  • sort=arbitrary: no sorting; often returns the oldest entities first, but no order is promised (this is the default for @e and @a)

Examples:

@a[limit=3,sort=nearest]    the nearest three players (same as @p[limit=3])
@a[limit=4,sort=furthest]   the farthest four players
@a[limit=2,sort=random]     two players chosen at random (same as @r[limit=2])

Notice the last two lines of each pair: @p is really just “@a with limit 1, sorted nearest,” and @r is “@a with limit 1, sorted random.” That’s also the trick from earlier: @e[sort=random, limit=1] is how you grab one random entity (rather than a random player, which is what @r gives you).

nbt= — a quick preview

The nbt= argument filters by an entity’s NBT data, the raw saved data a mob or item carries internally (its health, whether a sheep is sheared, what color it is, and so on). You’ll learn what NBT actually is in Chapter 12; for now just know nbt= exists and what it looks like:

@a[nbt={OnGround:true}]

That selects all players standing on the ground. One warning to be explicit about: reading NBT is a heavy process for the CPU, so use nbt= sparingly. In fact, the wiki points out that @e[nbt={Tags:[a,b]}] does the same job as @e[tag=a,tag=b], and the tag= version is both simpler and lighter on the game. So reach for tag= first; save nbt= for things only NBT can express.

Modern Minecraft Tutorials made for Bedrock Edition use different argument names: r= and rm= for distance, c= for limit, m= for game mode, and so on. The Java Edition this book teaches uses the longer, readable names (distance=, limit=, sort=) with the .. range syntax. If a guide tells you to write @e[r=10], that’s Bedrock; the Java version is @e[distance=..10].

Try It! The selector page lists more filters than we’ve covered: by experience level=, by gamemode=, by facing direction (x_rotation= / y_rotation=), by a cuboid volume (dx= / dy= / dz=), and more. You don’t need them yet, but if you’re curious, every one follows the same argument=value shape and the same .. range and ! rules you just learned. Two more (scores= and predicate=) wait on ideas from later chapters (scoreboards in Chapter 11, predicates in Chapter 18).

Combining filters

Because filters AND together, you build precise targets by stacking them. This is the everyday craft of data packs. Read each of these as a sentence:

@e[type=minecraft:zombie,distance=..10]

“Every zombie within ten blocks.” (The chapter’s headline example.)

@e[type=minecraft:armor_stand,tag=marker]

“Every armor stand wearing the marker label.”

@a[distance=..16,limit=1,sort=nearest]

“The single nearest player within sixteen blocks.”

@e[type=!minecraft:player,distance=..5]

“Everything that isn’t a player, within five blocks of here.”

The order you write the filters in doesn’t matter. [type=...,distance=...] and [distance=...,type=...] mean the same thing, because all the conditions must be true together.

Walkthrough: rounding up nearby zombies

Time to put selectors to work. You’ll type a short sequence of commands that:

1. finds every zombie within ten blocks of you,
2. teleports those zombies to you, and
3. gives them Glowing so you can see who got rounded up.

This combines a filtered selector (@e[type=...,distance=...]) with two commands you’ll meet here: /teleport and /effect give.

First, the two commands:

• /teleport <targets> <destination> moves the targeted entities to a destination, which can be another entity. So /teleport @e[...] @s means “teleport those entities to me.” (/teleport is the full name of the /tp command you saw in Chapter 1; they’re the same command.)
• /effect give <targets> <effect> [<seconds>] [<amplifier>] applies a status effect. The seconds and amplifier are optional; amplifier is the level minus one, so amplifier 0 is level I. If you leave seconds off it defaults to 30.

In your test world, summon a few zombies near you (you learned /summon in Chapter 1), then type these three commands in order, pressing Enter after each:

/teleport @e[type=minecraft:zombie,distance=..10] @s /effect give @e[type=minecraft:zombie,distance=..10] minecraft:glowing 15 0 /say Rounded up the nearby zombies!

The first teleports every zombie within ten blocks to you; the second gives those same zombies Glowing for fifteen seconds so you can spot them; the third announces what happened. A few things to notice:

• The selector is identical on both lines. Each command re-runs the selector fresh, so both the teleport and the effect act on the same group: zombies that were within ten blocks. (After the teleport they’re standing on top of you, but the second line’s distance=..10 still includes them, since they’re at distance zero.)
• @s is the destination. Because you’re typing these in chat, @s is you, so the zombies teleport to you.

The nearby zombies should snap to your position and start glowing. Any zombie farther than ten blocks away is left alone: that’s your distance=..10 filter doing its job.

Figure (to be captured). the player surrounded by glowing zombies right after running the round-up commands, with one un-glowing zombie visible in the distance that was outside the 10-block range

Under the Hood @s meaning “you” is doing quiet work here. A selector like @s only means “the player” if the command was run as that player, which it is when you type it in chat yourself, because you are the executor. In the next chapter you’ll learn the /execute command, which lets you deliberately change who @s is and where a command runs from: for example, “run this once as each zombie, at that zombie’s feet.” That’s how you’ll do per-entity work. For now, typing the command yourself keeps @s simple: it’s you.

Practice

Re-run the round-up commands and experiment with selectors:

1. Wider net. Change both distance=..10 filters to distance=..20 and re-run. More zombies get caught. Then try distance=5..20: now zombies closer than five blocks are skipped. Predict who gets rounded up before you run it, then check.

2. Round up something else. Type a command with the opposite mood: give every cow within fifteen blocks the Speed effect so they bolt. Use @e[type=minecraft:cow,distance=..15] and effect give ... minecraft:speed 10 2 (amplifier 2 is Speed III):

   /effect give @e[type=minecraft:cow,distance=..15] minecraft:speed 10 2 /say The cows have had too much coffee.

3. Only the closest. Type a command that teleports only the single nearest zombie to you, not all of them. Hint: add limit=1,sort=nearest to the selector, @e[type=minecraft:zombie,distance=..10,limit=1,sort=nearest].

4. Spare the named ones. Suppose some mobs are pets you’ve named. Add name=! filters or, better, plan ahead for Chapter 13 by imagining a tag=!pet filter that would skip any entity you’ve labelled pet. (You can’t add the tag yet, that’s Chapter 13, but you can already read it in a selector.)

What Can Go Wrong

What Went Wrong? “My selector grabbed nothing.” The most common cause is the AND rule: every filter has to be true at once. If you wrote @e[type=minecraft:zombie,distance=..2] and the nearest zombie is three blocks away, you get zero targets, not because the type is wrong, but because nothing satisfies both conditions. Loosen one filter at a time to find which one is excluding everyone.

What Went Wrong? “I got an error about my type argument.” Check three things. First, case: Java is case-sensitive, so it’s minecraft:zombie, never minecraft:Zombie. Second, you can only have one plain type= (no !) per selector; @e[type=zombie,type=pig] is invalid. Third, you can’t use type= with @a, @p, or @r at all, because those already mean “players”; use @e when you want to filter by entity type.

What Went Wrong? “Nothing happened, and there’s no error.” If a selector matches nobody, the command simply does nothing, quietly. That’s not a crash; it’s an empty target list. Run a harmless test like /say @e[type=minecraft:zombie,distance=..10] first: if it echoes the matched entities, your selector works and the problem is elsewhere; if it shows an empty result, your filter is too tight or the entities aren’t where you think.

What You Know Now

You can pick targets for any command without naming them. You know the five everyday selector variables: @s (yourself), @p (nearest player), @a (all players), @e (all entities), and @r (a random player), and that @e reaches everything in loaded chunks. You can attach filter arguments in square brackets and combine them, knowing they all have to be true at once: type= for entity kind (with ! to exclude, once-only for the plain form, and off-limits to @a/@p/@r), distance= with .. range syntax (..10, 10.., 8..16), name= for an exact name, tag= for a label (a preview of Chapter 13), and limit= with sort= (nearest/furthest/random/ arbitrary) to control how many and which. You’ve seen nbt= exists but is heavy and best avoided until Chapter 12. And you’ve typed a round-up sequence that filters, teleports, and buffs a precise group of entities: the pattern behind nearly every command you’ll write from here on.

Next chapter unlocks the command that makes selectors truly programmable: /execute, which lets you change who a command runs as and where it runs from, so you can do per-entity work like “as every zombie, at its position, strike lightning.”

Chapter 4 — The /execute Command

What You’ll Build

This is the most important command in Minecraft, and it’s the one that turns a list of commands into something that can actually think. So far, every command you’ve written runs as you, where you are, no matter what. /execute breaks all three of those rules. It lets you run a command as a different entity, run it at a different place, and run it only if something is true. By the end of this chapter you’ll be able to read a long /execute line left to right and say exactly what each piece does, and you’ll have typed two real /execute commands into the chat box: one that gives a player a potion effect while they stand on a gold block, and one that calls down lightning on every zombie at once. These two small lines use the same machinery that powers nearly every advanced data pack ever made.

This chapter assumes you’re comfortable with target selectors from Chapter 3 (@s, @e, @a, and filters like type= and distance=) and with coordinates from Chapter 2 (absolute, ~ relative, ^ local).

Why /execute exists

Every command secretly carries some hidden background information with it: who is running it, and where it’s running. The official description of the command says it plainly: /execute “executes another command but allows changing the executor, changing the position and angle it is executed at, adding preconditions, and storing its result.” Read that again, because the whole chapter is just those four powers spelled out:

• change the executor: run a command as a different entity (this changes what @s means).
• change the position: run a command at or positioned at a different place (this changes what ~ ~ ~ means).
• add preconditions: run the command only if (or unless) some condition is true.
• store its result: save a number the command produces (you’ll preview this here; the details come later).

Two pieces of vocabulary make the rest of the chapter easy. The executor is the entity a command runs as. It’s what @s (“self”) points at. The execution position is the point a command runs at, the spot relative coordinates like ~ ~ ~ are measured from. Plain commands always use you as the executor and your spot as the position. /execute is how you change either one.

A piece of /execute is called a subcommand (the game also calls them instructions). You chain subcommands together, and the very last one is always run, followed by the real command you want to carry out. Here’s the shape of every /execute line you’ll ever write:

/execute <subcommand> <subcommand> ... run <the actual command>

The subcommands fall into a few jobs: modifier subcommands change the context (who and where), condition subcommands test something (if/unless), a store subcommand saves a result, and the run subcommand carries out the real command at the end. We’ll meet one job at a time.

Modern Minecraft Older tutorials sometimes show a chat command typed straight into the box, like /execute @e ~ ~ ~ summon lightning_bolt. That old grammar was retired years ago. Current Java Edition uses the named-subcommand form you’re learning here (execute as @e at @s run summon lightning_bolt), which reads almost like a sentence. If a tutorial’s /execute looks like a string of bare selectors and coordinates with no words like as, at, or run, it’s out of date.

as — change who runs the command (the executor)

The as subcommand “sets the executor to target entity.” In plain terms: it changes who the command thinks it is, which changes what @s means. Its syntax is:

as <targets> -> execute

That little -> execute is shorthand for “another subcommand must follow”: as can’t be the end of the line. Here’s the classic example:

/execute as @e[type=sheep] run kill @s

Walk through it: as @e[type=sheep] makes the game pretend, one at a time, that it is each sheep. Then run kill @s kills “self,” and because “self” is now a sheep, every sheep dies. Without execute as, kill @s would just kill whoever typed the command.

This reveals something important. When a selector picks more than one entity, the rest of the chain runs once for each one. This is called forking into multiple branches: when the as subcommand selects multiple entities, the subcommands following it execute once per entity. This is how one line of /execute can act on a hundred mobs: you type the command once, and the fork runs it for each match.

at — change where the command runs (the position)

The as subcommand changes who, but, importantly, it does not change where. There’s an important detail here: as sets the executor without changing the execution position. So if you do execute as @e[type=sheep] run particle ..., every sheep is the executor, but the particle still appears at your feet, because the position never moved.

That’s what at is for. The at subcommand “sets the execution position, rotation, and dimension to match those of an entity.” Its syntax:

at <targets> -> execute

The two are almost always used together as as @e[...] at @s, which reads: “for each matching entity, become it (as), then move to its spot (at @s).” This example makes the pairing clear:

/execute as @e[type=sheep] at @s run tp @s ~ ~1 ~

This moves every sheep up one block. as @s makes each sheep the executor, at @s moves the position to that sheep, and tp @s ~ ~1 ~ teleports self one block above its current spot.

To see why order matters, compare these two lines:

• /execute as @e at @s run tp ^ ^ ^1: all entities move one block forward.
• /execute at @s as @e run tp ^ ^ ^1: all entities teleport to one block in front of the executor.

The game reads subcommands strictly left to right, so swapping as and at gives two completely different results. There’s also a trap worth memorizing: at never changes who the executor is. Watch this gotcha. /execute at @e[type=sheep] run kill @s kills the player running the command, because at does not change the executor. You moved the position to a sheep, but @s is still you.

positioned — set the position directly

at borrows a position from an entity. positioned lets you set the position yourself, with no entity needed: it sets the execution position directly. It has a few forms; the two you’ll use are:

positioned <pos> -> execute
positioned as <targets> -> execute

positioned <pos> takes coordinates, like positioned 0 64 0. This example searches for a village near a fixed point:

/execute positioned 0 64 0 run locate structure #village

positioned as @s, on the other hand, copies an entity’s position only. Unlike at, it leaves the rotation and dimension alone. For most beginner uses, at @s is what you want; reach for positioned when you need an exact coordinate or you only want the location, not the facing.

if / unless — run the command only when something is true

So far we can change who and where. The condition subcommands add whether. The if and unless subcommands restrict command execution to happen only under specified conditions. In most cases, unless is a negation of if, equivalent to “if not…”. When a condition fails, that branch simply stops (it “terminates”) and the run never happens.

if and unless come in several flavors. The two you’ll use constantly are if entity and if block.

if entity checks whether a matching entity exists. Syntax:

(if|unless) entity <entities> -> [execute]

The [execute] in brackets means another subcommand here is optional: if can be the last thing on the line, or it can be followed by run. So /execute if entity @e[type=creeper,distance=..10] run say A creeper is near! only says the message when a creeper is within 10 blocks.

if block “compares the block at a given position to a given block ID or a block tag.” Syntax:

(if|unless) block <pos> <block> -> [execute]

This is how you check what someone is standing on. This example kills any player standing on a wool block:

/execute as @a at @s if block ~ ~-1 ~ #wool run kill @s

Read it as a sentence: for each player (as @a), at their position (at @s), if the block one below them (~ ~-1 ~) is wool, kill them. The ~ ~-1 ~ means “same X and Z, one block down,” exactly the spot your feet rest on. You’ll reuse this exact pattern in the practice below, swapping wool for gold.

There are more condition types you’ll meet in later chapters. Three are worth naming now so the syntax doesn’t surprise you when an online tutorial uses it:

• if score compares scoreboard numbers, e.g. if score @s wins matches 3... Scoreboards are a whole system of their own. You’ll learn them in Chapter 11, and if score with them.
• if predicate checks a named, reusable condition you save as a JSON file. Predicates get their own Chapter 18.
• if data checks whether an entity or block has a piece of data; the data system (command storage) is Chapter 12.

Try It! unless is just if flipped. Once you’ve typed the gold-block command below, try changing if block to unless block and stand off the gold — the effect now applies everywhere except on gold. Reading unless as “if not” makes these lines click.

store — saving a result (preview)

The fourth power, store, stores the final subcommand’s result or success value somewhere. A command quietly produces a number when it runs (for example, if entity @e[type=zombie] produces how many zombies matched), and store catches that number and saves it. There are five places it can save to (a block, a bossbar, an entity, a score, or a storage), with syntax like:

store (result|success) score <targets> <objective> -> execute

You don’t have the tools to use the saved number yet: scores live in Chapter 11 and command storage in Chapter 12, and the deeper store patterns wait for Chapter 27. For now, just recognize the word: when you see execute store result score ... in someone else’s pack, it means “run this and remember the number it gives back.” We’ll come back and wire it up properly later.

run — the final step

Every chain ends with run. Its single argument is the command to be executed, whose context variables may be modified by the subcommands used. In other words, run is where you put the actual command, and all the as/at/if pieces before it have already set up the who, where, and whether.

Two rules keep you out of trouble:

• run can be used only once, at the very end. You can stack as many as, at, and if subcommands as you like, but run finishes the line.
• A chain that doesn’t end in run is only legal if it ends in a condition (if/unless). Only a run subcommand or a condition subcommand may finalize the chain; otherwise, the command is unparseable. If you end on as or at with nothing after, the game rejects the line.

Walkthrough: building a chain one piece at a time

The best way to understand a long /execute is to grow it. Let’s build up a command that warns you about nearby zombies, subcommand by subcommand, typing each version into chat as we go.

Start with the plainest version, just a message:

/say Checking for zombies...

Now make it speak as each zombie:

/execute as @e[type=zombie] run say I am a zombie.

If three zombies are loaded, that line forks into three branches and you get the message three times, once per zombie, each running as that zombie. Finally, only warn when zombies are actually close, by adding a condition. The finished pair of commands:

/execute if entity @e[type=zombie,distance=..16] run say A zombie is within 16 blocks! /execute as @e[type=zombie,distance=..16] at @s run say A zombie stands here.

The first line uses if entity as the last subcommand-before-run: the message fires once, only when at least one zombie is within 16 blocks. The second line forks over every nearby zombie and runs as and at each one. Type each into chat and press Enter to try it.

Practice 1 — if a player stands on gold, give them an effect

Now the real thing. We want: for every player, check the block under their feet, and if it’s a gold block, give them a potion effect. This is the wool example from earlier with two swaps: wool becomes gold, and kill becomes effect give. The effect command’s syntax is effect give <targets> <effect> [<seconds>] [<amplifier>]. Place a gold block, stand on it, open chat, and type:

/execute as @a at @s if block ~ ~-1 ~ minecraft:gold_block run effect give @s minecraft:speed 2 1

Read it left to right: as @a (for each player) at @s (at that player’s spot) if block ~ ~-1 ~ minecraft:gold_block (if the block one below is a gold block) run effect give @s minecraft:speed 2 1 (give self Speed for 2 seconds at amplifier 1). Typed once in chat, it gives you a 2-second burst of Speed if you’re standing on gold. To make it a constant boost that refreshes every tick while you stand on the gold, you’ll later put this exact line in a repeating command block (Chapter 6) or in a function that runs every tick (Part III). For now, type it by hand to watch the condition work.

Figure (to be captured). player standing on a single gold block with the Speed effect icon showing in the corner

What Went Wrong? Effect won’t apply? The most common cause is the block ID. Make sure you’re testing for a block ID like minecraft:gold_block, not an item: a gold ingot is an item, not a block, so if block will never match it. Also check the offset is ~ ~-1 ~ (one below) and not ~ ~ ~ (the block you’re standing inside, which is air).

Practice 2 — as every zombie, at its position, summon lightning

This one is pure spectacle and shows off forking. We want to run, for every zombie, summon lightning_bolt at that zombie’s own position. The summon command (Chapter 1) is summon <entity> [<pos>]; with no position it summons at the execution position, which is exactly what at @s sets up. Summon a few zombies, then type:

/execute as @e[type=zombie] at @s run summon minecraft:lightning_bolt

as @e[type=zombie] forks over every zombie; at @s moves the position onto each one; and summon minecraft:lightning_bolt (with no coordinates) strikes at that position. Because the chain forks, one short line strikes every zombie at once.

Figure (to be captured). several zombies being struck by lightning at once, one bolt per zombie

Try It! Add a condition so only nearby zombies get hit: change the selector to @e[type=zombie,distance=..20]. Or make it rain effects instead of lightning — swap the run for run effect give @s minecraft:glowing 30 0 so every zombie lights up. Notice how only the last part (after run) changes; the as ... at @s scaffolding stays the same. That scaffolding is the reusable heart of /execute.

What Can Go Wrong

Forgetting at after as. This is the number-one beginner mistake. /execute as @e[type=zombie] run summon lightning_bolt makes each zombie the executor, but it never moves the position, so all the lightning strikes at your feet instead of at the zombies. Whenever you want something to happen where an entity is, you almost always need as <sel> at @s together, not as alone.

Putting run in the wrong place, or twice. run must be last, and may appear only once. A line like /execute run say hi as @e won’t work because nothing is allowed after the run command. And a chain that ends on a modifier with nothing after it (/execute as @a at @s) is “unparseable,” because only a run or an if/unless may finish a chain.

Mixing up @s and the position. Remember that as changes the executor (@s) and at/positioned change the position (~ ~ ~): they’re two separate things. If your command targets the wrong entity, check your as. If it happens in the wrong place, check your at. The bug is almost always one of those two, in the wrong order or missing entirely.

What You Know Now

You can read and write the most important command in the game. You know that /execute runs another command after changing the executor (as), the position (at, positioned), and the condition (if/unless), and that the chain always finishes with run plus the real command. You understand forking (that a multi-entity selector makes the rest of the chain run once per entity) and you’ve used it to act on every zombie at once. You’ve previewed store and the if score / if predicate / if data conditions, which unlock fully once you learn scoreboards (Chapter 11), command storage (Chapter 12), and predicates (Chapter 18). You’ve typed live /execute lines that warn about nearby zombies, boost players standing on gold, and call lightning down on every zombie at once. From here on, /execute shows up in almost every chapter. It’s the glue that holds programmable data packs together.

Chapter 5 — Text Components: Styled and Dynamic Text

What You’ll Build

Back in Chapter 1 you met /say for plain messages, and you were promised a fancier message command called /tellraw once you’d built up to it. This is that chapter. /tellraw sends a text component: a small piece of JSON that describes what a message says, how it looks (color, bold, italics), and what it does when a player clicks or hovers over it. Text components are how Minecraft does every bit of styled, interactive text: colored chat, clickable links, hover tooltips, and big titles on the screen.

By the end of this chapter you’ll be able to color and style text, drop in dynamic pieces that fill themselves in (a player’s name, a translated word, a score), make text clickable and hoverable, and send it all to players with /tellraw and /title. You’ll finish by building a styled, clickable welcome message and firing it off in chat to greet everyone in color.

Everything in this chapter is typed straight into the chat box of your test world, the same way you’ve been running commands since Chapter 1.

What a text component is

A text component (the wiki sometimes calls it “raw JSON text,” its older name) is the format Minecraft uses for any formatted text. They start small: in /tellraw @a {"text":"Hello"}, that {"text":"Hello"} part is a text component, the simplest one there is.

The simplest text component is just a string of text. These three are all the same message:

• "Hello world": a plain string.
• {"text":"Hello world"}: an object (a {} block) with one field, text.
• ["Hello world"]: a list (a [] block) with one item in it.

So a text component can be written three ways: as a plain string, as a list, or as a compound object (the {} form). The string and list forms are just shorthand for the object form. Most of the time you’ll write the object form, because that’s the one you can attach color and clicks to.

A component can have children. There is always one root component at the top, and it can hold a list of more components in a field called extra. Here’s the key rule: children inherit the root’s formatting unless they set their own. So if the root is red, every child is red too until a child says otherwise.

The list shorthand uses this. Writing ["A", "B", "C"] is the same as {"text":"A", "extra":["B", "C"]}: the first item becomes the root, and the rest become its children. That means [{"text":"A","color":"red"}, "B", "C"] shows all three letters in red, because “B” and “C” are children of the red “A”.

Under the Hood (skippable) The whole format is recursive: a component can contain components, which can contain components, forever. That’s how a single message can mix colors, clickable words, and hover tooltips: each piece is its own little component nested inside the others. You almost never need deep nesting as a beginner, but it’s why the format can do everything from a one-word chat line to a full interactive menu.

Almost every field is optional. A text component doesn’t have to be complicated. {"text":"hi"} is a perfectly good one.

Color and style

The most common thing you’ll add is color and style. These are formatting fields you put right inside the component object, next to text.

The color field takes either one of Minecraft’s 16 named colors or a custom hex code:

• Named colors: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white.
• A hex color like "#FF8800": a # followed by a 6-digit hexadecimal color, the same kind of code used for colors on the web. This lets you pick any color, not just the 16 named ones.

So {"text":"Danger!","color":"red"} is red, and {"text":"Sunset","color":"#FF8800"} is a custom orange.

On top of color, there are several true/false style fields. Each is a boolean: true turns it on, false turns it off.

• bold: heavier text.
• italic: slanted text.
• underlined: a line under the text.
• strikethrough: a line through the text.
• obfuscated: scrambled, constantly-changing characters (the classic “magic” garble).

You can combine them freely. This component is bold, italic, and gold:

{"text":"Legendary Sword","color":"gold","bold":true,"italic":true}

Try It! The italic field has a sneaky use: some text is italic by default (like custom item names you’ll meet in Chapter 22). Setting "italic":false is how you turn that off later. For now, just remember that false is a real choice too, alongside true.

There’s also a font field that points at a font from a resource pack. It defaults to "minecraft:default" (the normal font), and there’s a built-in alternate font you can name as "alt". (Those are the two built-in font names; to see what the alt font actually looks like, try it in-game.) We’ll only use the built-in ones here; making your own fonts is a resource-pack topic for Chapter 30.

Dynamic content: text that fills itself in

So far our components show fixed text we typed. But components can also show dynamic content: values the game fills in when the message is sent. You choose which kind by including a special field instead of (or alongside) text. There are four kinds worth knowing now.

translate — built-in translations

The translate field shows a piece of text in the player’s own language. Minecraft ships with translation keys for nearly everything, and each player sees the message in whatever language their game is set to.

{"translate":"item.minecraft.diamond"}

That shows the word “Diamond,” translated for each player. The key item.minecraft.diamond is the identifier Minecraft uses internally for that item’s name.

Translations can have slots to fill in, written as %s in the translation text. You fill them with the with field, a list of components, one per slot:

{"translate":"%s joined the game","with":[{"text":"Steve","color":"yellow"}]}

If a key doesn’t exist, the game just shows the key text itself; you can supply a fallback field with backup text to show instead.

selector — entity names

The selector field shows the name of whatever a target selector picks (you learned selectors in Chapter 3). The game fills in the actual name(s) when the message is sent.

{"selector":"@p"}

That shows the nearest player’s name. If the selector could match more than one entity, separate names with a comma; if you want to be sure it’s exactly one, add limit=1 to the selector, like "@p[limit=1]".

score — a scoreboard value (preview)

The score field shows a number from the scoreboard, Minecraft’s system for tracking numbers per player. You’ll learn scoreboards properly in Chapter 11; here’s a preview so you recognize it. The score field is itself a small object with a name (whose score to show) and an objective (which counter):

{"score":{"name":"@s","objective":"coins"}}

That would show the running player’s value in a “coins” counter. Don’t worry about making a scoreboard yet; just know that this is how a live number gets into a message.

Under the Hood (skippable) Dynamic values are filled in once, at the moment the message is sent, a process the wiki calls resolution. A score that shows “100” stays “100” in that already-sent message even if the score later changes. Text components don’t keep updating themselves; each send is a fresh snapshot.

nbt — data from a block, entity, or storage (preview)

The nbt field shows raw data values from the game: from an entity, a block, or command storage (a place to keep data, taught in Chapter 12). It uses an NBT path (a way to point at one piece of data) and a source saying where to look:

{"nbt":"SelectedItem.id","entity":"@s","source":"entity"}

That would show the ID of the item the running player is holding. Like score, the data is filled in when the message is sent. We’re previewing this so you recognize it later; the storage side comes in Chapter 12.

Making text interactive: click and hover

Here’s where text components stop being just pretty and start being useful. Two fields make text respond to the player:

• click_event: what happens when the player clicks the text.
• hover_event: a tooltip shown when the player hovers the mouse over the text.

There’s also a simpler third field, insertion: when a player shift-clicks the text, the string you put here is inserted into their chat input (it adds to whatever they were typing rather than replacing it). It only works in chat messages. We won’t use it in the walkthrough, but it’s good to know it exists alongside the two big ones.

Modern Minecraft These two fields are written in snake_case: click_event and hover_event, with an underscore. A lot of older tutorials and YouTube videos from before this change write them in camelCase: clickEvent and hoverEvent, no underscore. Those no longer work in current Java Edition. If you copy an old example and the click does nothing, the underscore is the first thing to check. The same goes for the action names below: they’re snake_case too.

click_event

The click_event field is an object. Inside it, an action field names what kind of click behavior you want, and the other fields give it details. These are the available actions:

• open_url: opens a web link in the player’s browser. Needs a url field.
• run_command: runs a command as if the player typed it in chat. Needs a command field. The command does not need a leading / slash. (It can only run commands the player has permission for, and not ones that send chat directly.)
• suggest_command: opens chat and fills in some text or a command, ready for the player to edit and press enter. Needs a command field.
• copy_to_clipboard: copies text to the player’s clipboard. Needs a value field.
• change_page: in a written book only, jumps to a page number. Needs a page field.
• show_dialog: opens a custom pop-up screen (a dialog). Needs a dialog field. Dialogs are a whole feature of their own, covered in Chapter 39; this is just so you know the action exists.
• custom: sends a custom event to the server (it does nothing on a normal vanilla server; it’s for servers with their own add-ons). Takes an id and an optional payload.
• open_file: used by the game itself (for example when you take a screenshot). Servers and data packs can’t send this one, so you won’t use it.

A clickable component looks like this:

{"text":"[Click for a diamond]","color":"aqua","click_event":{"action":"run_command","command":"give @s diamond"}}

Clicking that text runs give @s diamond for the player.

hover_event

The hover_event field is also an object with an action field. The actions are:

• show_text: shows a text component as a tooltip. The text goes in a value field. (Note: a tooltip’s own text can’t itself have working clicks or hovers; tooltips are display-only.)
• show_item: shows an item’s tooltip, as if hovering it in your inventory. Takes an id (the item), an optional count, and optional components (extra item data, which you’ll meet in Chapter 21).
• show_entity: shows an entity’s name, type, and UUID. Takes an id (the entity type), an optional name, and a uuid.

A hovering component:

{"text":"Hover me","color":"yellow","hover_event":{"action":"show_text","value":{"text":"Surprise!","color":"green"}}}

And you can put both click_event and hover_event on the same component: clickable and hoverable at once. You’ll do exactly that in the walkthrough.

Sending a component: /tellraw

A text component is just data, so something has to send it. The first sender is /tellraw, which you met in Chapter 1. Its full form is:

/tellraw <targets> <message>

<targets> is a player selector (it must select players, not other entities), and <message> is a text component. So everything you’ve learned in this chapter goes in the <message> slot.

A few real examples, exactly as the game accepts them. Type each into the chat box and press Enter:

/tellraw @a {"text":"I am blue","color":"blue"} /tellraw @a {"text":"Text1\nText2"} /tellraw @p {"translate":"item.minecraft.diamond"}

The second one shows a handy trick: \n inside the text starts a new line.

Big screen text: /title

/tellraw writes to chat. /title writes big text on the screen, the kind you see at the center of the display when something dramatic happens. It has three places it can put text, plus controls for timing:

/title <targets> (title|subtitle|actionbar) <text> /title <targets> times <fadeIn> <stay> <fadeOut> /title <targets> (clear|reset)

• title: large center-screen text.
• subtitle: a smaller line just below the title. (A subtitle only appears together with a title, so set the subtitle first, then the title.)
• actionbar: a line of text just above the hotbar.
• times <fadeIn> <stay> <fadeOut>: how long, in ticks (1/20 of a second), the title fades in, stays, and fades out. The defaults are 10, 70, and 20 ticks (about half a second in, three and a half staying, one second out).
• clear removes the current title; reset puts the timing back to defaults.

In Java Edition, the <text> is a full text component, so it gets color and style just like /tellraw. This pair shows a bold title with a gray italic subtitle. Type them one after the other:

/title @a subtitle {"text":"The story begins...","color":"gray","italic":true} /title @a title {"text":"Chapter I","bold":true}

Notice the order: subtitle first, then title, because the subtitle rides along with the title that follows it.

Walkthrough: a styled welcome message

Time to put it together. You’ll greet the player with a big title on screen and a colored, clickable chat line, typing each command into the chat box of your test world.

Step 1 — the title. Type these two, in this order, so the subtitle rides along with the title:

/title @a subtitle {"text":"A grand adventure","color":"gray","italic":true} /title @a title {"text":"Welcome!","color":"gold","bold":true}

A gold “Welcome!” should fade in over a gray italic subtitle.

Step 2 — a colored chat line. Now build a greeting from several child components and send it:

/tellraw @a ["",{"text":"[Welcome] ","color":"aqua","bold":true},{"text":"Hello, "},{"selector":"@p"},{"text":"! Glad you're here."}]

Look at that line closely. It’s a lot of this chapter at once. The list starts with "" (an empty string as the root, so nothing inherits an accidental color), then a bold aqua tag, then plain text, then a selector that fills in the nearest player’s name, then more plain text.

Step 3 — make it clickable. Finally, a single component carrying both a click_event (which runs give @s diamond) and a hover_event (which shows a tooltip):

/tellraw @a {"text":"[Click here for a free diamond]","color":"green","underlined":true,"click_event":{"action":"run_command","command":"give @s diamond"},"hover_event":{"action":"show_text","value":{"text":"Yes, really — click it!","color":"yellow"}}}

You should see the green underlined line appear; hovering it shows the yellow tooltip, and clicking it hands you a diamond.

Figure (to be captured). the gold “Welcome!” title with gray italic subtitle on screen, and the colored clickable chat lines below; mouse hovering the green line shows the yellow tooltip

Modern Minecraft Right now you’re typing each of these lines by hand, which is the fastest way to see what every field does. Later you’ll save a sequence like this so it fires on its own: in a command block inside the world (Chapter 6), or as a function in a data pack (Part III) that can run the whole greeting the moment the pack loads. For now, the chat box is where you experiment.

Practice

1. Recolor the tag. Change the [Welcome] tag in the chat line to a custom hex color of your choice (for example "#FF55AA"). Type the line again to see it.

2. Add a help button. Send a /tellraw line that’s a clickable [Help] button. Use suggest_command (not run_command) so that clicking it fills in a command in the player’s chat instead of running it (for example suggesting /time set day). Give it a hover_event with show_text explaining what it does.

3. An action-bar status. Send a /title @a actionbar {...} line that prints a short status message just above the hotbar in a color of your choice. Notice how the action bar behaves differently from the big center title.

4. A translated word. Send a /tellraw that uses {"translate":"item.minecraft.diamond"} somewhere in a sentence (inside a list with other text), and confirm it shows the item’s name.

Try It! Combine this with Chapter 4’s /execute: type /execute as @a run tellraw @s {"text":"Hi!"} so the message runs once per player, with each player’s own name available to a selector inside. Think about why running it as each player changes what @s and @p mean.

What Can Go Wrong

• You wrote clickEvent / hoverEvent and nothing happens. This is the single most common text-component mistake today, because so many older tutorials use the camelCase spelling. Current Java Edition needs the snake_case click_event and hover_event, with an underscore. Same for the action names (run_command, show_text, and so on). Fix the spelling and the click comes back to life.

• The command reports a red JSON error. Text components are written in the JSON-like format you’ll meet properly in Chapter 8, and the same rules apply: every { needs a matching }, every [ a matching ], strings need their quotes, and there are no trailing commas after the last field. A long /tellraw line is easy to miscount, so type it carefully. The red feedback message points at roughly where the parser got confused.

• /tellraw says it can’t find players, or refuses your selector. /tellraw and /title only target players. A selector like @e (all entities) or one that resolves to a mob will be rejected, so use @a, @p, @s (when run by a player), or @r. If no players match, the command simply has no one to message.

• Your subtitle never shows. A subtitle only appears with a title. If you set subtitle but never send a title afterward, there’s nothing for it to ride along with. Set the subtitle first, then the title. The order in the walkthrough does this on purpose.

What You Know Now

You can build a text component: color it (named colors or #hex), style it (bold, italic, underlined, strikethrough, obfuscated), nest pieces as children that inherit formatting, and fill in dynamic content with translate, selector, and (previewed) score and nbt. You can make text interactive with click_event and hover_event, and you know they’re snake_case, unlike the old camelCase tutorials. You can send a component to chat with /tellraw and put big text on screen with /title (title, subtitle, action bar, and times), and you’ve typed out a styled, clickable welcome message of your own. Next chapter you’ll move commands off your keyboard and into the world with command blocks, so a button press can fire a message like this for you. (And later, in Chapter 11, scoreboards will make that score field come alive.)

Chapter 6 — Command Blocks

What You’ll Build

In the last five chapters every command you ran vanished the moment it finished. You typed it, pressed Enter, watched it work, and if you wanted it again you typed it again. At the end of Chapter 1 you felt the itch: “I wish I could run all of these at once.” This chapter scratches the first half of that itch by moving a command off your keyboard and into the world, where a button press, a lever, or a trail of redstone runs it for you.

The tool is the command block: a special block that holds a command and runs it when redstone powers it. By the end of this chapter you’ll hand yourself a command block, type a command into it, and trigger it with a button. Then you’ll line several command blocks up so a single button press fires a whole sequence in order, turning that ten-line “set up my test area” routine from Chapter 1 into one press of one button. Along the way you’ll meet the three kinds of command block and the switches that change how each one behaves. And at the end you’ll bump into the wall that command blocks can’t get past, which is exactly the wall the rest of the book is built to knock down.

Everything here happens in your Creative test world with cheats on, the same world you’ve used since Chapter 1.

Concepts

A command block is an indestructible block that runs a command when it’s activated by redstone. You can’t craft one, mine one, or use one in Survival without cheats, so it isn’t a normal building block. It’s a tool for Creative worlds, servers, and custom maps. Think of it as a command you’ve written down and nailed to a spot in the world, ready to fire whenever it gets a redstone nudge.

There are three kinds, and the game colors them so you can tell them apart at a glance:

• An impulse command block (orange) runs its command once each time it’s activated. This is the default, and the one you’ll use most.
• A repeating command block (purple) runs its command every game tick (20 times a second) for as long as it stays activated.
• A chain command block (cyan) runs its command when the command block pointing into it runs. It’s the link you use to join blocks into a sequence.

Under the Hood (skippable) A command block always runs at permission level 2, the operator level. That’s genuinely useful on a server: you can offer players a button that runs a /give they’d never be allowed to type themselves, without handing them operator powers. You don’t need this yet; it’s just why command blocks are considered an “operator” tool.

Getting a command block

You can’t find a command block in the normal Creative menu unless you switch it on, so the quickest way is the /give command you already know from Chapter 1. Open the chat box and type:

/give @s command_block

A command block drops into your inventory. Place it like any other block. (You can only place and break command blocks while you’re an operator in Creative mode, which in your test world you are.)

To put a command inside it, point at the block and use it (right-click) to open the command block GUI, the little editing screen. Type your command into the top box. One nice difference from the chat box: inside a command block the leading slash is optional, so give @s diamond and /give @s diamond both work. Press Tab to autocomplete as you type, then click Done (or press Enter) to save and close. The bottom box, Previous Output, will show the result the next time the block runs, which is handy for spotting a mistake.

What Went Wrong? “Right-clicking the block does nothing / I can’t open it.” The command block GUI only opens for an operator in Creative mode with cheats on. If you’re in Survival or cheats are off, you’ll just place a block you can’t edit. Make sure you’re in your Creative test world.

Triggering it with redstone

A command block sitting there does nothing on its own. It needs to be activated by redstone power. The simplest power source is a button or a lever stuck to the block, but anything that delivers redstone power works: a lever, a button, a block of redstone, a pressure plate, or redstone dust pointing at it.

Let’s build the kit button you’ve been wanting. Place a command block, open it, and enter:

give @s diamond_sword

Click Done. Now stick a button on the side of the block (place the button against it) and press the button. A diamond sword lands in your inventory, and it will do so every single time you press, without you ever opening the chat box again. You’ve just built your first machine.

Try It! Put a stone button on the front of the block and label the contraption in your head: “sword dispenser.” Press it five times and watch five swords appear. That repeatability is the whole point of a command block: type the command once, run it forever. Figure (to be captured). a command block with a stone button on its front face, and a diamond sword in the player’s hotbar after pressing

The three switches inside a command block

Open the command block GUI again and look at the row of buttons. Three of them change how the block behaves, and they map onto the three types and a couple of options:

• Block Type cycles Impulse → Chain → Repeat. Impulse runs once per activation; Repeat runs every tick while powered; Chain runs only when triggered by a block aimed into it. The block changes color (orange, purple, cyan) so you can read a build at a glance.
• Redstone switches between Needs Redstone and Always Active. “Needs Redstone” (the default for impulse and repeat blocks) means the block only runs when something powers it. “Always Active” means it runs without any redstone at all, which is the normal setting for chain blocks.
• Condition switches between Unconditional and Conditional. An unconditional block (the default) always runs. A conditional block runs its command only if the command block behind it ran successfully, which lets you build “do this only if that worked” logic.

A repeating command block is worth a quick experiment: set one to Repeat, give it effect give @a minecraft:night_vision 2 0 true, and power it with a lever. Flip the lever on and everyone has permanent night vision, refreshed every tick; flip it off and it fades. That “keep doing this while powered” behavior is what Repeat is for.

What Went Wrong? “I pressed the button and nothing happened.” Three things to check. First, the block needs redstone power actually touching it (a button on the block, a lever beside it). Second, an impulse block fires once per activation, so if the button’s already been pressed and reset, press it again. Third, on a server or in a stubborn world, confirm the command_blocks_work game rule is on (it’s on by default).

Chaining: one button, a whole sequence

Now the second half of Chapter 1’s wish: running many commands from a single press. This is what chain command blocks are for. The rule is simple: when a command block runs, it triggers the chain command block it’s pointing at, which runs and triggers the next one, and so on down the line, all in the same tick and in order.

Here’s how to rebuild Chapter 1’s “set up my test area” as one button:

1. Place an impulse command block. This is the trigger. Give it the first command: say Setting up the test area...
2. In a straight line, place more command blocks so each one faces into the next (place each new block by aiming at the previous one). Set every block after the first to Chain type and Always Active.
3. Fill the chain blocks with the rest of the sequence, one command each: give @s diamond_sword, then give @s diamond_pickaxe, then give @s bread 16, then summon cow, then summon pig, then summon zombie, and finally say Test area ready!.
4. Put a button on the first (impulse) block and press it.

The impulse block fires, triggers the first chain block, which triggers the next, straight down the line. One press, and your kit, your mobs, and both messages all happen at once. That ten-line routine you used to type by hand is now a single button.

Figure (to be captured). a row of command blocks — one orange impulse block with a button, followed by several cyan chain blocks all facing the same direction — with a freshly spawned cow, pig, and zombie nearby

What Went Wrong? “Only the first block ran.” The follower blocks must be set to Chain type and they must physically point into one another. A chain block also needs to be Always Active (or powered) to fire. If one block in the middle is still an orange impulse block, the chain breaks there. Walk the line and check each block’s type and the direction it faces.

The wall command blocks hit

Command blocks are brilliant for a contraption in one spot: a trap, a teleport pad, a kit button. But try to build something big with them and the cracks show. The commands are buried inside blocks scattered around your world, so finding the one with the typo means hunting through your build. They don’t travel: there’s no way to hand a friend “my command blocks” as a download the way you’d share a map or a mod. And a real project can need hundreds of commands, which becomes an unmanageable forest of blocks you can’t search, copy, or keep tidy.

What you really want is to write your commands as files: organized in folders, editable in a text editor, searchable, shareable as a single download, and not physically jammed into the world. Minecraft has exactly that system, and it’s where this book is headed next. It’s called a data pack, and the moment you meet it in Part III, every command you’ve learned to type becomes something you can save, name, and run by the dozen.

What Can Go Wrong

• The block won’t open or won’t place. Command blocks are operator tools: you need Creative mode with cheats on. In Survival, or with cheats off, you can’t edit or break them.
• Pressing the trigger does nothing. The block needs redstone power reaching it, and an impulse block fires once per activation (press the button again). On servers, the command_blocks_work game rule must be on (it is by default).
• A chain stops partway. Every follower block must be set to Chain type, must be Always Active (or powered), and must point into the next block. One impulse block or one wrong-facing block in the middle breaks the rest of the line.
• I can’t tell why a command failed. Open the block and read the Previous Output box at the bottom; it shows the result of the last run, the same success-or-red-failure idea you learned reading feedback in Chapter 1.

What You Know Now

You can hand yourself a command block with /give @s command_block, type a command into its GUI, and fire it with a button or lever, turning a command you used to retype into a machine you press. You know the three types and their colors: impulse (orange, once), repeating (purple, every tick), and chain (cyan, triggered in sequence), plus the Redstone and Condition switches that tune them. You can chain blocks so one button runs a whole routine in order, which finally grants Chapter 1’s wish to “run all of these at once.” And you’ve seen the ceiling: command blocks live buried in the world, can’t be shared, and don’t scale. Next, in Chapter 7, you’ll start climbing past that ceiling by learning what Minecraft is really doing under the hood, on your way to writing commands as files you can save and share.

Chapter 7 — How Minecraft Really Works

What You’ll Understand

Chapter 6 left you at a wall. You can type commands, aim them, and even bottle them into command blocks, but those blocks stay buried in the world, can’t be handed to a friend as a download, and fall apart once a project needs hundreds of them. The question you walked away with was simple: how do I make the commands I’ve been typing permanent and shareable? This chapter answers it, but not with a button or a block. It answers it with an idea, the one the rest of this book rests on: Minecraft builds its world by reading data files, and a data pack is how you hand it your own.

You won’t build anything in this chapter, and you won’t even open a single file yet. Once this idea clicks, though, everything ahead (recipes, custom items, new enchantments, whole dimensions) stops feeling like magic and starts feeling like filling in forms the game already knows how to read. By the end you’ll be able to explain, in your own words, what people mean when they call Minecraft “data-driven,” what a registry is, why folks say “vanilla is just a data pack,” and why this book teaches Java Edition.

What happens when you launch a world

Click Create New World, wait a moment, and you drop into a fresh landscape. It feels like the game invented that world on the spot, and in a way it did. A world (the game also calls it a level) is a single Minecraft “universe” that holds all the blocks and entities across each of its dimensions: the Overworld, the Nether, and the End. (Entities are mobs, dropped items, and other moving things.) Its terrain is procedurally generated, built automatically by the game from a set of rules rather than drawn by hand.

Once the world exists, the game has to keep it running. Nearly every video game, Minecraft included, is driven by one big repeating loop, and one trip around that loop is called a tick. Minecraft normally runs at a steady 20 ticks per second, one tick every 0.05 seconds, and almost everything that happens (a furnace smelting, a creeper stepping toward you, day turning to night) is scheduled by counting ticks. An in-game day is exactly 24,000 ticks, which works out to 20 real minutes.

So a world is really two things stacked together: a big pile of definitions (what a creeper is, what a furnace does, what an oak tree looks like) and a clock (the tick) that makes those definitions come alive, moment by moment. The interesting question, the one this whole book answers, is where those definitions come from. That’s the next section.

Minecraft is data-driven

Here’s the part most players never find out: Minecraft does not have “creeper-ness” or “the recipe for a torch” baked permanently into a locked black box. A huge amount of what makes the game the game is stored as plain data, separate files describing each feature, that Minecraft reads when it loads. That’s what people mean when they say Minecraft is data-driven: its behavior is driven by data files, not hand-wired into the program.

How much is stored this way? A lot. The game’s own machinery for this is the data pack, and a single data pack can configure advancements, dimensions, enchantments, loot tables (the lists that decide what a chest or a defeated mob drops), recipes, structures, biomes, and more. Each of those is just data describing “here is what this thing is and how it behaves.”

Modern Minecraft If you follow older tutorials online, you may see data packs treated as an exotic add-on for experts. That’s out of date. In current Minecraft, core systems like enchantments are themselves defined as data you can add to or replace: enchantments live in the game’s data right alongside recipes and loot. Thinking of Minecraft as “a program that reads data” isn’t a clever trick anymore; it’s just how the game is built.

The payoff of a data-driven game is huge for you, and it’s the answer to the wall you hit in Chapter 6. If the game reads its content instead of hard-coding it, then anywhere the game reads a file, you can supply a file, and the game will treat yours exactly as seriously as its own. That’s the escape from buried command blocks: instead of nailing a command into a spot in the world, you write it into a file you can name, search, copy, and hand to a friend. You don’t need to crack open Minecraft’s program. You just need to learn the shape of the data it already expects. That’s the entire skill this book teaches.

Registries: the master lists of everything

If Minecraft reads its content from data, it needs an organized way to keep track of it all: a set of master lists. Those master lists are called registries. A registry is a catalog of one kind of game thing, where every entry has a name the game can look up.

Minecraft has a registry for blocks, a registry for items, a registry for entity types (the kinds of mobs and other moving things), a registry for enchantments, a registry for biomes, and many more. They’re even organized neatly: there’s a single root registry, named minecraft:root, and every other registry is registered inside it. It’s a master list of master lists.

Most registries are meant only for the game’s own internal use. But some, called dynamic registries, are open: content can be added to them through data packs. That openness is what this whole book runs on. The features you’ll spend your time with (recipes, loot tables, enchantments, dimensions, biomes, and more) are exactly the ones the game lets you supply through a data pack. A few of them, like enchantments, biomes, and dimensions, are those open dynamic registries; others, like recipes and loot tables, are simply files the game reads straight out of your pack. Either way, the door is open. When you make a recipe later, you aren’t sneaking something past Minecraft. You’re handing it a file it was always willing to read.

Under the Hood (skippable) Why “registry” and not just “list”? Because a registry does more than hold things. It hands each entry a stable name so the rest of the game can refer to it without confusion. When a command, a recipe, or another data pack needs to point at “the diamond item” or “the plains biome,” it uses that registered name. We’ll meet those names, and the rules for writing them, properly in Chapter 8.

“Vanilla is just a data pack”

Now the sentence that surprises people. The plain, unmodified game, what players call vanilla Minecraft, defines its own features using a built-in data pack. The recipes you craft with, the loot in naturally generated chests, the biomes you explore: a big chunk of that is supplied by a data pack that ships inside the game, read the same way any data pack is read.

Sit with that for a second, because it changes how you should think about everything ahead. Minecraft doesn’t have a special privileged way of defining its content and a second-class hobby way of defining yours. There is just one system. The game reads the vanilla data pack to set itself up, and it reads your data packs the same way, through the same doors, into the same registries.

That’s genuinely good news for a beginner. The “real” way Mojang adds a recipe and the way you’ll add a recipe in Chapter 9 are the same way. What you learn here is how Minecraft actually works, and you’ll be using the real thing yourself.

Java Edition vs. Bedrock Edition (and why this book uses Java)

Before we go further, one fork in the road. Minecraft comes in two main versions, and they are not the same software under the hood.

Java Edition is the original version, first released back in 2009, and it runs on Windows, macOS, and Linux. Its name comes from the Java programming language it’s written in. Crucially for us, Java Edition’s code is the more open and modifiable of the two: it has by far the most established community of mods and custom servers, and the code itself isn’t scrambled to hide it, so people have documented it thoroughly.

Bedrock Edition is the multi-platform version, the one on phones, tablets, consoles, and the Windows “Minecraft for Windows” app. It’s built on a different codebase written in the C++ programming language so it can run on all those devices, and it has its own official add-on system for custom content.

Both editions can be customized, but they customize differently: different file formats, different folders, different rules. A book that tried to teach both at once would have to say “but on the other edition…” in every paragraph, and you’d learn neither well. So this book teaches Java Edition data packs. When you read “Minecraft” from here on, picture Java Edition unless we say otherwise.

Try It! Open Minecraft: Java Edition and start creating a new world. On the More tab of the Create New World screen there’s a Data Packs button. Click it. You’ll see the world already lists data packs available to it, with a place to drop your own in later. You don’t need to add anything yet; just notice that the door is right there, built into the menu. Figure (to be captured). Create New World → More tab → Data Packs screen, with the built-in pack listed

What a data pack actually is (plain English)

We’ve used the words “data pack” a lot. Time to pin them down, in plain language, with no file details yet (those come in Chapter 9).

A data pack is a collection of data that configures features of Minecraft. Physically, it’s nothing fancier than a folder (or a .zip file) that contains a special marker file telling the game “this folder is a data pack.” Drop that folder into a world’s data-pack location and the game will read it, layering your definitions on top of the vanilla ones, adding new features or modifying existing ones.

It helps to know what a data pack is not. Minecraft has a sibling system called a resource pack, and the two are easy to mix up. A resource pack changes how the game looks and sounds (textures, models, music, sound effects, fonts) without changing any behavior. A data pack changes what the game does: its rules, its content, its logic. The slogan to remember: resource packs change appearance; data packs change behavior. Many finished creations use both together (a custom sword needs a data pack to exist and a resource pack to look unique), and we’ll cover resource packs later in the book. But data packs are our main event, because data packs are where you change what Minecraft is.

And that’s the whole foundation. Minecraft reads its content from data; that data is organized into registries; the vanilla game is itself a data pack feeding those registries; and a data pack is just a folder of files you add to the very same system. Everything from here is learning the shapes of those files. The next chapter starts with the language they’re written in.

What Can Go Wrong

This chapter has no files to break, but two misunderstandings trip people up before they even start. Clear them up now:

• “I’ll need to hack or re-program Minecraft.” No. You never touch Minecraft’s program. You add data files to a system that is designed to read added data files. If you ever feel like you’re fighting the game, you’ve probably wandered off the data-pack path. Step back onto it.
• “My phone/console Minecraft will work the same as this book.” It won’t. That’s Bedrock Edition, which uses a different add-on system. To follow along, you need Minecraft: Java Edition on a Windows, macOS, or Linux computer.

What You Know Now (so far)

You can explain that Minecraft is data-driven (it reads its content from data files), that registries are the master lists that content lives in, that vanilla itself is a built-in data pack, and that a data pack is a folder of files you add to that same system, and you know this book is about Java Edition. Next chapter, you’ll set up a workshop and learn JSON, the simple language every one of those files is written in.

Chapter 8 — Setting Up and Learning the Language

What You’ll Build

In Chapter 7 you learned why Minecraft is the way it is: a data-driven game whose blocks, items, recipes, and worlds are all described in data files the game reads. So far you’ve made the game do things by typing commands; now you start making those things files. In this chapter you set up the tools to write those files, and you learn the two “languages” every file in this book is written in.

By the end you will have a real workshop: a plain-text code editor installed on your computer, ready for the data pack you build in Chapter 9. (You already have the other half of the workshop: the Creative test world with cheats you’ve been using since Chapter 1.) You’ll also be able to read and write JSON (the format every data-pack file uses) and read identifiers, the namespaced names like minecraft:stone that Minecraft uses to label everything. You won’t build a data pack yet (that’s the next chapter), but you’ll be able to hand-write a valid JSON file, spot the small mistakes that break one, and name your own things the way Minecraft expects.

Concepts

Plain-text editor. A plain-text editor is a program that saves exactly the characters you type and nothing else: no fonts, no bold, no hidden formatting. Data-pack files are plain text, so you need a plain-text editor to write them. Word processors like Microsoft Word or Google Docs are the wrong tool: they add invisible formatting and like to “helpfully” change your straight quotes " into curly quotes ”, which Minecraft cannot read. This is general computer advice, not a Minecraft rule, but it matters: write your files in a code editor, never in a word processor.

Test world. A test world is a throwaway world you use only for trying out data packs: the Creative-with-cheats world you’ve been using since Chapter 1. Cheats are what let you type commands like /reload, and keeping a separate test world means a broken experiment never touches a world you care about. That’s the world we’ll use here.

JSON. JSON (JavaScript Object Notation) is a lightweight, plain-text way of writing structured data as key-value pairs and lists. Minecraft uses JSON to store many things: the pack.mcmeta file that marks a data pack, and the data-pack files that define advancements, loot tables, tags, recipes, and predicates, among others. If you can read and write JSON, you can read and write data packs.

Identifier. An identifier (also called a resource location or namespaced ID) is a name in the form namespace:path that points to one specific game object (a block, an item, a function, and so on) with no ambiguity. minecraft:stone is the identifier for stone. The namespace is the part before the colon; the path is the part after it.

/reload. The /reload command re-reads the data packs in your world so your latest edits take effect without you leaving and rejoining. It will be the button you press all book long: edit a file, save it, run /reload, see the change. (You’ll learn in Chapter 9 exactly what it reloads.)

Walkthrough

Step 1 — Install a code editor

You need one plain-text code editor. This book recommends Visual Studio Code (usually just called VS Code), a free editor from Microsoft. To get it, open your web browser, search for “Visual Studio Code,” download it from the official site (code.visualstudio.com), and run the installer the normal way for your operating system. If you’d rather use something lighter on Windows, Notepad++ is a fine alternative: same idea, smaller program. Either one works for everything in this book; the listings look the same whichever you pick.

These download-and-install steps are ordinary computer steps, not Minecraft features, so they may look a little different depending on your computer and the year. Follow the official site’s instructions if anything has moved.

Try It! In VS Code you can install extensions (small add-ons). Search its Extensions panel for a JSON or Minecraft data-pack extension and install one. A good one will underline broken JSON in red as you type, which catches the mistakes in the “What Can Go Wrong” section before the game ever sees them. Extensions are optional; everything in this book works without them.

Step 2 — Confirm Your Test World Is Ready

You’ve been using a Creative test world with cheats since Chapter 1, and that’s the one we’ll use, so there’s no new world to make. Just load it and check one thing: that /reload is available, because that’s the command you’ll lean on all book long. Open the chat (press T or /), type the reload command, and press Enter:

/reload

Right now you have no data packs of your own, so nothing visible happens, but the command runs without an error, which tells you cheats are on and /reload is available. The /reload command re-reads the current data packs; if a pack has invalid data (such as a broken recipe), the game keeps the previous working version instead of applying the broken one. That safety net is why you can edit boldly: a typo won’t corrupt your world, it just won’t load until you fix it.

Modern Minecraft Some data-pack features can’t be refreshed with /reload alone. A handful of “dynamic” things (Minecraft calls them experimental settings, and they include features like custom dimensions and enchantments) only update when you leave the world and rejoin. Most of what you build early on (functions, recipes, loot tables, tags, advancements, predicates) does reload instantly. You met this distinction in Chapter 7; we’ll point it out again when it matters.

Step 3 — Learn JSON by writing a file

JSON is built from a few simple pieces. Make a scratch folder somewhere easy to find (your Desktop is fine) called json-practice, and create a new file in it. Let’s build that file up one piece at a time, then look at the finished version.

Values. A JSON file holds a single value. A value can be one of these basic types:

• A string: text wrapped in straight double quotes: "hello", "Hello, world". If you need a double quote inside the text, you escape it with a backslash: "An escaped \" quote".
• A number, written plainly: 2, -0.5. Numbers can have a decimal point and don’t use quotes.
• A boolean: exactly true or false (no quotes).
• An object, a labeled box (below).
• An array, an ordered list (below).

Objects { }. An object is a collection of key-value pairs wrapped in curly brackets. Each pair is a key (a name, in quotes) and a value, joined by a colon; pairs are separated by commas. Every key in one object must be unique. A value can itself be any type, including another object, which is how JSON nests. Here’s the example straight from how Minecraft documents it:

{
  "Bob": {
    "ID": 1234,
    "lastName": "Ramsay"
  },
  "Alice": {
    "ID": 2345,
    "lastName": "Berg"
  }
}

Read it as: an object with two keys, "Bob" and "Alice". Each of their values is another object with an "ID" (a number) and a "lastName" (a string). Objects inside objects: that’s nesting.

Arrays [ ]. An array is an ordered list of values wrapped in square brackets, separated by commas:

["Bob", "Alice", "Carlos", "Eve"]

The values in a JSON array can even be of different types if you want: a number next to a string next to a boolean is allowed.

Now put it together. Here is a complete, valid practice file using every piece: a string, a number, a boolean, a nested object, and an array:

Desktop/json-practice/my_first.json

{
  "name": "My First File",
  "version": 1,
  "finished": false,
  "author": {
    "id": 1234,
    "tools": ["vscode", "minecraft"]
  }
}

Type that in, then save it. If your editor (or its JSON extension) shows no red underlines, the file is valid JSON. Notice the shape: the whole file is one object { }; "author" is a nested object; and "tools" is an array of two strings. Indentation and line breaks are only there to make it readable (JSON doesn’t require them), but they make a long file far easier to follow, so use them.

Under the Hood (skippable) The five value types you’ll use in data packs are string, number, object, array, and boolean; those are the ones worth learning now. Some real data-pack files also use the empty value null to mean “nothing here,” but it’s rare enough that we won’t lean on it yet; you’ll meet null in a later chapter where a real file actually uses it.

Step 4 — Read identifiers and namespaces

Open your test world’s chat and start typing one of the commands you’ve used since Chapter 1, like /give, and the autocomplete shows names like minecraft:diamond and minecraft:stone. Each of those is an identifier: a namespace:path name. In minecraft:stone, the namespace is minecraft and the path is stone.

Why the namespace exists. A namespace is a labeled grouping that keeps two packs’ names from clashing. Imagine two data packs each add a function called start. Without namespaces those two start functions would collide and break. Give them different namespaces, say minigame_one and minigame_two, and they become minigame_one:start and minigame_two:start, which can’t conflict. This is exactly why your data pack will get its own namespace in Chapter 9.

The minecraft: default. Minecraft reserves the minecraft namespace for the vanilla game. In Java Edition, if you write a name with no colon, the game fills in minecraft for you, so stone and minecraft:stone mean the same thing. Because of that, you should only put your files in the minecraft namespace when you specifically want to add to or change vanilla (for example, adding your function to the built-in minecraft:load group, a Chapter 9 topic). For your own content, use your own namespace.

Naming rules (this is a real Minecraft rule, so follow it exactly). In Java Edition, both the namespace and the path may only contain these characters:

• lowercase letters a–z
• digits 0–9
• underscore _
• hyphen -
• dot .

The forward slash / is allowed in a path (it makes sub-folders) but not in a namespace. No capital letters, no spaces, no other symbols. The preferred style is snake_case: lowercase words joined by underscores, like my_cool_pack. So mypack:magic_sword is a good identifier; MyPack:Magic Sword is not (capital letters and a space are both illegal).

Pick a good namespace. When you choose your own namespace, make it specific. Don’t use vague “alphabet soup” like nc or an over-broad word like battle_royale; a more descriptive name (your project’s name, or your name plus the project) is easier to find and debug when several packs are loaded at once. In this book the reader’s namespace is always mypack: short, lowercase, and clearly not vanilla.

Modern Minecraft You may see identifiers written without a namespace in old tutorials, like just diamond. That still works in Java Edition because the game assumes minecraft:, but it’s recommended to always write the colon form. Being explicit (minecraft:diamond) makes it obvious which namespace you mean and avoids surprises.

Practice

1. Write and validate a JSON file. In your json-practice folder, make a new file called pet.json. Inside one object, give it: a "name" string, an "age" number, an "adopted" boolean, and a "favorite_foods" array of two or three strings. Save it. If your editor shows no errors, you wrote valid JSON. (If it does show an error, jump to “What Can Go Wrong.”)

2. Break it on purpose, then fix it. Add a comma after the last item in your array and save. Watch your editor flag it. Remove the comma to fix it. Getting comfortable making and fixing errors now will pay off in every later chapter.

3. Spot identifiers in-game. In your test world, press F3 + H together. This turns on “Advanced Tooltips,” so when you hover over any item in your inventory you’ll see its identifier (its namespace:path name) printed under it. Hover over five different items and write down their identifiers. Notice they’re all in the minecraft namespace and all use lowercase snake_case, the same rules you’ll follow for your own names.

Try It! Look closely at the identifiers you collected. Which part is the namespace and which is the path? Can you find an item whose path uses an underscore, like minecraft:iron_ingot? That’s snake_case in the wild.

What Can Go Wrong

A trailing comma. JSON separates items with commas between them, but the last item in an object or array must not be followed by a comma. This is the single most common JSON mistake.

Broken:

{
  "name": "Steve",
  "level": 5,
}

Fixed (the comma after 5 is gone):

{
  "name": "Steve",
  "level": 5
}

A missing or wrong quote. Every key, and every string value, must be wrapped in straight double quotes ". Forgetting one, or letting a word processor turn a straight quote into a curly ”, breaks the file.

Broken:

{ "name": Steve }

Fixed (the string value is now quoted):

{ "name": "Steve" }

A capital letter or space in a name. Identifiers must be lowercase with no spaces. MyPack:Cool Sword is invalid on two counts: the capital letters and the space. Write it as mypack:cool_sword instead. If a data pack later “can’t find” something you named, check first for a stray capital, space, or typo in the identifier.

What You Know Now

You finished setting up your workshop (a plain-text code editor alongside the cheats-on Creative test world you’ve had since Chapter 1) and learned the two languages the rest of the book is written in. You can hand-write a valid JSON file out of objects, arrays, strings, numbers, and booleans; nest one inside another; and spot the trailing-comma, missing-quote, and bad-name mistakes that break a file. You can read an identifier as a namespace:path name, you know minecraft: is the default namespace, and you know the lowercase snake_case naming rules you’ll use for your own mypack content. You can now build your first real data pack: that’s Chapter 9.

Chapter 9 — Building Your First Data Pack

What You’ll Build

Back in Chapter 6 you hit the wall: command blocks run your commands, but they’re buried in the world, can’t be shared as a download, and don’t scale. The answer is a function: the commands you’ve been typing since Chapter 1, saved in a file the game runs for you, no leading slash required. In Chapter 7 you learned that Minecraft is data-driven: the game reads files to decide what blocks, items, and recipes exist. In Chapter 8 you set up your editor and learned to read JSON and write identifiers like mypack:greeting. Now you put it all together in your Creative test world from Chapter 1.

By the end of this chapter you will have a real, working data pack. It will live inside your test world, it will announce itself in chat every time the world loads, and it will add a brand-new crafting recipe: a chainmail helmet you can craft from nine iron nuggets, which the game has never let you do before. You will turn the pack on, reload it, watch it greet you, and craft your helmet. And because things will break the first few times, you’ll also learn where Minecraft writes down what went wrong, so you can read the message and fix it yourself.

This is the pack you build the rest of the book on top of. Every later chapter adds files to this pack, the one you make right now. We’ll call it mypack from here on.

Concepts

A data pack is a folder (or a .zip file) full of data that configures features of Minecraft: things like advancements, recipes, loot tables, functions, and more. The vanilla game’s own features are defined by a built-in data pack, so when you make one, you’re doing exactly what Minecraft does to itself. (You learned this idea in Chapter 7; now you’ll build one.)

Three new things show up in this chapter:

• pack.mcmeta: a small text file, written in JSON, whose presence is what tells Minecraft “this folder is a data pack.” Without it, the game ignores your folder entirely. It also holds the pack’s version info and a description.
• A function: a plain-text file ending in .mcfunction that holds a list of commands, one per line. Running the function runs all those commands in order. This is how you tell the game to do something.
• A recipe: a JSON file that defines a new way to transform items, like a crafting recipe. This is how you tell the game what a new thing is.

You’ll also meet the minecraft:load function tag, a built-in list the game checks on startup. Any function whose name you add to that list runs automatically when the world loads or reloads. That’s how your greeting will fire on its own.

The Folder Hierarchy

A data pack has a strict shape. Get the folder names right and the game finds everything; get one wrong and the game silently skips it. Here’s the whole tree you’re about to build. Don’t type it yet, just look at the shape:

mypack/
├── pack.mcmeta
└── data/
    ├── mypack/
    │   ├── function/
    │   │   └── load.mcfunction
    │   └── recipe/
    │       └── chainmail_helmet.json
    └── minecraft/
        └── tags/
            └── function/
                └── load.json

Three rules explain that entire picture:

1. pack.mcmeta sits at the very top, right next to (not inside) the data folder. It is the only mandatory file: it’s what makes the folder a data pack at all.
2. Everything else lives under data/, sorted into namespace folders. A namespace (from Chapter 8, the part before the colon in namespace:path) keeps your files from colliding with anyone else’s. Your namespace is mypack, so most of your files go under data/mypack/. The special minecraft namespace is for files that hook into or override vanilla, which is why the load tag lives under data/minecraft/.
3. Inside a namespace, each kind of file gets its own folder named after the registry it belongs to. Functions go in function/. Recipes go in recipe/. The game loads the file data/<namespace>/<registry name>/<path>.json as the thing named <namespace>:<path>. So data/mypack/recipe/chainmail_helmet.json becomes the recipe mypack:chainmail_helmet.

Modern Minecraft Some older tutorials show folder names with an s: functions, recipes, advancements. Current Java Edition uses the singular form: function, recipe, advancement. If you copy an old tutorial and your files don’t load, a stray s on a folder name is a very common reason. The folder list in this book is the current one.

Writing pack.mcmeta

Create a folder named mypack somewhere easy to find, then make a file inside it called exactly pack.mcmeta. Type this into it:

mypack/pack.mcmeta

{
  "pack": {
    "description": "My first data pack",
    "min_format": 88,
    "max_format": 88
  }
}

Here’s what each field means:

• description is a text component (you met those in Chapter 5). For now, a plain string in quotes is fine. This is the text that appears next to your pack’s name on the Data Packs screen and in the output of the /datapack list command.
• min_format and max_format describe the range of pack versions your pack is built for. Each is a single number (or, if you ever need to be precise, a [major, minor] pair). The game compares these numbers against its own to decide whether your pack fits. min_format is the lowest version you support, and max_format is the highest.

Why 88? The pack format is a number that changes when Minecraft changes how it reads data-pack files. For Minecraft 1.21.9 and newer, the recommended pack.mcmeta uses min_format: 88 and max_format: 88, so 88 is the known-good current value this book uses throughout.

Don’t memorize a number for any one version, though. The pack format changes over time, and the surest value is the one your copy of Minecraft expects. To read it, run the /version command in-game, or press F3 + V. If the number you get is different from 88, use that number for both min_format and max_format.

Modern Minecraft You will see a LOT of older tutorials use a single field called pack_format instead, like "pack_format": 48. That field still works for backward compatibility, but since the snapshot 25w31a it was replaced by the min_format / max_format pair. There’s also a related legacy field called supported_formats. You only need pack_format or supported_formats if you’re trying to support game versions older than the new scheme, and they must be left out for a pack that only targets new versions. For everything in this book, use min_format / max_format and ignore the old field. (Chapter 46 covers the legacy fields in detail, for the day you need them.)

Under the Hood (skippable) The pack.mcmeta file can hold more than this: sections for experimental features, file filters, and overlays that swap in different files for different game versions. None of that matters yet: a description and a version range is a complete, valid data pack. We come back to the rest in Chapter 46.

Where the pack lives

A data pack belongs inside a world, in that world’s datapacks folder. The full path is your .minecraft/saves/<your world>/datapacks/ folder. Move your whole mypack folder into the datapacks folder of your test world (the Creative, cheats-on world you’ve used since Chapter 1).

To find that folder quickly: open Minecraft, go to Singleplayer, select your test world, click Edit, then Open World Folder. Inside is a folder called datapacks; drop mypack in there. When you’re done it should look like:

<your test world>/
└── datapacks/
    └── mypack/
        ├── pack.mcmeta
        └── data/
            └── ...

Try It! You can also add a data pack while creating a new world: on the Create New World screen, open the More tab and click Data Packs, then drag your pack’s folder into the window. Either way works; the datapacks folder is just where the game keeps them.

At this point you have a valid (if empty) data pack. The game will recognize it. But it doesn’t do anything yet. Let’s fix that.

Your First Function

A function is a text file ending in .mcfunction that contains a list of commands (one command per line) which run top to bottom when the function is called. There are two rules about writing them that trip up everyone at first:

• No leading slash. When you type a command into the chat bar you start it with /, like /say hi. Inside a .mcfunction file you write the command without the slash, just say hi. The slash is only for the chat bar.
• Lines starting with # are comments. The game ignores them. Use comments to leave notes to yourself.

Functions live in the function/ folder inside your namespace. Create the file:

mypack/data/mypack/function/load.mcfunction

# This function runs when the pack loads or reloads.
# It announces that mypack is active.
say mypack is loaded! Welcome back.

That’s a complete function. Its name, its identifier, is built from where it sits: namespace mypack, registry folder function, file load → the function mypack:load.

But right now nothing calls it. You could run it by hand by typing /function mypack:load, and it would print your message. Try that if you like. What we actually want, though, is for it to fire automatically every time the world loads.

Wiring it to minecraft:load

Minecraft keeps a built-in list called the minecraft:load function tag. Every function named in that list runs once when the world loads, when the server starts, and every time the data packs are reloaded. (There’s a sibling list, minecraft:tick, that runs functions every single tick; we’ll use that later.)

A tag is itself a small JSON file. Function tags go in the tags/function/ folder, and because we’re adding to Minecraft’s load tag, the file goes under the minecraft namespace, at data/minecraft/tags/function/load.json. Create it:

mypack/data/minecraft/tags/function/load.json

{
  "values": [
    "mypack:load"
  ]
}

The values array is just a list of function names to add to the tag. We’re adding one: mypack:load. (You’ll learn the full tag format, including the replace field and how tags from different packs merge, in Chapter 14. For now, this one-line list is all you need.)

Under the Hood (skippable) Why does adding your function name to the minecraft:load tag run it, instead of overwriting Minecraft’s own load functions? Because tag files merge by default: when several packs each add to #minecraft:load, the game combines all their lists rather than letting the last one win. That’s special to tags; most other files override each other. So your load.json quietly joins the party instead of kicking everyone else out.

What Went Wrong? One important catch: functions in minecraft:load run before any player has joined the world. That’s fine for say, which broadcasts to chat. But it means commands that need to target a player won’t find one at load time. Keep that in mind much later when you write fancier load functions. For now, say works perfectly.

Save both files. We’ll turn the pack on shortly, but first let’s add the recipe so we have something to craft.

Your First Recipe

A recipe is a JSON file that tells the game about a new item transformation. Crafting, smelting, stonecutting, and smithing are all recipes. We’re making the simplest interesting kind: a shaped crafting recipe, where the ingredients have to be placed in a specific pattern on the crafting grid.

Recipe files go in the recipe/ folder of your namespace. Create:

mypack/data/mypack/recipe/chainmail_helmet.json

{
  "type": "minecraft:crafting_shaped",
  "category": "equipment",
  "pattern": [
    "NNN",
    "N N"
  ],
  "key": {
    "N": "minecraft:iron_nugget"
  },
  "result": {
    "id": "minecraft:chainmail_helmet",
    "count": 1
  }
}

Let’s read it field by field. Every one of these is a real recipe field, copied from the recipe format:

• type says which kind of recipe this is. minecraft:crafting_shaped means “a shaped crafting-table recipe.”
• category controls which group it appears under in the recipe book. The allowed values are equipment, building, misc, and redstone; a helmet is equipment. (This field is optional: leave it out and it defaults to misc.)
• pattern is the shape, drawn as rows of text. Each string is one row of the crafting grid. Our pattern has a full top row ("NNN") and a middle row with a gap ("N N"); a space means “leave this slot empty.” That’s the classic helmet shape: across the top and down the sides. Every row string must be the same length, and a recipe can be up to 3×3.
• key explains what each letter in the pattern means. We used the letter N, and here we say N is minecraft:iron_nugget. You can pick any single character except a space for a key.
• result is what you get. id is the item it produces (minecraft:chainmail_helmet) and count is how many (one helmet). count is optional and defaults to 1, but writing it is clearer.

The file is named chainmail_helmet.json, so the recipe’s identifier is mypack:chainmail_helmet.

Modern Minecraft Older recipe tutorials often write the result as "result": {"item": "minecraft:chainmail_helmet"}. Current Java Edition uses id, not item, inside result. If your recipe loads but produces nothing, an old-style item key is a likely culprit.

Try It! The key can point at a tag instead of a single item (for example "#minecraft:planks" to accept any kind of wooden plank) or at a list of allowed items. That, plus shapeless, smelting, stonecutting, and smithing recipes, is all coming in Chapter 15. For now, one item per key is plenty.

Loading the Pack

Your folder is complete. Time to turn it on. Open your test world and press T (or /) to open the chat bar. You’ll type these commands into chat, with the leading slash:

First, check that the game can see your pack:

/datapack list

This lists every data pack the game found, split into available and enabled. You should see mypack in the list. (Hover over it in the chat output to see the description you wrote in pack.mcmeta.) If mypack isn’t there at all, the game didn’t recognize your folder; jump to “What Can Go Wrong” below.

Now enable it:

/datapack enable "file/mypack"

The name to enable is the one shown by /datapack list: packs in your datapacks folder show up as file/mypack. As soon as you enable a pack, the game loads it, and your minecraft:load function fires. You should immediately see your greeting in chat: mypack is loaded! Welcome back.

From now on, whenever you change a file in the pack, you don’t need to disable and re-enable it. Just run:

/reload

/reload re-reads the current data packs so your latest edits take effect without leaving the world, and it re-runs every minecraft:load function, so you’ll see your greeting again each time. This is the command you’ll run hundreds of times while building. (One thing to know: /reload re-reads recipes, functions, tags, loot tables, advancements, and predicates live. A few feature types (the kind marked experimental) need you to fully leave and rejoin the world instead. Recipes and functions, happily, reload live.)

Seeing your recipe

Open a crafting table. Click the recipe book (the little book icon to the left of the grid). Your chainmail helmet recipe is now discoverable there. The quickest way to test it: put nine iron nuggets in your inventory, open a crafting table, and lay them out in the helmet shape: top row full, two on the corners of the middle row, middle slot empty. A chainmail helmet appears in the output. You just crafted something vanilla Minecraft never allowed.

Figure (to be captured). crafting table with iron nuggets arranged in the helmet pattern and a chainmail helmet in the result slot; recipe book open showing the new recipe

Under the Hood (skippable) A recipe normally has to be “discovered” before it shows in your book, usually by picking up one of its ingredients. You can ignore discovery while testing: unless the doLimitedCrafting game rule is turned on, you can craft any recipe whether or not you’ve discovered it. So even before the book shows it, laying out the pattern works.

Practice

These extend the exact pack you just built, so keep working in mypack.

1. Make the greeting your own. Open load.mcfunction and change the say line to a message you like. Add a second say line below it with another message (remember, one command per line, no slash). Run /reload and watch both lines print.

2. Add a second recipe. Copy chainmail_helmet.json to a new file, chainmail_chestplate.json, in the same recipe/ folder. Change the result id to minecraft:chainmail_chestplate and change the pattern to a chestplate shape (sides down both edges, full bottom rows): ["N N", "NNN", "NNN"]. Run /reload and craft it. (Don’t forget: the new recipe’s identifier comes from its file name, so the file must be named differently from the first.)

3. Break it on purpose, then read the error. This is the most useful exercise in the chapter, and it builds the habit you’ll lean on for the rest of the book. Delete the comma after the pattern array’s closing ] so the JSON is invalid, run /reload, and watch the game complain. Then put the comma back and reload to confirm it’s fixed. The next section explains exactly what the complaint is telling you.

What Can Go Wrong

When a data pack misbehaves, Minecraft almost always tells you why; you just have to know where it writes it down. The game keeps a running log of what it’s doing, errors included, and that log is the first place to look when something doesn’t work. Exactly where that log lives on your computer, and how to read it, is the very first thing we cover in Chapter 10 (Debugging), so for now just hold on to the idea that the answer is written down somewhere; you’re never only guessing.

Here are the three failures you’ll hit most, and what each one means. (The exact wording of these messages can shift between Minecraft versions, so learn to recognize the kind of problem rather than memorizing the precise text.)

What Went Wrong? — “Expected value” / JSON syntax errors A message about an unexpected character or expected value, usually with a position number, means your JSON is malformed: a missing comma, an extra comma after the last item in a list, a missing quote, or a mismatched bracket. The position points roughly at where the parser got confused (often just after the real mistake). Open the file, find that spot, and check the punctuation. This is the error you triggered in Practice 3. (If your editor highlights JSON, set up in Chapter 8, it usually flags these before you even reload.)

What Went Wrong? — “Unknown resource location” / unknown item This means you named something the game can’t find, most often a typo in an item ID, like minecraft:iron_nuget (missing a g) or minecraft:chainmail_helemt. The game looks up minecraft:iron_nugget in its registry, doesn’t find your misspelling, and reports it. Fix the spelling of the identifier. The same error appears if you reference a tag or other resource that doesn’t exist.

What Went Wrong? — “Could not find function” / wrong folder structure If a function won’t run, or the game says it can’t find mypack:load, the file is almost certainly in the wrong place or has the wrong name. Re-check the path letter by letter: it must be data/mypack/function/load.mcfunction: singular function, the .mcfunction extension spelled exactly, and the namespace folder named mypack. The same applies if your greeting never appears on load: make sure data/minecraft/tags/function/load.json exists, is spelled correctly, and lists "mypack:load" in its values.

A fourth, sneakier failure: the pack doesn’t appear in /datapack list at all. That means the game didn’t accept the folder as a data pack. The usual cause is a missing, misnamed, or invalid pack.mcmeta. Check it’s named exactly pack.mcmeta (no .txt on the end, which some editors add silently), sits at the top of mypack next to data, and contains valid JSON.

What You Know Now

You built a complete, working data pack from nothing. You know that pack.mcmeta is the file that makes a folder a data pack, and that it carries a description plus a min_format/max_format version range (the modern replacement for the old single pack_format). You know the folder shape (pack.mcmeta at the top, everything else under data/<namespace>/<registry>/) and where packs live inside a world’s datapacks folder. You wrote a .mcfunction file (commands, one per line, no slash, # for comments) and wired it into the minecraft:load tag so it announces your pack automatically. You added a shaped crafting recipe with type, pattern, key, and result, and crafted a chainmail helmet from iron nuggets. And you can turn it all on with /datapack enable, refresh it with /reload, and read latest.log to fix the errors that come up.

You can now build a data pack that runs your own commands on load and adds your own recipes to the game. Everything in the rest of this book extends this same mypack. Next, in Chapter 10, you’ll sharpen the debugging skills you just started using so the inevitable mistakes cost you seconds instead of hours.

Chapter 10 — Debugging and Troubleshooting

What You’ll Build

You just built mypack in Chapter 9. Now comes the part nobody warns you about: sooner or later (probably sooner) one of its files won’t load, a recipe won’t show up, or a command will quietly do nothing. You won’t build a new pack in this chapter. You’ll build a habit for debugging the pack you already have. This short chapter hands you the small toolkit that turns “it’s broken and I have no idea why” into “let me look.” You’ll learn where Minecraft writes down what went wrong (the game log), how to read your position and surroundings with the F3 debug screen, how to poke at a block with the debug stick, and how to ask the game what data an entity or block is actually carrying with /data get. You’ll also pick up the single best habit in this whole book: doing your experimenting in a separate test world instead of the survival world you care about. Everything here comes back as a reference in every later chapter’s “What Can Go Wrong” box, so it’s worth the short read now.

This chapter extends the pack you started in Chapter 9 (your mypack pack) and uses the test world you’ve used since Chapter 1.

Reading the game log

When something goes wrong with a data pack, Minecraft usually tells you; you just have to know where it writes the message. The game keeps a running game log: a plain-text record of what it’s doing, including warnings and errors. Two places show it:

• In chat / on screen. Many data-pack problems show up the moment you run /reload or load the world: a red message in the chat, or a prompt before the world even opens. These are the ones you’ll see most as a beginner, and you don’t have to go hunting for a file to read them.
• In the log file on your computer. Minecraft writes the same information (and a lot more detail) to a text log file on disk. If you launched from a console window or the official launcher’s log view, the messages scroll past there too.

What Went Wrong? “I ran /reload and a red message flashed by too fast to read.” Open the chat (press T) and scroll up; chat keeps a history. The same text is also in the log file on disk, where it sits still so you can read it carefully.

Where does that file live? The exact name and folder differ by operating system and launcher, so the surest way to find it is the launcher itself: most launchers have a “logs” or “open game directory” button that takes you straight to it, and run-from-a-window setups print the same text to that window. When in doubt, open the log from your launcher rather than hunting for a path by hand.

What the log is good for is matching a symptom to a cause. A few things are worth knowing for certain:

• When Minecraft reads your function files, every normal line is parsed as a command, and if any line can’t be parsed, the whole function file refuses to load. One typo on line 12 takes down the entire function, so a function “doing nothing” often means it never loaded at all.
• If a data pack is corrupted or broken (for example it references something that doesn’t exist, like a non-existent entry added to a vanilla tag) Minecraft won’t just limp along. When you try to open the world it shows an error and offers Safe Mode, which disables every data pack except the built-in vanilla one so you can at least get in and fix things.
• /reload is forgiving: if your latest edit has invalid data (say, a malformed recipe), the change is simply not applied and the game keeps using the previous working version. So a reload that “did nothing” can mean your newest edit was rejected, so check the log.

Modern Minecraft Older tutorials sometimes tell you to dig through crash reports for every problem. In current Java Edition, most data-pack mistakes are far gentler than a crash: a bad function just won’t load, a bad pack triggers the Safe Mode prompt, and a bad /reload edit is quietly ignored while the old version keeps running. You rarely lose your world to a typo. You just have to read the message.

Minecraft’s exact error wording changes from version to version, and the precise text for a JSON syntax error, an unknown resource location, or a missing function isn’t worth memorizing. This book describes the kind of failure each one is so you can recognize it; the wording you see in your own game is the authority, so read the real message off the screen and match it to the kind of problem it describes.

The F3 debug screen

You met the F3 debug screen back in Chapter 2, where you used it to read your coordinates. Press F3 (on a Mac or some laptops, Fn+F3) and the screen fills with small text: a built-in overlay that shows technical information about where you are and what the game is doing. Here’s the rest of it, the part that’s useful when something’s broken. It looks intimidating, but you only need a few lines of it.

The most important line is your position. The debug screen shows your current coordinates (your XYZ) and which way you’re facing (your rotation), in the upper-left of the screen. It also shows your block position: the whole-number coordinates of the block you’re standing in. (Coordinates can be decimals because you stand between whole blocks; the block position is just those numbers rounded down. You worked through coordinates properly in Chapter 2; here you only need “F3 tells me where I am.”)

The debug screen even replaces your crosshair with a tiny set of colored axes so you can see which way is which: +X is red (east), +Y is green (up), and +Z is blue (south). That’s a handy memory aid when you start placing blocks with commands.

Figure (to be captured). the F3 debug screen, with the XYZ coordinate line and the colored +X/+Y/+Z crosshair annotated

The F3 screen lists other useful information too, including details about your surroundings such as the biome you’re in and information about the block you’re looking at, which is exactly what you want when a command “works here but not there.” When you need a coordinate to type into a command, or you want to confirm you’re standing where you think you are, F3 is the fastest answer.

Try It! Press F3, read your XYZ, walk ten blocks in one direction, and watch which number changes and whether it goes up or down. You’ve just learned, by experiment, which axis you walked along, no memorizing required.

The F3 screen shows coordinates, rotation, block position, and the colored +X/+Y/+Z crosshair, and it also lists the biome you’re in and details about the block you’re looking at. The exact labels for those last two move around as the screen changes between versions, so rather than memorizing them, press F3 and read them off your own screen. They’re right there once you know to look.

Under the Hood If you ever want a cleaner screen (for a screenshot or a recording) the gamerule reducedDebugInfo can hide some of this information. You don’t need it now; it’s just good to know the clutter is adjustable. (Skippable.)

The Debug Stick: inspecting block states

Most blocks carry extra settings called block states (also called block properties): little pieces of data that further define how the block looks or behaves. A button knows which way it faces; a door knows whether it’s open; a redstone lamp knows whether it’s lit. Those are block states.

The debug stick is a special item for looking at and changing those states by hand. It looks exactly like an ordinary stick but with an enchantment-style shimmer. You get it the way you get any item with commands, and you can only get it in a world that has commands turned on, which your test world does. Inside a function in your mypack pack you’d write it without the leading slash, like this:

data/mypack/function/give_debug_stick.mcfunction

# Hands the nearest player a debug stick for poking at block states.
# Run this in your TEST world only (Creative + cheats).
give @s minecraft:debug_stick

After a /reload, run it with /function mypack:give_debug_stick, or just type /give @s minecraft:debug_stick straight into chat; either works in a test world. (Quick reminder from Chapter 9: inside a .mcfunction file there’s no leading /; in the chat bar you keep it.)

Here’s how the debug stick works once you’re holding it:

• Hit a block (left-click) to select which block-state key you want to work with. Hitting a command block, for example, lets you switch between its conditional key and its facing key.
• Use the block (right-click) to cycle the value of the selected key. With facing selected on that command block, using it steps through down, east, north, south, up, and west.
• Sneak while hitting or using to go through the keys or values in reverse order.

The debug stick remembers which key you last picked for each kind of block (that memory is stored on the stick itself as a small piece of component data), so it feels natural once you’ve used it a couple of times.

Figure (to be captured). holding the debug stick, with the on-screen message showing the selected block-state key after hitting a block

What Went Wrong? “I’m in Survival and the debug stick does nothing.” That’s expected. The debug stick only works in Creative mode with cheats enabled, exactly the kind of world this book has you test in. In Survival or Adventure it behaves like a plain stick. (One more quirk: using it on an interactive block, like a chest, without sneaking opens the block instead of editing it. Sneak first.)

The debug stick is a debugging tool, not something you ship in a pack, but it’s perfect for answering “wait, what state is this block actually in?” while you’re testing.

/data get: inspecting data at runtime

The F3 screen and the debug stick tell you about blocks in the world. But a lot of what a data pack does lives in NBT data: the structured data attached to entities, block entities (like chests and command blocks), and a general-purpose store called command storage. When something isn’t behaving, you often need to see that hidden data directly. The command for that is /data.

/data has four instructions (get, merge, modify, and remove) but for debugging you only need the read-only one: get. The other three change data; we’ll use those properly when we reach command storage in Chapter 12. For now, get is your magnifying glass: it reads out the NBT of a block, an entity, or a storage and prints it back to you with no risk of changing anything.

The shape is always the same: data get followed by block <position>, entity <target>, or storage <id>, and then an optional path to zoom in on one piece.

Type these straight into the chat bar in your test world:

• See the item you’re holding: /data get entity @s SelectedItem
• Check your own saturation level (a number hidden in your player data): /data get entity @s foodSaturationLevel
• Read the contents of a chest at a known position (use F3 to find the coordinates): /data get block 1 64 1 Items

You can also store a quick inspection inside your pack so it’s one keystroke away while testing:

data/mypack/function/inspect.mcfunction

# Quick inspector: print the item I'm holding, then my saturation.
# Run with /function mypack:inspect after /reload.
data get entity @s SelectedItem
data get entity @s foodSaturationLevel

What Went Wrong? “/data get says it got nothing / no tag exists there.” /data get fails if there’s no data at the path you asked for, for example asking for Items on a block that isn’t a container, or a path that’s spelled differently than the real one. Start broad: run data get entity @s with no path to dump everything, then narrow down to the exact name you see in that output.

Under the Hood data get can also report the length of a list or string, handy later. For example, if a storage holds a list of six numbers, data get of that list returns 6. You don’t need this yet; it becomes useful once you’re storing your own data in Chapter 12. (Skippable.)

Common error patterns and their fixes

Most beginner data-pack problems fall into a handful of buckets. Here’s the field guide: match your symptom on the left, check the cause on the right.

• “My whole function does nothing after /reload.” One line in the file couldn’t be parsed, so Minecraft refused to load the entire function. Check the log for the complaint, and re-read the file for a typo, a wrong block/item name, or a stray / at the start of a line (functions don’t use the slash). Fix the one bad line and reload again.
• “My new recipe / edit didn’t take effect, but nothing’s red.” /reload silently ignores an edit with invalid data and keeps the previous working version. So the game is running your old file. Re-check your newest change for a JSON mistake (a trailing comma, a missing quote, the wrong brackets, all from Chapter 8) and reload.
• “The world won’t even open; it’s asking about Safe Mode.” A pack is corrupted or references something that doesn’t exist (a classic is adding a missing entry to a vanilla tag). Let Safe Mode open the world without packs, fix the offending file, then re-enable your pack.
• “Is my pack even on?” Type /datapack list to see every pack and whether it’s enabled; hover a pack in that output to read the description from its pack.mcmeta. If yours is missing, it’s in the wrong place; if it’s listed but disabled, run /datapack enable <name>. (These are the same loading commands from Chapter 9.)

Don’t worry about memorizing the exact red-text wording for a JSON syntax error, an unknown resource location, or a “can’t find that function” message; it varies by version. What matters is what each failure means. Read the message your own game prints (it is the real source of truth) and use the buckets above to map it to a fix.

What Went Wrong? The fastest debugging habit of all: break one thing on purpose. Delete a comma in a working recipe, run /reload, and read what the game says. Now you’ve seen that exact message while you already know the cause, so when it shows up for real, you’ll recognize it instantly.

Keep a test world, not your survival world

You’ll notice this whole chapter keeps saying “in your test world.” That’s the rule, and it’s worth stating plainly: do your data-pack experimenting in a separate test world (a Creative world with cheats enabled), not in the survival world you care about. You made exactly such a world back in Chapter 1 for this reason.

Why bother with two worlds?

• Power. The debug stick only works in Creative with cheats, and /give, /data, /reload, and /datapack all need cheats on. Your test world has all of that; a normal survival world usually doesn’t.
• Safety. Testing means breaking things: flipping block states, summoning mobs, dealing damage, wiping data. A throwaway world means a mistake costs you nothing. Your survival builds and your hard-won gear stay untouched.
• A clean slate. When you’re hunting a bug, you want as few moving parts as possible. A fresh flat test world lets you reproduce a problem without your survival world’s chaos getting in the way.

When a pack works in your test world and you’re happy with it, then you add it to the world you actually play, and you’ll already know it loads cleanly.

A first look at /test and the GameTest framework

Everything so far is manual debugging: you, looking. Minecraft also has the beginnings of an automated testing system, and it’s worth knowing it exists even though we won’t use it in depth until Part IX.

The system is called the GameTest framework: a way to run small, repeatable tests in the world (each test usually paired with a saved structure that sets up the scene), and the /test command family runs them. The idea is that instead of checking by hand whether your contraption still works, you describe the test once and let the game run it for you, reporting pass or fail.

In a data pack, this framework is backed by two registry folders you’ll meet properly later:

• test_environment (data/<namespace>/test_environment/): a way to group up GameTests and give them the right preconditions to run. Think of it as the shared setup several tests need.
• test_instance (data/<namespace>/test_instance/): a test that can be run by the GameTest framework. This is one individual test.

For now, just file those two names away: test_environment is the setup, test_instance is the test. We’ll build real ones in Part IX, where automated testing gets the full treatment.

Under the Hood Both of those folders are marked by the game as experimental settings: having a valid file in one flags the whole pack as using experimental features, and changes to them don’t pick up with a plain /reload the way functions and recipes do. That’s why this is a Part IX topic, not a first-week one. (Skippable.)

The full Java /test subcommand syntax is a topic of its own, and it’s the kind of thing best learned by typing /test in-game and reading the suggestions the command bar offers you. This chapter stays at the “here’s what these are for” level on purpose; Part IX gives /test the full treatment, with real test_environment and test_instance files behind it.

Practice

1. Read the log on purpose. In your mypack pack, open your load function from Chapter 9 and misspell the /say command (for example type sayy). Run /reload, find the message, then fix it. You’ve now seen what a broken function looks like and confirmed your fix.
2. Inspect yourself. Give yourself any item, then run /data get entity @s SelectedItem and read what the game prints. Try it with a plain stick and again with an enchanted tool, and notice how the enchanted one carries more data.
3. Flip a block state. Give yourself the debug stick with your new give_debug_stick.mcfunction, place a button or a command block, and use the stick to change its facing state. Confirm the change with F3’s “looking at this block” info.
4. Two-world discipline. If you’ve only got one world so far, make a second fresh Creative+cheats world right now and label it clearly as your test world. From here on, that’s where the experiments happen.

What Can Go Wrong

• Editing in the wrong world. If /give, /data, or the debug stick “don’t work,” you’re almost certainly in a world without cheats. Check that you’re in your Creative test world.
• Trusting a silent /reload. No red text does not guarantee success: an invalid edit is ignored silently and the old version keeps running. When in doubt, make a visible change (like editing your /say text) so you can confirm the reload actually took.
• Hunting the file log when the answer is in chat. Most beginner errors print right in the chat on /reload or when the world opens. Scroll the chat up first; only go digging in the on-disk log for the stubborn ones.

What You Know Now

You can now find and read Minecraft’s game log and match its messages to a cause; read your position and surroundings off the F3 debug screen; use the debug stick to inspect and flip a block’s block states in your test world; use /data get to read the hidden NBT data on an entity, block, or storage at runtime; recognize the common breakage patterns (a function that won’t load, a silently-ignored reload, the Safe Mode prompt) and their fixes; explain why a separate test world is the safe place to experiment; and you’ve met the GameTest framework and its test_environment / test_instance folders well enough to know they’re coming back in Part IX. This is your reference chapter — every “What Can Go Wrong” box from here on assumes these tools are in your hands.

Chapter 11 — Scoreboards: Counting and Comparing

What You’ll Build

This chapter starts a new part of the book: storing and tracking data. Up to now your mypack functions have done things (said messages, summoned mobs, given effects), but they’ve had no memory. The moment a function finishes, the game forgets everything it just did. This part fixes that, and it does so with three different tools. The scoreboard you’ll learn here is the first, and it’s the right tool for one specific job: keeping a whole number attached to a player or an entity, changing it over time, showing it on screen, and comparing it. By the end of this chapter you’ll have added a live kill counter to mypack, a number on the right side of your screen that ticks up every time you defeat a mob, and you’ll finally be able to use execute if score, the comparison you were promised back in Chapter 4.

This chapter extends the pack you started in Chapter 9 (mypack). It assumes you’re comfortable calling functions (Chapter 9), with target selectors like @s and @a (Chapter 3), and with the /execute command — its as/at/run pieces and the idea of forking over many entities (Chapter 4). That’s also where you first saw if score named; here you learn it for real.

Modern Minecraft Older data pack tutorials lean on scoreboards as “Minecraft’s variable system” and try to store everything in them. That’s no longer how experienced creators work. In current Java Edition a scoreboard is one of three storage tools, and it’s best at exactly one kind of data: a whole number you might want to see or compare. Complex data (lists, text, nested settings) belongs in command storage (Chapter 12), and simple on/off flags belong in entity tags (Chapter 13). Chapter 13 ends with a decision guide for picking between them. Keep that in the back of your mind as you read: scoreboards are useful, but they are not the answer to everything.

What a scoreboard is

A scoreboard is, in the game’s own words, a gameplay mechanic used through commands to track, set, and list the scores of entities in many different ways. Strip away the formality and it’s simpler than it sounds: a scoreboard is a big table of numbers. Each row pairs a who (a player or entity) with a what (a named counter), and the cell holds a number.

That named counter is called an objective. An objective tracks a score for entities that meet a single criterion, and every score is a 32-bit integer, a whole number that can range from roughly negative two billion to positive two billion (the exact limits are -2,147,483,648 and 2,147,483,647). Two things matter about that: scores are always whole numbers (never 2.5), and they can be negative.

The who in the table is called a score holder. A score holder’s name can either be the player’s username or the entity’s UUID, a UUID being the long unique ID every entity carries (you met UUIDs glancingly before; just think “the entity’s permanent serial number”). So one objective can hold a different number for every player and every mob at once. The objective is the column; each holder is a row.

An objective has two main properties of its own: a name, used internally when you reference it in commands, and a criterion, which decides what the objective tracks. In Java Edition the name must be a single, case-sensitive string of alphanumeric characters (A–Z and 0–9), hyphen -, plus +, dot . and underscore _. In plain terms: pick a short, lowercase, no-spaces name, the same kind of name you’ve been using for functions.

Creating an objective

Everything about scoreboards happens through one command, /scoreboard, which manages and displays scores for your scoreboard objectives. It has two big families of subcommands: scoreboard objectives ... (which create and configure the counters themselves) and scoreboard players ... (which read and change the numbers in them). We’ll start with creating an objective.

The syntax is:

scoreboard objectives add <objective> <criteria> [<displayName>]

<objective> is the internal name you’ll use everywhere else, <criteria> is what it tracks (next section), and the optional <displayName> is a prettier label shown on screen. Two companions you’ll reach for:

scoreboard objectives list
scoreboard objectives remove <objective>

list lists all existing objectives, and remove deletes the named objective from the scoreboard system, wiping its data from every holder and removing it from any display. If you try to add a name that already exists, the command fails; if you remove one that doesn’t, it fails too. Both are harmless mistakes that just print a red message.

Criteria: what an objective tracks

A criterion determines an objective’s behavior and tracks statistical game elements. When a criterion’s source value changes, the change is automatically reflected in the objective’s score. This is the most important idea in the chapter, so read it twice. The criterion is the difference between a number you control and a number the game controls.

The simplest criterion is dummy. A dummy objective tracks nothing on its own: the game never touches it. Its score only changes when a command changes it. That makes dummy the right choice whenever you want to be in charge of the number: a timer, a points total, a counter you increment yourself. (One note: in Bedrock Edition dummy is the only criterion that exists; the rich automatic ones below are Java-only, another reason this book is a Java book.)

The other criteria are automatic: the game updates them for you whenever the matching thing happens in the world. A good worked example is the deathCount criterion: make an objective with it, and a player’s score increments whenever they die. You never write a command to bump it; the game does, every time that player dies. There are many such criteria for health, hunger, experience, statistics, and more; some are compound criteria with dotted names, like minecraft.killed_by:minecraft.zombie, under which a player’s score increments whenever they are killed by a zombie.

Under the Hood (skippable) Why the two kinds? An automatic criterion is wired to a number the game already keeps (your death total, your play time, a statistic) and the objective just mirrors it. A dummy objective is a blank counter with no wiring, waiting for your commands. A useful rule of thumb: if Minecraft already counts the thing, there’s probably an automatic criterion for it; if it’s your idea (a quest stage, a minigame score), use dummy and drive it yourself.

Finding more criteria Java Edition has a long list of automatic criteria (for health, hunger, experience, triggers, statistics, and more) and the full set runs to dozens of alphabetical names. This chapter sticks to the handful you’ll actually reach for: dummy, deathCount, and the compound minecraft.killed_by:… form. When you want to browse the complete alphabetical list, the in-game command auto-complete (type scoreboard objectives add name and press Tab) and the wiki’s Scoreboard page are the best places to see every criterion at once. The kill counter below is built on dummy plus a function that increments it, so it needs no special criterion name at all.

Changing a score: set, add, remove

To read and change the numbers you use the scoreboard players subcommands. The four you’ll use constantly are:

scoreboard players set <targets> <objective> <score>
scoreboard players add <targets> <objective> <score>
scoreboard players remove <targets> <objective> <score>
scoreboard players get <target> <objective>

• set: sets the targets’ scores in the given objective, overwriting any previous score. Use it to force a number to an exact value.
• add: increments the targets’ scores in that objective by the given amount. This is how a counter goes up.
• remove: decrements the targets’ scores in that objective by the given amount. This is how it goes down.
• get: returns the scoreboard value. Handy for checking a number, and it can feed execute store result … run scoreboard players get … later.

There’s also reset: scoreboard players reset <targets> [<objective>]. Be careful here: reset does not merely set the scores to 0, it removes the targets from the scoreboard system. So reset is forget this holder entirely, while set … 0 is keep them, value zero. They look the same on screen but mean different things; for a counter you almost always want set … 0, not reset.

Here’s a tiny demo function so the four verbs feel concrete. Create:

mypack/data/mypack/function/kills_demo.mcfunction

# kills_demo — show set / add / remove on the "kills" objective
scoreboard players set @s kills 0
scoreboard players add @s kills 3
scoreboard players remove @s kills 1
scoreboard players get @s kills

After /reload and /function mypack:kills_demo, your kills score is 0, then 3, then 2, and the final get prints 2 back to you. (We’ll create the kills objective itself in the walkthrough.)

Try It! There’s a whole set of arithmetic operations for combining two scores (assignment =, addition +=, subtraction -=, multiplication *=, floor-division /=, modulus %=, swap ><, and min/max < / >) run with scoreboard players operation <targets> <objective> <operation> <source> <objective>. You don’t need them for a simple counter, and we’ll use them in the minigame project (Chapter 33). For now, just know the word operation means “do math between two holders’ scores.”

Displaying a score

A number you can’t see isn’t much fun. Scores can be shown in display slots: these can appear in the player list, on the sidebar at the right side of the screen, or below a player’s name tag. Each slot shows one objective at a time. You set a slot with:

scoreboard objectives setdisplay <slot> [<objective>]

Java Edition names three display slots exactly: sidebar (the panel on the right edge of the screen), list (the tab player list), and below_name (under players’ name tags in the world). For example, scoreboard objectives setdisplay sidebar kills puts the kills objective on the sidebar. Leaving the objective off (scoreboard objectives setdisplay sidebar) clears that slot back to empty.

One detail worth knowing: only the sidebar can show non-player entities’ scores; list and below_name are player-only.

No action-bar slot Those three (sidebar, list, and below_name) are the only slots setdisplay accepts. There’s no action-bar display slot. If you want a score in the action bar, that’s a different tool: use the /title … actionbar command from Chapter 5 with a text component, which can embed a score via the score text component. That’s a text feature, not a setdisplay slot, so reach back to Chapter 5 for it rather than looking for a fourth slot here.

Fake players: numbers under made-up names

Here’s a trick that surprises everyone the first time. A score holder’s name can be any arbitrary username you choose, belonging to no real player at all. A made-up name used this way is called a fake player.

Why bother? Because a fake player gives you a place to store a global number, one that belongs to the whole pack rather than to any particular player. Want a single shared “total mobs spawned” count, or a “current game phase,” or a constant like 100 you compare against? Store it on a fake player:

scoreboard players set #total kills 0
scoreboard players add #total kills 1

#total isn’t a real player, so nobody owns it: it’s just a labeled box for a number. The leading # is a deliberate convention: fake players with names starting with a # character never show up in the sidebar. So a # name is a hidden global that stays out of the on-screen list. Creators use the # prefix for behind-the-scenes values they want to keep hidden from players.

Under the Hood (skippable) Player names can’t contain spaces, so there’s a trick worth knowing: a “figure space” (an invisible-looking character, U+2007) can stand in for a space in a fake player’s display. You won’t need that for normal work (short #names are clearer), but if you ever see a fake player whose name looks like it has gaps, that’s what’s happening.

Comparing scores: if score (the Chapter 4 promise, paid off)

Back in Chapter 4 you met execute if block and execute if entity, and I told you a third condition, if score, was coming once you had scoreboards. Now you do. (if|unless) score checks whether a score has a specific relation to another score, or whether it is in a given range. There are two forms.

Comparing two scores. The syntax is:

(if|unless) score <target> <targetObjective> (<|<=|=|>=|>) <source> <sourceObjective> -> [execute]

The middle piece is one of five comparison operators (<, <=, =, >=, >), read exactly like in math. Here’s an example that checks whether two scores are equal:

execute if score @s A = @s B

That reads: “if my score in objective A equals my score in objective B.” You can compare across holders, too: if score @s kills > #total kills asks whether my kills beat the stored total.

Comparing a score to a range. The second form tests one score against a range of numbers:

(if|unless) score <target> <targetObjective> matches <range> -> [execute]

A <range> is written the same way you wrote distance= ranges back in Chapter 3: 10 means exactly ten, 10.. means ten or more, ..10 means ten or less, and 5..10 means anywhere from five to ten. So if score @s kills matches 10.. means “if my kills are ten or more.” This range form is the one you’ll use most for milestones and thresholds.

Just like if entity and if block, the trailing -> [execute] means another subcommand is optional: if score can sit at the end of a chain (just testing), or be followed by run to do something when the test passes. And unless score is simply if score flipped. This example, execute as @a unless score @s test = @s test run say "Score is reset", fires only when a player has no score set (a value compared to itself fails when it doesn’t exist).

Try It! Selectors can filter by score directly, too. There’s a scores selector argument: @e[scores={<name>=<min>..<max>}]. For example, @a[scores={kills=10..}] targets every player whose kills is ten or more. It’s the same range idea as if score … matches, just packed into a selector. Try swapping one for the other once your counter works.

Walkthrough: a kill counter on the sidebar

Now the real project. We want a number on the sidebar that goes up by one every time you kill a mob. We’ll build it from pieces you now know: a dummy objective named kills, a sidebar display, and a tick-driven check that watches for kills and increments the score. We use dummy plus our own increment so that we stay in full control of when the number moves.

Step 1 — create the objective and show it

Make a setup function that creates the objective and puts it on the sidebar. This should run once, when the pack loads. Create:

mypack/data/mypack/function/score_setup.mcfunction

# score_setup — create the kill counter and show it on the sidebar
scoreboard objectives add kills dummy "Mob Kills"
scoreboard objectives setdisplay sidebar kills

The first line makes a dummy objective named kills with the on-screen label "Mob Kills". The second line shows that objective on the sidebar. Now wire this into the load tag so it runs automatically. You already created this file in Chapter 9 for mypack:load. Add the new function to its list (don’t replace what’s there):

mypack/data/minecraft/tags/function/load.json

{
  "values": [
    "mypack:load",
    "mypack:score_setup"
  ]
}

What Went Wrong? If you run score_setup twice (say, after a second /reload), the second scoreboard objectives add kills dummy … line fails with a red message saying the objective already exists, and that’s harmless. The objective from the first run is still fine. A load function trying to re-create an existing objective is a normal, ignorable warning, not a bug in your pack.

Step 2 — count the kills

A dummy objective won’t move on its own. That’s the whole point of dummy: you drive it. So we make a small function that adds one to a player’s kills, and call it whenever a kill should count. Create a function you call to register a kill:

mypack/data/mypack/function/add_kill.mcfunction

# add_kill — register one mob kill for the player who runs it
scoreboard players add @s kills 1

Run /function mypack:add_kill and your sidebar kills number climbs by one each time. To make it feel automatic in a test, pair it with the /execute skills from Chapter 4. For instance, a tick function that adds a kill for every player standing on a gold block reuses the exact as @a at @s if block pattern you already wrote:

mypack/data/mypack/function/kill_on_gold.mcfunction

# kill_on_gold — demo: stand on a gold block to rack up the counter
execute as @a at @s if block ~ ~-1 ~ minecraft:gold_block run scoreboard players add @s kills 1

This is just a stand-in so you can watch the sidebar move without fighting mobs. To make it run every tick, list it in the tick function tag, the every-tick sibling of the load tag you met in Chapter 9. This is the first function you’ve wanted on every tick, so create the file:

mypack/data/minecraft/tags/function/tick.json

{
  "values": [
    "mypack:kill_on_gold"
  ]
}

/reload, stand on a gold block, and watch “Mob Kills” climb on the sidebar.

Figure (to be captured). the sidebar on the right of the screen titled “Mob Kills” showing a rising number while the player stands on a gold block

Step 3 — react at a milestone

Finally, do something when the counter crosses a threshold. This is where if score earns its keep. Create a function that congratulates the player once they hit ten kills:

mypack/data/mypack/function/kill_milestone.mcfunction

# kill_milestone — celebrate at 10 kills
execute as @a if score @s kills matches 10.. run say Ten kills! Nice work.

as @a forks over every player; if score @s kills matches 10.. passes only for players whose kills is ten or more; and run say … fires for each one who qualifies. Call it from chat with /function mypack:kill_milestone, or add it to a tick function if you want it watched constantly (though a constant version would repeat every tick, so a real pack would set a “done” flag, which is exactly the kind of on/off state you’ll learn to store in Chapters 12 and 13).

When scoreboards are the right tool

You’ve now seen what a scoreboard does well, so here’s the honest summary the rest of this part builds on. Reach for a scoreboard when you need:

• a whole number: scores are integers, nothing else (no text, no lists, no decimals);
• that you might display: the sidebar, list, and below-name slots are built for exactly this;
• or compare: if score and the scores= selector argument make numeric thresholds easy;
• or have the game track for you: automatic criteria like deathCount update themselves.

That’s a real, common set of needs: kill counts, timers, points, lives, levels. But notice what’s not on the list: anything beyond a single whole number. A player’s chosen difficulty, a list of completed quests, a block of configuration: those are the wrong shape for a scoreboard, and trying to cram them in is the classic “scoreboards as variables” mistake from the Modern Minecraft note at the top. The next chapter introduces command storage, which holds exactly that richer data, and Chapter 13 caps the part with a decision guide so you’ll never have to guess which of the three tools to grab.

What Can Go Wrong

Forgetting to create the objective first. Every scoreboard players … command needs an objective that already exists. If you add @s kills 1 before any objectives add kills … has run, the command fails because the objective doesn’t exist. This is why the walkthrough creates kills in a load function: it’s guaranteed to exist before any other function tries to use it.

Confusing reset with set … 0. Remember the warning from earlier: reset removes the holder from the objective entirely, while set … 0 keeps them with a value of zero. If your sidebar suddenly stops listing a player after you “zeroed” them, you probably used reset when you meant set … 0.

Wrong display-slot name. setdisplay takes exactly sidebar, list, or below_name. A typo like side_bar or belowname won’t match, and the score simply won’t appear. If your number isn’t showing up, check the slot name first, and confirm you actually ran the setdisplay line at all (a freshly added objective is invisible until you display it).

What You Know Now

You can use the first of the book’s three storage tools. You know a scoreboard is a table pairing score holders with objectives, that every score is a whole 32-bit integer, and that an objective’s criterion decides whether you drive the number (dummy) or the game does (automatic criteria like deathCount). You can create objectives with scoreboard objectives add, change scores with set / add / remove (and the careful difference between reset and set 0), show a score with scoreboard objectives setdisplay in the sidebar, list, or below_name slot, and stash global numbers on fake players (with a # prefix to hide them). And you’ve finally delivered on the Chapter 4 promise: execute if score, both the two-score comparison (@s A = @s B) and the matches <range> form, to branch a command on a number. Your mypack pack now shows a live “Mob Kills” counter on the sidebar. Next chapter: command storage, for all the data that isn’t a single number.

Chapter 12 — Command Storage: The Modern Default

What You’ll Build

In the last chapter you used scoreboards to track numbers: kill counts, timers, simple whole numbers you can compare and show on the screen. Scoreboards are great at exactly that: one number per player. But the moment you want to remember something that isn’t a single number (a difficulty setting written as a word, a list of active game rules, a little bundle of related values that belong together), a scoreboard starts to feel like the wrong tool.

This chapter introduces the right tool: command storage. Command storage is a named container that can hold any shape of data (numbers, words, lists, and whole nested structures), and it doesn’t need a block or an entity to live in. It’s the modern default for complex state and configuration in data packs. Along the way you’ll meet NBT, the data format Minecraft uses inside storage (and inside entities and blocks), and you’ll finally learn the full /data command. Back in Chapter 10 you only used /data get to look at things; here you’ll learn to write, change, and remove data too.

By the end you’ll have built a small difficulty-settings config system inside the mypack pack you started in Chapter 9: a storage that remembers a chosen difficulty, a multiplier, and a list of rules, with functions to set it up, read it back, and change it.

This chapter extends your mypack pack and uses the test world you’ve used since Chapter 1.

What command storage is

Command storage is a general-purpose, key-value container that commands can read from and write to, without the overhead of attaching the data to a block or an entity. Think of it as a labeled box that floats free in your world: you don’t have to summon a mob or place a chest to have somewhere to keep your data. You just name a box and start putting things in it.

Each storage is identified by a resource location, the same namespace:path naming you met in Chapter 8 for things like minecraft:stone. So a storage has an ID like mypack:config. The namespace part is what keeps two different packs from clashing: if your pack uses mypack:config and someone else’s pack uses theirpack:config, they’re completely separate boxes that never interfere with each other. That’s a big part of why storage is the recommended place for a pack’s data.

Under the Hood (skippable) Behind the scenes, each namespace’s storage is saved into a file called command_storage.dat inside the data folder of your world save, under a folder named for that namespace. You never touch this file by hand (the /data command does it all for you), but it’s nice to know your storage is genuinely saved with the world and survives quitting and reloading.

A storage is only useful if commands can read and write it. Here’s the split, straight from the wiki: the commands that read from storage are data get, data modify, and execute (if|unless) data; the commands that write to storage are data merge, data modify, data remove, and execute store. Storage can also be read by text components: that’s exactly the nbt text source that Chapter 5 previewed and pointed here. In this chapter we’ll focus on the /data family; execute store (writing a command’s result into storage) and execute if data (using storage as a condition) are useful partners you’ll meet properly in Chapter 27.

A gentle introduction to NBT and SNBT

Before you can put data into storage, you need to know what the data looks like. Minecraft stores data in a format called NBT, short for Named Binary Tag. NBT is a tree of tags, where each tag has a type, a name, and a value. That’s the whole idea: a piece of data, a label for it, and what kind of thing it is.

You won’t write NBT directly; it’s a binary format meant for the computer. Instead you write SNBT, which stands for stringified Named Binary Tag: the readable, text version of NBT that Java Edition commands use. SNBT looks a lot like the JSON you learned in Chapter 8, with one big difference we’ll get to. At the top, SNBT is usually a compound — a set of key-value pairs inside curly braces { }, exactly like a JSON object. Here’s an example straight from the wiki:

{
  key1: 123,
  'key2': 'somevalue1',
  "key3": {
    subkey1: 0x1C8,
    "subkey2": "somevalue2"
  }
}

Notice two things. First, the keys don’t have to be in quotes (key1 works bare); in plain JSON they always must be. Second (and this is the difference that trips people up), NBT has several different kinds of numbers, and you often have to say which kind you mean by adding a letter after the number. JSON just has “number”; NBT has bytes, shorts, integers, longs, floats, and doubles.

Here are the suffix letters you’ll actually use, exactly as the wiki gives them. When the game turns NBT into readable SNBT, “a number is always followed by a letter (lowercase for b, s, f, d, and uppercase for L) except integer”:

• b: a byte (a tiny whole number), e.g. 3b
• s: a short (a small whole number), e.g. 3s
• (no letter): an int (a regular whole number), e.g. 3
• L: a long (a huge whole number), e.g. 3L
• f: a float (a decimal number), e.g. 3.2f
• d: a double (a more precise decimal), e.g. 3.2d

One more very useful rule: true and false are stored as 1b and 0b, a byte that’s 1 or 0. So when you want a yes/no flag in storage, you can write true, and Minecraft keeps it as 1b.

Under the Hood (skippable) When you write a value with no letter, the game picks the type for you: “When no letter is used, it assumes double if there’s a decimal point, int if there’s no decimal point.” So 5 becomes an int and 5.0 becomes a double. If you specifically want a float or a short, add the letter. Most of the time, plain ints and quoted strings are all a beginner needs. Reach for the letters only when a particular game property demands a specific type.

Modern Minecraft Old tutorials lean heavily on raw NBT, treating it as the main way to customize items and store state. In current Java Edition, item customization lives in data components (you’ll meet those in Part VI), and your pack’s own data belongs in command storage. You still need to read NBT (it’s how the game describes entities and blocks), but you rarely have to wrestle with the raw binary format. SNBT in commands is as deep as this book goes.

Writing your first value

Let’s put something in a box. The command to write data is /data modify, and to target a storage you write storage <namespace>:<name>. Here is the shape of the command for storage, the same /data modify storage you saw named in the Book Plan:

/data modify storage mypack:config Difficulty set value "normal"

Read it left to right:

• data modify: we’re changing data.
• storage mypack:config: in the storage box named mypack:config.
• Difficulty: at the tag named Difficulty (this part is an NBT path, coming up next).
• set value "normal": set it to the value "normal".

If the mypack:config storage didn’t exist yet, this creates it. If Difficulty wasn’t there yet, this adds it. You don’t “declare” a storage ahead of time — writing to it brings it into being.

Remember the rule from Chapter 9: inside a .mcfunction file you write commands without the leading /. So in a function this exact line would read data modify storage mypack:config Difficulty set value "normal". When this chapter shows a command to type into chat to test something, it keeps the /.

Reading it back with /data get

To look at what’s in a storage, use /data get, the same /data get you used in Chapter 10 to inspect things, now pointed at a storage:

/data get storage mypack:config

That reads back the entire contents of the mypack:config storage and prints it to you with syntax highlighting. To read just one piece, add an NBT path:

/data get storage mypack:config Difficulty

There’s a neat bonus to data get. When you point it at a list or a string, it doesn’t print the contents; it returns the length. The wiki gives this exact example. Suppose you store a list:

/data merge storage wiki:example {List:[2,5,8,9,6,10]}

Then running this returns 6, the number of items in the list:

/data get storage wiki:example List

And for a string:

/data merge storage wiki:example {String:"Example string with a character count of 43"}

Running this returns 43, the number of characters:

/data get storage wiki:example String

That length-returning behavior is genuinely handy: it’s how you ask “how many things are in this list?” without writing any extra machinery.

NBT paths: pointing inside the data

That Difficulty in the middle of the command is an NBT path: “a descriptive string used to specify one or more particular elements from an NBT data tree.” When your storage holds a flat value the path is just a name. But storage can hold structures inside structures, and a path is how you dive into them. A path is written as nodes separated by dots (.). Here are the node types you need, taken straight from the wiki’s own examples:

• foo: the tag named “foo” under the root.
• foo.bar: the tag “bar” inside the compound “foo”.
• foo.bar[0]: the first element of the list “bar”. (Lists count from 0, just like the list positions you saw with selectors in Chapter 3.)
• foo.bar[-1]: the last element of the list “bar”.
• foo.bar[{baz:5b}]: every element of the list “bar” whose “baz” tag equals 5b.
• foo{bar:"baz"}: the “foo” tag, but only if its child “bar” has the value "baz".

So a path like Settings.rules[0] means “inside the Settings compound, the first item of the rules list.” You build paths by chaining nodes until you’ve pointed at exactly the data you want.

Under the Hood (skippable) A path doesn’t have to select just one tag — it can select several at once. The wiki notes that commands like data get “require the size of the tag collection obtained by the NBT path to be 1” (you can only get one thing), while data modify “allows the size of the tag collection obtained by the NBT path to be greater than 1” (you can change many matching tags in one command). As a beginner you’ll almost always point at a single tag, so you can set this aside until you need it.

Storing strings, lists, and nested objects

Storage holds whole structures, and that’s the whole point. You can set a tag to an entire structure in one go. Watch what set value can take:

A string (text in quotes):

/data modify storage mypack:config Difficulty set value "hard"

A list (square brackets, items separated by commas):

/data modify storage mypack:config Rules set value ["keep_inventory", "no_mob_griefing"]

A nested object (a compound inside a compound):

/data modify storage mypack:config Settings set value {difficulty: "normal", mob_health_multiplier: 1.5f, hardcore: false}

That last one stores three different kinds of value together (a string, a float, and a yes/no flag, with false kept by the game as 0b) all under one tidy Settings tag. This is what a scoreboard cannot do, and why storage is the default for anything more complicated than a single number. The structure is yours to design: whatever shape your pack’s data wants, you can write it.

The /data command in depth

You’ve now met all four of the /data instructions in passing. Let’s lay them out properly. The wiki lists exactly four: get, merge, modify, and remove. Each one can target a block <targetPos>, an entity <target>, or a storage <target>: the same three kinds of place. Here’s each instruction.

get — read data

/data get storage mypack:config Settings.difficulty

get reads “the entire NBT data or the subsection of the NBT data” at the target and prints it. It can take an optional scale at the end: a number it multiplies the result by, useful when you need a number in different units. With no path, it reads everything; with a path, just that part.

merge — blend in a compound

/data merge storage mypack:config {LastWinner: "Alex", Round: 3}

merge takes a compound of SNBT and blends it into what’s already there. Tags you mention get set; tags you don’t mention are left alone. So the command above adds (or updates) LastWinner and Round without disturbing your Settings tag. merge is the quick way to update a few top-level fields at once.

modify — the precise editor

modify is the workhorse, and it has five operations. These names come straight from the wiki; do not improvise others. After data modify <target> <path> you pick one of:

• set: “Set the tag specified by <targetPath> to the source data or direct value data.” Replaces whatever was there.
• merge: “Merge the source data or direct value data into the pointed-to object.” Like the top-level merge above, but aimed at a specific compound via its path.
• append: “Append the source data or direct value data onto the end of the pointed-to list or array.”
• prepend: “Prepend the source data or direct value data onto the beginning of the pointed-to list or array.”
• insert <index>: “Insert the source data or direct value data into the pointed-to list or array as element <index>, then shift higher elements one position upward.” (insert needs a position number; append and prepend don’t.)

So to add a rule to the end of a Rules list:

/data modify storage mypack:config Rules append value "no_fall_damage"

To slip one in at the front:

/data modify storage mypack:config Rules prepend value "no_fall_damage"

To put one specifically at position 1 (the second slot, counting from 0):

/data modify storage mypack:config Rules insert 1 value "no_fall_damage"

remove — delete data

/data remove storage mypack:config Settings.hardcore

remove “removes NBT data at <path>” from the target. Point it at a tag and that tag is gone. There’s one safety rule worth knowing: you can’t remove (or edit) a player’s data this way. “Player NBT data cannot be removed.” Your own storage, though, is entirely yours to prune.

value, from, and string: three ways to feed modify

In every modify example above, you typed the data in directly after the word value. That’s one of three sources the wiki gives for modify (and they apply to set, merge, append, prepend, and insert alike):

• value <value>: the direct value you type in, as you’ve been doing.
• from <source>: copy the data from another place, such as another storage, an entity, or a block.
• string <source>: copy data from a source as a string, with optional start/end character positions to grab just part of it.

The from source is what makes storage feel connected to the rest of the world: you can copy a value out of an entity or a block and into your storage, or shuffle data between two storages. For example, to copy a value from one storage into another:

/data modify storage mypack:config LastResult set from storage mypack:scratch Result

You’ll use from heavily once you start reading live data out of mobs and blocks, which is exactly the next section.

Reading data from entities and blocks

Storage is a box you fill, but /data get can also read the data the game keeps on entities and block entities (blocks that hold extra data, like chests and signs). This is how you inspect the live world, and it’s the same /data get entity you first used, read-only, in Chapter 10.

Here are real examples from the wiki. To view the data of the item you’re holding:

/data get entity @s SelectedItem

To read your current saturation level:

/data get entity @s foodSaturationLevel

These follow the same pattern as storage: data get, then the target (entity @s), then an NBT path (SelectedItem). The path syntax is identical whether you’re reading a storage, an entity, or a block. That’s why you learned paths once and can use them everywhere.

Reading a block works the same way, with block and a position. The wiki walks through a great example: a player has put a written book in a chest and wants the text on one of its pages. They build the path up one piece at a time by running /data get and reading the output, until they reach:

/data get block ~ ~ ~ Items[1].components.minecraft:written_book_content.pages[3].raw

Don’t worry about every part of that path yet (the components piece belongs to Part VI). The point is the technique. You aim /data get at a block, read what comes back, then add one more node to your path to drill deeper, repeating until you’ve isolated exactly the value you want. That trial-and-error path-building is one of the most useful debugging habits in the whole book.

Try It! Stand on a chest with an item in it and run /data get block ~ ~ ~ in chat to dump its entire block data, then add Items to the path and run it again. Watch the output shrink to just the contents. Add [0] to see the first item. You’re learning to read NBT by exploring it, the same skill that lets you copy real game data into your storage with from.

When storage is the right choice

You now have two data tools (scoreboards from Chapter 11 and command storage from this chapter), and a fair question is which one when. The full decision guide (which adds entity tags as a third option) comes in the very next chapter. For now, here’s the storage half of it.

Reach for command storage when:

• The data is a word, a list, or a bundle of related values rather than a single whole number.
• The data describes the pack or the world rather than one specific player (configuration, game state, saved settings).
• You want a clean, namespaced place to keep your pack’s data that won’t clash with other packs.

Reach for a scoreboard when the thing you’re tracking really is a single integer you might compare or display: a kill count, a timer, a level. Storage can hold a number too, but a number you constantly compare and show on the sidebar is a scoreboard’s home turf.

A short way to remember it: scoreboards count; storage remembers. If you’d describe the data as “a number,” try a scoreboard. If you’d describe it as “some information,” reach for storage.

Walkthrough: a difficulty-settings config system

Let’s build something real in mypack: a config storage that remembers a difficulty setting, a matching mob-health multiplier, and a list of active rules, the kind of thing every bigger data pack needs. You’ll write three functions: one to set up the defaults, one to read the config back, and one to change the difficulty.

Step 1 — the init function

This function writes the default config into mypack:config. We store one tidy compound called Settings so all the config lives together.

mypack/data/mypack/function/config_init.mcfunction

# Set up the default difficulty config in storage mypack:config.
# One compound, "Settings", holds everything: a difficulty word,
# a mob-health multiplier (a float), and a list of active rules.
data modify storage mypack:config Settings set value {difficulty: "normal", mob_health_multiplier: 1.0f, rules: ["keep_inventory"]}

One command, and the whole config exists. difficulty is a string, mob_health_multiplier is a float (the f makes sure it’s stored as a decimal), and rules is a list with one rule in it to start.

Step 2 — run it on load

Your pack already runs mypack:load every time it loads, wired up through the minecraft:load function tag back in Chapter 9. Add a line to your existing load function so the config is always set up when the pack loads. Open load.mcfunction and add the call:

mypack/data/mypack/function/load.mcfunction

# The greeting from Chapter 9 stays as it was; we add a call to set up config.
say mypack is loaded! Welcome back.
function mypack:config_init

Now every /reload (or world load) refreshes the config to its defaults. (Later, you’ll likely want to set defaults only if the config doesn’t already exist — that needs execute if data, which is a Chapter 27 topic. For now, resetting on load is perfectly fine and easy to reason about.)

Step 3 — the read function

A small function to dump the whole config so you can see it while testing:

mypack/data/mypack/function/config_get.mcfunction

# Print the whole config, then just the chosen difficulty.
data get storage mypack:config
data get storage mypack:config Settings.difficulty

The first line shows everything; the second drills in with the path Settings.difficulty to show just the chosen difficulty word.

Step 4 — the set-difficulty function

This function switches the config to “hard”: it changes the difficulty word, bumps the multiplier, and adds a rule to the rules list.

mypack/data/mypack/function/set_difficulty.mcfunction

# Switch the config to "hard".
# 1. change the difficulty word with set
data modify storage mypack:config Settings.difficulty set value "hard"
# 2. raise the mob-health multiplier with set
data modify storage mypack:config Settings.mob_health_multiplier set value 2.0f
# 3. add a rule to the END of the rules list with append
data modify storage mypack:config Settings.rules append value "no_mob_griefing"

Three operations, each pointing at a different part of the same Settings compound: two sets and one append. Notice you never had to recreate the whole config — you reached straight in and changed just the pieces you wanted, using NBT paths.

Step 5 — test it

Reload and try the functions in chat (these are typed into chat, so they keep the /):

/reload
/function mypack:config_get
/function mypack:set_difficulty
/function mypack:config_get

The first config_get shows normal with multiplier 1.0f and one rule. After set_difficulty, the second config_get shows hard, multiplier 2.0f, and no_mob_griefing added to the list. You’ve built a working, readable, changeable config system, and there isn’t a scoreboard in sight, because none of this is a single comparable integer.

Figure (to be captured). chat output of /function mypack:config_get before and after set_difficulty, showing the Settings compound change from normal/1.0f to hard/2.0f with the extra rule

Practice

1. Add a “peaceful” setter. Write mypack:set_peaceful that sets Settings.difficulty to "peaceful", sets Settings.mob_health_multiplier to 0.5f, and uses prepend to add "no_hostile_spawns" to the front of Settings.rules. Compare how prepend differs from the append you used in the walkthrough.

2. Remove a rule. Write a function that uses data remove to delete the first rule with the path Settings.rules[0], then run config_get to confirm the list got shorter.

3. Count the rules. Recall that data get on a list returns its length. Write a one-line function that runs data get storage mypack:config Settings.rules and read the number it returns in chat.

4. Insert in the middle. Use data modify storage mypack:config Settings.rules insert 1 value "no_fire_spread" to slip a new rule into position 1 of the rules list, then read the list back and confirm the new rule landed in the second slot (positions count from 0).

5. Copy from a block. Place a chest, put an item in it, stand on it, and use data modify storage mypack:config FirstSlot set from block ~ ~ ~ Items[0] to copy the first item into your config storage. Run config_get to see real game data sitting in your box.

What Can Go Wrong

What Went Wrong? — “No tag exists at the path” If you read or remove a path that isn’t there, the command fails with a message about no tag existing at that path. Usually it’s a typo in the path or a missing piece, for example asking for Settings.dificulty (misspelled) or Difficulty when you actually stored it under Settings.difficulty. Run data get storage mypack:config with no path to dump everything, then read the real tag names back and fix your path. NBT tag names are case-sensitive, so Settings and settings are two different boxes.

What Went Wrong? — appending to something that isn’t a list append, prepend, and insert only work on a list or array. If you point one at a single value or a compound by mistake, the command fails (the wiki’s wording: the target “isn’t a list or array tag”). Make sure the path you’re appending to really points at a [ ] list, for example Settings.rules, not Settings.difficulty.

What Went Wrong? — the number is the wrong “kind” NBT cares about number types. If a value needs a float and you write a plain 2 (an int), it may not behave as expected, because 2 and 2.0f are different types of tag. When a value should be a decimal, add the f (float) or d (double) suffix, like 2.0f. When you read data back with data get, the game shows you the letters — that’s your clue to what type each value is.

What You Know Now

You can create a command storage, a namespaced, free-floating container (mypack:config) that needs no block or entity, and fill it with any shape of data. You met NBT and its readable form SNBT, including the type letters (b, s, L, f, d) and the rule that true/false are stored as 1b/0b. You can write data with /data modify storage (set value), read it with /data get (which returns the length of a list or string), and point inside structures with an NBT path (foo.bar[0], [-1], dotted nodes). You learned the full /data command: get, merge, modify (with its five operations set, merge, append, prepend, insert), and remove, plus the three modify sources value, from, and string. You can read live data out of entities and blocks with /data get, and you can say when storage beats a scoreboard. And your mypack pack now has a real, working difficulty-config system.

You can now build: a saved configuration for any data pack; a place to remember lists and structured state across reloads; and the habit of reading game data with /data get to debug. Next chapter adds the third data tool, entity tags, and completes the “which tool for which job?” decision guide.

Chapter 13 — Entity Tags and Choosing the Right Tool

What You’ll Build

Over the last two chapters you met two ways to remember things: scoreboards (Chapter 11), which track numbers, and command storage (Chapter 12), which holds any shape of data you like. This chapter adds the third and simplest tool in the set, the entity tag, and then steps back to answer the question all three chapters have been building toward: given a job, which tool should I reach for?

By the end you’ll be able to slap a plain on/off label onto any entity with /tag, pick out every entity wearing that label with @e[tag=...] (the tag= filter Chapter 3 promised you’d learn here), and tell at a glance whether a task wants a scoreboard, command storage, or an entity tag. To prove it, you’ll add three tiny systems to your mypack pack: a team marker built from tags, a countdown timer built from a scoreboard, and a quest tracker built from command storage, one system per tool, so the differences are impossible to miss.

This chapter extends the pack you started in Chapter 9 (your mypack pack) and uses the test world you’ve used since Chapter 1. It assumes the selector skills from Chapter 3, the scoreboard skills from Chapter 11, and the command-storage skills from Chapter 12.

What an entity tag is

An entity tag is the simplest tracker in the whole game: a short word you stick onto a specific entity that is either there or not there. There’s no number and no structure, just a label that’s present or absent, like a sticker on a box. The game stores these as scoreboard tags: a simple list of single-word strings stored directly in the entity, with a maximum of 1024 tags per entity. Each entity carries its own little list of stickers, and you can ask “does this entity have the red_team sticker?” and get back a plain yes or no.

That’s the whole idea. A scoreboard answers how many? Command storage answers what’s the data? An entity tag answers a simpler question: is this flag on or off for this particular entity? A flag is just programmer-speak for an on/off marker: the entity either has the tag or it doesn’t.

Because a tag lives on the entity itself, it travels with that entity. Tag a zombie boss and that one zombie stays boss until something removes the tag or the zombie dies, and you don’t have to keep a separate list of which zombie is the boss. That’s what makes tags so handy for marking this mob, that armor stand, or these few players out of a crowd.

Under the Hood The game’s own name for entity tags is “scoreboard tags,” and they really are stored alongside the scoreboard system, but don’t let the name fool you. They have nothing to do with the numbers a scoreboard tracks; they’re a separate on/off list. The book calls them entity tags because that describes what they are: labels attached to entities. (Skippable.)

Adding and removing tags with /tag

You manage entity tags with the /tag command. It has exactly three jobs: add a label, remove a label, and list the labels an entity currently has. Here is the syntax:

tag <targets> add <name>
tag <targets> remove <name>
tag <targets> list

• tag <targets> add <name>: adds the tag <name> to every entity matched by <targets>.
• tag <targets> remove <name>: removes the tag <name> from every matched entity.
• tag <targets> list: lists all tags currently on the matched entities.

The <targets> part is a target selector (the same selectors you learned in Chapter 3), so you can tag one entity, a filtered group, or yourself. The <name> is the label: a single word, and (like scoreboard objective names) case-sensitive, so Boss and boss are two different tags.

Let’s give your pack its first tagging function. Inside a .mcfunction file there’s no leading /, just as you’ve done since Chapter 1. This one marks every nearby zombie as belonging to the red team:

data/mypack/function/mark_red_team.mcfunction

# Mark every zombie within 10 blocks as the red team
tag @e[type=minecraft:zombie,distance=..10] add red_team
say Red team assembled!

Run it from chat the way you’ve run your other functions (/function mypack:mark_red_team) after summoning a few zombies near yourself. Every zombie in range now carries the red_team sticker. Nothing looks different yet; the tag is invisible. To prove it’s there, point /tag ... list at one zombie, or (better) use the tag in a selector, which is the next section.

If you ever want to clear the label, the mirror-image function removes it from the same group:

data/mypack/function/clear_red_team.mcfunction

# Take the red team tag back off every nearby zombie
tag @e[type=minecraft:zombie,distance=..10] remove red_team
say Red team disbanded.

What Went Wrong? Adding a tag an entity already has, or removing one it doesn’t have, isn’t an error you need to worry about: the command simply reports that nothing changed for that entity. Tags are safe to “add again”: an entity can hold a given tag only once, so re-adding red_team to an already-red zombie just leaves it red.

Using tags in selectors: @e[tag=...]

Back in Chapter 3 you saw the tag= filter listed but were told its full story would wait for this chapter. Here it is. You filter a selector by tag with the tag= argument, which has four forms:

[tag=<string>]    Include only targets with the specified tag.
[tag=!<string>]   Exclude any targets with the specified tag.
[tag=]            Include only targets with exactly zero tags.
[tag=!]           Include only targets that have at least one tag.

So @e[tag=red_team] means “every entity carrying the red_team sticker,” and @e[tag=!red_team] means “every entity not carrying it.” The two empty forms are occasionally handy: @e[tag=] finds entities with no tags at all, and @e[tag=!] finds entities that have at least one tag of any kind.

You can stack tag filters. Multiple tag arguments are allowed, and all arguments must be fulfilled for an entity to be selected: they’re combined with AND, exactly like the other filters from Chapter 3. So @e[tag=red_team,tag=boss] matches only entities that have both the red_team and the boss stickers, while @e[tag=red_team,tag=!stunned] matches red-team entities that are not stunned.

Now that you can select tagged entities, you can do something visible with the team you marked. Add a function that makes every red-team zombie glow:

data/mypack/function/red_team_glow.mcfunction

# Make every red team member glow for 30 seconds
effect give @e[tag=red_team] minecraft:glowing 30 0

Run mypack:mark_red_team to assign the team, then mypack:red_team_glow, and the marked zombies light up with the glowing outline while any un-marked mobs nearby stay dark. That outline is your proof the tag is doing its job.

Figure (to be captured). a cluster of glowing red-team zombies with one ordinary, non-glowing zombie standing just outside the original 10-block range

Try It! Combine tags with everything else from Chapter 3. @e[type=minecraft:zombie,tag=red_team,distance=..20] targets red-team zombies within twenty blocks. Or split your mobs into two teams: tag one group red_team and another blue_team, then write a function that only buffs @e[tag=red_team] and another that only buffs @e[tag=blue_team]. Tags turn one undifferentiated crowd into named groups you can command separately.

Two very different things both called “tag”

Here is the single most important thing to keep straight in this chapter, because the next chapter is going to reuse the word “tag” for something completely different.

Modern Minecraft The word tag means two unrelated things in Minecraft, and tutorials online rarely warn you:

1. Entity tag (this chapter): a runtime label you put on one specific entity with the /tag command, and check with @e[tag=...]. It’s a sticker on a single mob/player/armor stand, added and removed live while the world runs.
2. Registry tag (Chapter 14): a JSON file in your data pack that groups types of things, written with a leading #, like #minecraft:logs standing for “every kind of log block.” It groups whole categories of blocks, items, or entity types, and you can’t change it with a command while playing.

The game itself draws the line: the /tag command is distinct from entity type tags, which are applied to entity types and can’t be changed by commands. When Chapter 14 starts talking about #minecraft:logs, remember it means the second kind, a group of block types in a file, not the on/off sticker you learned here.

Quick mental test: red_team on a particular zombie is an entity tag (one entity, on/off, runtime). #minecraft:logs standing for all log blocks is a registry tag (a category of types, defined in a file). Same word, two worlds.

When an entity tag is the right choice

Reach for an entity tag when the thing you want to remember is a simple yes/no flag that belongs to a specific entity. Signs you want a tag:

• You’re marking entities so a later command can find them again: “the mobs in this arena,” “the armor stand that anchors my machine,” “players who already opened the chest.”
• The answer is genuinely on-or-off. There’s no count to keep and no structured data, just is it marked or not?
• The flag should ride along with the entity. Tag a mob and the mark stays with that mob wherever it wanders, with no separate bookkeeping.

If you catch yourself wanting to store a number on the entity, or a list, or several related values, a tag is the wrong tool. That’s a job for the next two tools, which is exactly what the decision guide is about.

The decision guide: which tool for which job?

You now own all three of Part IV’s tools. Here’s how to choose between them. Ask yourself what shape the information is:

A few rules of thumb the table doesn’t spell out:

• Start with the shape of the data, not the system you know best. Old tutorials lean on scoreboards for everything, even things that aren’t numbers, because scoreboards used to be the only flexible option. In current Java Edition that’s the wrong instinct: if the data isn’t a plain integer, command storage is almost always cleaner.
• A flag is not a number. “Has this player finished the quest?” is on/off, so that’s a tag, not a scoreboard objective set to 0 or 1.
• It’s fine to mix them. A real system often uses all three: tags to mark which entities are in play, a scoreboard for the score, and storage for the settings. The three practice systems below each use just one tool so you can feel the difference, but nothing stops you combining them.

Modern Minecraft If you’ve followed older data-pack guides, you’ve probably seen scoreboards used as a catch-all “variable system,” with fake players standing in for strings and flags. That style still works, but it’s no longer how modern packs are built. The split this book teaches (numbers on scoreboards, structured data in command storage, on/off flags as entity tags) matches how current Java Edition data packs are actually written, and it’ll keep your packs far easier to read.

Practice: three systems, one per tool

You’ll now build all three example systems in mypack. Each one is deliberately small; the point is to see the same idea (“remember something”) solved three different ways.

1. A team marker (entity tags)

You already wrote mark_red_team and red_team_glow above, so the tag-based team marker is essentially done. Round it out with a function that reports who’s on the team. The tag=! form is the easy way to count the other side: anything nearby that isn’t red team.

data/mypack/function/team_report.mcfunction

# Announce the two sides
say Red team members nearby:
tag @e[type=minecraft:zombie,tag=red_team,distance=..20] list
say Everyone NOT on red team gets marked blue:
tag @e[type=minecraft:zombie,tag=!red_team,distance=..20] add blue_team

This is the whole shape of a tag system: add to join a group, tag=/tag=! to select members or non-members, remove to leave. No numbers, no files — just labels.

2. A countdown timer (scoreboards)

A timer is a number that changes over time, so it’s a scoreboard job. From Chapter 11 you know how to create an objective and change a holder’s score; here you’ll store the time on a fake player (a made-up score-holder name that isn’t a real player) called #timer, and show it on the sidebar.

First, a setup function that creates the objective and starts the clock at 10:

data/mypack/function/start_timer.mcfunction

# Create the timer objective (safe to run again; errors are harmless if it exists)
scoreboard objectives add mypack_timer dummy
# Show it on the sidebar
scoreboard objectives setdisplay sidebar mypack_timer
# Start the countdown at 10 on a fake player
scoreboard players set #timer mypack_timer 10
say Timer started at 10.

Then a tick step that subtracts one each time it runs. You met the tick function tag in Chapter 11 (mypack/data/minecraft/tags/function/tick.json), so append this function’s id to that file’s values rather than creating a new tick tag:

data/mypack/function/timer_tick.mcfunction

# Subtract 1 from the timer every time this runs
scoreboard players remove #timer mypack_timer 1

mypack/data/minecraft/tags/function/tick.json

{
  "values": [
    "mypack:kill_on_gold",
    "mypack:timer_tick"
  ]
}

(The mypack:kill_on_gold line was already in your tick tag from Chapter 11; you’re adding mypack:timer_tick beside it, not replacing the file.) Run mypack:start_timer and watch the number on the right side of your screen tick down. This is the scoreboard’s home turf: a whole number you can change, compare with /execute if score (Chapter 11), and display, none of which a tag or storage does as neatly.

Try It! Right now the timer keeps counting past zero into negative numbers. With /execute if score from Chapter 11 you can stop it at zero and fire off an event, a great mini-exercise once you’ve finished this chapter.

3. A quest tracker (command storage)

A quest has structure (a stage name, maybe a count of items collected, maybe a list of objectives), so it’s a command-storage job. From Chapter 12 you know that command storage is a general-purpose, namespaced container identified by a resource location like mypack:quest. Here you’ll start a quest by writing a small structured value into storage:

data/mypack/function/quest_start.mcfunction

# Begin the quest: store a stage name and a starting count
data modify storage mypack:quest stage set value "find_the_key"
data modify storage mypack:quest items_collected set value 0
say Quest started: find the key.

Then a function that advances the quest by reading the data back and moving to the next stage:

data/mypack/function/quest_advance.mcfunction

# Move the quest to its next stage and show the stored data
data modify storage mypack:quest stage set value "open_the_door"
data get storage mypack:quest

Run mypack:quest_start, then mypack:quest_advance, and the data get line prints the whole quest object back to you so you can see the structure you’ve stored. Notice what storage gives you that the other two tools don’t: a named value with a stage string and a number side by side, all under one tidy id, with no entity and no fake-player tricks. That’s exactly the “complex or structured data” row of the decision guide.

Three systems, three tools, one lesson: match the tool to the shape of what you’re remembering: a flag, a number, or structured data.

What Can Go Wrong

• The tag selector matches nothing. Tags are case-sensitive, so @e[tag=Red_Team] will not find entities you tagged red_team. Check the exact spelling and capitalization in your /tag add. Also remember every filter in a selector must hold at once: @e[type=minecraft:zombie,tag=red_team] only matches entities that are both zombies and tagged, so if you tagged a skeleton, that bracket skips it.

• You used a tag where you needed a number (or vice versa). If you find yourself adding tags like score_1, score_2, score_3 to fake a count, stop. That’s a scoreboard’s job. And if you set a scoreboard objective to 1 or 0 just to mean “done / not done,” that’s really a flag, so an entity tag is simpler. When a design feels awkward, re-check it against the decision guide: numbers → scoreboard, structured data → storage, on/off → tag.

• You confused the two kinds of tag. Trying to write @e[tag=#minecraft:logs] won’t work: #minecraft:logs is a registry tag (a group of block types, Chapter 14), not an entity tag (a runtime label, this chapter). The tag= selector argument only reads the on/off labels you add with /tag. Keep the two meanings of “tag” apart and this class of bug disappears.

What You Know Now

You can now add a plain on/off label to any entity with tag <targets> add <name>, take it off with remove, and inspect it with list; select labeled entities with @e[tag=...], its negation tag=!, and the empty tag=/tag=! forms; and stack tag filters knowing they all must hold at once. Just as importantly, you can now choose among Part IV’s three tools: command storage for complex or structured data, a scoreboard for an integer you want to count or display, and an entity tag for a simple on/off flag that rides along on a specific entity. And you can tell an entity tag (a runtime sticker on one entity) apart from a registry tag (a file grouping types of things), the distinction that carries you straight into the next chapter, where the other kind of tag takes center stage.

Chapter 14 — Tags: Grouping Things Together

What You’ll Build

Part V is where your data pack stops being mostly commands and starts being mostly files: JSON files that quietly tell the game what things are, what they belong to, and what should happen. The very first of those file types is the tag, and it’s a good place to start, because you’ve secretly been using tags since Chapter 9 without knowing it.

By the end of this chapter you’ll be able to write a JSON file that groups a bunch of blocks (or items, or kinds of mob, or functions) under one name, refer to that whole group with a single # word, extend a built-in Minecraft group by adding your own things to it, and test the result with a command. To prove it works you’ll add a small file to your mypack pack (a block tag called mypack:my_logs) and then write a function that checks whether the block under your feet belongs to it.

This chapter extends the pack you started in Chapter 9, your mypack pack, and uses the test world you’ve used since Chapter 1. It assumes JSON (Chapter 8), the pack’s folder layout and the minecraft:load function tag (Chapter 9), and /execute ... if block ... run from Chapter 4.

First: this is not the tag from last chapter

Chapter 13 ended with a warning, and this chapter is exactly why. The word tag means two completely different things in Minecraft, and we have now arrived at the second one. Before anything else, let’s nail the difference down so it never trips you up.

Modern Minecraft Two unrelated features share the name tag. Tutorials online almost never warn you:

1. Entity tag (Chapter 13) — a runtime label you stick on one specific entity with the /tag command and check with @e[tag=...]. It’s a sticker on a single mob or player, added and removed live while you play. It has no # and lives in no file.
2. Registry tag (this chapter) — a JSON file in your data pack that groups whole types of things: every kind of log block, every kind of plank, a list of functions. You refer to it with a leading #, like #minecraft:logs, and you can’t change it with a command mid-game. You edit the file and /reload.

Quick test: red_team stuck on a particular zombie is an entity tag. #minecraft:logs standing for all log block types is a registry tag. Same word, two worlds. This whole chapter is about the second kind.

The divide is clear: an entity tag is a label applied to a single entity at runtime, while registry tags are applied to entity types and can’t be changed by commands. So from here on, when you see a # in front of a name, think registry tag, a group of types defined in a file, never the on/off sticker from last chapter.

What a registry tag actually is

A registry tag is a named list of game things of one kind, grouped so you can talk about all of them at once. Tags let you group different game elements together; they reference groups of registry entries, so Minecraft treats multiple items, blocks, or entities as a single category. The built-in tag #minecraft:logs, for example, stands for all log blocks at once, so a command or recipe that uses #minecraft:logs automatically applies to oak logs, birch logs, cherry logs, and every other block on the list, with no need to spell each one out.

Two things make tags one of the most useful pieces of a data pack:

• You name a group once and reuse it everywhere. Instead of listing twenty blocks in five different places, you list them once in a tag and point everything at #yourname:yourtag.
• You can change how the game itself behaves by editing its tags. Minecraft’s own rules lean on built-in tags all over the place: which blocks a tool mines faster, which blocks bees pollinate, which mobs burn in sunlight. Add a block to the right vanilla tag in your pack and you bend that rule without touching a single line of the game’s code.

The word “registry” comes back from Chapter 7: a registry is the game’s master list of one kind of thing (all blocks, all items, all entity types, and so on). A registry tag is just a smaller named list picked out of one of those master lists: a group of blocks out of all blocks, a group of items out of all items. That’s why there’s a different kind of tag for each registry.

Where tags live: data/<namespace>/tags/<registry>/

Tags are files in your data pack, and they go in a tags folder. Here is the layout:

mypack/
  pack.mcmeta
  data/
    <namespace>/
      tags/
        function/
          <name>.json      a function tag
        <registry>/
          <name>.json      a tag for that registry

Inside tags/ you make one folder per registry, and its name is the registry’s name. The four you’ll meet in this chapter are:

• tags/block/: block tags, groups of block types (like #minecraft:logs).
• tags/item/: item tags, groups of item types (like #minecraft:planks, used by recipes that accept “any plank”).
• tags/entity_type/: entity type tags, groups of kinds of mob (like a list that means “all zombie types”).
• tags/function/: function tags, groups of functions, including the two special ones we’re about to revisit.

Modern Minecraft Just like the function and recipe folders from Chapter 9, these folder names are singular: block, item, entity_type, function, not blocks/items/tags/functions. Older guides (and old packs) used plural names. If your tag silently does nothing, a plural folder name is the first thing to check.

The tag’s name comes from where the file sits, exactly like every other identifier in the book. A file at data/mypack/tags/block/my_logs.json is the block tag mypack:my_logs. (A file at data/wiki/tags/block/foo/example.json makes the tag wiki:foo/example; subfolders just become part of the path, same as Chapter 8.) To use a tag, you put a # in front of that name: #mypack:my_logs. The # is what tells the game “this is a tag (a whole group), not a single block.”

The JSON inside a tag file

A tag file is a small JSON object with up to two fields. Here’s the simplest possible block tag, a group of three log blocks, saved into your pack:

data/mypack/tags/block/my_logs.json

{
  "replace": false,
  "values": [
    "minecraft:oak_log",
    "minecraft:birch_log",
    "minecraft:spruce_log"
  ]
}

Two fields, and that’s the whole format:

• values is the list, an array (Chapter 8) of names. Each name is a thing you’re putting in the group. Here they’re three block identifiers, so this tag means “oak, birch, or spruce log.”
• replace is a true/false switch we’ll explain in a moment. It’s optional and defaults to false, so you can leave it out, but we’ll write it in for now to make it visible.

A values list can hold three kinds of entry:

1. A plain resource location: the name of a thing to include, like "minecraft:oak_log".
2. Another tag, prefixed with #, which pulls in everything that tag contains. So a values list can contain "#minecraft:planks", meaning “and also every plank.” (Tags referencing tags is allowed and handy; just don’t make a loop where two tags point at each other, which causes a loading failure.)
3. An object with options, for the one special case in the next callout.

Here’s an entry of type 2 in action, a tag that says “all my logs, plus everything already in the vanilla planks group”:

data/mypack/tags/block/my_building_blocks.json

{
  "replace": false,
  "values": [
    "#mypack:my_logs",
    "#minecraft:planks"
  ]
}

Because both entries start with #, this tag is built entirely out of other tags: it folds in your own mypack:my_logs and the built-in minecraft:planks and treats them as one big group. That’s the “name a group once, reuse it everywhere” idea taken one step further: groups made of groups.

Under the Hood The third kind of values entry is an object with two fields, used when you want to list something that might not exist (say, a block from a mod the player may not have installed):

{
  "values": [
    { "id": "mypack:future_block", "required": false }
  ]
}

Here, id is the name (in any of the formats above), and required decides whether the whole tag fails to load if that entry is missing. It’s true by default; setting it to false means “skip this one quietly if it isn’t found” instead of breaking the tag. You won’t need this often as a beginner, but it’s why you sometimes see entries written as objects rather than plain strings. (Skippable.)

The big reveal: load and tick were tags all along

Open up your pack and look at a file you wrote back in Chapter 9:

data/minecraft/tags/function/load.json

{
  "values": [
    "mypack:load",
    "mypack:score_setup"
  ]
}

Look at the path. Look at the contents. It’s a file in tags/function/, with a values list of function names. It’s a registry tag (a function tag), and you’ve been writing them since your very first data pack. You just didn’t have the word for it yet.

Here’s what these two special function tags do: functions tagged in the minecraft:tick tag run every tick at the start of the tick, and functions tagged in minecraft:load run once at the start of the tick after a server (re)load. That’s exactly the behavior you’ve relied on. The file at data/minecraft/tags/function/load.json is the minecraft:load tag (it’s in the minecraft namespace because that’s the folder it sits in), and listing mypack:load in its values is how you told the game “run my load function when the pack loads.” Same machinery for the tick tag you started in Chapter 11:

data/minecraft/tags/function/tick.json

{
  "values": [
    "mypack:kill_on_gold",
    "mypack:timer_tick"
  ]
}

Every function you’ve ever hooked into “run on load” or “run every tick” you did by adding its name to a values list in a function tag. The only thing new in this chapter is the name for what you were doing, plus the fact that the same trick works for blocks, items, and mob types too.

Under the Hood Function tags run their functions in the order of their first appearance in a tag, and if the same function is listed twice (directly or through a sub-tag) it still runs only once. For load and tick that ordering is the one place where the order of a tag’s values actually matters. For most tags (which only ever get asked “is this thing in the group, yes or no?”) the order is irrelevant. (Skippable.)

Extending a vanilla tag vs. replacing it

Now back to that replace field, because it controls the single most powerful thing tags can do: quietly add your stuff to a built-in Minecraft group.

Here’s the key rule. When two data packs (and remember, vanilla itself is a data pack) define a tag with the same name:

• If replace is false (or left out, which is the default), your values are added on top of what’s already there. You extend the group.
• If replace is true, your tag completely replaces the lower-priority one. You wipe out everything that was in it and start fresh with only your values.

So to add a block to a vanilla tag, you make a file with the same name as the vanilla tag (same namespace, same path) and leave replace off. Watch: this adds cherry logs to Minecraft’s own #minecraft:logs group, without disturbing the dozens of logs already in it:

data/minecraft/tags/block/logs.json

{
  "replace": false,
  "values": [
    "minecraft:cherry_log"
  ]
}

Notice the namespace is minecraft, not mypack: the file lives at data/minecraft/tags/block/logs.json because it’s the minecraft:logs tag you’re extending. With replace false, oak, birch, spruce, and the rest stay exactly where they are; your one line just joins the party. From now on, anything in the game that checks #minecraft:logs will treat cherry logs as a log too.

Flip replace to true and the meaning changes completely:

data/minecraft/tags/block/logs.json

{
  "replace": true,
  "values": [
    "minecraft:cherry_log"
  ]
}

This version says “#minecraft:logs now means only cherry log, forget everything else.” Every other log type falls out of the tag, and any game behavior tied to #minecraft:logs suddenly ignores them. That’s almost never what you want for a vanilla tag, but it’s exactly what you want when you’re defining your own fresh tag and don’t care about merging with anything. Rule of thumb: extend (false / leave it off) when touching a vanilla tag; only reach for replace: true when you mean to throw the old contents away.

A few vanilla tags worth knowing, all real groups you can extend or point at:

• #minecraft:logs: every log block.
• #minecraft:planks: every plank block (and the matching item tag is used by recipes that take “any plank”).
• #minecraft:leaves, #minecraft:wool: leaves and wool blocks.
• #minecraft:swords: the item tag grouping all swords.

Walkthrough: build and test a block tag

Let’s put it all together. You’ll make a block tag and then write a command that checks it.

Step 1 — create the tag. If you followed along above, you already have it; if not, save this:

data/mypack/tags/block/my_logs.json

{
  "replace": false,
  "values": [
    "minecraft:oak_log",
    "minecraft:birch_log",
    "minecraft:spruce_log"
  ]
}

Step 2 — write a function that tests it. Back in Chapter 4 you learned /execute ... if block ... run, which checks the block at a position. The block you test for can be a single block ID or a block tag, and to use a tag you write it with a #, just like everywhere else. This function checks whether the block one space below you is in your my_logs group:

data/mypack/function/tag_check.mcfunction

# Is the block under my feet one of my logs?
execute if block ~ ~-1 ~ #mypack:my_logs run say Standing on a my_logs block!

The position ~ ~-1 ~ is “right where I am, but one block down” (relative coordinates from Chapter 2), and #mypack:my_logs is your tag. The command succeeds (and the say runs) only if the block down there is oak, birch, or spruce log, because those are the three types your tag groups.

Step 3 — try it. Run /reload so the game reads your new files, place an oak log, stand on top of it, and run the function from chat with /function mypack:tag_check. You should see the message. Step off onto plain dirt and run it again: silence, because dirt isn’t in the tag. One tag, three block types, one tidy check.

Figure (to be captured). chat shows “Standing on a my_logs block!” after running mypack:tag_check while the player stands on top of an oak log block

Try It! Add a fourth log to your tag’s values (say "minecraft:cherry_log"), /reload, and your same tag_check function now recognizes cherry logs too. You changed what the check matches without touching the function at all. That’s the whole point of tags: edit the group in one place, and everything that points at #mypack:my_logs updates at once.

Practice

1. Make an item tag. Create data/mypack/tags/item/my_gems.json grouping "minecraft:diamond" and "minecraft:emerald". Item tags can be searched in the Creative inventory by typing #mypack:my_gems in the search box; try it and watch both gems appear.

2. Extend a real vanilla group. Pick a vanilla tag from the list above and add a block to it the extend way (matching namespace and path, replace left off). For example, drop something into data/minecraft/tags/block/wool.json. /reload and confirm the original contents are still there by checking a block that was already in the tag.

3. Build a tag out of tags. Write a block tag whose values are nothing but two # references (one to your own mypack:my_logs and one to a vanilla tag) and use it in a tag_check-style function. Confirm that the combined group matches blocks from both source tags.

What Can Go Wrong

• You forgot the #. Inside a command, #mypack:my_logs means “the tag,” but mypack:my_logs with no # means “a single block named mypack:my_logs,” which doesn’t exist, so the command errors or never matches. The # is what turns a name into a group. (And the opposite mistake from last chapter: don’t put a # on an entity tag; @e[tag=red_team] never takes one.)

• replace: true wiped a vanilla tag. If a built-in behavior suddenly stops working after you edited a vanilla tag (bees ignoring your flowers, a tool no longer mining fast), check whether you left replace set to true. On a vanilla tag that throws away everything the game put there. Switch it to false (or delete the line) so your entry is added instead of substituted, then /reload.

• Wrong folder, or a plural folder name. A block tag must sit in tags/block/, an item tag in tags/item/, and so on. Put it in the wrong registry folder and it groups the wrong kind of thing (or nothing). And the folder names are singular: tags/block/, never tags/blocks/. A silently-ignored tag is almost always a misspelled or mis-pluralized folder.

• An entry doesn’t exist and the whole tag breaks. If a name in values points at something the game can’t find, loading the tag fails. Either fix the spelling, or, if it’s deliberately optional, use the object form { "id": "...", "required": false } so that one missing entry is skipped instead of breaking the rest.

What You Know Now

You can now write a registry tag: a JSON file under data/<namespace>/tags/<registry>/ that groups types of things (blocks, items, entity types, or functions) under one name you address with a #. You know the format is just values (the list) and an optional replace flag; that values entries can be plain names, other tags prefixed with #, or { "id": ..., "required": false } objects; and that replace: false extends a tag while replace: true replaces it, which is how you safely add your own blocks to Minecraft’s own groups. You finally know what those load.json and tick.json files have been all along: function tags, the same mechanism wearing a special name. And you can test a block tag in-game with /execute if block ~ ~-1 ~ #mypack:my_logs. Tags are the quiet backbone of the declarative files coming next (recipes, loot tables, advancements, and more all lean on them), so this is the tool that makes the rest of Part V click.

Chapter 15 — Recipes

What You’ll Build

Way back in Chapter 9 you wrote a single recipe: a chainmail helmet crafted from iron nuggets. It worked, it showed up in the recipe book, and then you moved on. That recipe used just one of the many kinds of recipe Minecraft understands. This chapter opens the whole box.

By the end you’ll be able to add almost any kind of recipe to the pack you started in Chapter 9, your mypack pack. You’ll write shaped and shapeless crafting recipes; smelting, blasting, smoking, and campfire cooking recipes (with their own cook times and experience rewards); stonecutting recipes; both kinds of smithing recipe; the special transmute and dye recipes; and you’ll make any of them accept “any kind of wood” or “any copper ore” by feeding them the registry tags you learned in Chapter 14. You’ll also learn how to remove a vanilla recipe you don’t want, and how to control where your recipes appear in the recipe book.

This chapter extends the mypack pack from Chapter 9 and uses the test world you set up in Chapter 8. It assumes you know the recipe/ folder and the shaped recipe from Chapter 9, and registry tags (#namespace:path) from Chapter 14.

Modern Minecraft Every recipe in this chapter puts its output in a result object whose item-ID field is named id. Older tutorials (and packs written before this changed) use a field called item instead. If you copy a recipe off the internet and it doesn’t load, the first thing to check is whether it says "item": where it should say "id":. Throughout this book we always use id.

Where recipes live (a quick recap)

Every recipe is a single JSON file. Your custom recipe files go in the recipe folder of your namespace: a recipe with the ID mypack:path/to/file lives at data/mypack/recipe/path/to/file.json inside the pack. That’s exactly where the Chapter 9 helmet recipe sits. Vanilla’s own recipes live in the same kind of place but under the minecraft namespace (data/minecraft/recipe/...), a fact we’ll use later in this chapter to switch one off.

Every recipe file, no matter its kind, is a JSON object with one field in common: a string called type. The type tells the game which shape of recipe this is (shaped crafting, smelting, stonecutting, and so on) and therefore which other fields it should expect. Get the type right and the rest of the file follows from it. The sections below are organized one type at a time.

Shaped crafting, revisited

A shaped crafting recipe is one where the ingredients have to be arranged in a particular shape on the crafting grid. The helmet you made in Chapter 9 is one: the iron nuggets have to sit in an upside-down-U shape or the recipe won’t match. Here it is again, unchanged, so we have something to build on:

mypack/data/mypack/recipe/chainmail_helmet.json

{
  "type": "minecraft:crafting_shaped",
  "category": "equipment",
  "pattern": [
    "NNN",
    "N N"
  ],
  "key": {
    "N": "minecraft:iron_nugget"
  },
  "result": {
    "id": "minecraft:chainmail_helmet",
    "count": 1
  }
}

Let’s read it slowly, because the two fields that make it shaped (pattern and key) work together as a pair.

pattern is a list of strings, one per row of the crafting grid. Each string is a row, and each character in the string is one grid slot. The recipe above has two rows, "NNN" and "N N", so it uses a 3-wide, 2-tall area of the grid. Every string in the list must be the same length. A row can be 1, 2, or 3 characters wide, and you can have 1, 2, or 3 rows.

key is an object that says what each character means. Here, the single key N maps to minecraft:iron_nugget. Any single character may be used as a key except the space character: a space in the pattern always means “this slot must be empty.” That’s why "N N" has a real gap in the middle: the helmet has a hole in its bottom row.

The category field is new compared to Chapter 9’s bare version. It controls which tab the recipe shows up under in the recipe book. For crafting recipes the allowed values are equipment, building, misc, and redstone; if you leave category out, it defaults to misc. Armor is equipment, so the helmet sits in the equipment tab.

The result object is the output. Its id is the item the recipe makes, and the optional count is how many you get. If you leave count out, you get 1. We’ve written "count": 1 explicitly here just to show where it goes.

Try It! Change the result’s count to 4 and /reload. Now one grid of nuggets gives you four helmets. Silly, but it proves the field works. Set it back to 1 when you’re done.

Grouping recipes with group

There’s one more optional field worth knowing for crafting recipes: group. It’s a plain string identifier, and recipes that share the same group are bundled together into a single entry in the recipe book instead of cluttering it with near-duplicates. Vanilla uses this for things like all the different wooden planks, which share a planks group. You don’t have to use it, but it keeps a busy recipe book tidy. (A subtle detail: if two recipes share a group but have different category values, the game splits them back into two groups, so keep the category the same across a group.)

Shapeless crafting

A shapeless crafting recipe doesn’t care where the ingredients sit on the grid, only that they are all present. The classic example is flint and steel: you need one iron ingot and one piece of flint, and it doesn’t matter which slots they go in. Its type is minecraft:crafting_shapeless, and instead of pattern/key it has a single list field called ingredients:

mypack/data/mypack/recipe/flint_and_steel.json

{
  "type": "minecraft:crafting_shapeless",
  "category": "equipment",
  "ingredients": [
    "minecraft:iron_ingot",
    "minecraft:flint"
  ],
  "result": {
    "id": "minecraft:flint_and_steel",
    "count": 1
  }
}

The ingredients list must have at least one and at most nine entries, one for every slot in the 3×3 grid. Each entry is one ingredient that must appear somewhere in the grid. The same category values, the optional group, and the same result shape (id + optional count) all work exactly as they did for shaped recipes.

Under the Hood There’s a small quirk worth knowing: if a shapeless recipe lists the same nine ingredients as a shaped recipe’s full grid, the game effectively treats it as the shaped one. You’ll almost never hit this; it’s here so the behavior doesn’t surprise you. Skippable.

Ingredients, three ways

So far every ingredient has been a single item ID like "minecraft:iron_ingot". But anywhere a recipe asks for an ingredient, you actually have three ways to write it. This is the same in every recipe type, so learning it once pays off everywhere.

1. A single item ID: a plain string, the form you’ve already seen:

"minecraft:iron_ingot"

2. A tag, written with a leading #. This is where Chapter 14 pays off. A #tag means “any item in this group counts.” Remember from Chapter 14 that a registry tag is a named group of types; #minecraft:planks is the built-in group of every plank variant. Use it as an ingredient and your recipe accepts oak, birch, spruce, or any other plank without you listing them:

"#minecraft:planks"

3. An array of IDs: a JSON list of specific item IDs, meaning “any one of exactly these”:

["minecraft:oak_planks", "minecraft:spruce_planks"]

The difference between forms 2 and 3 is how you choose the set. A #tag borrows an existing group (or one you defined yourself in Chapter 14) and stays in sync with it. An array spells out an exact short list right there in the recipe. Use a tag when a sensible group already exists; use an array when you want just two or three specific items and don’t want to make a whole tag file for them.

Here’s a shapeless recipe that uses a tag ingredient, a custom “wooden button” that accepts any plank:

mypack/data/mypack/recipe/any_plank_button.json

{
  "type": "minecraft:crafting_shapeless",
  "category": "redstone",
  "ingredients": [
    "#minecraft:planks"
  ],
  "result": {
    "id": "minecraft:oak_button",
    "count": 1
  }
}

And the same idea with an explicit array, accepting only oak or spruce:

mypack/data/mypack/recipe/oak_or_spruce_button.json

{
  "type": "minecraft:crafting_shapeless",
  "category": "redstone",
  "ingredients": [
    ["minecraft:oak_planks", "minecraft:spruce_planks"]
  ],
  "result": {
    "id": "minecraft:oak_button",
    "count": 1
  }
}

Notice the array in the second file is nested inside the ingredients list: ingredients is the outer list (one entry per grid slot), and that one entry is itself the little array of acceptable items. In a shaped recipe you’d do the same thing inside key: a key can map to a single ID, a #tag, or an array, just like an ingredient. The three forms are completely interchangeable everywhere an ingredient is asked for.

What Can Go Wrong Forgetting the # on a tag is the most common recipe mistake. "minecraft:planks" (no hash) tells the game to look for an item literally named planks, which doesn’t exist, so the recipe fails to load. "#minecraft:planks" (with hash) tells it to look for the tag. One character, big difference, and Chapter 10’s game log will report the bad recipe if you miss it.

Cooking: smelting, blasting, smoking, and campfire

Furnaces, blast furnaces, smokers, and campfires all run on recipes too. They share almost the same shape, differing mainly in their type string and their default cook time:

• minecraft:smelting — a regular furnace.
• minecraft:blasting — a blast furnace (ores and metal things).
• minecraft:smoking — a smoker (food).
• minecraft:campfire_cooking — a campfire.

A cooking recipe takes a single ingredient (written in any of the three ingredient forms above), turns it into a result, and adds two optional numbers: cookingtime and experience.

Here’s a smelting recipe that turns stone bricks into cracked stone bricks:

mypack/data/mypack/recipe/cracked_stone_bricks.json

{
  "type": "minecraft:smelting",
  "category": "blocks",
  "ingredient": "minecraft:stone_bricks",
  "cookingtime": 200,
  "experience": 0.1,
  "result": {
    "id": "minecraft:cracked_stone_bricks"
  }
}

cookingtime is how long the item takes to cook, measured in ticks (the game runs 20 ticks per second, as you learned in Chapter 7, so 200 ticks is 10 seconds). It’s optional. If you leave it out, smelting defaults to 200 ticks, while blasting, smoking, and campfire_cooking default to 100 ticks. Blast furnaces and smokers run hotter, so even their default is faster.

experience is how much experience the player gets when they collect the cooked item. It’s a decimal number and it’s optional. A small detail to remember: campfires never drop experience, so an experience field on a campfire_cooking recipe simply does nothing.

Notice what the cooking result does not have: a count. Cooking recipes always produce one output item, so their result only ever has id (and, optionally, components, more on that later). Adding a count here won’t help. This is different from crafting and stonecutting, where count is allowed.

The category choices differ a little by machine. Smelting allows food, blocks, and misc (default misc); blasting allows blocks and misc; smoking and campfire both allow only food (default food). For campfires the category and group fields are accepted but do nothing, because campfires have no recipe book.

Here’s a campfire example (baking a potato over a fire) showing the longer cook time vanilla uses:

mypack/data/mypack/recipe/campfire_baked_potato.json

{
  "type": "minecraft:campfire_cooking",
  "category": "food",
  "ingredient": "minecraft:potato",
  "cookingtime": 600,
  "experience": 0.35,
  "result": {
    "id": "minecraft:baked_potato"
  }
}

Stonecutting

A stonecutting recipe is the simplest of all. You put one ingredient into a stonecutter, pick the output from the menu, and it converts instantly: no shape, no cook time, no experience. Its type is minecraft:stonecutting, and it has just two fields you care about: an ingredient and a result. There’s no category or group for stonecutting at all.

mypack/data/mypack/recipe/deepslate_to_stairs.json

{
  "type": "minecraft:stonecutting",
  "ingredient": "minecraft:cobbled_deepslate",
  "result": {
    "id": "minecraft:cobbled_deepslate_stairs",
    "count": 1
  }
}

Stonecutting result objects can carry a count, unlike cooking. That’s handy when one input should yield several outputs.

We’ll come back to stonecutting in the Practice section, where you’ll build a small family of stonecutter recipes for block variants.

Smithing: two very different recipes

The smithing table runs two completely different kinds of recipe, and it’s important not to mix them up. They have different type strings and do different jobs:

• minecraft:smithing_transform: changes the base item into a new item. This is how a diamond axe becomes a netherite axe.
• minecraft:smithing_trim: decorates the base item with an armor trim, leaving it the same item with a new pattern stamped on. This is how you add a trim to a chestplate.

Both share three ingredient slots, named for where they sit in the smithing table:

• template: the smithing template item (optional).
• base: the item being upgraded or trimmed.
• addition: the material being added (optional).

smithing_transform — upgrading an item

mypack/data/mypack/recipe/netherite_axe.json

{
  "type": "minecraft:smithing_transform",
  "template": "minecraft:netherite_upgrade_smithing_template",
  "base": "minecraft:diamond_axe",
  "addition": "#minecraft:netherite_tool_materials",
  "result": {
    "id": "minecraft:netherite_axe"
  }
}

A smithing_transform recipe has a result, the new item it produces. The important behavior is that the result copies the components of the base item. So if your diamond axe was enchanted and nearly worn out, the netherite axe that comes out keeps those enchantments and that damage. The addition here uses a #tag ingredient, so any item in the netherite_tool_materials group works.

smithing_trim — stamping a trim

mypack/data/mypack/recipe/silence_trim.json

{
  "type": "minecraft:smithing_trim",
  "template": "minecraft:silence_armor_trim_smithing_template",
  "base": "#minecraft:trimmable_armor",
  "addition": "#minecraft:trim_materials",
  "pattern": "minecraft:silence"
}

The big difference: a smithing_trim recipe has no result field at all. It doesn’t make a new item; it adds the trim’s pattern onto whatever armor went in as the base. Which trim it applies is named by the pattern field (here, minecraft:silence). The base and addition use #tags so the recipe works for any trimmable armor and any trim material. If you write a smithing_trim recipe and try to give it a result, you’ve accidentally written it like a transform. They are not interchangeable.

What Can Go Wrong The two smithing types look similar but answer different questions. Transform answers “what new item does this become?”, so it needs a result. Trim answers “which pattern goes on this armor?”, so it needs a pattern and no result. Pick the type by the question you’re answering.

Transmute and dye: two special crafting types

Two more crafting-table recipe types do things the basic shaped/shapeless types can’t, because they carry information from the input over to the output.

crafting_transmute — change the item, keep its components

A transmute recipe (minecraft:crafting_transmute) changes one item into another while preserving all of the input’s components. Vanilla uses it to re-dye a shulker box: you put in any shulker box plus a dye, and out comes the recolored box with everything still inside it, because the contents are components that get copied across.

It has three fields beyond type: an input (the item to copy), a material (an extra ingredient consumed alongside it), and a result:

mypack/data/mypack/recipe/blue_shulker_box.json

{
  "type": "minecraft:crafting_transmute",
  "category": "misc",
  "group": "shulker_box_dye",
  "input": "#minecraft:shulker_boxes",
  "material": "minecraft:blue_dye",
  "result": {
    "id": "minecraft:blue_shulker_box"
  }
}

The input here is a #tag (any shulker box), the material is a specific dye, and the result is the blue box, which keeps whatever the input box was holding.

crafting_dye — the armor-dyeing recipe

A dye recipe (minecraft:crafting_dye) is the special type behind dyeing leather armor and similar items. It has a target (the item this recipe applies to), a dye ingredient (which dyes are allowed), and a result:

mypack/data/mypack/recipe/dye_leather_horse_armor.json

{
  "type": "minecraft:crafting_dye",
  "category": "misc",
  "group": "dyed_armor",
  "dye": "#minecraft:dyes",
  "target": "minecraft:leather_horse_armor",
  "result": {
    "id": "minecraft:leather_horse_armor"
  }
}

The dye ingredient uses the #minecraft:dyes tag, so any dye works. For this recipe to match, the item being dyed must have the dye-able minecraft:dye component, a detail we won’t go deeper on until components get their own chapter.

What can go on a result

You’ve now seen the two optional result fields several times. Here they are collected in one place:

• count: how many copies of the item the recipe produces. Allowed on crafting and stonecutting and smithing-transform results; defaults to 1. Not used on cooking results, which always make exactly one item.
• components: extra data attached to the resulting item, like a custom name, enchantments, or what’s stored inside it.

We won’t unpack components fully here; they get their whole own chapter (Chapter 21). For now, just know the field exists and where it goes. A result with components looks like this in outline:

"result": {
  "id": "minecraft:diamond_sword",
  "count": 1,
  "components": { }
}

Under the Hood A few crafting recipes are not data-driven at all — things like copying a written book or a map, or dyeing armor with several dyes at once. Those use built-in type names that start with crafting_special_ (and there’s a crafting_decorated_pot too). You can’t really author these yourself; they exist so that, if you ever turn off the vanilla data pack, you can switch the built-in recipes back on one by one. You won’t need them for your own recipes. Skippable.

Removing a vanilla recipe

Sometimes you want to make an existing recipe go away instead of adding one. Maybe your pack replaces wooden swords with something custom and you don’t want players crafting the plain one.

The trick relies on how packs overlap. The rule is simple: data packs that load later, with a recipe file at the same resource location, replace the existing recipe. Vanilla’s wooden-sword recipe lives at data/minecraft/recipe/wooden_sword.json. If your pack contains a file at that exact same path (under the minecraft namespace, not mypack), your version wins, because your pack loads after the built-in vanilla pack.

So to disable the wooden sword recipe, put a file at the matching path that defines a recipe which can never be crafted: for example one whose ingredient is an item the player can’t reasonably get, or simply a different, harmless recipe. The cleanest approach players use is to overwrite it with a recipe that produces something trivial. Here’s an override that turns the wooden-sword slot into a recipe requiring a barrier block (a block normal players never have):

mypack/data/minecraft/recipe/wooden_sword.json

{
  "type": "minecraft:crafting_shapeless",
  "category": "misc",
  "ingredients": [
    "minecraft:barrier"
  ],
  "result": {
    "id": "minecraft:wooden_sword",
    "count": 1
  }
}

Because this file sits at vanilla’s resource location and your pack loads later, it replaces vanilla’s wooden-sword recipe. The original recipe is gone; only your (effectively uncraftable) version remains.

Good to Know Overriding a recipe at its resource location, as shown here, is the supported way to take a vanilla recipe out of play: same path, later pack wins. There’s no separate “delete this recipe” or empty-file syntax to learn; the override-with-a-dummy recipe is the clean, intended approach.

Modern Minecraft A recipe being in the game and a recipe being unlocked in your recipe book are two separate things. Players can craft any loaded recipe whose ingredients they hold, whether or not it’s been “discovered,” unless a world turns on the doLimitedCrafting game rule; then only unlocked recipes can be crafted. You can hand out a recipe with the /recipe give command, but most packs let advancements unlock recipes automatically; that’s a Chapter 19 topic.

Practice: a stonecutter for custom block variants

Time to build something. Imagine mypack adds a decorative theme based on polished blackstone, and you want the stonecutter to offer a tidy little family of cuts from a single block of polished blackstone bricks. Stonecutting is perfect for this: one input, many possible outputs, instant conversion.

Make three stonecutting recipes. Each takes minecraft:polished_blackstone_bricks and produces a different variant.

mypack/data/mypack/recipe/blackstone_brick_slab.json

{
  "type": "minecraft:stonecutting",
  "ingredient": "minecraft:polished_blackstone_bricks",
  "result": {
    "id": "minecraft:polished_blackstone_brick_slab",
    "count": 2
  }
}

mypack/data/mypack/recipe/blackstone_brick_stairs.json

{
  "type": "minecraft:stonecutting",
  "ingredient": "minecraft:polished_blackstone_bricks",
  "result": {
    "id": "minecraft:polished_blackstone_brick_stairs",
    "count": 1
  }
}

mypack/data/mypack/recipe/blackstone_brick_wall.json

{
  "type": "minecraft:stonecutting",
  "ingredient": "minecraft:polished_blackstone_bricks",
  "result": {
    "id": "minecraft:polished_blackstone_brick_wall",
    "count": 1
  }
}

Notice the slab recipe produces a count of 2: one brick block cuts into two slabs, which matches how Minecraft normally trades blocks for slabs. The stairs and wall give one each.

Now load it:

1. Save all three files.
2. In your test world, run /reload (typed in chat, with the slash) to re-read the pack.
3. Open a stonecutter, place a polished blackstone brick block in it, and you should see all three cuts offered. Pick one.

Figure (to be captured). a stonecutter menu showing the three polished-blackstone-brick variants — slab, stairs, and wall — offered from a single input block

Try It! Give one of your stonecutting recipes a #tag ingredient instead of the single block ID. If you made a custom tag in Chapter 14 that groups several “brick”-style blocks, point the recipe at #mypack:your_tag and a single stonecutter recipe will now accept any of them.

What Can Go Wrong

You wrote "item" instead of "id" in the result. This is the number-one recipe bug, especially when copying older tutorials. The modern field name is id. A recipe with "item": in its result won’t load; Chapter 10’s game log will flag it on /reload.

You put a count on a cooking result. Smelting, blasting, smoking, and campfire results take only id (and optional components), never count. They always make one item. If you expected a cooking recipe to output a stack, that isn’t how cooking works.

You forgot the # before a tag. "#minecraft:planks" is the tag (any plank); "minecraft:planks" (no hash) is read as an item literally named “planks,” which doesn’t exist, so the recipe silently fails to load. Whenever an ingredient should mean “any of a group,” check for the hash.

You mixed up the two smithing types. A smithing_trim recipe must not have a result; a smithing_transform recipe must. If your trim recipe isn’t trimming, check that you used minecraft:smithing_trim with a pattern and no result.

What You Know Now

You can now write recipes of every major family: shaped and shapeless crafting; smelting, blasting, smoking, and campfire cooking (with cook times and experience); stonecutting; both smithing_transform and smithing_trim; and the special crafting_transmute and crafting_dye types. You know the three ways to write any ingredient (a single ID, a #tag that borrows a Chapter-14 group, or an array of IDs) and that those forms are interchangeable everywhere. You can set a recipe’s category and group to place it neatly in the recipe book, put a count on the results that allow one, and even remove a vanilla recipe by overriding its file path. You used all of this to give mypack a stonecutter family for custom block variants. The one thing we deferred, the components you can attach to a result, gets its own chapter soon, when you learn what data components really are.

Chapter 16 — Loot Tables: Pools, Entries, and Weights

What You’ll Build

Every time a chest in a dungeon hands you a surprise, a zombie drops rotten flesh, or your fishing rod hooks an enchanted book, Minecraft is reading a loot table, a JSON file that decides which items appear in that situation. In this chapter you’ll learn how a loot table is put together, and then you’ll write one of your own: a treasure chest for your mypack pack that almost always gives a common item but, once in a while, drops something rare.

By the end you’ll be able to read and write the three nested pieces every loot table is built from (pools, a group of possible drops; entries, the individual things that can drop; and weight, the dial that makes some entries rarer than others), and you’ll know how to make a count exact, random within a range, or random-but-clustered using a number provider.

This chapter leans on the registry tags you learned in Chapter 14 (those #namespace:path groups of item types, like #minecraft:planks) because a loot table can drop a whole tag at once. It extends the mypack pack you started in Chapter 9 and uses the test world from Chapter 1. Loot tables can do even more than choosing items: they can attach conditions (“only if killed by a player”) and run functions (“set the count to 3, add an enchantment”). Those two powers are big enough to get their own chapter, so we’ll preview them at the end and teach them properly in Chapter 17. This chapter is about getting the structure rock-solid first.

What a loot table is, and what it controls

A loot table is a technical JSON file used to dictate what items should generate in various situations, such as what items should be in naturally generated containers, what items should drop when breaking a block or killing a mob, what items can be fished, and more. One file, asked over and over, “what items come out this time?”

The “situation” a loot table runs in has a name: it’s called the loot context. You don’t have to memorize the list, but it’s worth seeing how many corners of the game loot tables quietly run. A loot table can be invoked for:

• Container contents: opening a barrel, chest, trapped chest, hopper, minecart with chest, boat with chest, minecart with hopper, dispenser, dropper, shulker box, dyed shulker box, or decorated pot.
• Mob drops: the loot from a living entity’s death.
• Block drops: the items dropped when mining a block (or when a block is exploded).
• Fishing: the items obtained via fishing.
• Gifts: a gift from a cat, villager, or sniffer, and the item laid by a chicken.
• Archaeology: using a brush on suspicious sand or suspicious gravel that has a loot table.

There are more (bartering with piglins, shearing certain mobs, vault loot, advancement rewards), but those six cover the situations a beginner meets first. The important takeaway: a chest’s loot and a zombie’s drops are data, and data packs can change or add them.

Modern Minecraft A few drops are not loot tables. Loot tables do not affect dropped experience, and don’t cover dropped non-item entities such as slimes from larger slimes or silverfish from infested blocks. Some unbreakable blocks (bedrock, end portals) have no loot table at all, and a few drops like the wither’s nether star are handled specially. If a drop seems to ignore your loot table, it may be one of these exceptions.

Where loot tables live

Like every other kind of file in a data pack, a loot table lives in a fixed folder. Loot tables are defined using JSON files stored within a data pack in the path data/<namespace>/loot_table.

So inside your mypack pack, your loot tables go here:

mypack/data/mypack/loot_table/

Just like the function, recipe, and tags/function folders you’ve already used, the folder name is singular: loot_table, not loot_tables. (Older tutorials from before the great folder-renaming will show you the plural. It won’t work today. See “What Can Go Wrong.”)

The shape of a loot table: pools

The top level of a loot table file is a JSON object. The field that does the real work is pools, a list of all pools for this loot table. Pools are applied in order.

A pool is one group of possible drops. Think of a pool as a single bag you reach into. A loot table can have several bags (several pools), and when the loot table runs, it reaches into every bag. Here’s the smallest useful loot table: one pool, holding one possible drop.

mypack/data/mypack/loot_table/treasure_chest.json

{
  "pools": [
    {
      "rolls": 1,
      "entries": [
        {
          "type": "minecraft:item",
          "name": "minecraft:bread"
        }
      ]
    }
  ]
}

Notice pools is an array (square brackets) because there can be more than one pool, and inside it each pool is its own object. Two fields appear in that pool, and they’re the heart of this whole chapter: rolls and entries.

Rolls: how many times you reach in

The rolls field is a number provider that specifies the number of rolls on the pool. A roll is one draw: in each roll of a pool, the pool draws one entry from all its entries, and each roll of a pool is independent. So "rolls": 1 means reach into this bag once and pull out one entry. "rolls": 3 would reach in three separate times, and because each roll is independent, you could pull the same entry more than once.

For now we’re writing rolls as a plain number. Later in the chapter you’ll see that rolls can also be a random count, which is where number providers come in.

Entries: what’s in the bag

The entries field is the list of things that could come out of a pool. One loot entry is chosen per roll as a weighted random selection from all loot entries in the pool. So each roll picks exactly one entry from this list. Get the list right and you control everything the pool can produce.

The four entry types

Every entry has a type field, a resource location naming what kind of entry it is. There are several types; this chapter uses the four most useful ones. Each is shown below as a complete entry object.

item — drop one specific item. It drops a single item stack (the default is a stack of 1 of the item). It needs a name field, the resource location of the item:

{
  "type": "minecraft:item",
  "name": "minecraft:diamond"
}

tag — drop items from a registry tag. This is where Chapter 14 pays off. The tag entry’s name is “the resource location of the item tag to query, e.g. minecraft:arrows.” It has a second field, expand, a true/false switch:

{
  "type": "minecraft:tag",
  "name": "minecraft:arrows",
  "expand": false
}

Here’s what the switch does precisely. With "expand": false it is a singleton entry that drops all items in the tag: pick this entry on a roll and you get one of each item in the tag. With "expand": true it provides one singleton entry per item in the tag with the same weight, so the tag fans out and the roll picks just one item from the tag at random. For a treasure chest you almost always want true, so each roll gives a single random arrow type rather than every arrow at once.

loot_table — drop the result of another loot table. This lets you reuse a table inside another. Its field is value, the loot table to be used. Point it at one of your own tables, for example a mypack:rare_drops table you’ve written in the same loot_table folder:

{
  "type": "minecraft:loot_table",
  "value": "mypack:rare_drops"
}

One rule: the value cannot be the ID of the current loot table file. Recursive calling is not allowed, so a table can’t include itself, or you’d get an infinite loop.

empty — drop nothing. It drops nothing, and takes no extra fields:

{
  "type": "minecraft:empty"
}

An empty entry sounds pointless, but it’s the secret to making a pool sometimes give nothing, which you’ll use in a moment.

Weight: making some entries rarer

If a pool has several entries, how does it choose between them on each roll? By weight. Every item (and tag) entry can carry a weight field. It determines how often this singleton entry is chosen out of all the singleton entries in the pool: entries with higher weights are used more often. If you leave weight off, it defaults to 1.

The exact rule is a simple fraction:

The chance of an entry being chosen is [this entry’s weight ÷ total weight of all entries in the pool].

So weight is a share, not a percentage. Suppose a pool has three entries with weights 10, 1, and

1. The total weight is 12, so the first entry is chosen 10⁄12 of the time (about 83%), and the other two are 1⁄12 each (about 8%). Want something rarer? Give it a smaller weight relative to the others. Here’s a pool that hands out bread most of the time and a diamond rarely:

{
  "rolls": 1,
  "entries": [
    {
      "type": "minecraft:item",
      "name": "minecraft:bread",
      "weight": 20
    },
    {
      "type": "minecraft:item",
      "name": "minecraft:diamond",
      "weight": 1
    }
  ]
}

The total weight is 21, so each roll gives bread 20⁄21 of the time and a diamond 1⁄21 of the time, roughly a 1-in-21 treasure.

Try It! Add a third entry to that pool, an empty entry with "weight": 9. Now the totals are bread 20, empty 9, diamond 1 (total 30), so a roll gives nothing 9⁄30 (about 30%) of the time. Mixing in empty is exactly how vanilla chests leave some slots blank.

Number providers: exact, range, or clustered

Back to rolls. So far it’s been a plain number like 1. But rolls is a number provider, the game’s flexible way to supply a number that can be fixed or random. There are three you’ll reach for, plus a couple of advanced ones we’ll save for later.

constant — an exact value. This is what a plain number already is. The long form names a type and gives the exact number in a value field:

{
  "type": "minecraft:constant",
  "value": 3
}

Writing "rolls": 3 is just the shorthand for this. Most of the time the shorthand is all you need.

uniform — a random number in a range. This is a random number following a uniform distribution between two values (inclusive). It takes a min and a max, and every number in between is equally likely:

{
  "type": "minecraft:uniform",
  "min": 1,
  "max": 4
}

Use this for "rolls" when you want a chest to hold a varying number of drops (here, anywhere from 1 to 4). There’s also a handy shorthand: a bare { "min": ..., "max": ... } object (with no type) is automatically treated as a uniform distribution.

binomial — a clustered random number. This is a random number following a binomial distribution. Instead of min/max, it takes n (the amount of trials) and p (the probability of success on an individual trial):

{
  "type": "minecraft:binomial",
  "n": 10,
  "p": 0.5
}

You can read this as “flip n coins, each landing heads with probability p, and count the heads.” With n of 10 and p of 0.5 you’ll usually get a number near 5, only rarely 0 or 10. Use uniform when every count is equally likely; use binomial when you want results to cluster around a middle value.

Under the Hood Number providers show up in more places than rolls, and there are more types than these three. There are also score (read a scoreboard value), storage (read a value from command storage), enchantment_level, and sum. You won’t need them for a basic loot table; we’ll meet score and friends when they matter. (Skippable.)

Walkthrough: a weighted treasure chest

Let’s pull it all together into one real file for your pack. Open your mypack pack and create the folder mypack/data/mypack/loot_table/ if it isn’t there yet. Inside it, make a file called treasure_chest.json with this content:

mypack/data/mypack/loot_table/treasure_chest.json

{
  "pools": [
    {
      "rolls": {
        "type": "minecraft:uniform",
        "min": 2,
        "max": 4
      },
      "entries": [
        {
          "type": "minecraft:item",
          "name": "minecraft:bread",
          "weight": 20
        },
        {
          "type": "minecraft:item",
          "name": "minecraft:iron_ingot",
          "weight": 6
        },
        {
          "type": "minecraft:item",
          "name": "minecraft:diamond",
          "weight": 1
        },
        {
          "type": "minecraft:empty",
          "weight": 5
        }
      ]
    }
  ]
}

Walking through it: there’s one pool. Its rolls is a uniform number provider from 2 to 4, so each time the chest is filled the game reaches into the bag 2, 3, or 4 times. Each reach picks one entry by weight. The total weight is 20 + 6 + 1 + 5 = 32, so a single roll gives bread 20⁄32 of the time, an iron ingot 6⁄32, a diamond 1⁄32, and nothing (empty) 5⁄32. A diamond is genuinely rare, but over 2 to 4 rolls per chest you’ll see one now and then.

Save the file and run /reload in your test world to load it. Now you need to point a chest at the table. The cleanest way to test a loot table without setting up structures is the /loot command, which simply runs a loot table and hands you the result. Type this in your chat bar:

/loot give @s loot mypack:treasure_chest

That asks the game to roll your mypack:treasure_chest table and place the results in your own inventory. Run it a few times. You should mostly get bread and iron, with the occasional diamond, and sometimes fewer items than the maximum because of the empty entries and the random rolls.

Figure (to be captured). inventory after running /loot give @s loot mypack:treasure_chest several times, showing mostly bread and iron with one diamond

Under the Hood When a real chest is placed with a loot table attached, the table and a seed are stored on the container as data, and the actual items aren’t generated until there is an interaction with the container (e.g. opening or destroying). That’s why two chests with the same table and seed give identical loot, and why /loot is the quick way to test, since it rolls the table immediately. (Skippable.)

Practice: extend the treasure chest

Now make the table your own. Each of these builds directly on the file above.

1. Add a tag entry. Give the rare slot more variety: replace the single diamond entry with a tag entry that drops a random arrow from minecraft:arrows, using "expand": true so each roll yields just one arrow type:

   {
     "type": "minecraft:tag",
     "name": "minecraft:arrows",
     "expand": true,
     "weight": 1
   }
   

   (You can use any item tag you learned to write in Chapter 14, including one of your own.)

2. Add a second pool. Remember the loot table runs every pool. Add a second pool that always gives exactly one “guaranteed” reward, separate from the random bag above.

   {
     "rolls": 1,
     "entries": [
       {
         "type": "minecraft:item",
         "name": "minecraft:emerald"
       }
     ]
   }
   

   Add this as a second element of the top-level pools array (after the first pool’s closing brace, separated by a comma). Now every chest is guaranteed one emerald plus the 2–4 random draws from the first pool.

3. Try binomial rolls. Change the second pool’s rolls from 1 to a binomial provider with "n": 3 and "p": 0.5. Run /loot give @s loot mypack:treasure_chest a dozen times and watch how the emerald count clusters around 1–2 rather than spreading evenly.

After each change, save and /reload, then test with /loot.

What Can Go Wrong

You used the folder name loot_tables (plural). Modern Minecraft data-pack folders are all singular, so the game looks for loot_table and ignores a loot_tables folder entirely. If /loot give @s loot mypack:treasure_chest says the table is unknown, check the folder name first.

An item entry has no name. An item entry without its name field has nothing to drop and the file won’t load correctly. Every item and tag entry needs a name; only empty (and the number-provider snippets) skip it.

You expected weight to be a percentage. Weight is a share of the total, not a percent. An entry with "weight": 10 isn’t a 10% chance unless the weights happen to total 100. Always compute the chance as weight ÷ total weight of all entries in that pool.

Nothing dropped and you think it’s broken. Remember rolls can be random and you may have an empty entry in the mix, so a single run legitimately producing few or zero items is normal. Run /loot several times before deciding something’s wrong.

Preview: conditions and functions (Chapter 17)

The loot tables in this chapter are pure structure: pools, entries, weights, counts. But you may have noticed two optional fields that keep appearing on pools and entries: conditions and functions. They’re the next two superpowers, and Chapter 17 is devoted to them.

A conditions list is a set of tests that must all pass for a pool or entry to be used (for example, only drop this if the mob was killed by a player). A functions list applies item modifiers onto all item stacks dropped, for example set the dropped count to 3, or add a random enchantment. Here’s a taste (don’t worry about the details yet, this is a Chapter 17 listing):

{
  "type": "minecraft:item",
  "name": "minecraft:diamond",
  "weight": 1,
  "functions": [
    {
      "function": "minecraft:set_count",
      "count": 2
    }
  ]
}

That entry would drop two diamonds instead of one. You’ll learn set_count, enchanting, custom names, and the condition system in the next chapter. For now, you already own the part everything else builds on: you can decide what can drop and how often.

What You Know Now

You can write a loot table from scratch. You know it’s a JSON file in data/<namespace>/loot_table/, that it’s built from pools, that each pool draws one entry per roll, and that weight sets how often each entry wins. You can drop a single item, a whole tag of items, the result of another loot_table, or empty for nothing. And you can make a count exact with constant, random with uniform, or clustered with binomial. You built a weighted treasure chest in mypack and tested it with /loot. Next chapter, you’ll teach those drops to react to who triggered them and to come out modified — conditions and functions.

Chapter 17 — Loot Tables: Conditions and Functions

What You’ll Build

In the last chapter you built a loot table out of pools, entries, and weights: the machinery that decides which items can drop and how rare each one is. That’s half the story. A loot table that can only say “drop a diamond 5% of the time” is useful, but it can’t yet say “…but only if a player did the killing,” or “drop three diamonds,” or “drop a diamond sword that’s already enchanted and has a custom name.” Those two missing powers are what this chapter adds.

The first is conditions, tests that decide when a pool or an entry is allowed to drop at all. The second is functions, steps that modify the item on its way out: bumping its stack size, enchanting it, renaming it, giving it lore. Together they turn a plain list of possible drops into something that reacts to how the loot was earned and hands back exactly the item you designed.

By the end you’ll have made zombies rarely drop a custom-named, enchanted diamond sword, but only when a player lands the kill, by writing one loot table file in the mypack pack you started in Chapter 9. Along the way you’ll learn five condition types and six functions, with the names exactly right.

This chapter extends your mypack pack and uses the test world you’ve used since Chapter 1. It assumes the loot-table structure from Chapter 16 (pools, entries, weights, number providers).

Where conditions and functions live in a loot table

Before meeting any specific condition or function, you need to know where they go. Recall the shape of a loot table from Chapter 16: a root object with a pools list, and each pool with an entries list. Conditions and functions slot into that shape at three levels, and the wiki spells out each one.

At the pool level, a pool may have a conditions field (“a list of predicates, that must all pass for this pool to be used”) and a functions field that “applies item modifiers in order, onto all item stacks dropped by this pool.” At the entry level, a single (singleton) entry may also have its own conditions (“a list of predicates that must all pass for this singleton entry to be included into the pool”) and its own functions, applied “onto all item stacks dropped by this singleton entry.” And at the very top of the file, the loot table’s root object may carry a functions list that applies “onto all item stacks dropped by this table,” covering every pool at once.

So the rule of thumb is: put a condition or function where you want its reach. Gate a whole pool? Use the pool’s conditions. Modify just one item among several? Use that entry’s functions. The syntax is the same everywhere; only the placement changes.

A note on the word “predicate” The wiki calls the things in a conditions list “predicates.” A predicate is just a test that comes out true or false. In this chapter you’ll write these tests inline, right inside the loot table. In Chapter 18 you’ll learn to save a test as its own reusable file (also called a predicate) and point many loot tables, commands, and advancements at it. Same idea, two homes: here it lives inside the loot table; there it gets its own file.

Conditions: deciding when an entry drops

A condition is one entry in a conditions list: a small object that names a test and gives it whatever values it needs. Every condition has a condition field holding the resource location (the namespace:path name you met in Chapter 8) of the test type. If you list several conditions, all of them must pass: the pool or entry drops only when every test comes out true.

Here are the five condition types this chapter uses. The names and fields are copied exactly from the wiki’s predicate page.

random_chance: “Generates a random number between 0.0 and 1.0, and checks if it is less than a specified value.” It has one field, chance, a number from 0.0 to 1.0. So chance: 0.05 means “pass about 5% of the time.” This is how you make a drop rare.

{ "condition": "minecraft:random_chance", "chance": 0.05 }

killed_by_player: “Checks if there is a attacking_player entity.” In plain terms, it passes only when a player dealt the killing blow. If a cactus, a fall, or another mob killed the zombie, this test fails and the gated drop is skipped. It needs no fields at all:

{ "condition": "minecraft:killed_by_player" }

match_tool: “Checks tool used to mine the block.” More broadly, it checks the item that was used (for a mob kill, the weapon in the killer’s hand). It takes a predicate field describing the item to match (the same item-matching format advancements use). You’ll see its shape in the “Try It!” box later; for now, know that this is how a loot table can react to what the player was holding.

entity_properties: “Checks properties of an entity.” It takes an entity field naming which entity from the situation to look at (such as "this", the entity that died) and a predicate field describing what to check about it. This is the general-purpose “look at the mob/player and test something about it” condition.

location_check: “Checks the current location against location criteria.” It takes a predicate field describing the place (biome, dimension, and so on), plus optional offsetX, offsetY, and offsetZ numbers to shift the spot being checked. This is how a drop can depend on where it happened: only in the Nether, only in a particular biome.

Why do killed_by_player and the tool check only work on mob drops? Some conditions need information the situation has to provide. The wiki calls that information loot context: “a set of parameters available to loot tables, predicates, item modifiers, and number providers.” When a living entity dies, its loot context supplies an attacking_player entity and the Tool that was used, which is exactly what killed_by_player and match_tool read. A chest being opened has no killer and no weapon, so those same conditions would always fail there. That’s why this chapter’s project lives on a mob loot table: it’s the context that hands these conditions what they need.

Functions: modifying the item that drops

A function (the wiki also calls it a loot function or item modifier) is one step that changes the item being dropped. Where a condition is a yes/no gate, a function is an action: “set the count to 3,” “enchant it,” “give it this name.” Functions live in a functions list, and each one names its type in a function field, the same resource-location naming as conditions, just a different key. The wiki notes that functions in a list are “applied in order,” so later functions act on the result of earlier ones.

A function can also carry its own conditions list: “A list of predicates, of which all must pass, for this function to be applied.” That lets you, say, only rename the sword when a player got the kill, while still dropping a plain sword otherwise. Handy, but optional.

Here are the six functions this chapter uses, with their exact fields from the wiki.

set_count: “Sets the stack size.” Its main field, count, is a number provider (the exact / uniform / binomial pickers from Chapter 16), so the count can be fixed or randomised. An optional add boolean, when true, makes the change relative to the current count instead of replacing it.

enchant_with_levels: “Enchants the item, with the specified enchantment level (roughly equivalent to using an enchanting table at that level).” Its levels field is a number provider giving the enchantment level to spend; a higher level means stronger, more numerous enchantments, exactly like a real enchanting table. An optional options field is a list limiting which enchantments may be chosen; leave it out and “all enchantments are possible.”

set_name: “Adds or changes the item’s custom name.” Its name field is a text component, the rich-text format from Chapter 5, so you get colour and styling for free. An optional target field chooses which name to set: the wiki’s allowed values are "custom_name" (the default) or "item_name" (the item’s built-in display name).

set_lore: “Adds or changes the item’s lore.” Lore is the small grey description text under an item’s name. Its lore field is a list of text-component lines. It also requires a mode field saying how to combine with any existing lore: one of "append", "insert", "replace_all", or "replace_section". For a fresh item, "replace_all" is the simplest: it sets the lore to exactly your lines.

enchanted_count_increase: “Adjusts the stack size based on the level of the specified enchantment on the killer entity.” This is the Looting bonus: more loot when the killer’s weapon has the Looting enchantment. Its count field (a number provider) is how many extra items to add per level of the enchantment; an optional limit caps the final stack size (0 means no cap); and enchantment names which enchantment to read, normally minecraft:looting.

Modern Minecraft If you follow an older tutorial, you’ll see this function called looting_enchant. That name is gone. In current Java Edition the wiki lists it as enchanted_count_increase: same job (a Looting-style bonus), new name, and it now works for any enchantment you name, not just Looting. If a looting_enchant from an old guide silently does nothing, this rename is why.

set_components: “Sets components of an item.” This is the modern, all-purpose way to attach custom data to an item: its single field, components, is “a map of components ID to component value.” Components are a deep topic. They’re how every piece of modern item data (damage, custom model, container contents, and much more) is stored, so this book gives them their own home in Chapter 21. Here you only need to know set_components exists and is the function you reach for when a simpler one like set_name doesn’t cover what you want.

Modern Minecraft set_components replaces the old set_nbt function you’ll see in pre-1.20.5 tutorials. The mental shift (from one big blob of “NBT” to a tidy map of named components) is the same one running through all of modern item handling, and Chapter 21 is where you’ll learn it properly. For this chapter, the friendly functions (set_name, set_lore, enchant_with_levels) do everything our sword needs, so you won’t have to write a single component yet.

Walkthrough: the rare zombie sword

Time to build the project. The plan: edit the zombie’s loot table so that, on top of its normal drops, a zombie killed by a player has a small chance to drop a diamond sword that is enchanted, named “Cursed Blade,” and carries a line of lore, and gets a Looting bonus to boot.

Step 1 — find the right file

A mob’s drops come from a loot table named after the mob, in the singular. To change what zombies drop, you create a file at this path inside your pack:

mypack/data/minecraft/loot_table/entities/zombie.json

Notice the namespace is minecraft, not mypack. The wiki explains why: “Editing this file in a datapack would make every zombie in a Minecraft world use the modified datapack’s loot table rather than the default zombie loot table.” Because you’re overriding vanilla’s own minecraft:entities/zombie table, your file has to sit at the same address. (This is the same override trick you’d use for any vanilla file: your version wins.)

What Can Go Wrong? Overriding the whole file means you replace vanilla’s zombie drops, not add to them. If you only write your sword pool, zombies stop dropping rotten flesh entirely. The listing below keeps rotten flesh in a first pool so the vanilla drop survives. When you override a vanilla table, you’re responsible for everything it used to do.

Step 2 — write the loot table

Here is the complete file. Read it once top to bottom, then we’ll walk the new parts.

mypack/data/minecraft/loot_table/entities/zombie.json

{
  "type": "minecraft:entity",
  "pools": [
    {
      "rolls": 1,
      "entries": [
        {
          "type": "minecraft:item",
          "name": "minecraft:rotten_flesh",
          "functions": [
            { "function": "minecraft:set_count", "count": { "min": 0, "max": 2 } }
          ]
        }
      ]
    },
    {
      "rolls": 1,
      "conditions": [
        { "condition": "minecraft:killed_by_player" },
        { "condition": "minecraft:random_chance", "chance": 0.05 }
      ],
      "entries": [
        {
          "type": "minecraft:item",
          "name": "minecraft:diamond_sword",
          "functions": [
            {
              "function": "minecraft:enchant_with_levels",
              "levels": { "min": 20, "max": 30 }
            },
            {
              "function": "minecraft:set_name",
              "name": { "text": "Cursed Blade", "color": "dark_purple", "italic": false }
            },
            {
              "function": "minecraft:set_lore",
              "mode": "replace_all",
              "lore": [
                { "text": "Dropped by the restless dead", "color": "gray", "italic": true }
              ]
            },
            {
              "function": "minecraft:enchanted_count_increase",
              "enchantment": "minecraft:looting",
              "count": { "min": 0, "max": 1 }
            }
          ]
        }
      ]
    }
  ]
}

Step 3 — read it back

Start at the top. "type": "minecraft:entity" declares the loot context: this table runs on a mob’s death, which (from the box earlier) is what makes killed_by_player and the Looting bonus work. The first pool is plain Chapter-16 material: one roll, one entry, rotten flesh, with a set_count of 0–2 so the vanilla drop is preserved.

The second pool is where this chapter lives. Its conditions list holds two tests, and both must pass for the pool to run: killed_by_player (a player got the kill) and random_chance with chance: 0.05 (the 1-in-20 rarity). Gate the pool, and the whole sword is skipped most of the time. Clean and cheap.

Inside, the single entry drops a minecraft:diamond_sword, then its functions list reshapes that plain sword in order:

1. enchant_with_levels with levels 20–30 enchants it as if at an enchanting table set to a random level in that range: strong, varied enchantments every time.
2. set_name gives it the custom name “Cursed Blade.” The name value is a Chapter-5 text component, so "color": "dark_purple" tints it; the "italic": false is just ordinary text-component styling (Chapter 5) turning the slant off.
3. set_lore with mode: "replace_all" sets a single grey, italic line of lore beneath the name.
4. enchanted_count_increase reads minecraft:looting on the killer’s weapon and adds 0–1 extra swords per Looting level, a small bonus for a well-enchanted player.

Step 4 — load and test

Save the file, then in your test world’s chat run /reload so the game re-reads your pack. Now go hit some zombies. Punching them won’t always work. Remember, killed_by_player needs a player kill, and even then the 5% chance means most zombies drop only rotten flesh. Kill a dozen or two and a glowing, purple-named “Cursed Blade” should eventually clatter to the ground.

Figure (to be captured). the “Cursed Blade” diamond sword item dropped on the ground, showing its dark-purple custom name and grey lore line in the floating tooltip

Try It! Want the sword only when the player kills with a particular weapon? Add a match_tool condition to the pool. The wiki says match_tool takes a predicate field that describes the held item, “using same structure as advancements” — the same item-matching format an advancement uses to check what you’re holding:

{
  "condition": "minecraft:match_tool",
  "predicate": { }
}

The exact contents of that item predicate (matching by item id, by item tag, by enchantment, and so on) are the advancement item-condition format. You’ll meet it properly in Chapter 18 alongside predicate files. For now, an empty predicate: {} matches any tool and lets you see the wiring; fill it in once Chapter 18 has shown you the item-predicate fields.

Practice

These extend the zombie-sword table you just built. Make a copy of the file first if you want to keep the original.

1. Make it rarer, then richer. Lower the random_chance to 0.02. Then add a second line of lore using set_lore. Remember lore is a list, so add another text-component object to the list. Reload and confirm both lines show up.

2. A location-gated drop. Add a new pool whose conditions include a location_check, and have it drop a small bonus (say, a few minecraft:bone) only somewhere specific. Use the entity_properties or location_check field shapes from this chapter as your guide; you’ll fill in the exact predicate contents properly in Chapter 18, so for now a bare location_check with an empty predicate: {} is enough to see the wiring.

3. A table-wide function. Move a set_count out of an entry and up to the loot table’s root functions list. Watch how it now applies to every drop (rotten flesh included) because a root function runs “onto all item stacks dropped by this table.” This shows you the difference between gating at the entry, the pool, and the whole table.

What Can Go Wrong

The sword never drops, no matter how many zombies you kill. Two usual causes. First, check you’re killing them yourself: killed_by_player fails for fall damage, cacti, or another mob finishing the job. Second, 5% is genuinely rare; kill more, or temporarily raise chance to 1.0 to confirm the table works, then lower it back.

You changed the file but nothing changed in game. Did you run /reload? Loot-table files hot-reload with /reload (unlike dynamic registries, which need a world reboot, Chapter 7). Also re-check the path: it must be data/minecraft/loot_table/entities/zombie.json exactly, with the singular loot_table folder: the same singular-folder rule that bites people on function and recipe.

Zombies stopped dropping rotten flesh. You overrode vanilla’s whole table and forgot to keep its drops. Add a plain pool for rotten flesh back, as in the listing: overriding means you own all of the mob’s loot, not just your additions.

What You Know Now

You can now make a loot table react. Conditions (random_chance, killed_by_player, match_tool, entity_properties, location_check) decide when a pool or entry is allowed to drop, and you know they read from the situation’s loot context, which is why kill-based and tool-based conditions belong on mob tables. Functions (set_count, enchant_with_levels, set_name, set_lore, enchanted_count_increase, and the all-purpose set_components) decide how the dropped item is modified, applied in order, optionally gated by their own conditions. You override a vanilla mob’s drops by writing a file at the same minecraft: address, and you keep the vanilla loot you still want.

You can now build: rare custom mob drops, enchanted and named reward items, Looting-scaled bonuses, and drops that only happen under conditions you choose. Next, in Chapter 18, you’ll lift those inline conditions out into reusable predicate files, so the same test can guard a loot table, a command, and an advancement without being rewritten each time. And the one function we only previewed here, set_components, opens up in Chapter 21, where data components get the full treatment.

Chapter 18 — Predicates: Reusable Conditions

What You’ll Build

Back in Chapter 17 you wrote conditions on loot pools — little “only if…” tests like random_chance or match_tool that decided whether an entry dropped. Those tests were trapped inside one loot table. This chapter sets them free. You’ll learn that the very same condition vocabulary can be saved on its own, in a small JSON file called a predicate, and then reused anywhere the game accepts a yes/no check: in commands, in target selectors, and back inside loot tables and advancements.

By the end you’ll have added a predicate named mypack:raining_dark_forest to the pack you started in Chapter 9, plus a function that hands out effects to every player standing in a rainy dark forest, and nowhere else. You’ll also finally use execute if predicate and the predicate= selector argument, both of which were named-but-deferred all the way back in Chapters 3 and 4.

This chapter assumes you’re comfortable with /execute and its if/run pieces and chaining (Chapter 4), with target selectors like @a and @e and their square-bracket arguments (Chapter 3), and with the idea of loot-table conditions from Chapter 17, since predicates use the exact same condition types. It also leans on JSON objects, arrays, and booleans (Chapter 8) and the data/<namespace>/... folder layout (Chapters 8–9).

Modern Minecraft Older tutorials wrote the same entity[...]-style checks over and over, copied between commands. Modern data packs write the check once as a predicate and reference it by name. If the rule changes, you edit one file. Predicates are also the only way to express conditions too complex for the selector syntax: “is this entity holding an enchanted diamond sword in a dark forest while it rains” is a predicate, not a string of selector arguments.

What a predicate is

A predicate is a JSON structure the game invokes to check a condition within the world. It returns a pass or fail result to whatever invoked it, which then acts differently based on the result. That’s the whole idea: a predicate is a named yes/no question the game can ask about the world. Put another way, predicates are a flexible way for data packs to encode “if this, then that” logic without needing custom code.

A predicate file is a standalone data pack file containing one or more predicates. Like every other data pack file you’ve made, it lives at a fixed address. Predicate files go in:

data/<namespace>/predicate/

So a predicate you call mypack:is_raining is the file data/mypack/predicate/is_raining.json. The name follows the same namespace:path rule as your functions and recipes.

Inside the file is a JSON object with one required field, condition, and then extra fields that depend on which condition you chose. The root has a condition string (the resource location of the condition type to check) plus the other parts of the predicate specific to that type. The condition value is an identifier just like minecraft:say or minecraft:diamond; for built-in conditions you can write it with or without the minecraft: prefix, and the examples in this chapter spell it out in full so there’s never any doubt.

Here is the smallest useful predicate — “is it raining right now?”:

data/mypack/predicate/is_raining.json

{
  "condition": "minecraft:weather_check",
  "raining": true
}

The condition field picks the kind of check (weather_check), and raining is the extra field that check needs. When the game asks this predicate its question, it answers true (pass) only when it’s raining, and false (fail) otherwise. That’s exactly what weather_check does: it checks the current game weather, with a boolean raining that passes only if it is raining or thundering, and a second boolean thundering that passes only if it is thundering.

Under the Hood (skippable): loot context Some conditions need a fact about the world to do their job: a position, a tool, an entity. This bundle of facts is called the loot context, a set of parameters available to loot tables, predicates, item modifiers, and number providers. Whoever invokes a predicate supplies a context. What happens when a needed fact is missing is clear-cut: a condition like location_check requires an origin provided by loot context, and always fails if it isn’t provided. That’s why some predicates work in one place and silently fail in another. Keep it in mind for “What Can Go Wrong” at the end of the chapter. Conditions marked “invokable from any context” (like weather_check, time_check, random_chance) work everywhere.

Single-condition predicates

Let’s build a small library of one-condition predicates before combining them. Each is a complete file; each uses a standard built-in condition type.

Time of day — time_check

time_check compares the current day time against given values and is invokable from any context. It takes a value (the time to compare against) and an optional period. This predicate passes during the first half of the day:

data/mypack/predicate/is_daytime.json

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

A Minecraft day is 24,000 ticks long (you met that number in Chapter 7). The period field first reduces the time modulo the given number before it’s checked. Setting it to 24000 causes the checked time to be equal to the current daytime, so the comparison resets each day instead of climbing forever. The value here is a min/max range, the long form; there’s also a shorthand where value is a single integer.

A coin flip — random_chance

random_chance generates a random number between 0.0 and 1.0 and checks if it is less than a specified value. Its one field is chance, a success rate as a number from 0.0 to 1.0. This one passes a quarter of the time:

data/mypack/predicate/one_in_four.json

{
  "condition": "minecraft:random_chance",
  "chance": 0.25
}

You met random_chance as a loot condition in Chapter 17. It is the same condition type, and that’s the whole point of predicates. Anything you learned as a loot condition is also a predicate.

Checking an entity — entity_properties

The condition you’ll reach for most often is entity_properties. It checks properties of an entity and is invokable from any context. It has two fields: entity (which entity to look at) and predicate (the actual test, which uses the same structure as advancements). The simplest entity to name is "this", the entity the predicate is being asked about.

This predicate passes when the entity is holding a diamond sword in its main hand:

data/mypack/predicate/holding_diamond_sword.json

{
  "condition": "minecraft:entity_properties",
  "entity": "this",
  "predicate": {
    "equipment": {
      "mainhand": {
        "items": ["minecraft:diamond_sword"]
      }
    }
  }
}

Reading it inside-out: equipment is a field for testing the items that this entity holds in its equipment slots, with one key per slot (the valid keys are mainhand, offhand, head, chest, legs, feet, and body). Each slot holds an item test, and item conditions include an items field, a list of item IDs that tests if the type of item matches any of the listed values. So this whole structure reads: “the item in this entity’s main hand is a diamond sword.”

Checking the block underfoot — block_state_property

block_state_property checks the mined block and its block states, and it requires a block state provided by loot context, always failing if that isn’t provided. It has a block field (a block ID; the test fails if the block doesn’t match) and an optional properties map of block state names to values. This one passes when the block is an oak log laid on its side along the X axis (you met block states with the Debug Stick in Chapter 10):

data/mypack/predicate/sideways_oak_log.json

{
  "condition": "minecraft:block_state_property",
  "block": "minecraft:oak_log",
  "properties": {
    "axis": "x"
  }
}

Because this condition needs a block-state context, it works inside a block’s loot table or a mine context, not from a bare /execute if predicate standing in open air, which supplies no block. We’ll come back to that in “What Can Go Wrong.”

Checking the held tool — match_tool

match_tool checks the tool used to mine the block and, like block_state_property, requires a tool provided by loot context, always failing if it isn’t provided. Its single field is predicate, an item test using the same structure as advancements (the same item test you saw inside equipment above):

data/mypack/predicate/mined_with_netherite_pickaxe.json

{
  "condition": "minecraft:match_tool",
  "predicate": {
    "items": ["minecraft:netherite_pickaxe"]
  }
}

This is the predicate form of the loot condition you used in Chapter 17 to check what tool broke a block. Saved as a file, you can now reuse it across every loot table that wants “only when mined with a netherite pickaxe.”

Checking an active enchantment — enchantment_active_check

The last single condition is a specialist. enchantment_active_check checks if the enchantment has been active, needs the enchantment-active-status context, and is therefore only usable from the enchanted_location loot context. Its one field is a boolean active, whether to check for an active (true) or inactive (false) enchantment:

data/mypack/predicate/enchant_is_active.json

{
  "condition": "minecraft:enchantment_active_check",
  "active": true
}

You won’t call this one from a command. It only makes sense deep inside an enchantment’s own effects, which is a Chapter 35 topic. It’s listed here so you recognize it as a predicate condition and know it belongs to enchantments specifically.

Reference box: the other condition types There are more condition types than this chapter drills. You don’t need them yet, but here’s the full menu so nothing surprises you later: location_check (covered below), damage_source_properties, entity_scores, killed_by_player, survives_explosion, table_bonus, random_chance_with_enchanted_bonus, value_check, and reference (covered at the end of this chapter). Each one is a condition value just like the ones above. Many belong to loot and advancement contexts you’ll meet in Chapters 17, 19, and 36.

Invoking a predicate

A predicate that no one asks is useless. Predicate files can be invoked in several different manners from other data pack files.

From a command, with /execute if predicate. The /execute if predicate subcommand can invoke a predicate file or an in-line predicate definition to decide whether to continue with a subcommand chain. The predicate is invoked once at the current contextual position of execution. It slots into the if/run chain you learned in Chapter 4. For example:

execute if predicate mypack:is_daytime run say Good morning!

(As always in this book, that line lives inside a .mcfunction file, with no leading slash.) The say runs only on the days the predicate passes.

From a target selector, with predicate=. This is the argument that was previewed but deferred back in Chapter 3. The selector argument predicate= checks predicate files as a filter for entity selection. The predicate file is invoked once per entity that needs filtering, each time at the entity’s location. So this selects every player holding a diamond sword, using the predicate file from earlier:

execute as @a[predicate=mypack:holding_diamond_sword] run say You're armed!

Each player is tested in turn; only those who pass are selected. Like every selector argument, you can combine predicate= with the others you know — @a[predicate=mypack:holding_diamond_sword, distance=..10].

From inside loot tables and advancements. Predicates are also used in other locations within other data pack files such as advancements and loot tables. In a loot table, the conditions list you wrote in Chapter 17 is a list of predicates: a pool’s conditions are a list of predicates that must all pass for this pool to be used. So a condition you tested inline in Chapter 17 can instead be saved as a predicate file and pulled in by name, which is the next topic.

Combining conditions: all_of, any_of, inverted

Single checks are handy, but real rules combine them: “raining and in a dark forest,” “diamond sword or netherite sword,” “not daytime.” There are three combiner condition types for exactly this.

all_of — AND. Evaluates a list of predicates and passes if all of them pass. Its field is terms, the list of predicates to evaluate.

any_of — OR. Evaluates a list of predicates and passes if any one of them passes. It also uses a terms list.

inverted — NOT. Inverts another predicate condition. Its field is term (a single predicate, not a list): the condition to be negated.

Each term inside a combiner is itself a full predicate object, the same {"condition": ...} shape, nested as deeply as you like. Here’s “not daytime,” combining inverted with the is_daytime test from earlier, written inline:

data/mypack/predicate/is_nighttime.json

{
  "condition": "minecraft:inverted",
  "term": {
    "condition": "minecraft:time_check",
    "value": {
      "min": 0,
      "max": 12000
    },
    "period": 24000
  }
}

Under the Hood (skippable): the list shortcut A predicate file’s root can be either a compound or a list containing multiple predicates. In the latter case all predicates must evaluate to true. So a JSON array at the top of a predicate file is a built-in all_of. One catch with any_of: any_of only applies to terms; nested lists are all_of. When in doubt, write the combiner out explicitly. It’s clearer to a reader and never surprises you.

Building raining_dark_forest

Now the chapter’s goal: a predicate that passes only when it’s raining and the location is a dark forest. That’s an all_of of two conditions. The first you already have: weather_check with raining: true. The second is location_check.

location_check checks the current location against location criteria, requires the origin context, and has a predicate field whose body uses the same structure as advancements. In that advancement location structure, the biome is tested with a biomes field (the biome at this location), written as a list of biome IDs. The dark forest (the dense, dark-oak biome where woodland mansions generate) has the identifier minecraft:dark_forest, one entry in the full biome ID table Chapter 42 puts to work. Putting it together:

data/mypack/predicate/raining_dark_forest.json

{
  "condition": "minecraft:all_of",
  "terms": [
    {
      "condition": "minecraft:weather_check",
      "raining": true
    },
    {
      "condition": "minecraft:location_check",
      "predicate": {
        "biomes": ["minecraft:dark_forest"]
      }
    }
  ]
}

Reading it top to bottom: the outer all_of passes only when both terms pass. The first term is the weather check. The second is a location check whose inner predicate says “the biome here is in this list,” and the list holds just the dark forest. Because location_check needs the origin position, you must invoke this predicate from somewhere that has a position, which is what /execute ... at ... gives you.

Now a function to use it. We want: for every player, go to where they are, and if the predicate passes there, give them an effect. You built as @a ... at @s chains like this in Chapter 4:

data/mypack/function/dark_forest_effects.mcfunction

execute as @a at @s if predicate mypack:raining_dark_forest run effect give @s minecraft:regeneration 5 0

Walk through it with your Chapter 4 eyes: as @a forks once per player; at @s moves the check to that player’s position (giving location_check its origin); if predicate mypack:raining_dark_forest tests there; and only if it passes does run effect give @s … grant five seconds of Regeneration. Players standing in a rainy dark forest get the effect; everyone else gets nothing.

To make it run continuously, append it to the tick function tag you first created in Chapter 11 and have been adding to since. (You already have entries here from earlier chapters, so add this one to the end of the list, don’t replace them.)

data/minecraft/tags/function/tick.json

{
  "values": [
    "mypack:kill_on_gold",
    "mypack:timer_tick",
    "mypack:dark_forest_effects"
  ]
}

Save, run /reload, fly to a dark forest, and /weather rain. Stand under the dark-oak canopy and watch the Regeneration hearts appear; step into the next biome and they stop renewing.

Figure (to be captured). player standing in a rainy dark forest with the Regeneration effect icon and swirling particles visible; rain falling through the dark-oak canopy

Reusing predicates by name: reference

The last condition type closes the loop on reuse. reference invokes a predicate file and returns its result. Its field is name, the resource location of the predicate to invoke. This lets one predicate stand on the shoulders of another instead of copy-pasting its guts.

Say you want a stricter rule: raining in a dark forest and the player is holding a diamond sword. You already have mypack:raining_dark_forest and mypack:holding_diamond_sword as files, so just reference both:

data/mypack/predicate/armed_in_storm.json

{
  "condition": "minecraft:all_of",
  "terms": [
    {
      "condition": "minecraft:reference",
      "name": "mypack:raining_dark_forest"
    },
    {
      "condition": "minecraft:reference",
      "name": "mypack:holding_diamond_sword"
    }
  ]
}

If you later change what counts as a “dark forest storm,” you edit raining_dark_forest.json once and every predicate that references it updates automatically. One warning: a cyclic reference causes a parsing failure, so don’t make predicate A reference B while B references A.

Practice

1. Stormy nights only. Write data/mypack/predicate/stormy_night.json as an all_of of two references: mypack:is_nighttime and a new is_thundering predicate (a weather_check with "thundering": true). Add a tick line that gives Night Vision to players when it passes.

2. Either sword. Write data/mypack/predicate/holding_a_sword.json using any_of with two entity_properties terms, one checking for minecraft:diamond_sword, one for minecraft:netherite_sword in mainhand. Test it with @a[predicate=mypack:holding_a_sword].

3. Safe zone. Write a predicate that passes when a player is not in a dark forest: wrap a reference to mypack:raining_dark_forest’s location half in an inverted. (Hint: you’ll first want a in_dark_forest predicate holding just the location_check, then invert a reference to it.)

What Can Go Wrong

What Went Wrong? “My predicate never passes anywhere.” You probably invoked a context-hungry condition from a context that doesn’t supply its fact. The rule is explicit: location_check, block_state_property, and match_tool always fail if not provided their origin/block/tool. A bare execute if predicate standing in midair has a position but no block and no tool, so a block_state_property predicate fails there every time. Fixes: give location_check a position with at @s (as we did), and only use block_state_property/match_tool from a loot table or a context that actually breaks a block.

What Went Wrong? “Invalid predicate” / it won’t load. Two classic typos. First, the field that names the check is condition, not type; type is what loot entries and number providers use, but a predicate’s check is keyed by condition. Second, the combiners take their field names exactly: all_of and any_of use a terms list, while inverted uses a single term (no s). Mixing them up (a terms object or an inverted with a list) fails to load.

What Went Wrong? “I nested predicates in a plain list and it acts like AND, not OR.” That’s the list shortcut biting you. A JSON array of predicates means all must pass (all predicates must evaluate to true), and any_of only applies to terms; nested lists are all_of. If you wanted OR, write an explicit any_of with a terms array, not a bare list.

What You Know Now

A predicate is a named yes/no condition stored as JSON in data/<namespace>/predicate/, keyed by a condition field. You can write single checks (weather_check, time_check, random_chance, entity_properties, block_state_property, match_tool, enchantment_active_check) and combine them with all_of, any_of, and inverted. You can invoke a predicate three ways: from a command with execute if predicate, from a selector with predicate=, and from inside loot tables and advancements. You can chain predicates together with reference so a rule is written once and reused everywhere. And mypack now has a raining_dark_forest predicate that fires real effects only when the weather and the biome both agree. Next chapter puts predicates to work as the brains of advancements, the game’s built-in event detectors.

Chapter 19 — Advancements: Detecting Player Events

What You’ll Build

So far everything your pack does, you set in motion: you /reload, or you run a function, or a command in the tick tag fires twenty times a second whether anything interesting happened or not. In this chapter you build something different: files that wait for the player to do something and react the moment it happens.

By the end you’ll have two new files working in the pack you started in Chapter 9. The first is a normal-looking advancement: the first time a player steps into the Nether, a toast pops up in the corner and a function runs to welcome them. The second is sneakier: a hidden advancement with no popup at all. Its only job is to notice when a player eats a golden apple and quietly run a function. The player never sees the advancement screen change. To them it just feels like the world is paying attention.

That second pattern (an advancement whose only purpose is to detect an event and run a function) is one of the most useful tools in the whole book. You’ll lean on it when you build the bigger projects later on.

Figure (to be captured). the “Into the Nether” toast sliding in at the top-right as the player enters the Nether portal

Advancements are really event listeners

You already know advancements as a player: the screen you open with the L key, full of little framed icons across tabs like Minecraft, Nether, The End, Adventure, and Husbandry. When you complete one, a sliding toast notification appears in the top-right corner, often with a chat message and a little sound. The icons live in trees: each tab starts with a leftmost root advancement and branches outward, and you drag around to see the branches.

That’s the surface. Here’s the secret: an advancement is an event listener that happens to show a toast. An event listener is just a file that watches for one specific thing to happen in the game and does something when it does. Under the hood, every advancement says “watch for this event; when it fires, mark me complete (and maybe run a reward).” The popup, the icon, the tab are all optional display. Strip the display away and you’re left with a pure detector: a file that silently waits for an event and fires a reward. That is what makes advancements so useful for a data pack, and it’s the opposite of how most tutorials present them.

Modern Minecraft. Older tutorials treat advancements as “achievements you design for players to chase.” That’s one use. But the vanilla game itself uses display-less advancements as plumbing, for example the hidden advancements that quietly unlock recipes in your recipe book. The wiki notes that some advancements “lack a display so that they can utilize triggers and rewards instead of excessive commands,” and that leaving display off even loads a touch faster. Think of an advancement as a trigger plus a reward, with display bolted on only when you want the player to see it.

Where they live, and the smallest possible advancement

Advancements are JSON files. They go in your namespace under a folder named, like all your other data-pack folders, in the singular:

data/mypack/advancement/

Just like function/, recipe/, and predicate/, it’s advancement, not advancements — singular, following the same folder convention you’ve used since Chapter 9 (if your version ever disagrees, the game log from Chapter 10 will tell you the folder it expected). The filename (minus .json) becomes the last part of the advancement’s id. A file at data/mypack/advancement/into_the_nether.json has the id mypack:into_the_nether.

Every advancement needs exactly one required thing: a criteria block. Everything else (display, requirements, rewards, parent) is optional. A criterion (the singular of criteria) is one event to watch for. The smallest legal advancement is just one criterion:

mypack/data/mypack/advancement/tiny_example.json

{
  "criteria": {
    "got_dirt": {
      "trigger": "minecraft:inventory_changed",
      "conditions": {
        "items": [
          {
            "items": ["minecraft:dirt"]
          }
        ]
      }
    }
  }
}

Let’s name every piece, because the shape repeats forever:

• criteria — the object holding all the events to watch. Required.
• got_dirt — the criterion name. You invent this. It can be any text. You’ll refer back to it by this exact name later (in requirements), so pick something readable.
• trigger — which event to listen for, written as an identifier like minecraft:inventory_changed. This is the heart of the criterion. Required inside a criterion.
• conditions — optional extra tests that must also pass when the trigger fires. Here: “…and one of the items that just entered my inventory was dirt.” The exact fields you can put in conditions depend on which trigger you chose.

When the trigger fires and all its conditions pass, the criterion is marked complete. With only one criterion and no requirements, completing it completes the whole advancement.

Under the Hood (skippable). The conditions block always allows a player field that tests the player who would receive the advancement, using the same kind of entity-condition object you met with predicates in Chapter 18. It can test an entity’s type, location, nbt, gamemode, and more. Some triggers also add their own fields on top: inventory_changed adds items, consume_item adds item, and so on. So a criterion’s conditions is “the standard player test, plus whatever extras this particular trigger offers.”

The triggers: the events you can listen for

There are several dozen triggers in vanilla Minecraft, far too many to memorize, and most you’ll never touch. The skill isn’t knowing them all; it’s knowing how to look one up and copy its shape. Here are the handful that cover most real detectors, each taken straight from the advancement reference:

Two of these deserve a flag right now, because beginners misuse them constantly:

• minecraft:location and minecraft:tick are polling triggers. They don’t wait for a player action. They just fire on a clock (location once a second, tick every tick) and then check their conditions. They’re how you answer “is the player currently somewhere / in some state?” rather than “did the player just do something?” Handy, but use them sparingly; a tick-based advancement is checking 20 times a second.
• minecraft:changed_dimension is the one that fires on crossing into a dimension. There’s also a minecraft:nether_travel trigger, but read its description carefully: it “triggers when the player travels to the Nether and then returns to the Overworld.” That’s a round-trip, not an entry. For “first time entering the Nether,” changed_dimension with to set to the Nether is the right tool, which is exactly what we’ll use.

Try It! Open the advancement reference and skim the trigger list. Pick one that sounds fun (minecraft:slept_in_bed, minecraft:used_totem, minecraft:tame_animal) and read its “extra conditions.” Every one follows the same pattern: a trigger line plus an optional conditions object. Once you’ve read three, you’ve read them all.

Reusing the Chapter 18 condition objects

You don’t have to learn the inside of conditions from scratch, because several triggers reuse the exact condition objects you already met. When a trigger’s condition says it checks an entity (like player_killed_entity’s entity field), that entity is described with the same kind of entity check you saw in Chapter 18, one that can test type, location, distance, effects, equipment, nbt, and more. When it checks a location (like changed_dimension’s cousin checks, or a location test inside player), it uses location fields like biomes, block, dimension, position, and structures. So a criterion like “killed a creeper” is just player_killed_entity with an entity whose type is minecraft:creeper, copied from the reference:

mypack/data/mypack/advancement/killed_a_creeper.json

{
  "criteria": {
    "boom": {
      "trigger": "minecraft:player_killed_entity",
      "conditions": {
        "entity": {
          "type": "minecraft:creeper"
        }
      }
    }
  }
}

requirements: combining several criteria

By default, if an advancement has more than one criterion, the player must complete all of them. Often that’s not what you want; sometimes “do any one of these” is the goal. The requirements field gives you that control.

requirements is a list of lists (a JSON array of arrays). Each inner list is a group that names some of your criteria. The rule, straight from the reference:

The advancement is granted when every group has at least one completed criterion in it.

That’s AND across the groups, OR inside each group. Two patterns cover almost everything:

“Complete all of them” (AND). Put each criterion in its own group:

"requirements": [
  ["criterion_a"],
  ["criterion_b"]
]

Two groups; each must have one completed criterion; so you need both. (This is also exactly what you get for free if you omit requirements entirely.)

“Complete any one of them” (OR). Put all the criteria in a single group:

"requirements": [
  ["criterion_a", "criterion_b", "criterion_c"]
]

One group; it just needs one of its three criteria completed; so any of them grants the advancement.

What Can Go Wrong? Every name inside requirements must be a criterion name you actually defined up in criteria. A typo there means that group can never be satisfied. And watch the brackets: requirements is a list of lists. ["a","b"] (one group, OR) behaves very differently from [["a"],["b"]] (two groups, AND). If your advancement “won’t fire even though the event happened,” this nesting is the first place to look.

rewards: what happens when it completes

When an advancement completes, it can hand out rewards. There are four, and the last one is the star of the show:

mypack/data/mypack/advancement/rewards_example.json

{
  "criteria": {
    "trigger_me": {
      "trigger": "minecraft:tick"
    }
  },
  "rewards": {
    "experience": 10,
    "recipes": ["mypack:chainmail_helmet"],
    "loot": ["mypack:reward_chest"],
    "function": "mypack:on_complete"
  }
}

• experience — an integer number of experience points to grant. Defaults to 0.
• recipes — a list of recipe ids to unlock in the player’s recipe book. This is the vanilla trick: hidden advancements with a recipes reward are how recipes get unlocked.
• loot — a list of loot-table ids; the player is given the items those tables roll. (Point it at one of your own tables from Chapters 16–17: here, an imagined mypack:reward_chest.)
• function — a single function id to run. This is the one you’ll use most. It turns an advancement into a launcher for any function you can write, which means anything a data pack can do. Note one limit from the reference: it must be a function, not a function tag.

The function runs as the player who earned the advancement, at their position, so inside it, @s is that player and ~ ~ ~ is where they are. That’s what makes the advancement-fires-a-function pattern so natural: the function already knows who and where.

display: the part the player sees (or doesn’t)

The display block controls the toast, the icon, and where the advancement shows up on the advancement screen. Leave display out entirely and the advancement still works; it just never appears anywhere and never pops a toast. Here are its fields, from the reference:

• icon — required if you include display. An object with an item id (and optional count / components). This is the picture shown in the frame.
• title — required if you include display. A text component (Chapter 5): the name shown on the toast and in the screen.
• description — required if you include display. A text component: the hover text.
• frame — the frame style: task (the default), goal, or challenge. They give the icon a different border and header; challenge is the fancy one that shows the pink “Challenge Complete!” header.
• background — only used by a root advancement: the texture behind that whole tab.
• show_toast — true/false; whether the corner toast appears. Defaults to true.
• announce_to_chat — true/false; whether a chat message is posted. Defaults to true.
• hidden — true/false; whether this advancement (and its children) stay invisible on the screen until completed. Defaults to false.

So you have two independent ways to keep things quiet, and they do different jobs:

• "hidden": true hides the entry on the advancement screen until it’s earned, but the toast still pops when it completes.
• Omitting display entirely is the real stealth move: no screen entry, no toast, no chat, nothing. The advancement exists purely to detect an event and fire its reward.

For a silent detector, leave display out. For a “secret achievement” the player can discover, use display with "hidden": true.

parent advancements, roots, and tabs

Advancements form trees, and the parent field is what links them. Set parent to another advancement’s id and yours becomes a child of it, drawn one column to the right with an arrow pointing in. Leave parent out and your advancement is a root, and a root with valid display data automatically creates a brand-new tab in the advancement menu. The background field sets that tab’s backdrop. Children of a root appear inside its tab. For the detectors in this chapter we won’t bother with tabs at all, but now you know how the vanilla trees are built.

Walkthrough A — “Into the Nether” (a visible advancement)

Let’s build the first real one: a normal advancement that pops a toast the first time a player enters the Nether, and runs a welcome function. Two files.

First the function it will run. It greets the player and gives a small gift. Remember, it runs as and at the player, so @s is them:

mypack/data/mypack/function/nether_welcome.mcfunction

title @s actionbar {"text":"Welcome to the Nether — bring summer clothes!","color":"gold"}
effect give @s minecraft:fire_resistance 30 0

(If you want a sound too, add a playsound line using the Chapter 2 syntax; pick any sound id you’ve confirmed exists in your version; we leave it off here to keep the listing to things we’ve already grounded.)

Now the advancement. The event is “crossed into the Nether,” which is changed_dimension with to set to the Nether dimension. We give it display so the player sees a toast, and a function reward pointing at the file above:

mypack/data/mypack/advancement/into_the_nether.json

{
  "display": {
    "icon": {
      "id": "minecraft:flint_and_steel"
    },
    "title": {
      "text": "Into the Nether"
    },
    "description": {
      "text": "Step through a Nether portal for the first time"
    },
    "frame": "task",
    "show_toast": true,
    "announce_to_chat": true,
    "hidden": false
  },
  "criteria": {
    "entered_nether": {
      "trigger": "minecraft:changed_dimension",
      "conditions": {
        "to": "minecraft:the_nether"
      }
    }
  },
  "rewards": {
    "function": "mypack:nether_welcome"
  }
}

Save both, run /reload in your test world, and walk through a Nether portal. You should see the “Into the Nether” toast slide in, the action-bar greeting appear, and gain Fire Resistance for 30 seconds. The advancement is now complete for that player, which means by itself it will only ever fire once per player per world. For an “achievement,” that’s exactly right. For a detector you want to fire over and over, we need one more trick, coming up next.

Figure (to be captured). advancement screen open (L key) showing the new “Into the Nether” task icon with its description tooltip

Under the Hood (skippable). changed_dimension also accepts a from field, so you could require a specific origin: say, only count entering the Nether from the Overworld with "from": "minecraft:overworld". We left it off so any route into the Nether counts.

Walkthrough B — the hidden golden-apple detector

Now the pattern this chapter is really about. We want: every time a player eats a golden apple, run a function, with no toast, no screen entry, nothing visible. And “every time,” not just once.

Two ideas combine here:

1. No display block → the advancement is a silent detector. The player never sees it.
2. The reward function revokes the advancement from the player at the end → this un-completes it, so it is armed again and will fire on the next golden apple too.

That second idea is the key to re-triggering. An advancement, once complete, won’t fire again for that player, unless you take it back. The /advancement command does exactly that.

First the detector. The event is consume_item (it fires when the player finishes eating or drinking something), and we narrow it with an item condition to golden apples. Notice: no display field at all.

mypack/data/mypack/advancement/ate_golden_apple.json

{
  "criteria": {
    "ate_gapple": {
      "trigger": "minecraft:consume_item",
      "conditions": {
        "item": {
          "items": ["minecraft:golden_apple"]
        }
      }
    }
  },
  "rewards": {
    "function": "mypack:on_golden_apple"
  }
}

Now the reward function. It does whatever you want and then revokes itself. The revoke line is what re-arms the detector. The function runs as the eating player, so @s targets exactly them:

mypack/data/mypack/function/on_golden_apple.mcfunction

title @s actionbar {"text":"The golden apple's magic flows through you...","color":"yellow"}
advancement revoke @s only mypack:ate_golden_apple

Read that last line carefully, because it’s the whole trick. From the /advancement command:

advancement (grant|revoke) <targets> only <advancement> [<criterion>]: adds or removes a single advancement.

So advancement revoke @s only mypack:ate_golden_apple takes the advancement back from this one player, un-completing it. The next golden apple they eat re-fires consume_item, re-completes the advancement, runs the function again, which revokes again… a perfect, reusable detector.

Save both files (ate_golden_apple.json and on_golden_apple.mcfunction), /reload, then eat a golden apple (/give @s golden_apple 5 first if you need a few). You should get the action-bar message every time, not just once.

Modern Minecraft. This “hidden advancement → function → revoke itself” loop is the standard way data packs react to player events that the game otherwise gives you no hook for: eating a specific food, killing a specific mob, picking up an item. It’s lighter and cleaner than scanning every player every tick with a tick-tag function, because the game tells you the moment the event happens. Keep this pattern in your back pocket; you’ll reach for it constantly.

Practice

1. Pick a different food. Copy ate_golden_apple.json to a new file (say ate_cake.json, id mypack:ate_cake) and change the item’s items to a food you like, and point its function reward at a new function that does something fun and then revokes mypack:ate_cake. Confirm it re-fires every time.

2. A combat detector. Build a hidden advancement (no display) using minecraft:player_killed_entity with an entity condition whose type is a mob you choose, for example minecraft:zombie. Its reward function should reward the player (some experience or an item) and revoke the advancement so it fires on every kill of that mob. Tip: you can give experience two ways here, via the advancement’s rewards.experience or inside the function; pick one and notice the difference (the reward fires once per completion; the function fires every time the function runs).

3. A visible “secret.” Take your “Into the Nether” advancement and make a second, harder one that you keep "hidden": true (but still has display). Choose a frame of "challenge" so it shows the pink “Challenge Complete!” header, and watch how it stays invisible on the advancement screen until you earn it.

What Can Go Wrong

• “My advancement only fired once.” That’s the default behavior: a completed advancement won’t re-fire for that player. If you want it to repeat, the reward function must advancement revoke @s only <its own id> at the end, like the golden-apple detector. Forgetting that line is the single most common mistake with detectors.

• “Nothing happens at all.” Check three things in order: (1) the file is under data/mypack/advancement/ (singular folder); (2) the trigger id is spelled exactly, with the minecraft: namespace; (3) your conditions aren’t too strict, so start with no conditions, get the trigger firing, then add conditions one at a time. A /reload after every edit, too.

• “The function reward errors or hits the wrong player.” The reward function runs as the player who earned it, so use @s, not @p or @a. And it must be a plain function id, not a function tag; the reference explicitly disallows tags here.

What You Know Now

You can read an advancement as what it really is: an event listener, a trigger to watch for, optional conditions to narrow it, optional requirements to combine several triggers (AND across groups, OR within a group), rewards to fire when it completes (above all a function), and display only when you actually want the player to see a toast. You learned the two stealth levels ("hidden": true, off the screen but still toasts, and no display at all, a truly silent detector) and the revoke-to-re-arm loop that turns a one-shot advancement into a reusable event hook. You can now build packs that respond to what players do: eating, killing, traveling, entering a place. That reactive, hidden-detector pattern is the backbone of the bigger projects ahead.

Chapter 20 — Item Modifiers

What You’ll Build

Back in Chapter 17 you learned that a loot table can do more than just pick an item to drop. It can also change that item on the way out, using little building blocks called functions: set_count to change the stack size, set_name to rename it, set_lore to add description lines, enchant_with_levels to enchant it, and so on. Those functions were tucked inside the loot table, only running when the loot table rolled.

In this short chapter you’ll learn how to lift those exact same functions out of a loot table and into their own reusable file, called an item modifier. An item modifier is a recipe for transforming an item, and because it lives in its own file with its own name, you can point at it from anywhere and fire it at any item you like, whenever you like, using a command. No loot table, no mob death, no dropped item required.

By the end you’ll have built a modifier called mypack:upgrade_held that takes whatever item the player is holding and upgrades it on the spot (adding an enchantment and a line of golden lore), plus a one-line function that runs it. You’ll be able to hold a plain stone sword, run the function, and watch it turn into something that looks legendary.

This chapter closes Part V. It extends the mypack pack you started in Chapter 9 and uses the test world you’ve used since Chapter 1.

A function, with a new home

Here is the single most important idea in this chapter, so let’s say it plainly first.

An item modifier is a reusable loot function (or a list of loot functions) saved as its own JSON file. A single modification inside an item modifier is itself called an item function or loot function.

In other words, the things you call “functions” inside a loot table and the things that make up an item modifier are the same things. set_count, set_lore, set_name, enchant_with_levels: every function type you met in Chapter 17 is available here, with the same name and the same fields. The only difference is where the function lives and what makes it run:

• A loot-table function lives inside a loot table file and runs when that loot table is rolled (a mob dies, a chest generates, you fish something up).
• An item modifier lives in its own file under data/<namespace>/item_modifier/ and runs when you tell it to, with the /item command, on an item that already exists in the world.

Why bother splitting it out? Two reasons. First, reuse: if five different loot tables all want to “make this a named, enchanted hero item,” you can write that recipe once as an item modifier and have all five point at it, instead of copy-pasting the same block of functions five times. Second, on-demand transformation: a loot table only changes items as they drop. An item modifier can change an item that is already in a chest or in a player’s hand, something a loot table simply can’t do.

Where item modifiers live, and what they look like

Item modifiers are JSON files, and like every other data-pack file you’ve made, their folder is singular and they sit under your namespace:

data/<namespace>/item_modifier/

For your pack that means data/mypack/item_modifier/. The file name (minus the .json) becomes the modifier’s id, exactly like recipes and loot tables: a file at data/mypack/item_modifier/increase_count.json is referred to as mypack:increase_count.

Now the shape. An item modifier is a single loot function, or an array of loot functions, to apply to the item. The root element can be either a single compound following the structure of a loot function, or a list containing multiple loot functions.

So a modifier file comes in two shapes:

1. A single function: the whole file is one JSON object { ... } describing one function.
2. An array of functions: the whole file is a JSON list [ ... ] of those objects. When you use the list form, every modifier in it is applied in sequence, one after another, in order.

A single function object always has at least one field:

• function — the resource location of the loot function type to apply, e.g. "minecraft:set_count". This is the same set of type names you saw in Chapter 17.

It may also carry:

• conditions — an optional list of predicates (the reusable condition checks from Chapter 18); the function only runs if all of them pass. We won’t need conditions here, but it’s good to know a function can be gated this way.
• plus whatever extra fields that particular function needs: count for set_count, lore for set_lore, and so on.

Running a modifier with /item modify

A modifier file just sits there until something runs it. The thing that runs it is the /item command. It comes in two variations: item modify invokes a modifier alone upon the target slot, while item replace replaces the item in the target slot with another and then invokes a modifier upon it.

We’ll focus on item modify. Here is its exact syntax:

item modify (block <pos>|entity <targets>) <slot> <modifier>

Reading it left to right: you say whether you’re modifying a block’s container (a chest, a furnace) at a position, or an entity’s inventory (a player or mob); then you give the slot to act on; then the modifier to apply. The <slot> is the name of one inventory slot, and its valid values depend on whether you picked a block or an entity. The slot names we’ll use include:

• weapon.mainhand — the item in the entity’s main hand (what they’re holding).
• weapon.offhand — the off-hand item.
• armor.head — the helmet slot.
• hotbar.8 — a numbered hotbar slot.
• container.26 — a numbered slot inside a container block like a chest.

Here is a worked example, which is also the perfect first modifier to build. The file:

data/example/item_modifier/increase_count.json

{
  "function": "minecraft:set_count",
  "count": 1,
  "add": true
}

And the command that fires it at the item in your main hand:

/item modify entity @s weapon.mainhand example:increase_count

That modifier uses the set_count function with "add": true, which means the change is relative to the current count, so each time you run it, the stack in your hand grows by one. Let’s build the same thing in your pack and then make it do something far more interesting.

Make this file:

mypack/data/mypack/item_modifier/increase_count.json

{
  "function": "minecraft:set_count",
  "count": 1,
  "add": true
}

That’s a complete, valid item modifier: a single function, the simplest possible shape. After you save it and run /reload in your test world, hold any stackable item (say, a stack of cobblestone) and type this in the chat bar:

/item modify entity @s weapon.mainhand mypack:increase_count

The stack grows by one. Run it again, and it grows again. You just fired a data-pack file at the item in your hand.

Modern Minecraft — If you follow older tutorials you may see this written with /replaceitem or with raw tag/NBT edits. Those are gone. In current Java Edition the /item command is the way to put items into slots and to transform items in place, and it does it by running an item modifier, the very same loot-function language used everywhere else in the game. Learn this one tool and it pays off in loot tables, advancements, and commands all at once.

Figure (to be captured). a stack of cobblestone in hand growing by one after running mypack:increase_count

Walkthrough: an upgrade-the-held-item modifier

Now for the real goal: a modifier that adds an enchantment and a line of lore to whatever item the player is holding. Because we want to do two things (enchant and add lore), we’ll use the array form of an item modifier: a JSON list of functions, applied in order.

We need two function types from the same loot-function family you met in Chapter 17:

• set_enchantments — a new enchantment function for us here, and a sibling of the enchant_with_levels you used in Chapter 17. Where enchant_with_levels rolls random enchantments for a given enchanting level, set_enchantments lets you set specific enchantments by name. It modifies the item’s enchantments, and takes an enchantments compound, where each key is an enchantment ID and each value is the enchantment power (level). (The level is technically a number provider, the same little value-or-range objects you met with loot tables, but a plain whole number is a perfectly valid number provider, so we’ll just write 3.)
• set_lore — the loot function from Chapter 17, used here on its own. It adds or changes the item’s lore, taking a lore list of lines, where each line is a text component (the rich-text format from Chapter 5), plus a required mode field. The allowed modes are "append", "insert", "replace_all", and "replace_section". We’ll use "append" to add our line without erasing any existing lore.

Here is the complete modifier file. It’s a list, so the whole file is wrapped in [ ... ]:

mypack/data/mypack/item_modifier/upgrade_held.json

[
  {
    "function": "minecraft:set_enchantments",
    "enchantments": {
      "minecraft:unbreaking": 3
    }
  },
  {
    "function": "minecraft:set_lore",
    "mode": "append",
    "lore": [
      {
        "text": "Upgraded by mypack",
        "color": "gold",
        "italic": false
      }
    ]
  }
]

Read it as a two-step recipe. Step one (set_enchantments) adds Unbreaking III to the held item: the key minecraft:unbreaking is the enchantment, the value 3 is the level. Step two (set_lore) appends one golden line of lore that reads Upgraded by mypack. The lore line is a plain text component exactly like the ones you wrote in Chapter 5: a text field with color and a styling flag. We set "italic": false because, as you saw with custom text in Chapter 5, Minecraft typically italicizes custom lore, so turning it off keeps the line sitting upright.

Under the Hood (skippable) — Why is the file a list this time, but increase_count.json was a single object? Both are legal. A single object is a one-function modifier; a list lets you chain several. A list behaves much like the sequence modifier type: there’s even an explicit sequence function type that does the same thing. For two functions, the bare list is the simplest form, so that’s what we use.

Now the function that runs it. We point item modify at the player’s main hand:

mypack/data/mypack/function/upgrade_item.mcfunction

item modify entity @s weapon.mainhand mypack:upgrade_held
say Your held item has been upgraded!

Notice there’s no leading / inside the function file. That’s our rule from Chapter 9. The @s selector means “the entity running this function,” so when a player runs it, it acts on their main hand. Save everything, run /reload, then hold a sword (or any item) and run:

/function mypack:upgrade_item

Your held item gains Unbreaking III and a golden Upgraded by mypack line under its name. Hold a different item and run it again, and the same modifier works on whatever you’re holding, because the modifier describes a transformation, not a specific item.

Figure (to be captured). a stone sword tooltip showing “Unbreaking III” and a gold “Upgraded by mypack” lore line after running mypack:upgrade_item

What item modifiers are good for

Now that you can write and fire a modifier, here are the three big uses, the same three the rest of this book leans on.

Applying a set of components. There’s a function type called set_components whose whole job is to set an item’s data components at once. It sets the components of an item, and it can even remove a component by prefixing its name with !. Components are the heart of how modern Minecraft describes items, and they’re the entire subject of the next chapter (Chapter 21), so we’re only previewing here. The point for now: when you want to stamp a whole bundle of properties onto an item in one shot, an item modifier with set_components is the tool, and you’ll meet it properly next.

Transforming loot. Because an item modifier is built from the very same functions a loot table uses, you can write a transformation once and reference it from a loot table with the reference function (which calls sub-functions), instead of repeating the functions inline. Your loot keeps one shared definition of “what a hero item looks like.”

Dynamic item creation. With /item modify (and its sibling /item replace, which can put a fresh item into a slot and then modify it), a data pack can build and alter items while the game is running: upgrade a player’s gear when they hit a milestone, restyle the contents of a chest, swap a tool’s enchantments mid-quest. None of that can a static loot table do on its own.

Practice

1. A renaming modifier. Write mypack/data/mypack/item_modifier/rename_blade.json as a single function using set_name. set_name adds or changes the item’s custom name and takes a name text component. Give the name a color of your choice. Then make a function that runs item modify entity @s weapon.mainhand mypack:rename_blade and try it on a sword.

2. Stack the steps. Turn rename_blade.json into the array form and add a second function after the rename: a set_lore with "mode": "append" that adds a flavor line. Run it and confirm both the name and the lore change in one command: proof that a list of functions applies in order.

3. Fire it at a chest. Place a chest, put an item in its first slot, and from a function run item modify block ~ ~ ~ container.0 mypack:upgrade_held while standing on the chest. (Adjust the ~ ~ ~ coordinates to point at the chest; those relative coordinates are from Chapter 2.) Watch the item inside the chest get upgraded. This is the “transform an item that already exists” power that loot tables don’t have.

What Can Go Wrong

“Unknown item modifier” or the command fails outright. The <modifier> you name must be the resource location of an existing item modifier. Almost always a failure here means a typo in the id or a misplaced file: the path must be exactly data/mypack/item_modifier/upgrade_held.json (folder singular, namespace folder spelled mypack), and you must /reload after creating it. If the id is right but the file won’t load, your JSON is malformed: a missing comma between the two functions in the array is the classic culprit.

Nothing happens, but no error appears. Check the slot. The command fails or does nothing when the target doesn’t have the specified slot. For example, you ran it against an empty weapon.mainhand (you weren’t holding anything), or you aimed at a block that isn’t a container. Hold an item first, and make sure a chest is actually at the coordinates you gave.

The lore line is missing or replaces everything. set_lore requires its mode field. Leave it out and the function is invalid; set it to "replace_all" by accident and you’ll wipe any lore that was already there. Use "append" when you mean “add a line.”

What You Know Now — Part V Recap

This chapter closes Part V, the part where you learned to make Minecraft do things by writing data files rather than by typing commands. You can now:

• Write recipes, loot tables, predicates, and advancements, and, as of this chapter, item modifiers, which are reusable loot functions in their own files under data/<namespace>/item_modifier/.
• Choose between the two modifier shapes: a single function object, or an array of functions applied in sequence.
• Fire a modifier at any item in the world with /item modify, naming the slot (weapon.mainhand, armor.head, container.0, …) to act on.
• See why an item modifier reaches places a loot table can’t: it transforms items that already exist, on demand.

The single thread running through all of Part V is that the same small building blocks reappear everywhere: a loot function is a loot function whether it’s inside a loot table, referenced from an advancement reward, or standing alone as an item modifier. In Part VI, starting with Chapter 21, we go one level deeper into the items themselves: data components, the named properties that define every item stack, the thing set_components was quietly setting all along.

Chapter 21 — Understanding Data Components

What You’ll Build

Way back in Chapter 1 you learned /give, and you gave yourself plain items: a diamond, a sword, a stack of bread. Since then, little promises have been piling up. In Chapter 5 you saw show_item mentioned but skipped it. In Chapter 17 a loot function called set_components appeared and we said “later.” In Chapter 20 your item modifier used set_components again and we said “later” again.

This is later. This chapter is the keystone of Part VI, and it answers one question: what is an item made of? Once you can answer that, you can build a sword that’s already enchanted, a stick named “Magic Wand,” a bone carrying secret data only your data pack can read, or a glass block you can wear on your head, all from a single /give command, no anvil and no crafting required.

By the end you’ll have a function in your mypack pack called mypack:component_demo that hands you a small collection of custom-built items and, more importantly, you’ll understand the system behind them so the next three chapters are just filling in details. This chapter extends the mypack pack you started in Chapter 9 and uses the test world you’ve used since Chapter 1.

An item is an ID plus components

Here is the big idea, stated as plainly as possible:

“Data components, or simply components, are structured data used to store information and define behavior.”

A data component (also called an item component when it lives on an item) is a named property attached to an item. Each component has an ID (a namespace:path identifier, exactly like the ones you met in Chapter 8) and a value. The component minecraft:custom_name holds an item’s name; minecraft:damage holds how worn-out a tool is; minecraft:enchantments holds its enchantments. An item, in modern Minecraft, is really just an item ID plus a bag of components.

That bag can travel: item components can exist anywhere that an item is stored, such as the player’s inventory, container block entities, and structure files. A named sword keeps its name whether it’s in your hand, in a chest, or saved inside a structure file, because the name isn’t painted on. It’s a component riding along with the item.

Modern Minecraft. If you’ve watched older tutorials, you may have heard about NBT tags and things like {display:{Name:...}} glued onto items. Components are the system that replaced most of that. In fact, data components partially replace the NBT format. When a tutorial tells you to edit an item’s NBT directly, it’s almost always out of date: the modern answer is a component. We’ll keep pointing this out, because the internet is full of the old way.

One honest limit: not everything about an item is a component. Some behavior is welded to the item ID itself, and that behavior cannot be removed from the item, nor applied to a different item that does not have that behavior by default. You can’t turn a dirt block into a sword by bolting components onto it. Components decorate and configure an item; they leave what it fundamentally is untouched.

Every item already has components: defaults

You don’t start from an empty bag. Every item type (item ID) has a set of default data components.

A diamond sword doesn’t need you to tell it that it’s a weapon with a durability bar: those facts come built in. Look at the master list of components and you’ll see each one tagged with an item that has it by default: weapon is listed next to the diamond sword, max_damage (durability) next to the diamond axe, food next to cooked beef, enchantment_glint_override next to the experience bottle. Those are default components: the properties an item type carries automatically.

Here’s the clever part. Item stacks must specify an item ID, which implicitly sets these default components, and default components are not saved on individual item stacks. In plain English: the defaults aren’t written down on each individual sword. The game already knows what a diamond sword’s defaults are, so it doesn’t waste space repeating them. A freshly given diamond sword stores nothing extra: it’s just the ID, and the game fills in the rest.

So what do you store? Only the parts you change. Those implicitly-set default components may be overridden by an individual item stack. To override a component is to specify your own value for it on one particular item, replacing the default. That’s the whole game of this chapter: take an item, override a component or two, and you’ve built something custom.

The bracket syntax: [component=value]

Now the syntax you’ve been waiting for since Chapter 1. When you write an item in a command (like the item argument of /give) you can attach components in square brackets right after the item ID. Here is the exact form:

items are represented in the format item_id[component1=value, component2=value], with component being the namespaced ID of a component, and the value being the value of the component written in SNBT format.

Let’s unpack that, because every piece matters:

• item_id comes first: the item you’re starting from, e.g. diamond_sword. (Because minecraft: is the default namespace from Chapter 8, you may write diamond_sword or minecraft:diamond_sword; they mean the same thing.)
• [ ... ]: square brackets hold the list of components.
• component=value: each entry is a component ID, an = sign, then its value.
• Commas separate multiple components inside the brackets.
• The value is written in SNBT, the same string-NBT format you learned in Chapter 12, with its {key:value} compounds, [...] lists, and number suffixes. A component value can be a single number, a quoted string, a compound, or a whole text component, depending on the component.

So this command, a standard custom_name example, gives you a renamed stick:

/give @s stick[custom_name={text:"Magic Wand",color:"light_purple",italic:false}]

Read it left to right: start with a stick, override its custom_name component, and the value is a text component: yes, exactly the objects you built in Chapter 5, with text, color, and italic. The named sword from the Cursed Blade in Chapter 17 and the upgraded item in Chapter 20 were setting this very same component, just from inside JSON instead of inside brackets.

Two short rules round this out:

“Any components that are not specified are implicitly set to the component’s default value for that item type. If no components are specified, the square brackets can be removed, leaving just the item ID.”

In other words: anything you don’t mention keeps its default, and diamond with no brackets is just a plain diamond. The brackets are optional; they’re only there when you want to change something.

Removing a component with !

Adding and changing components covers two of the three things you can do. The third is removing one, and it has its own punctuation: the exclamation mark, !. Components can be removed by prefixing them with an exclamation mark, like item_id[!component3].

Notice there’s no =value: you’re knocking the component out rather than setting it to anything. The classic example uses the enchanted-look glow that some items have by default:

/give @s experience_bottle[!enchantment_glint_override]

An experience bottle normally shimmers with the enchantment glint. Writing !enchantment_glint_override removes that override component, taking the shimmer away. (You’ll meet a tidier version of this with a different item in the walkthrough below.) The ! form is how you say “I don’t want this component on this item,” and you’ll reach for it whenever an item’s default behavior is in your way.

Under the Hood (skippable). Remember that some behavior is welded to the item ID and can’t be removed. The ! form removes a component override, pushing a component back toward its default or absent state. It does not let you strip out the hardcoded essence of an item. You can remove enchantment_glint_override from an experience bottle; you cannot remove “is a sword” from a sword.

Where it all lives: the components compound

When you’re typing a /give, you see the friendly bracket form. But once that item is sitting in the world, how is it actually stored? Here is the saved shape of any item:

When saved in the NBT format, items are written as a compound with: id (the item’s resource location), count (how many are stacked, default 1), and components, an optional map of additional (non-default) data components.

So an item on disk is a small compound with up to three tags: id, count, and components. That third one, the components compound, is the bag we’ve been talking about, and the word additional is the key. Only the components you overrode get written there. The defaults stay invisible, filled in by the game, exactly as we said earlier.

The bracket form and the components compound are two views of the same thing. When you write stick[custom_name=...] in a command, the game stores it as a stick whose components compound contains one entry, minecraft:custom_name. The brackets are the keyboard-friendly way to write components, and the components compound is how the game saves them.

Try It! Give yourself a renamed item, then read its components back with the read-only tool from Chapter 10 / Chapter 12: hold the item and run /data get entity @s SelectedItem. You’ll see the components compound printed out, holding only the component you changed: proof that defaults aren’t stored on the stack.

Walkthrough: a function that builds custom items

Let’s put the system to work. You’ll add one function to your mypack pack that gives you a handful of items, each showing off one idea from this chapter. Create this file:

mypack/data/mypack/function/component_demo.mcfunction

say Handing out custom-built items...

# 1. ADD a component: a renamed, recolored stick (text component as the value)
give @s stick[custom_name={text:"Magic Wand",color:"light_purple",italic:false}]

# 2. ADD several at once: a wooden sword that's already enchanted
give @s wooden_sword[enchantments={sharpness:3,knockback:2}]

# 3. CHANGE a number: a diamond axe that's nearly worn out (damage = points used up)
give @s diamond_axe[damage=500]

# 4. REMOVE a component with ! : an experience bottle with no glint
give @s experience_bottle[!enchantment_glint_override]

# 5. Hidden data only your pack can read (we'll use this kind of thing later)
give @s iron_sword[custom_data={foo:1}]

Every line here is a /give whose item carries components in brackets, each a standard worked example of one component. Let’s walk through what each one teaches:

• The stick adds a custom_name component whose value is a text component. The name shows up in light purple and, because we set italic:false, without the slanted “this-was-renamed” styling.
• The wooden sword adds two enchantments at once by setting the enchantments component to {sharpness:3,knockback:2}: Sharpness III and Knockback II, ready to swing, no enchanting table needed.
• The diamond axe changes the damage component to 500. To be precise: damage is the number of durability points used up, so a high number means a nearly-broken tool.
• The experience bottle removes its enchantment_glint_override with !, so it stops shimmering.
• The iron sword carries a custom_data component, {foo:1}. The custom_data component holds custom data not used by the game: a private notepad your data pack can stamp on an item and check for later. We’re only planting the flag here; Chapter 24 digs into it.

Now wire the function so you can run it. You already have the mypack:load greeting from Chapter 9; this new function is something you trigger on demand, so you just call it by name. Make sure your pack is loaded, then in the chat bar type:

/reload
/function mypack:component_demo

/reload re-reads your data pack (Chapter 8), and /function runs your new file. Five custom items should land in your inventory. Hover over each one to see the name, the enchantments, and (for the items with hidden data) nothing unusual on the tooltip, because custom_data is invisible to players.

Figure (to be captured). inventory after running mypack:component_demo, showing the purple “Magic Wand” stick, the enchanted wooden sword’s glint, and the non-glinting experience bottle side by side

Modern Minecraft. Notice we never opened an anvil, an enchanting table, or a crafting grid. Every one of these items was born customized, straight from a component. That’s the shift this part of the book is about: in modern Minecraft you describe the item you want in data, and the game makes it.

Practice

These extend the demo function — keep working in the same mypack:component_demo file (or copy it to a new one if you’d like to keep the original).

1. Two names, one item. A lore component adds description lines under an item’s name. Add a line giving yourself a diamond with both a custom_name and a lore line, separating the two components with a comma inside one set of brackets. (Peek at the next chapter’s territory — that’s fine, you’re just practicing the bracket syntax here.)

2. Glint on, glint off. enchantment_glint_override can be set, not just removed. Give yourself a plain stick that shimmers by setting enchantment_glint_override to true, then on the next line give yourself an experience_bottle that doesn’t shimmer using the ! removal form. Run both and compare.

3. Read it back. Give yourself any item with two overridden components, then hold it and run /data get entity @s SelectedItem. Find the components compound in the output and confirm it lists exactly the two components you changed, and none of the defaults.

What Can Go Wrong

You typed : instead of = inside the brackets. Components use component=value, with an equals sign. The format is item_id[component1=value]. A colon belongs inside SNBT compounds ({text:"..."}), not between a component and its value. Mixing them up is the single most common component typo.

You forgot the quotes (or added the wrong ones) in the value. The value is SNBT (Chapter 12), so a text string like a name needs to follow SNBT’s rules: strings inside a component value are quoted, e.g. {text:"Magic Wand"}. If the game rejects your command, re-check that every brace { }, bracket [ ], and quote in the value is balanced and matched, just like any JSON you wrote in Part V.

You expected ! to delete the item’s behavior, and it didn’t. Removing a component with ! only removes an override; it can’t strip behavior that’s welded to the item ID. [!enchantment_glint_override] works because the glint is a component; trying to !-remove a sword’s swordness won’t do anything, because that isn’t a component at all. Such behavior cannot be removed from the item.

What You Know Now

You now understand the modern item system from the ground up. An item is an item ID plus a bag of data components: named properties like custom_name, enchantments, and damage. Every item type ships with default components it fills in automatically and doesn’t bother saving; you build custom items by overriding those defaults. In commands you write components in square brackets after the item ID (item_id[component=value, ...], with values in SNBT), and you remove a component by prefixing it with !, as in item_id[!component]. Under the surface, your overrides live in the item’s components compound alongside its id and count. You can give yourself items with any of this baked in from a single /give. Everything in the next three chapters is just which components exist and what their values look like. Chapter 22 covers how items look (names, lore, rarity, models), Chapter 23 covers what they do (food, tools, weapons, armor, durability), and Chapter 24 covers the specialty components, including a proper tour of the custom_data you just planted.

Chapter 22 — Display Components

What You’ll Build

In this chapter you’ll make a single item look legendary. By the end you’ll have one command that hands you a sword with a glowing purple name, two lines of golden description text underneath it, an “epic” rarity color, and a shimmering enchantment glint, even though the sword isn’t actually enchanted. You’ll write that command into a function in the mypack pack you’ve been building, run it in your test world, and be able to read every piece of it. None of these changes touch what the sword does, only how it looks and reads. That’s the whole idea of this chapter.

Figure (to be captured). the finished “legendary” sword held in hand, tooltip showing the purple name, two gold lore lines, and the enchantment glint

Concepts

Display components vs. functional components

In Chapter 21 you learned that every item carries data components: labelled pieces of data you write inside square brackets after the item’s id, like item_id[component=value]. Some components change what an item does: how much food it restores, what it can break, whether it can be eaten. Others change only how the item looks and reads: its name, the description lines in its tooltip, its color, whether it sparkles. This chapter is about that second group. We’ll call them display components: components whose job is appearance, not behavior. (That’s our grouping name for them; each one is a normal data component from the same list you met in Chapter 21.)

Data components are structured data used to store information and define behavior, and not all characteristics of an item are covered by them. The display components decorate an item without redefining it.

Two names: custom_name and item_name

Here’s a wrinkle that confuses a lot of people: an item can have two different names, and they are separate components.

• minecraft:item_name is the item’s default base name, written as a text component, present on all items by default. It cannot be erased using an anvil, and it is not italicized. Think of it as the name the item ships with, the one a custom item type would use so it reads as “Ruby” instead of “Diamond” everywhere.
• minecraft:custom_name is the player-assigned name of this item, block, or entity, typically assigned with an anvil or a name tag. It has the highest priority to display as the item’s name, and appears italic unless overridden by the text component format.

So if an item has both, the custom_name wins on screen. The everyday way to picture it: item_name is the printed label on the box, and custom_name is the sticker you slapped on top.

Modern Minecraft. In older versions, an item’s name was a single NBT field (display.Name). Now there are two separate components with two different jobs. If a tutorial tells you to edit display.Name, it’s out of date. You want custom_name (or item_name) as a component, exactly like the recipes and loot you’ve already been writing.

What a tooltip is made of

A tooltip is the little box that pops up when you hover over an item in your inventory. From top to bottom it can show: the item’s name, then any lore lines you’ve added, then automatic lines the game adds for components that have something to say (enchantments, durability, and so on). The display components in this chapter let you write the name and lore, color the name, and even hide parts of the tooltip you don’t want shown.

Walkthrough: building the legendary sword

We’ll add the components one at a time, see what each does, then combine them into the final command. Every command below goes inside a function file (no leading /), just like every command since Chapter 9. We’ll collect them into one function at the end.

Step 1 — Name it with custom_name

A custom_name value is a text component, the same {text:..., color:..., ...} object you learned in Chapter 5. Here’s an example (it gives a stick, but the shape is what matters):

give @s stick[custom_name={text:"Magic Wand",color:"light_purple",italic:false}]

That gives “a stick named ‘Magic Wand’ in light purple non-italicized text.” Two things to notice. First, the value is a text-component object, so all your Chapter 5 styling fields work here: color, bold, italic, and the rest. Second (and this catches everyone), the example sets italic:false on purpose. A custom_name appears italic unless overridden by the text component format: Minecraft italicizes custom names by default, so adding italic:false turns that off and the name reads upright. We’ll do the same on our sword.

Step 2 — Describe it with lore

Lore is the description text shown below the name in the tooltip. The minecraft:lore component is a list, and each entry in the list is a text component representing one line. The list has a maximum of 256 lines, far more than you’ll ever need.

A one-line example:

give @p stick[lore=[{text:"This Stick is very sticky."}]]

And a two-line example, which is what we want for the sword:

give @p emerald[lore=[{text:"A shiny Emerald!",italic:false,color:"gold"}, {text:"Maybe share it with a friend?",italic:false,color:"yellow"}]]

This gives an emerald that has 2 lines of lore in its tooltip. The first line has a golden color, and the second has a yellow color, and both lines have had their italics removed. Notice the pattern: lore is an array [ ... ], and each element {text:"..."} is one line. To add a line, add another text component to the list.

Try It! Lore lines are full text components, so a line can be obfuscated, colored with a #hex value, or even split into pieces with an extra list (Chapter 5). Try a line that’s {text:"???",obfuscated:true,color:"dark_gray"} for a “cursed, unreadable” effect.

Step 3 — Tier it with rarity

The minecraft:rarity component sets how special the game treats the item, which shows up as the default color of its name. Its value is one of four strings: rarity can be common, uncommon, rare, or epic. If this component does not exist on the item, then common is used.

give @p iron_sword[rarity=epic]

That “gives an iron sword with a light purple name.” So epic paints the name light purple, which is the color we want for something legendary.

Under the Hood (skippable). Rarity sets the default name color, but custom_name carries its own color field, and that wins. On our sword we set both rarity=epic and a purple custom_name color, so they agree. If you ever set rarity=epic but gave the custom_name a different color, the custom_name color would be what you actually see. The rarity color only shows through when the name itself doesn’t specify one.

Step 4 — Make it shine with enchantment_glint_override

The shimmering “enchanted” sparkle on an item is called the glint. Normally only enchanted items have it. The minecraft:enchantment_glint_override component lets you force that decision either way. Its value is a simple boolean (true or false). When true, the item displays a glint, even without enchantments; when false, the item does not display a glint, even with enchantments.

This example removes a glint:

give @s experience_bottle[enchantment_glint_override=false]

That “gives an experience bottle without the visual enchantment glint, which is otherwise applied by default.” For our legendary sword we want the opposite, a glint with no real enchantment, so we’ll use enchantment_glint_override=true.

Step 5 — Assemble the legendary /give

Now we stack all four components into one command, separated by commas inside a single pair of square brackets. Put this in a new function file:

mypack/data/mypack/function/legendary_blade.mcfunction

give @s diamond_sword[custom_name={text:"Stormcaller",color:"light_purple",italic:false},lore=[{text:"Forged in the first storm.",italic:false,color:"gold"}, {text:"Wielded by none who returned.",italic:false,color:"yellow"}],rarity=epic,enchantment_glint_override=true]

Reading it left to right: it gives you a diamond_sword whose custom_name is “Stormcaller” in upright light-purple text; whose lore is two lines, gold then yellow, both upright; whose rarity is epic; and whose glint is forced on. Four display components, one item, no change to how the sword fights.

Wire it into the pack the same way as every function, but this one you’ll trigger by hand rather than on load, so it doesn’t need a tag. In your test world, after /reload, run it from chat:

/function mypack:legendary_blade

You should be holding Stormcaller, glinting and purple, with its two gold-and-yellow lore lines.

Figure (to be captured). chat showing /function mypack:legendary_blade run, and the resulting tooltip

Under the Hood (skippable). You could have typed this whole give straight into chat with a leading /. Putting it in a function instead means you can hand out the exact same legendary blade again and again (from an advancement reward, a loot table, or another function) without retyping a long bracket string. That’s the “think in data packs” habit: build the thing once, call it by name.

The pointer components

The remaining display components don’t carry their own appearance. They point at something else. Three of them point at assets you’ll build later in a resource pack (Chapter 29), so here we’ll learn what they are and the exact value they take, and leave the asset-building for Part VIII.

item_model — swap the item’s whole model

minecraft:item_model replaces what the item looks like by pointing at a model definition. Its value is a string, a resource location. It’s the resource location of the item, which references the item model definition file in a resource pack. This example reuses a vanilla model:

give @s netherite_sword[item_model="minecraft:diamond_sword"]

That “gives a netherite sword that looks like a diamond sword.” When you make your own models in Chapter 29, you’ll point item_model at one of yours (like item_model="mypack:ruby") and the item will render as that model. Be aware that referencing nonexistent models will cause the missing model to be used, so the pointer only works once the asset exists.

custom_model_data — data for a model to read

minecraft:custom_model_data is the classic hook for custom models. Unlike item_model, it doesn’t name a model; it carries data that a model definition reads to decide which variant to show or how to tint it. Its value is a compound holding up to four lists:

• floats: a list of floats, for the range_dispatch model type.
• flags: a byte-array of booleans, for the condition model type.
• strings: a list of strings, for the select model type.
• colors: a list of RGB values, for the model model type’s tints.

For example:

give @s bone[custom_model_data={floats:[4.0, 5.6, 99.1],strings:["foo:bar"],colors:[8323327, [0.5,0,1], 0x7F00FF]}]

Modern Minecraft. This is a real trap for old tutorials. custom_model_data used to be a single number (custom_model_data:3). It is now a compound with floats, flags, strings, and colors lists, as shown above. If a video tells you to set custom_model_data to one integer, it’s from before the change — use the compound shape shown above. We’ll actually wire it up to a model in Chapter 29; for now, know what its data looks like.

tooltip_style — a custom tooltip box

minecraft:tooltip_style changes the background and frame of the tooltip box itself. Its value is a string resource location pointing at custom sprite textures in a resource pack. It references textures for a _background and a _frame sprite, and invalid specifications will use the missing texture. Like item_model, the pointer is written here but the artwork is a Chapter 29 job.

tooltip_display — hide parts of the tooltip

minecraft:tooltip_display lets you suppress tooltip lines. It allows the tooltips provided specifically by any given item component to be suppressed. Its value is a compound with two fields:

• hide_tooltip: a boolean. If true, the item has no tooltip when hovered at all.
• hidden_components: a list of component resource locations; each one’s tooltip line is hidden.

To hide one component’s line while keeping the rest:

give @p diamond_sword[tooltip_display={hidden_components:["minecraft:enchantments"]},enchantments={sharpness:1}]

That “gives a diamond sword that is enchanted with Sharpness I, but doesn’t show the enchantments in the tooltip.” And to hide the whole tooltip:

give @p diamond_sword[tooltip_display={hide_tooltip:1b}]

That gives a sword “that when hovered, it shows no tooltip at all.” (The 1b is the SNBT way of writing the boolean true, from Chapter 12: a b-suffixed 1.)

item_name in practice

We met item_name in the concepts section as the default base name. You set it the same way as custom_name, with a text component. This example uses the plain-string form of a text component:

give @s diamond[minecraft:item_name="Dirt"]

That “gives a diamond that is named ‘Dirt’.” Because a bare string "Dirt" is itself a valid text component (Chapter 5), you can write the name with or without the full {text:...} object. Reach for item_name when you want a base name that isn’t italic and that a player can’t rename away in an anvil, and reach for custom_name (as we did on the sword) for the top-priority, player-style name.

Practice

These extend the legendary blade and the components above. Put each in a function or run it from chat in your test world.

1. Arm the whole team. Change the give in legendary_blade.mcfunction to target every player instead of just yourself, by swapping @s for @a (Chapter 3). Reload and run it, and everyone online gets a Stormcaller.

2. A quiet enchantment. Give yourself an enchanted item whose enchantment is hidden from the tooltip and whose glint is turned off, so it looks completely ordinary:

   give @s iron_sword[enchantments={sharpness:2},tooltip_display={hidden_components:["minecraft:enchantments"]},enchantment_glint_override=false]
   

   Confirm in-game that it has no glint and no enchantment line, yet still hits harder.

3. A renameable label. Give a diamond an item_name of your choice (a base name) and also a custom_name (the sticker on top). Hover it: you should see the custom_name, because it has the highest priority. Then imagine renaming it in an anvil: the custom_name would change, but the item_name underneath would not.

What Can Go Wrong

• Your custom name comes out italic. You forgot italic:false. A custom_name appears italic unless overridden: Minecraft slants custom names by default. Add italic:false inside the text-component value (as in every example above) to make it upright.

• rarity does nothing visible. Two common causes. Either you set a custom_name whose own color overrides the rarity color (the name color wins — see the Under the Hood box in Step 3), or you misspelled the value. Rarity must be exactly common, uncommon, rare, or epic; anything else isn’t a valid value.

• The glint won’t turn off on an enchanted item. Make sure you used enchantment_glint_override=false, not true. false “does not display a glint, even with enchantments”; true forces one on. The two are opposites, and it’s easy to type the wrong one.

What You Know Now

You can change how an item looks and reads without changing what it does. You can name it two different ways, custom_name (top priority, player-style, italic-by-default) and item_name (the un-erasable base name); describe it with lore lines; color its name with rarity; force or remove the enchantment_glint_override shimmer; hide tooltip lines (or the whole tooltip) with tooltip_display; and write the pointers (item_model, tooltip_style, and custom_model_data) that hook an item up to custom artwork you’ll build in Chapter 29. Most of all, you can read a long bracketed /give and say exactly what each component does, the skill the rest of Part VI builds on.

Chapter 23 — Functional Components: Food, Tools, Weapons, and Armor

What You’ll Build

In Chapter 21 you learned what data components are: the named pieces of data stamped onto every item, written in square brackets after the item’s ID like iron_sword[custom_data={foo:1}]. Most of the components you’ve met so far have been about how an item looks or reads: its name, its lore, its custom model. This chapter is about the other half, the components that change how an item behaves.

By the end of this chapter you’ll be able to make almost any item act like almost any other kind of gear. You’ll turn a plain item into food with your own nutrition and a built-in effect; give a tool custom mining rules; turn an item into a weapon, or even into a shield that blocks attacks; make an item wearable in an armor slot; pile stat bonuses onto it; and control its whole durability life: how much it can take, whether it can be enchanted, and what repairs it. You’ll also meet three brand-new components from the 26.x updates: glider (elytra-style flight on any item), kinetic_weapon (charge/ram attacks), and death_protection (a totem’s “save you once” behavior, now data-driven).