ItemStack serialization

Aug 15, 2019
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>
      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 .. >
        attribute-modifiers:
          <attribute name>:
          - ==: org.bukkit.attribute.AttributeModifier
            amount: <amount>
            name: <modifier name>
            uuid: <modifier uuid>
            operation: <operation id>
          - < .. more attribute modifiers .. >
          < .. more attributes .. >
        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
    Attribute names can be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
    Minecraft's default modifier names (attribute names) and uuids can be found here: https://minecraft.gamepedia.com/Attribute
    Attribute modifier operation ids: https://minecraft.gamepedia.com/Attribute#Operations

    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?
  • Loading...
  • Loading...