Items¶
Quick Start: Spice it up with twists.
Item payloads feed <give>, <dropitem>, and <intercept>: one
[material, qty] pair, or a nested list of pairs for several
stacks at once. The tags themselves live in the cheatsheet.
Payloads¶
| Shape | Meaning |
|---|---|
[material, qty] |
One stack ([diamond, 3]). |
[[a, 1], [b, 2]] |
One stack per pair. |
Materials are lower-case ids (diamond, iron_sword); qty clamps
to 99 per stack, past the material's own max. Oversized stacks
stay whole in <give> (one slot each, dropped on overflow).
Unknown materials warn and skip, so one bad pair never voids its
siblings. (ON_CRAFT_PREPARE and ON_BLOCK_PLACED
take exactly one pair, never a nested list; on placed the pair names
the new block and air cancels.)
Native Data¶
A third index carries verbatim Minecraft component data, the same blob a vanilla command takes between square brackets. Build it in mcstacker.net for your server version, then strip the outer brackets:
The engine wraps the string in brackets and hands it to the server
parser unchanged; it never validates component names itself. In
YAML, single-quoted lines double the inner quotes (''); the GUI
editor takes the raw form with plain single quotes.
This is version-coupled by design: Mojang renames components
between releases, so a blob from another version warns and keeps
the plain stack instead of breaking anything. The classic 1:1 is
an elytra: elytra[unbreakable={},custom_name={"italic":false,
"text":"Skyfall"},enchantments={"unbreaking":10}] becomes
[elytra, 1, 'unbreakable={},custom_name={"italic":false,
"text":"Skyfall"},enchantments={"unbreaking":10}'].
JMH Item Data¶
Lists past the qty are JMH item data: friendly key/value pairs the engine applies itself, stable across Minecraft updates. Keys match case-blind, and duplicates keep the last with a warning:
| Key | Value |
|---|---|
name |
Display name, MiniMessage colors allowed. |
lore |
One line, or a list of lines. |
glow |
true or false: enchantment glint without enchantments. |
enchantments |
[id, level?], or a list of pairs; level defaults 1. |
tag paid |
An invisible marker (100 chars at most), readable via <itemtag>. |
potion |
[id, amplifier, seconds, icon?], or a list; potions and tipped arrows only. |
unbreakable |
true or false: never lose durability. |
keep paid |
true or false: the stack cannot leave the inventory. |
- '<give:Steve,[diamond_sword, 1, [name, <red>Dragonslayer</red>], [lore, [Forged in fire, Second line]], [enchantments, [sharpness, 5]], [tag, quest_blade]]>'
Names and lore read white and non-italic unless the text sets its
own color or italics. Lore lines over 100 visible chars wrap at
word edges (MiniMessage markers do not count); \n forces a
break, and a list of lines is the preferred shape. Tags normalize
to lower-case (quest blade becomes quest_blade) and read back
unprefixed through <itemtag:player,slot>. Potion amplifiers are 0-based (0
is level I), seconds accept -1 for infinite and fractional values
for exact ticks (0.20 is 4 ticks), an optional trailing false
hides the effect icon (default true), and doses on a
non-potion item warn and skip. Unknown enchantment or potion ids
warn and skip as well. <random-enchant:[1,3]> draws one
[id, level] pair for that key (cursed and treasure enchants
included); the level draws from the one arg (1 default), a
single or [min, max] whole pair clamped to 0..255, and
malformed args warn and fall back to level 1. Every dose lands as a
fully visible custom effect with its exact amplifier and duration,
and the vanilla base is never touched, so brews carry exactly the
authored doses and nothing else. Dose-carrying potions without a
name key take a generated name from their first dose (Potion of
Glowing for a leading glowing dose) instead of the Uncraftable
Potion default; splash brews, lingering brews, and tipped arrows
read their own formats (Splash Potion of Glowing, Lingering
Potion of Glowing, Arrow of Glowing). An explicit name key or
a native display name wins either way. The
modifiers.potion-name, modifiers.splash-potion-name,
modifiers.lingering-potion-name, and modifiers.tipped-arrow-name
messages hold the formats ({effect} fills the effect display).
unbreakable sets the flag directly, replacing native
unbreakable={} blobs in payloads. keep shares the compass
lock-to-inventory guards: kept stacks cannot be dropped, stashed in
containers, or hoppered out, with no lobby switch (the flag is the
switch; false clears it). <itemkeep:player,slot> reads the flag
back (true/false, null when the player is offline), and it
reads true for the native tracking compass too.
MiniMessage markers pass through the tag layer untouched at runtime, so colors in names just work with no validation warnings. When native data and JMH data share one item, JMH overwrites where defined and native fills the rest. For niche components (armor trims and friends), native data stays the recommended path.