Chapter 24 — Specialty Components

What You’ll Build

Over the last three chapters you’ve been learning data components, the named properties that ride along on an item stack. Chapter 21 taught you the system: every item has default components, and you override them inside square brackets with the /give command, like diamond_sword[custom_name="My Sword"]. Chapter 22 covered the components that change how an item looks (name, lore, rarity, glint), and Chapter 23 covered the ones that change what an item does (food, tools, weapons, armor).

This chapter is the grab-bag that closes Part VI. It’s a guided tour of the rest of the components worth knowing: the ones that let an item carry enchantments, hold a potion’s effects, store other items inside itself, draw a custom banner or map, trim a piece of armor, place a pre-loaded block, or carry a secret note that only your data pack reads. None of these is hard on its own. The skill this chapter builds is recognising which component does which job, and reading its value shape so you can write it correctly.

By the end you’ll have made a custom splash potion that throws a cloud of your own chosen effects, using nothing but a /give command. You’ll also have met custom_data again (the component that is your data pack’s private scratchpad) and seen why it’s the single most important component in this whole chapter for the kind of work the rest of the book does.

This chapter extends the mypack pack from Chapter 9 and uses the test world from Chapter 1. Everything here is a /give command you can type straight into the chat bar to see the result instantly.

How to read this chapter. This is a reference tour, not a single build. Skim the headings, try the /give examples that interest you, and come back to look things up later. Every component name and value shown is copied exactly from the wiki’s Data component format page. When you need the precise spelling of a field, this chapter (and Appendix C) is where to find it.

A quick reminder of the shape

From Chapter 21, the format inside the square brackets is always the same:

item_id[component1=value, component2=value]

Each component is a name, and each value is written in SNBT, the same text form of NBT you learned in Chapter 12 (numbers, quoted strings, {} compounds, [] lists, the 1b/0b booleans). A few components are a single word or number; most are a {...} compound or a [...] list. The wiki’s Data component format page says it plainly:

“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.”

You can leave the minecraft: namespace off a component name in a command (the game assumes it), so enchantments and minecraft:enchantments mean the same thing. We’ll write the short form throughout.

Enchantments: enchantments and stored_enchantments

The enchantments component holds a map of each enchantment to its level: a list of key-value pairs where the key is the enchantment’s resource location and the value is the level number. Put it on a sword and the sword is actually enchanted:

/give @s wooden_sword[enchantments={sharpness:3,knockback:2}]

That gives a wooden sword with Sharpness III and Knockback II. (Notice the level is the roman-numeral tier, so 3 means III.)

There’s a near-twin called stored_enchantments, and the difference matters. The wiki spells it out:

“This component adds active enchantments and should not be confused with the stored_enchantments component, which is used to add inactive enchantments, such as with enchanted books.”

So enchantments makes the enchantment work right now: swing the sword and Knockback fires. stored_enchantments is what an enchanted book uses: the enchantment is dormant, just carried, until you combine the book with a real item in an anvil. The clearest possible test:

“hitting an entity with an enchanted_book[enchantments={knockback:2}] would knock any entity hit per knockback II while hitting an entity with an enchanted_book[stored_enchantments={knockback:2}] would not.”

Both use the same inner shape ({enchantment_id: level}); they differ only in whether the enchantment is live or stored.

Modern Minecraft. In old tutorials you’ll see enchantments written as a long Enchantments:[{id:...,lvl:...}] NBT list. The modern component is the compact map you see above: one enchantment per line, name then level. If a tutorial shows the old list form, it’s pre-component and won’t paste in as-is.

Potions: potion_contents

The potion_contents component is what makes a potion a potion. It holds three things:

“The base potion, custom list of mob effects, and custom color contained in this potion, splash potion, lingering potion, tipped arrow, or area effect cloud.”

The simplest form just names a base potion:

/give @a potion[potion_contents={potion:"minecraft:night_vision"}]

That’s a plain Night Vision potion. But you can skip the base potion entirely and supply your own list of effects with custom_effects. Each effect is a compound with an id (which effect), an amplifier (the level, where 0 is level I), and a duration in ticks. Here is an example of a potion carrying a custom Wither effect:

/give @a potion[potion_contents={custom_effects:[{id:"minecraft:wither",amplifier:1,duration:3600}]}]

amplifier:1 means Wither II, and duration:3600 is 3600 ticks. From Chapter 7 you know there are 20 ticks per second, so that’s 180 seconds, three minutes. We’ll build on this exact shape in the practice at the end.

There’s a companion component, potion_duration_scale, that multiplies how long the effects last:

/give @p potion[potion_contents={potion:swiftness},potion_duration_scale=2]

That gives a Potion of Swiftness whose default 3-minute duration is doubled to 6 minutes: the =2 is the multiplier, so =3 would triple it.

Items that hold items: container and bundle_contents

Some items carry other items inside them. A shulker box is the classic example, and the container component is how its contents are stored. It holds the items contained in the container’s slots, and each entry pairs an item with a slot number:

/give @s barrel[container=[{slot:0,item:{id:apple}}]]

That’s a barrel with an apple already sitting in its first slot (slot 0). Each entry in the list is a compound with two parts: item (the item stack to store) and slot (which slot, numbered from 0). The component supports up to 256 slots, though a given block only uses as many as it has: a chest uses 27, a decorated pot just 1.

A bundle holds items too, but more loosely: it has no fixed slots, just a pile. Its component is bundle_contents, and it’s simply a list of item stacks:

/give @s bundle[bundle_contents=[{id:"diamond",count:2}]]

That bundle starts with two diamonds in it. Note that bundle_contents only does anything on an actual bundle; adding this component to any item other than a bundle does nothing.

Fireworks: firework_explosion and fireworks

These two go together. A firework star carries a single firework_explosion, one burst effect. A firework rocket carries fireworks, which bundles a list of those bursts plus a flight duration.

A single explosion (a firework star) has these fields:

• shape: the burst shape, one of small_ball, large_ball, star, creeper, or burst.
• colors: a list of colors (as packed integers) for the initial particles.
• fade_colors: a list of colors the particles fade into.
• has_trail: a boolean; whether the burst leaves a trail (the diamond effect).
• has_twinkle: a boolean; whether it twinkles (the glowstone-dust effect).

The fireworks component (the rocket) wraps that up:

• flight_duration: a byte from -128 to 127 (defaults to 1); this is also how many gunpowder the rocket would take to craft.
• explosions: a list of explosion compounds, each with the same shape/colors/ fade_colors/has_trail/has_twinkle fields as above (up to 256 of them).

A note on colors. Firework colors are stored as a color packed into a single integer: one number that encodes red, green, and blue together. We’ll meet exactly how that number is built in a moment with map_color. For now, know that a firework color is one integer per color, listed inside colors or fade_colors.

Try It! Build a firework /give line of your own from the field list above: try a firework star with firework_explosion={shape:"star",has_twinkle:true} and watch the shape in the tooltip. Adding colors requires a packed-integer color; see map_color below for how to read one.

Compasses: lodestone_tracker

A lodestone compass points at a fixed spot instead of spinning toward spawn. The lodestone_tracker component stores where it points:

• target: an optional compound holding pos (the block coordinates as an integer array) and dimension (the dimension’s ID). If target is left out, the compass spins randomly.
• tracked: a boolean. If true (the default), the component is removed when the lodestone is broken; if false, the compass keeps pointing there even with no lodestone.

To make a compass that points toward a lodestone located in the Overworld at x=1, y=2, z=3, the component form is a target of {pos:[1,2,3],dimension:"minecraft:overworld"}.

Under the Hood (skippable). A lodestone compass also renames itself (its base item name is overridden to “Lodestone Compass”), and while it’s in your inventory the game keeps checking whether its lodestone still exists. That polling is why a tracked:true compass goes back to spinning the moment its lodestone is mined.

Maps: map_id, map_color, map_decorations

A filled map is really just a pointer to map data the world stores separately. Three components customise it.

map_id is that pointer, an integer “number of this filled map, representing the shared state holding map contents and markers.” Two maps with the same map_id show the same picture, because they point at the same stored data.

map_color is an integer color for the little map item’s texture tint:

/give @s filled_map[map_color=16711680]

That gives “a filled map with red markings on item texture.” The number 16711680 is how pure red is written as a single packed integer, and it’s worth understanding because the same trick encodes firework colors, leather-armor dye, and more. A packed color squeezes three values (red, green, blue, each 0–255) into one number: red counts in the millions, green in the thousands, blue in the ones. Pure red (255,0,0) comes out as 16711680. You don’t have to do this math by hand; some other components also accept colors written as a hex code like 0x7FFF33 or as a list of three decimals like [0.5, 1.0, 0.2], but map_color itself takes the single integer.

map_decorations puts markers on the map: the little icons for players, banners, monuments, and so on. It’s a set of named icons, each with:

• type: which icon. There are many, including player, frame, red_marker, blue_marker, target_x, target_point, mansion, monument, the banner_<color> icons, the village_<biome> icons, jungle_temple, and swamp_hut.
• x and z: the world coordinates of the marker (as decimals).
• rotation: which way the icon points, 0.0 to 360.0 degrees clockwise from north.

The key you give each decoration is just “an arbitrary unique string identifying the decoration”: any name you like, used so you can tell two markers apart.

Banners and shields: banner_patterns and base_color

A banner’s design is a stack of coloured patterns. The banner_patterns component is a list of those patterns, applied bottom to top. Each entry has a color (the dye color of that layer) and a pattern (which design). For example:

/give @s black_banner[banner_patterns=[{pattern:"triangle_top",color:"red"},{pattern:"cross",color:"white"}]]

That’s a black banner with a red triangle and a white cross laid over it.

base_color sets the background color. It’s mainly used on shields, which can wear a banner design:

/give @s shield[base_color="lime"]

There’s a friendly side effect: a shield with a base_color gets renamed, so base_color=green makes the item show as “Green Shield.” And if you put banner_patterns on a shield without a base_color, the game fills in white as the background automatically.

Armor trim: trim

An armor trim is the decorative edging you apply at a smithing table. The trim component stores which design and which material:

/give @p leather_leggings[trim={"pattern":"host","material":"emerald"}]

That gives “leather pants with the ‘host’ pattern made of emerald.” Two fields: pattern (the ID of the trim pattern) and material (the ID of the trim material, which decides the trim’s colour). Both pattern and material are resource locations naming entries in registries you’ll meet in Chapter 38, where trim patterns and materials are defined; here you’re just naming ones that already exist.

Placing and spawning: block_entity_data and entity_data

Two components let an item carry data that “wakes up” when the item turns into something else.

block_entity_data is NBT applied when the item is placed as a block, but only for blocks that have a block entity (a block with extra stored data, like a spawner, chest, or sign). This example loads a spawner with a spider:

/give @s spawner[block_entity_data={id:"mob_spawner",SpawnData:{entity:{id:"spider"}}}]

Place that block and it’s a working spider spawner. The data must include an id tag naming the block entity type, and it excludes the position tags (x/y/z) and a couple of others: the game fills those in when you place it.

entity_data is the matching idea for things that spawn an entity: spawn eggs, buckets, armor stands, item frames. It’s “NBT applied to an entity when created from an item”:

/give @s armor_stand[entity_data={id:"armor_stand",Small:1b}]

That armor stand spawns small. Like block_entity_data, it must include an id, and a couple of tags are excluded (UUID and Passengers). A fun example shows the trick at its sneakiest, a wolf spawn egg that actually spawns a cat:

/give @p minecraft:wolf_spawn_egg[entity_data={id:"minecraft:cat"}]

What Can Go Wrong? Both block_entity_data and entity_data can add a red message to the item’s tooltip (for operator players only) warning the player that placing it may result in command execution. That’s a deliberate safety feature: Minecraft flags items that could run commands when placed or used. If you see that red warning, the game is just telling you this item carries data that can run commands.

Your data pack’s scratchpad: custom_data

Of every component in this chapter, this is the one you’ll reach for most in the rest of the book. custom_data is, in Minecraft’s own words:

“key-value pairs of any custom data not used by the game, either as an object or a SNBT string.”

That phrase (not used by the game) is the whole point. Every other component means something to Minecraft: enchantments enchants, food feeds, trim decorates. custom_data means nothing to the game at all. It’s a blank notebook the game faithfully carries around on the item but never reads. It’s yours. You decide what goes in it, and only your data pack reads it back out.

/give @s iron_sword[custom_data={foo:1}]

That’s an iron sword secretly tagged with {foo:1}. To you that means whatever you want it to mean: “this is quest item #1,” “this sword has been blessed,” “this is the third key.” You mark items with custom_data, then later check for it. This is exactly how you build custom items that your pack recognises: tag the item on the way out, test for the tag when it’s used.

You first met this idea back in Chapter 17 and Chapter 18, where a predicate could test an item’s components. custom_data is the component you’ll most often test for, and the chapters ahead lean on it constantly. It’s the bridge between “an ordinary-looking item” and “an item my data pack treats specially.”

Modern Minecraft. Long ago, packs faked custom items by abusing the item’s name or a stray NBT tag, and detection was fragile. custom_data is the clean, supported home for “my pack’s private label on this item.” When an old tutorial tells you to match on a custom name to detect a special item, the modern answer is almost always: put a custom_data tag on it instead.

Damage immunity: damage_resistant

damage_resistant makes an item “invulnerable to the specified damage types when in entity form or equipped” (entity form meaning when it’s lying on the ground as a dropped item). This example makes a fireproof cake:

/give @s cake[damage_resistant={types:"#minecraft:is_fire"}]

It has one field, types, and the value is “a damage type tag prefixed with #.” That # should look familiar: it’s the registry-tag reference syntax from Chapter 14. #minecraft:is_fire is a group of fire-related damage types, not a single one. The damage-type registry and its tags are a Chapter 36 topic; here you only need to know the value is a #-prefixed tag naming which kinds of damage the item shrugs off.

A handful of newer specialty components

These are smaller but genuinely useful, and you’ll meet them in tutorials, so it’s worth knowing what they do.

use_remainder: “replaces the item with a remainder item if its stack count has decreased after use.” In plain terms: what’s left behind after you use it. A water bottle becomes an empty bottle; here’s a splash potion leaving gunpowder:

/give @p splash_potion[use_remainder={id:"minecraft:gunpowder"}]

The remainder is a full item stack, so it can carry its own components and count. Here’s cooked chicken that turns into two named bones after eating:

/give @p cooked_chicken[use_remainder={id:"minecraft:bone",components:{custom_name:{text:"Chicken Bone"}},count:2}]

break_sound: the sound that plays “when the item runs out of durability and breaks.” The value is the ID of a sound event:

/give @s diamond_sword[break_sound="item.wolf_armor.break"]

That diamond sword plays the wolf-armor break sound when it finally snaps.

provides_banner_patterns: marks an item so that, placed in a loom, it offers a banner pattern. The value is a banner-pattern tag, prefixed with #:

/give @p diamond[provides_banner_patterns='#minecraft:pattern_item/globe']

That diamond can hand the globe pattern to a banner at a loom.

provides_trim_material: similarly marks an item so it “provides the specified trim material when used in a trimming recipe.” The component name is exact; build the /give line from it, with the value set to the ID of a trim material. Note that the item must also be in the #trim_material tag to work in the built-in recipes.

jukebox_playable: makes an item playable in a jukebox; the value names a jukebox song definition to play, and the song’s artist and title get added to the item’s tooltip. For instance, you can make a diamond that plays Pigstep when inserted into a jukebox. The component name is exact; build the /give line from it, with the value set to the resource location of a jukebox song.

sulfur_cube_content: “the item stored inside the sulfur cube.” It holds a single item stack and adds a gray “Contains: <item>” line to the tooltip. The component name is exact; build the /give line from it, with the value set to a single item stack (the same item-stack shape used by bundle_contents and use_remainder). Confirm the host item’s id in-game if you’re unsure of it.

The mob-customising components: .../variant, .../collar, .../size, .../color

A whole family of components lets a spawn egg or bucket decide which kind of mob it makes. Their names always have a slash: the mob, then the property. They’re called entity variant components, a group of components present in items like spawn eggs, mob buckets, paintings, and item frames, which modify some of the properties of the entity stored within those items. A few examples:

/give @s wolf_spawn_egg[wolf/variant="rusty"]
/give @s wolf_spawn_egg[wolf/collar="blue"]
/give @s salmon_spawn_egg[salmon/size="large"]
/give @s sheep_spawn_egg[sheep/color="blue"]
/give @s axolotl_spawn_egg[axolotl/variant="blue"]

Reading the names: wolf/variant picks the wolf’s breed ("rusty"), wolf/collar sets its collar color, salmon/size is one of small/medium/large, sheep/color and wolf/collar take a dye color, and axolotl/variant names an axolotl type (the example uses "blue"; the full list of variants comes from registries in Chapter 42). There are many more (cat/variant, horse/variant, villager/variant, tropical_fish/pattern, and so on), each following the same mob/property=value shape.

The values these accept (the full list of wolf variants, painting variants, and the like) come from registries you’ll meet in Chapter 42, where mob variants are defined and where you can even add your own. For now: recognise the mob/property naming, and know that the value is the name of an existing variant.

Practice: a custom splash potion

Time to put potion_contents to work. You’re going to build a splash potion (the kind you throw) that bursts into a cloud of your chosen effects. Everything you need is the custom_effects shape you saw earlier: a list of effects, each with an id, an amplifier (level, starting at 0), and a duration in ticks.

Open your test world’s chat bar and run this, noting splash_potion as the item, so it’s throwable:

/give @s splash_potion[potion_contents={custom_effects:[{id:"minecraft:regeneration",amplifier:1,duration:600},{id:"minecraft:speed",amplifier:0,duration:1200}]}]

Read it left to right. It’s a splash potion whose potion_contents carries two custom effects: Regeneration II (amplifier:1) for 600 ticks (30 seconds), and Speed I (amplifier:0) for 1200 ticks (60 seconds). Throw it and anything caught in the splash gets both. Hover the bottle first and you’ll see both effects listed in the tooltip: when present on an item, the mob effects are listed in the item’s tooltip.

Figure (to be captured). the custom splash potion’s tooltip showing Regeneration II and Speed I, and the coloured cloud after it’s thrown

Now the color. You can set a custom color on the potion too. Inside potion_contents, custom_color is an integer, “the overriding color of this potion texture, and/or the particles of the area effect cloud created.” It’s a decimal color number, the same hex-as-decimal trick you met for leather armor and biome water: pick a hex color, convert it to decimal, and drop it in. A vivid magenta (#FF00FF → 16711935) makes the swirl unmistakable:

/give @s splash_potion[potion_contents={custom_effects:[{id:"minecraft:regeneration",amplifier:1,duration:600},{id:"minecraft:speed",amplifier:0,duration:1200}],custom_color:16711935}]

Without custom_color, a potion’s swirl color is decided by its effects, so even the plain two-effect brew above comes out tinted on its own; custom_color just overrides that with a color you choose.

Try It! Swap in your own effects. Want a “panic potion”? Try custom_effects:[{id:"minecraft:blindness",amplifier:0,duration:200},{id:"minecraft:slowness",amplifier:2,duration:200}]. Want a long, gentle heal? One Regeneration I for a big duration. Remember amplifier:0 is level I, and 20 ticks make a second.

Try It! (give it a name). Combine this chapter with Chapter 22: add a custom_name so your brew reads as something special, e.g. splash_potion[potion_contents={custom_effects:[{id:"minecraft:regeneration",amplifier:1,duration:600}]},custom_name={text:"Potion of Second Wind",color:"light_purple",italic:false}].

What Can Go Wrong

Mixing up enchantments and stored_enchantments. If your enchanted book “doesn’t do anything” when you hold it, that’s correct: stored_enchantments is meant to be inactive until you combine the book with an item in an anvil. Use enchantments (not stored_) when you want the effect to fire from the item itself.

Forgetting the id in block_entity_data / entity_data. Both components require an id tag naming the block-entity type or entity type. Leave it out and the data has nothing to attach to. And don’t be alarmed by the red operator-only warning on the tooltip: that’s the game safely flagging that the item carries placeable/spawnable data.

Expecting custom_data to do something. It won’t, by design. custom_data is data the game never reads. If you tag a sword with custom_data={hero:1b} and expect the sword to behave differently on its own, nothing will happen until your pack tests for that tag (with a predicate, as in Chapter 18) and acts on it. The component is the label; your pack supplies the behaviour.

What You Know Now

You’ve toured the specialty data components: enchantments and stored_enchantments (live vs. dormant), potion_contents (with custom_effects) and potion_duration_scale, the item-holding container and bundle_contents, firework_explosion/fireworks, lodestone_tracker, the map trio map_id/map_color/map_decorations, banner banner_patterns + base_color, armor trim, the place-and-spawn pair block_entity_data / entity_data, the all-important custom_data scratchpad, damage_resistant, and the newer use_remainder, break_sound, provides_banner_patterns, provides_trim_material, jukebox_playable, sulfur_cube_content, plus the mob/variant-style entity variant components. You can read any component’s value shape and write it into a /give command, and you’ve thrown a splash potion you brewed yourself.

That closes Part VI. You now think of an item as a small bundle of named components you can read, write, and combine, the basis for everything from custom items to quest systems. The complete component list lives in Appendix C.

You can now build: custom enchanted gear, custom potions and tipped arrows, pre-filled shulker boxes and bundles, decorated banners, shields, and trimmed armor, lodestone compasses and marked maps, pre-loaded spawners and spawn eggs, and, most importantly, items your own data pack secretly recognises through custom_data.