Item Serialization - Shopkeepers/Shopkeepers-Wiki GitHub Wiki

This page describes the YAML format Bukkit/Spigot uses when a plugin saves or loads items to/from files. Shopkeepers for example uses this for storing items inside its save.yml file. And the format used for specifying items inside the config is derived from this format as well.

This page requires updating whenever new item meta data is added, or when Bukkit/Spigot changes something on its item serialization. The current version is based on: 1.21-R0.1-SNAPSHOT (2024-08-03)

Depending on the item's type, it can contain different data.

Data common to all items:

path-to-item:
  ==: org.bukkit.inventory.ItemStack
  v: <data version>
  type: <item type name>
  amount: <stack size>
  meta:
    ==: ItemMeta
    meta-type: <meta type id>
    item-name: <item name Json, see https://minecraft.wiki/w/Data_component_format#item_name>
    display-name: <custom name Json, see https://minecraft.wiki/w/Data_component_format#custom_name>
    lore:
    - <lore line Json, see https://minecraft.wiki/w/Data_component_format#lore>
    - < ... more lore lines >
    custom-model-data: <custom model data integer value, see https://minecraft.wiki/w/Data_component_format#custom_model_data>
    max-stack-size: <max stack size, see https://minecraft.wiki/w/Data_component_format#max_stack_size>
    rarity: <rarity name, see https://minecraft.wiki/w/Data_component_format#rarity>
    BlockStateTag:
      <key>: <value>
      < ... more block states, see https://minecraft.wiki/w/Data_component_format#block_state>
    enchants:
      <enchantment namespaced key>: <enchantment level>
      < ... more enchantments >
    enchantment-glint-override: <true/false, see https://minecraft.wiki/w/Data_component_format#enchantment_glint_override>
    attribute-modifiers: # See https://minecraft.wiki/w/Data_component_format#attribute_modifiers
      <attribute namespaced key>:
      - ==: org.bukkit.attribute.AttributeModifier
        key: <arbitrary modifier namespaced key>
        operation: <operation id>
        amount: <amount>
        slot: <slot group name>
      - < ... more attribute modifiers >
      < ... more attributes >
    ItemFlags:
    - <item flag name>
    - < ... more item flag names >
    hide-tool-tip: <true/false, see https://minecraft.wiki/w/Data_component_format#hide_tooltip>
    Unbreakable: <true|false, see https://minecraft.wiki/w/Data_component_format#unbreakable>
    fire-resistant: <true/false, see https://minecraft.wiki/w/Data_component_format#fire_resistant>
    Damage: <damage, see https://minecraft.wiki/w/Data_component_format#damage>
    max-damage: <max damage, see https://minecraft.wiki/w/Data_component_format#max_damage>
    repair-cost: <repair cost, see https://minecraft.wiki/w/Data_component_format#repair_cost>
    tool:
      ==: Tool
      default-mining-speed: <float>
      damage-per-block: <integer>
      rules:
      - ==: ToolRule
        blocks: <Either a `#`-prefixed block tag namespaced key, or a list of block namespaced keys>
        speed: <float>
        correct-for-drops: <true/false>
      - < ... more tool rules >
    food:
      ==: Food
      nutrition: <integer>
      saturation: <float>
      can-always-eat: <true/false>
      eat-seconds: <float>
      using-converts-to: <serialized ItemStack>
      effects:
      - ==: FoodEffect
        effect:
          ==: PotionEffect
          effect: <effect type id>
          duration: <duration>
          amplifier: <amplifier>
          ambient: <true|false>
          has-particles: <true|false>
        probability: <float>
      - < ... more food effects >
    jukebox-playable:
      ==: JukeboxPlayable
      song: <song namespaced key, see https://minecraft.wiki/w/Data_component_format#jukebox_playable>
      show-in-tooltip: <true/false>
    PublicBukkitValues: <custom plugin data as SNBT string>
    custom: <custom data encoded as base64 text, see https://minecraft.wiki/w/Data_component_format#custom_data>
    internal: <other data encoded as base64 text>
    unhandled: <unhandled data encoded as base64 text>

The data version depends on the used server version and determines the item data migrations performed by the server when the item gets loaded. There is no documentation available for this.
Available item type names: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
Available enchantment names: See https://minecraft.wiki/w/Data_component_format#enchantments and https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html
Available item flag names: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html
Since Minecraft 1.20.5, item flags no longer map to the HideFlags item tag, but to various other item properties / components:

HIDE_ENCHANTS: Enchantments show-in-tooltip
HIDE_ATTRIBUTES: Attributes show-in-tooltip
HIDE_ADDITIONAL_TOOLTIP: hide_additional_tooltip and stored enchantments show-in-tooltip
HIDE_UNBREAKABLE: Unbreakable show-in-tooltip
HIDE_ARMOR_TRIM: Armor trim show-in-tooltip
HIDE_DYE: Leather armor dyed color show-in-tooltip

Available attributes and vanilla modifiers: See https://minecraft.wiki/w/Attribute#Attributes and https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
Attribute modifier operation ids: https://minecraft.wiki/w/Attribute#Operations
Stringified NBT (SNBT) format: https://minecraft.wiki/w/NBT_format#SNBT_format
When a namespaced key is mentioned on this page, we refer to a Minecraft resource location: https://minecraft.wiki/w/Resource_location

In older Minecraft versions, the display name and lore used formatting codes starting with § (not &): https://minecraft.wiki/w/Formatting_codes.
In modern Minecraft versions, it is more common to use Json text for the display name and lore: https://minecraft.wiki/w/Raw_JSON_text_format

Food component data: https://minecraft.wiki/w/Data_component_format#food
Information on potion effects: https://minecraft.wiki/w/Effect
Tool component data: https://minecraft.wiki/w/Data_component_format#tool

Certain items can additionally contain more specific data inside the meta section. Their meta-type ids and the data they store are described next one by one.
Every time some item contains any data which is not explicitly listed here, this data is getting stored inside the unhandled internal data mentioned above. There is no documentation for how this data looks like.

Items not explicitly listed here:

Meta type id: UNSPECIFIC

These items only store the common data as it has been described above.

Armor stand:

Meta type id: ARMOR_STAND

The item's entity tag is stored within the general internal data of the item.

Banner:

Meta type id: BANNER

patterns:
- ==: Pattern
  color: <color name>
  pattern: <pattern code>
- < ... more patterns >

Available color names and pattern codes: https://minecraft.wiki/w/Banner#Block_data

Shield:

Meta type id: SHIELD

base-color: <color name>
patterns:
- ==: Pattern
  color: <color name>
  pattern: <pattern code>
- < ... more patterns >

Available color names and pattern codes: https://minecraft.wiki/w/Banner#Block_data
Other block entity data is stored inside the internal data.

Block entities:

Meta type id: TILE_ENTITY

blockMaterial: <item type>

It seems like the blockMaterial entry can be omitted and gets automatically restored by the server when the item gets loaded.
List of existing block entities: https://minecraft.wiki/w/Block_entity
They currently store all their data inside the internal data.

Writable book (book-and-quill):

Meta type id: BOOK

pages:
- <page text>
- < ... more pages >

Unlike written books, the pages are stored as plain text (not JSON text).

Written book:

Meta type id: BOOK_SIGNED

title: <book title>
author: <author name>
pages:
- <page text Json>
- < ... more pages >
generation: <generation code>
resolved: <true/false>

Unlike writable books, the pages are stored as JSON text: https://minecraft.wiki/w/Raw_JSON_text_format
Book generation codes: https://minecraft.wiki/w/Written_Book#Item_data

Skull:

Meta type id: SKULL

skull-owner:
  ==: PlayerProfile
  uniqueId: <profile uuid>
  name: <profile name>
  properties:
  - name: textures
    value: <texture data encoded as base64>
    signature: <signature>
  < ... further properties (unusual) >
note_block_sound: <namespaced key>

A profile always needs either an uuid, a name, or both.
The name must be a valid player name. See https://minecraft.wiki/w/Player#Username
The uuid and name might not necessarily belong to an existing player.

Armor:

Meta type id: ARMOR

trim:
  material: <trim material namespaced key>
  pattern: <trim pattern namespaced key>

Trim materials and patterns: https://minecraft.wiki/w/Armor#Item_data

Leather armor (e.g. horse leather armor):

Meta type id: LEATHER_ARMOR

color:
  ==: Color
  ALPHA: <alpha value>
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>

The color values are numbers between 0 and 255. Alpha values other than the default 255 have no effect.

Colorable armor (e.g. player leather armor, wolf armor, etc.):

Meta type id: COLORABLE_ARMOR

trim:
  material: <trim material namespaced key>
  pattern: <trim pattern namespaced key>
color:
  ==: Color
  ALPHA: <alpha value>
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>

Trim materials and patterns: https://minecraft.wiki/w/Armor#Item_data
The color values are numbers between 0 and 255. Alpha values other than the default 255 have no effect.

Filled maps:

Meta type id: MAP

scaling: <true|false>
display-map-color:
  ==: Color
  ALPHA: <alpha value>
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>

The color values are numbers between 0 and 255. Alpha values other than the default 255 have no effect.

Potions and tipped arrows:

Meta type id: POTION

potion-type: <potion type name>
custom-color:
  ==: Color
  ALPHA: <alpha value>
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>
custom-effects:
- ==: PotionEffect
  effect: <effect type id>
  duration: <duration>
  amplifier: <amplifier>
  ambient: <true|false>
  has-particles: <true|false>
- < ... more potion effects >

Available potion type names: https://minecraft.wiki/w/Potion#Item_data
The color values are numbers between 0 and 255. Alpha values other than the default 255 have no effect.
Available potion effect type ids and other related information to potion effects: https://minecraft.wiki/w/Effect

Suspicious stew

Meta type id: SUSPICIOUS_STEW

effects:
- ==: PotionEffect
  effect: <effect type id>
  duration: <duration>
  amplifier: <amplifier>
  ambient: <true|false>
  has-particles: <true|false>
- < ... more potion effects >

Available potion effect type ids and other related information on potion effects: https://minecraft.wiki/w/Effect

Spawn egg:

Meta type id: SPAWN_EGG
Since MC 1.13, the entity type is defined by the spawn egg's item type.
Any additional entity data (including a potentially different entity type) is stored inside the internal data.

Enchanted book:

Meta type id: ENCHANTED

stored-enchants:
  <enchantment id>: <enchantment level>
  < ... more enchantments >

Available enchantment names: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html

Firework rocket:

Meta type id: FIREWORK

firework-effects:
- ==: Firework
  flicker: <true|false>
  trail: <true|false>
  colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  fade-colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  type: <firework effect type name>
- < ... more firework effects >
power: <power>

The color values are numbers between 0 and 255. Alpha values other than the default 255 have no effect.
Power is a number between 0 and 127. Each power is approximately half a second of flight time.
Available firework effect type names: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/FireworkEffect.Type.html

Firework star:

Meta type id: FIREWORK_EFFECT

firework-effect:
  ==: Firework
  flicker: <true|false>
  trail: <true|false>
  colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  fade-colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  type: <firework effect type name>

The color values are numbers between 0 and 255. Alpha values other than the default 255 have no effect.
Available firework effect type names: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/FireworkEffect.Type.html

Knowledge book:

Meta type id: KNOWLEDGE_BOOK

Recipes:
- <namespace>:<key>
- <namespace>:<key>

Crossbow:

Meta type id: CROSSBOW

charged-projectiles:
- <serialized arrow item (uses the same format as described on this page)>
- < ... more serialized arrow items >

Compass:

Meta type id: COMPASS

LodestonePosWorld: <lodestone world name>
LodestonePosX: <lodestone x coordinate>
LodestonePosY: <lodestone y coordinate>
LodestonePosZ: <lodestone z coordinate>
LodestoneTracked: <true|false>

Bundle:

Meta type id: BUNDLE

items:
- <ItemStack>
- < ... more ItemStacks >

Tropical fish bucket:

Meta type id: TROPICAL_FISH_BUCKET

fish-variant: <variant integer>

The variant determines the shape, pattern, pattern color, body color and name of the stored fish. See: https://minecraft.wiki/w/Tropical_Fish#Entity_data

Fish buckets can also store an entity tag and a bucket entity tag in their internal data.

Axolotl bucket:

Meta type id: AXOLOTL_BUCKET

axolotl-variant: <variant integer>

Axolotl buckets can also store an entity tag and a bucket entity tag in their internal data.

Other items with entity tag (item frame, cod/pufferfish/salmon buckets, painting):

Meta type id: ENTITY_TAG

The item's entity tag (eg. item frame's invisibility flag, etc.) is stored within the general internal data of the item.

Goat horn

Meta type id: MUSIC_INSTRUMENT

instrument: <instrument namespaced key>

Goat horn instruments: https://minecraft.wiki/w/Goat_Horn#Item_data

Ominous bottle

Meta type id: OMINOUS_BOTTLE

ominous-bottle-amplifier: <ominous bottle amplifier level>

The ominous bottle amplifier level must be an integer number between 0 and 4: https://minecraft.wiki/w/Ominous_Bottle#Item_data