Bukkit

Every box can have its own gui, or not have a gui at all. Gui is configured in the 'gui' section in the box config.

Main Settings

'enabled'

First (and can be the only) key in the section determines whether the box has a gui or not (true of false). If false, all subsequent gui settings will be ignored and you can remove them.

'rolling' List of Sections

Each subsectionin this list is written using short format with curly braces.

Each section contains of two keys -- 'delay' and 'iterations'. When gui opens, it will update as many times with delay as specified in every section.

For example, if list contains only one element

{delay: 1, iterations: 20}

it means that gui will roll 20 times with 1 tick delay (1 tick = 1/20 sec), e. g. gui will roll 1 second and then stop.

If list contains more than one section, then when iterations of the first section will end, next section will become active.

For example,

- {delay: 1, iterations: 20}
- {delay: 5, iterations: 5}

means that gui will roll 20 times with 1 tick delay, then 5 times with 5 tick delay, and then stop.

'window' Section

The most important section -- here are described contents of the gui window.

'type' String

Determines type of the inventory. Can be CHEST (having from 1 to 6 rows), DISPENSER (3x3 dispenser), HOPPER (5 slots hopper).

'format' List of Strings

This list determines location of the items in the gui.

The list must have a certain amount of Strings and each string must have a certain amount of characters, depending on type of the inventory.

If the type is CHEST, list can contain from 1 to 6 Strings, and every String must contain 9 characters; if DISPENSER, 3 Strings x 3 characters; if HOPPER, one String with 5 characters. Each character represents an individual slot of the inventory, that can has some item or not, depending on the character.

The character can be one of these:

Space -- empty slot, nothing will be here.

a-z, A-Z -- are the most important characters.

First of all, slots marked by letters of the alphabet, will contain random items from the box.

Secondly, when gui will roll, items in such slots will be moved in direction 'z' -> 'a', and in the last slot 'z' (or just last in alphabet order) will appear a new random item from the box.

For example, if format is ' abc ' (it's invalid, don't try to use it), then when gui will roll, slot 'a' will take item from slot 'b', 'b' from 'c', and in slot 'c' will appear random item. This is how item rolling organized.

Thirdly, if letter is uppercase (A-Z), then, besides default rolling behavior, from these slots will be taken dropped items, when gui will stop. The format must have at least one such slot.

A correct version of the previous example ' abc ' will be ' aBc ' which means that when the gui stops, player will get an item from 'B' slot.

Finally, any other characters are used for placing decorative items (fillers) in the slots. If plugin meets any non-space character that isn't an alphabet character, it will check whether filler with such name exists. If so, plugin will place corresponding filler in the slot.

'fillers' Section

This section contains subsections, which have names containing only one character (thus they must be quoted using single quotes ').

Each filler must contain a section that describes an item that will be placed in the inventory. Items can be static or animated. Static item is a section containing at least one required key 'id' -- id of the item (string or numeric, same rules apply as to box item type). Also it can contain 'data', 'amount', 'name', 'lore' and 'enchants' keys, identical to the ones used in the box item format.

To make a static filler, you need to add 'item' section that will describe the item, for example:

{id: STAINED_GLASS_PANE, data: 15}

# 1.13 version:
{id: BLACK_STAINED_GLASS_PANE}

represents a black (data value is 15) glass pane. In 1.13+ you can't specify numeric id and data, so you should write {id: BLACK_STAINED_GLASS_PANE}.

To make an animated filler, you need to add 'animated' List of Sections (like 'rolling' List) instead of 'item' section. Every item in it is a static item, that also has 'delay' Number -- amount of ticks that item will stay before changed to the next item. When end of list is reached, animation will continue from the start.

For example,

- {id: STONE, delay: 20}
- {id: DIRT, delay: 20}

means that slot will contain a stone, then after 1 second (20 ticks) it will be changed to a dirt block, then after another 1 sec it will be changed back to the stone and so on.

Finally, the filler can contain 'inStop' section, that describes an item, that will be placed in the slot when gui will stop rolling. It contains one key -- 'item' or 'animated', that are identical to ones above. Usually, 'onStop' contains a static item {id: AIR}, which means when gui will stop, filler will disappear.

If the filler does not contain 'onStop' section, it will be not changed when gui stops.

Example

Default gui:

gui:
  # gui is enabled
  enabled: true
  
  # Rolling sections. In this case -
  # gui will roll 50 times with 1 tick delay,
  # then 20 times with 2 ticks delay,
  # then 10 times with 3 ticks,
  # then 5 times with 4 ticks and then stop.
  rolling:
  - {delay: 1, iterations: 50}
  - {delay: 2, iterations: 20}
  - {delay: 3, iterations: 10}
  - {delay: 4, iterations: 5}
  
  # Window settings
  window:
    # Gui is a chest...
    type: CHEST
    
    # ...is containing 3 rows (like in one-block chest).
    # Second row is fully occupied with items from the box,
    # three center slots will contain drop items.
    # And two fillers present - '@' and '#'
    format:
    - '@@@###@@@'
    - 'abcDEFghi'
    - '@@@###@@@'
    
    fillers:
      # Filler above inactive slots
      '@':
        # Static item - black glass
        item: {id: 160, data: 15, delay: 20}
        onStop:
          # Will disappear, when gui stops (become an air)
          item: {id: 0}
      # Filler above active slots
      '#':
        # Animated item - green/yellow glass
        animated:
        - {id: 160, data: 4, delay: 10}
        - {id: 160, data: 5, delay: 10}
        # onStop does not exists, filler will be not changed