Bukkit

Each box has its own unique id. ID is a positive integer number. ID is being used in /givebox command.

Box settings are stored in file /RandomBox/boxes/<box id>.yml. You can easily create new box just by copying existing box config and renaming it to a new unique id.

Box Name

Required

Box name is specified using 'boxName' String. This is the custom name of the box item in the inventory, title of the box GUI and is shown in the list of boxes (/rb list). Can be colored using '&' character.

Box Item

Required

Box item's type (or material) is specified using 'boxItem' setting. Its value can be a number (for example -- 57 is a diamond block) or a String ('DIAMOND_BLOCK'). You can't use numeric ids since 1.13, so you should use string ids. You can view list of materials here (for 1.13+).

Data Value

Using 'data' setting you can specify a data value for the box item. Data is used for coloring wool or glass, or making player heads. This setting is deprecated since 1.13 because item types were flattened. It means, for example, red wool in 1.12 was item with type WOOL and data 14, since 1.13 it is now RED_WOOL without data.

Making Player Heads

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

boxItem: SKULL_ITEM
data: 3
skullOwner: 'saharNooby'

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

CustomModelData (1.14+)

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

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}'

Box Lore

Lore of the box item can be changed using 'lore' List of Strings. Lines of the lore can be colored using '&' character.

The lore can also contain automatically generated lists of drop items. To add them, you need to add lines like this:

items <max amount> <format>

Where <max amount> is max amount of items that will be showed in list, and <format> is a format string that will be applied for every item.

Format, aside from any strings and color codes, can contain these placeholders:

• %ordinal% -- Index of the item
• %name% -- Name of the item
• %amount% -- Amount of items in the item stack
• %chance% -- Drop chance (as specified in config)
• %chancePercents% -- Drop chance in percents (calculated by formula item_chance / sum_of_chances * 100)

Default Lore

If there is no 'lore' List, then box will have default lore:

Drop items:
items 0 &7%ordinal%. &ex%amount% %name%

Additional Settings

'checkPermission'

If set to true, plugin will check whether player has permission randombox.open.<box id>. If not so, box will be not opened, and player will see a message saying they not have permission to open a box.

If player has permission randombox.open.*, they can open any box, even without specific permission for some box.

'openWhenClicked'

If set to true, the box will be opened when player will try "use" it (right click). If not set, the box can be opened only with /openbox command.

'addGlow'

If set to true, box will have Luck I enchantment, so the it will glow.

'unstackable'

If set to true, every box item will contain some random string it its name. Such items will not stack, even if they can stack by default (for example, blocks or most items like seeds).

'limits'

This is an otional list of sections. Each limit specifies how frequently a group of players can open this box. You can create several limits, and using permissions enable of disable different limits for different players. Format of a limit:

  # Interval specifies minimum time between box openings.
  # Available time units: s (sec), m (min), h (hours), d (days).
  - interval: 1m
    # Message that is sent when player tries to open a box too fast.
    # You can localize time units in the placeholder, for example (Russian): %remains[с.,м.,ч.,д.]%
    message: '&cYou can open this box only after %remains[s.,m.,h.,day(s)]%!'
    permissions:
      # Permission that is required in order for this limit to work.
      # If player does not have this permission, limit will not be checked.
      # If not specified, the limit will be checked for any player.
      check: 'some.permission.to.check'
      # Permission for bypassing the limit.
      # If not specified, the limit can't be bypassed even by OPs.
      bypass: 'some.permission.to.bypass'

Configuring GUI

Required

GUI format is described here.

Configuring Effects

Effect format is described here.

Configuring Drop Items

Items that can be dropped from a box are specified in 'items' section. Format of an item is described here.