ItemStack serialization - Historical

Applied By blablubbabc: Aug 14, 2019 at 12:10 AM

ItemStack serialization

ItemStack serialization

Learn about the format bukkit uses when it saves or loads items to or from configuration files!



This page describes the format bukkit uses when a plugin saves/loads an ItemStack to/from a configuration file.

This page requires updating whenever new meta data is added to items, or when bukkit/spigot changes something on their serialization.
The current version is based on: 1.14.4-R0.1-SNAPSHOT (from 14.08.2019)

Depending on the item type, the item can contain different data. First, the data that is common to all items is described:

Code (Text):
path-to-item:
  ==: org.bukkit.inventory.ItemStack
  v: <data version> # determines item data conversions; TODO: documentation of the available versions?
  type: <item type name>
  damage: <item data value / durability>
  amount: <stack size>
  meta:
    ==: ItemMeta
    meta-type: <meta data type id>
    display-name: <display name>
    loc-name: <localized display name>
    lore:
    - <lore line>
    - < .. more lore lines .. >
    custom-model-data: <custom model data integer value>
    BlockStateTag: <serialized block state data> # concretize/example? same format as PublicBukkitValues
    enchants:
      <enchantment name>: <enchantment level>
      < .. more enchantment entries .. >
    repair-cost: <repair penalty>
    ItemFlags:
    - <item flag name>
    - < .. more item flag names .. >
    Unbreakable: <true|false>
    Damage: <damage value>
    internal: <unhandled data compressed as base64 text>
    PublicBukkitValues: <any custom plugin stored data> # TODO concretize/example?
 
All item type names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
The enchantment names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html
The item flag names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html

Certain items can additionally contain more specific data inside the 'meta' section. Their meta data 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 in the unhandled 'internal' data mentioned above.

Items not listed here:
Meta data type id: UNSPECIFIC
They are only storing the common meta data as it has been described above.

Banner:
Meta data type id: BANNER
Code (Text):
base-color: <color name>
patterns:
- ==: Pattern
  color: <color name>
  pattern: <pattern code>
- < .. more patterns .. >
A list of all color names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/DyeColor.html
A list of all pattern codes can be found here: http://minecraft.gamepedia.com/Banner/Patterns

Block entities:
Meta data type id: TILE_ENTITY
Code (Text):
blockMaterial: <item type>
See the minecraft wiki for a list of block entities: http://minecraft.gamepedia.com/Block_entity
They currently store all their data in the 'internal' data.

Writable book (book-and-quill):
Meta data type id: BOOK
Code (Text):
title: <book title>
author: <author name>
pages:
- <page text>
- < .. more pages .. >
generation: <generation code>
The generation codes can be found here: http://minecraft.gamepedia.com/Written_book#Data_values

Written book:
Meta data type id: BOOK_SIGNED
This stores the same data as book-and-quill items.

Skull:
Meta data type id: SKULL
Code (Text):
skull-owner: <skull profile name>
Only the profile name seems to get stored currently.

Leather armor:
Meta data type id: LEATHER_ARMOR
Code (Text):
color:
  ==: Color
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>
All color values are numbers between 0 and 255.

Filled maps:
Meta data type id: MAP
Code (Text):
scaling: <true|false>
display-loc-name: <location name>
display-map-color:
  ==: Color
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>
All color values are numbers between 0 and 255.

Potions and tipped arrows:
Meta data type id: POTION
Code (Text):
potion-type: <potion type name>
custom-color:
  ==: Color
  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 .. >
The potion type names can be found here: http://minecraft.gamepedia.com/Potion#Data_values
All color values are numbers between 0 and 255.
The potion effect type ids and other related information to potion effects can be found here: http://minecraft.gamepedia.com/Status_effect

Spawn egg:
Meta data type id: SPAWN_EGG
The entity type is defined by the spawn egg item type since MC 1.13.
Any additional entity data is stored in the 'internal' data.

Enchanted book:
Meta data type id: ENCHANTED
Code (Text):
stored-enchants:
  <enchantment id>: <enchantment level>
  < .. more enchantment entries ..>
The enchantment names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html

Firework rocket:
Meta data type id: FIREWORK
Code (Text):
firework-effects:
- ==: Firework
  flicker: <true|false>
  trail: <true|false>
  colors:
  - ==: Color
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < .. more colors .. >
  fade-colors:
  - ==: Color
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < .. more colors .. >
  type: <firework effect type name>
- < .. more firework effects .. >
power: <power>
All color values are numbers between 0 and 255.
The firework effect type names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/FireworkEffect.Type.html

Firework star:
Meta data type id: FIREWORK_EFFECT
Code (Text):
firework-effect:
  ==: Firework
  flicker: <true|false>
  trail: <true|false>
  colors:
  - ==: Color
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < .. more colors .. >
  fade-colors:
  - ==: Color
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < .. more colors .. >
  type: <firework effect type name>
All color values are numbers between 0 and 255.
The firework effect type names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/FireworkEffect.Type.html

Knowledge book:
Meta data type id: KNOWLEDGE_BOOK
Code (Text):
Recipes:
- <namespace>:<key>
- <namespace>:<key>
Tropical fish bucket:
Meta data type id: TROPICAL_FISH_BUCKET
Code (Text):
fish-variant: <variant integer>
The variant determines the shape, pattern, pattern color, body color and name.

Crossbow:
Meta data type id: CROSSBOW
Code (Text):
charged: <true|false>
charged-projectiles: <list of serialized arrow items> # TODO concretize/example?