Bukkit

Config of every box has 'items' section containing subsections describing drop items. Names of the subsections can be arbitrary.

Settings of a Item Stack

Item

Required

ID of the item is specified by 'id' setting. As in box config, its value can be either a number or a string.

Data Value

Using 'data' setting you can specify a data value for the item. Data is used for coloring wool or glass, or making player heads. 

Player Heads

If item is a head ('id' is SKULL_ITEM, 'data' is 3 OR on 1.13+ 'id' is PLAYER_HEAD), then you can specify an owner of the head by adding 'skullOwner' String set to a player name. The full definition of the item would look like this:

id: SKULL_ITEM
data: 3
skullOwner: 'saharNooby'

# 1.13+ version
id: PLAYER_HEAD
skullOwner: 'saharNooby'

Player head textures

You can set a custom texture (looking like a long string 'eyJABCDEF==') using 'texture' setting. There is a site with almost 30K textures.

CustomModelData (1.14+)

Using 'customModelData' you can set CustomModelData on the item, if you are running the plugin on 1.14+ server. This setting is ignored on older versions.

Amount

Amount of items in a stack is specified by 'amount' setting. It's value can be a constant value like 16, or a range 'n-m', where 'n' is minumum amount, and 'm' is maximum. Every time the item will drop, the amount will be selected randomly from this range.

Name

Required

Name is specified by 'name' String. This is the custom name of the item stack, also it will be displayed in chat (when message 'You got:' is shown). Can be colored using '&' character.

Lore

Specified by 'lore' List of Strings. Can be colored using '&' character.

Enchants

You can specify enchantments in section 'enchants'. Every key in it must be a valid enchantment name (like in game), and it's value must be an enchantment level. Level of the enchantment can be higher than allowed in vanilla; and unenchantable items (like sticks) can have enchantments too.

Arbitrary NBT tags

You can specify arbitrary NBT tags (as used in /give command) using 'nbtTag' setting. See more info on Minecraft wiki.

Example:

# Hides enchantments
nbtTag: '{HideFlags:1b}'

Other Settings

'dontAssignName'

If set to true, the item stack won't have a name. It's useful to make items from a box and vanilla items can stack.

'dontGiveItem'

If set to true, player will not get any item stack in his inventory. There will be only commands executing or effect showing.

Commands

Drop item can contain a list of commands, that will be executed when item drops. Commands are specified in 'commands' section, every subsection with arbitrary name in it specifies one command. Subsection contains these settings:

• 'line' String is the command itself. Can contain %player% placeholder, that will be replaced with a player name.
• 'fromConsole' Boolean -- if set to true, the command will be executed from console. Useful for giving items, xp or permissions.

Effect

Item can have an effect (firework launch, sound playing or message broadcasting) which will be done instead of box's 'drop' effect when the item drops. Effect is specified in 'dropEffect' section. Format of the effect is identical to the box effect format.

'broadcast' String in the effect can also contain %item% placeholder, which will be replaced with name of the item, and when player hovers on it in chat, they will see a text identical to the text that appears when player hovers on the item in the inventory.

Display Format

Lore of a box can contain a list of drop items, where each item has identical format. By using 'inBoxLoreFormat' you can specify item's own format, that will be used for item list.

Drop Chance

Required

The most important setting is 'chance'. Its value must be an integer positive number. The more part chance takes in the sum of chances, the more probability of drop will be.

Example:

items:
  item1: {chance: 2}
  item2: {chance: 3}

Sum of chances is 2 + 3 = 5. Probability of dropping first item is 2 / 5 * 100% = 40%, second item -- 3 / 5 * 100% = 60%.

It means that first item will drop in 40% of cases, and second item will drop in 60% of cases.

If you want items with equal probabilities, set chances to same number, for example 1.

Item Example

# A Diamond Sword
item: DIAMOND_SWORD

amount: 1

name: '&cDiamond sword'

lore:
- '&7This sword dropped'
- '&7from a box.'

enchants:
  sharpness: 8
  unbreaking: 5
  fire: 4
  knockback: 2

dropEffect:
  # Big instant red and orange ball
  firework:
    type: BALL_LARGE
    colors: ['RED', 'ORANGE']
    fadeColors: ['GRAY']
    power: 0
  # Explosion sound
  sound: {sound: EXPLODE}
 
  broadcast: '&6%player% got an amazing %item% &6from %box%!'

chance: 2