ItemStack serialization

Oct 15, 2017
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.12.2-R0.1-SNAPSHOT (from 15.10.2017)

    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
      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 .. >
        enchants:
          <enchantment name>: <enchantment level>
          < .. more enchantment entries .. >
        repair-cost: <repair penalty>
        ItemFlags:
        - <item flag name>
        - < .. more item flag names .. >
        Unbreakable: <true|false>
        internal: <unhandled data compressed as base64 text>
    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.

    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
    Code (Text):
    id: <entity id>
    The entity ids can be found here: http://minecraft.gamepedia.com/Data_values/Entity_IDs
    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 charge:
    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>
  • Loading...
  • Loading...