Items

A menu icon, a special item, a kit entry, a lobby hotbar slot and a shield are the same block of YAML. This is the one parser for all of them.

PluginItems items = Items.of(this);
 
Item icon = items.parse(section);              // once, when the file loads
ItemStack stack = items.render(icon, player);  // whenever somebody looks at it

Item is a definition, not an ItemStack. It holds its placeholders unresolved, is shared by every player who sees it, and can be compared, cached and tested without a running server. Turning one into an item is per-viewer work.

The object

material decides what the item is, and carries more than a material name:

Both - and : separate a prefix from its payload, case-insensitively. Heads never block: a texture or URL never touches the network, and a player head that has not been fetched yet comes back plain.

Text

name and display-name are separate, not a fallback pair: one is painted on the item — bold, gradient-filled, with a counter in it — and the other is what a plugin quotes back to a player.

Appearance

Underscore and hyphen spellings both work throughout.

Traits

Only some materials have these, so they live in a separate record — the other few thousand items carry one shared reference instead of six null fields each.

potion:
  base_type: HEALING
  upgraded: true            # STRONG_HEALING
  color: "#ff4d4d"
  custom_effects:
    - type: SPEED
      amplifier: "%level%"  # resolved per viewer
      duration: 600
 
armor_trim:
  pattern: "%helmet_trim_pattern%"
  material: "%helmet_trim_material%"
 
banner_patterns:
  base_color: WHITE
  patterns:
    - pattern: STRIPE_BOTTOM
      color: LIGHT_GRAY
 
banner_design: "%shield_preview%"   # a design computed per viewer
 
force-consumable: true
consumable-time: 1.0
consumable-nutrition: 6
consumable-saturation: 14.4
consumable-sound: ITEM_HONEY_BOTTLE_DRINK
 
attributes:
  - "attack_damage|8"
  - "movement_speed|0.05"
 
nbt:
  kind: special
  uses: 3

A trait that does not fit its material does nothing. A potion set on a sword is a leftover key in a config file, not a reason to fail while drawing a menu.

Items that are not what they look like

A plugin's own items are drawn with whatever material suits them, and the material is what the server acts on: a token drawn as an ender pearl is a thrown ender pearl, one drawn as food is eaten, one drawn as a block is placed. Every one of those spends something the player was meant to keep.

PluginItems items = Items.of(this);
items.inert("item");     // the data key this plugin's own items carry

Anything carrying that key is now inert: using it does nothing. It can still be picked up, dropped, traded, put in a chest and clicked in a menu — it simply refuses to be spent as the item it is drawn as. Asking twice replaces the keys rather than registering a second guard, so a plugin that reloads in place does not end up with one per reload.

Storing what somebody is holding

The other direction, for an icon picker:

String icon = Source.of(player.getInventory().getItemInMainHand()).raw();

A plain item is stored as its material name — STONE, not four hundred characters of base64. Anything carrying meta is stored whole as bytes:. An empty hand is AIR.

The name and the lore are dropped. Everything the item looks like is kept — model, colour, patterns, glint — but whatever draws the icon writes its own name and lore. They are also nearly all of an item's size: a kit sword's gradient name serialises as component JSON and runs past the 512 characters an icon column allows.

Naming one for a person

Source.of(config.icon()).label();      // "Nether Star"

label() is for a person; raw() is what goes back into a config or a column.

Drawing one back

ItemStack icon = Items.icon(home.icon());

One call, the whole grammar, no plugin and no viewer — for a caller holding a bare string out of a column. A menu icon does not need it: write material: "%home_icon%" and the row resolves it with the viewer.