v3 ItemBuilder

❗ This Documentation is Outdated! It is recommended to use v4 with its documentation instead.

See V4 Getting Started for more information.

⚠️ Usage ⚠️

This feature is only available in spigot-utils and its inheritors (spigot-jar).

KamiCommon provides an abstract class called IBuilder for wrapping and managing properties of a bukkit ItemStack.
Many libraries in KamiCommon accept an IBuilder object as the item to be built. (see GUI system)
This class has two superclasses: ItemBuilder and IAItemBuilder.

IBuilder

This class is responsible for the bulk of the builder logic. You can create a new builder similar to ItemStack, load a builder from a config, or start from an existing ItemStack and modify it.
Methods should be self explanatory, once you are done modifying the item you can use:

ItemStack stack = builder.build();

ItemBuilder

This is the vanilla implementation of IBuilder. It can only load from a Material.

IAItemBuilder

This is a special builder meant for servers using ItemsAdder. It allows creating items from an IA namespaced-id.

IBuilder Config Loading Format

See IBuilder for details on this implementation.

Configuration Keys

Required Keys:

• material or materials

Additional Keys:

• name, lore, amount, damage, enchantments, nbt

Key Breakdown

Material

• Key: material or materials
• Type: String
• Info: A Material or XMaterial name, we recommend using XMaterial names
  • When using IAItemBuilder, this string can be a namespaced-id (e.g. itemsadder:custom_item)

Name

• Key: name
• Type: String
• Default: null (MC uses default item name)
• Info: Determines the name of the item, ampersand (&) color codes supported

Lore

• Key: lore
• Type: String List
• Default: null (MC adds no lore)
• Info: Determines the lore of the item, ampersand (&) color codes supported

Amount

• Key: amount
• Type: Integer
• Default: 1
• Info: How many of the item should be in the ItemStack (max = stack size of that material).

Damage

• Key: damage
• Type: Integer
• Default: 0
• Info: >0 Applies that amount of damage to the ItemStack
  • For pre 1.13 servers you can either use an XMaterial name in the material field, or use this damage field with the color value.

Enchantments

• Key: enchantments
• Type: Section
• Default: None
• Info: Each sub-key (user defined) should match an EnchantmendID, recommend using XEnchantment values. The sub-key value should be an integer for the level.

Nbt

• Key: nbt
• Type: Section
• Default: None
• Info: Each sub-key (any name) contains three sub-keys: key, type and value.
  • sub-key.key is the NBT key (String) for this nbt pair
  • sub-key.type can be one of the following: String, Boolean, Byte, Short, Integer, Long, Float, Double, UUID, Byte_Array, Int Array, Long Array
  • sub-key.value can be whatever, but its format should match the type above (UUID being a String loaded as UUID)

Example Configurations

Example 1:

A partially damaged stone sword, with unbreaking 3 and sharpness 2 Configured with custom nbt for plugin management

testItem:
  material: STONE_SWORD
  name: "&cNa&ame"
  lore:
  - '&aA'
  - "&bB"
  - "&cC"
  amount: 3
  damage: 50
  enchantments:
    SHARPNESS: 2
    UNBREAKING: 3
  nbt:
    a:
      key: 'test_weapon'
      type: String
      value: 'weapon1'

Example 2:

An example using XMaterial to not need the damage field, even on pre 1.13 servers.
Note: The damage (color for 1.8) will be loaded from the XMaterial enum automatically.

greenWool:
  material: GREEN_WOOL
  name: "&aGreen Wool"