Skip to main content

VoidChest Menu Configurations

Configuration
gui/type/<voidchest_type>.yml
VoidChestMenu:
  title: "%voidchest% &7| &fVoidChest Menu"
  # rows is ignored if you have a structure
  # IF YOU DON'T HAVE A STRUCTURE YOU NEED TO SPECIFY ITEM SLOTS
  rows: 6
  animation: true
  # Default action is executed when you click an item without a specific action.
  defaultAction: voidchest:nothing
  # The bottom inventory action is set to nothing by default
  # You can change it to voidchest:open_container to open the container OR voidchest:open_upgrades to open the upgrades menu
  #bottomInventoryAction: voidchest:nothing
  structure:
    - "# # # # # # # # #"
    - "# A # C # P # U #"
    - "# # # # # # # # #"
    - "# H # L # T # B #"
    - "# # # # # # # # #"
    - "S # # # E # # # O"

  items:
    # Without Structure example:
    #"#":
    #  item: BLACK_STAINED_GLASS_PANE
    #  name: " "
    #  lore: [ ]
    #  glow: false
    #  amount: 1
    #  action: voidchest:nothing
    #  slots: [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ... 53 ]
    "#":
      item: BLACK_STAINED_GLASS_PANE
      name: " "
      lore: [ ]
      glow: false
      amount: 1
      action: voidchest:nothing

    "A":
      item: DIAMOND
      name: "&6&lAuto Sell"
      lore:
        - "&7Enable automatic selling of contents."
        - "&7Status: &e%status_auto_sell%"
        - ""
        - "&eClick to toggle."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#FFE066"
        - "#FFB347"
        - "#FFA500"
        - "#FF8C00"
        - "#FF4500"
      action: voidchest:toggle_auto_sell

    "C":
      item: HOPPER
      name: "&6&lChunk Collector"
      lore:
        - "&7Collect items in the chunk automatically."
        - "&7Status: &e%status_chunk_collector%"
        - ""
        - "&eClick to toggle."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#FFA07A"
        - "#FF7F50"
        - "#FF6347"
        - "#FF4500"
        - "#FF0000"
      action: voidchest:toggle_chunk_collector

    "P":
      item: TNT
      name: "&c&lPurge Non-Sellable"
      lore:
        - "&7Delete non-sellable items automatically."
        - "&7Status: &e%status_purge%"
        - ""
        - "&eClick to toggle."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#FFB6C1"
        - "#FF69B4"
        - "#FF1493"
        - "#DB7093"
        - "#C71585"
      action: voidchest:toggle_purge

    "U":
      item: FEATHER
      name: "&b&lUpgrades"
      lore:
        - "&7Open the upgrades menu to enhance your VoidChest."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#87CEFA"
        - "#00BFFF"
        - "#1E90FF"
        - "#4682B4"
        - "#5F9EA0"
      action: voidchest:open_upgrades

    "H":
      item: ARMOR_STAND
      name: "&b&lHologram Display"
      lore:
        - "&7Toggle the hologram for this VoidChest."
        - "&7Status: &e%status_hologram%"
        - ""
        - "&eClick to toggle."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#D8BFD8"
        - "#DA70D6"
        - "#BA55D3"
        - "#9932CC"
        - "#8A2BE2"
      action: voidchest:toggle_hologram

    "L":
      item: LAVA_BUCKET
      name: "&d&lVoidChest Charge"
      lore:
        - "&7Add one hour of charge time to your VoidChest."
        - ""
        - "&7Current Charge: &e%charge%"
        - "&7Price per Renewal: &e$%price%"
        - "&7Renewal Time: &e%renewal%"
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#FF69B4"
        - "#FF1493"
        - "#DB7093"
        - "#C71585"
        - "#800080"
      action: voidchest:add_charge

    "T":
      item: SLIME_BALL
      name: "&a&lTransfer Non-Sellable"
      lore:
        - "&7Transfer non-sellable items to a linked chest."
        - "&7Status: &e%status_transfer_non_sellable%"
        - ""
        - "&eClick to toggle."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#98FB98"
        - "#7CFC00"
        - "#32CD32"
        - "#228B22"
        - "#006400"
      action: voidchest:toggle_transfer_non_sellable

    "B":
      item: GOLD_INGOT
      name: "&9&lBank Transfer"
      lore:
        - "&7Choose whether income goes to your bank."
        - "&7Current Destination: &e%status_bank%"
        - ""
        - "&eClick to toggle."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#87CEEB"
        - "#4682B4"
        - "#4169E1"
        - "#1E90FF"
        - "#0000CD"
      action: voidchest:toggle_bank

    "O":
      item: CHEST
      name: "&6&lChest Inventory"
      lore:
        - "&7Access the inventory of your VoidChest."
        - ""
        - "&eClick to open."
      glow: true
      amount: 1
      animation: "wave"
      colors:
        - "#F0E68C"
        - "#FFD700"
        - "#FFA500"
        - "#FF8C00"
        - "#FF4500"
      action: voidchest:open_container

    "S":
      item: BOOK
      name: "&b&lStatistics"
      lore:
        - "&8&m---------------------"
        - " &6&lOwner: &e%owner%"
        - " &a&lVoidChest: &e%voidchest%"
        - " &b&lBooster: &e%booster%x"
        - " &a&lMoney Made: &e$%money%"
        - " &3&lItems Sold: &e%items_sold%"
        - " &4&lItems Purged: &e%items_purged%"
        - "&8&m---------------------"
      glow: false
      amount: 1
      animation: "wave"
      colors:
        - "#B0E0E6"
        - "#ADD8E6"
        - "#87CEFA"
        - "#87CEEB"
        - "#4682B4"
      action: voidchest:nothing

    "E":
      item: PLAYER_HEAD
      name: "&c&l» &e&lExit &c&l«"
      lore: [ ]
      skullProperty: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNDQ2NjRlZGVhNzAxOTMzMjZhYTMxZjhmNTBmODBjMjkzN2I1YThmMDczNThhNWIwODQ5ZGRmNWI1YjJjOGMzNiJ9fX0="
      frames:
        0:
          item: PLAYER_HEAD
          skullProperty: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzY2ZmU5NzM4YTY5M2NlMjlkZWY1MmU3OTQ0OTNhZTAwMGVhYmE3MWJhNjYwNTY5MDY1ZWE2NjI4NTEzNTQxZiJ9fX0="
          amount: 1
          glow: true
      glow: true
      animation: "wave"
      colors:
        - "#FF0000"
        - "#DC143C"
        - "#B22222"
        - "#8B0000"
        - "#800000"
      action: voidchest:close
Actions
NamespaceDescription
voidchest:add_chargeAdd Charge
voidchest:open_containerOpen Chest Container
voidchest:open_filtersOpen Filters Menu
voidchest:open_upgradesOpen Upgrades Menu
voidchest:toggle_auto_sellToggle Auto Sell
voidchest:toggle_bankToggle Bank
voidchest:toggle_chunk_collectorToggle Chunk Collector
voidchest:toggle_hologramToggle Hologram
voidchest:toggle_purgeToggle Purge of Non Sellable Items
voidchest:toggle_transfer_non_sellableToggle Transfer of Non Sellable Items
voidchest:nothingDo Nothing
voidchest:closeClose The Current Inventory

UI Commands​

UI Commands allow you to execute Minecraft commands directly from GUI items.

Unlike action, which executes an internal VoidChest action (voidchest:*), UI Commands execute any Bukkit/Spigot command as either the player or the console.

UI Commands

Example​

items:
  "I":
    item: IRON_BLOCK
    name: "Example UI Command Item"
    lore: [ ]
    glow: false
    amount: 1
    action: voidchest:nothing

    commands:
      open:
        command: "warp spawn"
        console: false
        cooldown: 0
        cooldownKey: "warp_spawn_cmd"
        persistent: false

        requirements:
          permission:
            type: permission
            permission: "myplugin.warp"
            message: "&cYou don't have permission!"

          level:
            type: level
            level: 10
            message: "&cYou need to be level 10!"

          balance:
            type: placeholder
            placeholder: "%vault_eco_balance%"
            value: ">=10000"
            message: "&cYou need at least $10,000!"

Commands Section​

Each key inside commands represents a unique command entry.

commands:
  teleport:
    command: "warp spawn"
    console: false
SettingDescription
commandThe command to execute. Do not include /.
consoleExecutes the command as the console instead of the player.
requirementsOptional requirements that must pass before the command executes.

Multiple commands may be configured.

commands:
  first:
    command: "say Hello"

  second:
    command: "spawn"

Commands execute in the order they appear.

Requirements​

Requirements determine whether a command should be executed.

If any requirement fails:

  • Remaining requirements are skipped.
  • The configured failure message is sent.
  • The command is not executed.

Requirements are completely optional.

Permission Requirement​

Requires the player to have a permission.

requirements:
  permission:
    type: permission
    permission: "myplugin.use"
    message: "&cYou don't have permission!"
SettingDescription
permissionPermission node to check.
messageMessage sent when the player does not have the permission.

Level Requirement​

Requires the player to have a minimum experience level.

requirements:
  level:
    type: level
    level: 30
    message: "&cYou must be level 30."
SettingDescription
levelRequired Minecraft XP level.
messageMessage shown when the requirement fails.

Placeholder Requirement​

Evaluates a PlaceholderAPI placeholder.

requirements:
  balance:
    type: placeholder
    placeholder: "%vault_eco_balance%"
    value: ">=10000"
    message: "&cYou don't have enough money!"
SettingDescription
placeholderPlaceholderAPI placeholder to evaluate.
valueComparison expression.
messageMessage shown when the comparison fails.

Numeric Operators​

OperatorMeaning
>=100Greater than or equal
<=100Less than or equal
!=100Not equal
>100Greater than
<100Less than
=100Equal

Example:

value: ">=5000"

String Operators​

OperatorDescription
~VIPContains VIP
!~VIPDoes not contain VIP
^AdminStarts with Admin
$OwnerEnds with Owner
equalsIgnoreCase:AdminCase-insensitive equality
regex:^VIP_[0-9]+$Regular expression match

Example:

value: "~VIP"

Execution Order​

When a player clicks an item:

  1. The GUI action (action) executes.
  2. Every configured UI Command is processed.
  3. Each command checks all of its requirements.
  4. If every requirement passes, the command executes.
  5. If any requirement fails, that command is skipped and its failure message is shown.

Command Cooldown​

The cooldown option prevents players from executing the same UI command repeatedly within a short period of time. This helps prevent spam clicking and reduces unnecessary command execution.

The value is specified in seconds.

  • 0 = No cooldown
  • 10 = Player can execute the command once every 10 seconds
  • 60 = Player can execute the command once every minute

Example:

commands:
  open:
    command: "warp spawn"
    console: false
    cooldown: 10

In this example, after using the command, the player must wait 10 seconds before they can use it again.

Cooldown Key​

The cooldownKey option defines the unique identifier used to track the cooldown.

Cooldowns with the same key share the same timer, even if they belong to different items or commands.

This allows you to create a shared cooldown across multiple UI buttons.

Example:

items:
  "I":
    item: IRON_BLOCK
    commands:
      open:
        command: "warp spawn"
        cooldown: 30
        cooldownKey: "teleport_cooldown"

  "D":
    item: DIAMOND_BLOCK
    commands:
      open:
        command: "warp shop"
        cooldown: 30
        cooldownKey: "teleport_cooldown"

With the configuration above:

  1. Player clicks Warp Spawn
  2. The teleport_cooldown cooldown starts
  3. Player cannot use Warp Shop until the cooldown expires

If no cooldownKey is provided, the plugin will use a generated key based on the command.

Persistent Cooldown​

The persistent option controls whether the cooldown is saved permanently.

When enabled, cooldowns survive:

  • Server restarts
  • Plugin reloads
  • Configuration reloads

Example:

commands:
  open:
    command: "claim reward"
    cooldown: 86400
    cooldownKey: "daily_reward"
    persistent: true

With this configuration:

  • The player can claim the reward once every 24 hours
  • Restarting the server will not reset the cooldown
  • Reloading the plugin will not allow the player to claim again

If persistent is set to false, cooldowns are stored only in memory and will be reset after a server restart or plugin reload.

Example:

commands:
  open:
    command: "warp spawn"
    cooldown: 10
    cooldownKey: "warp_spawn_cmd"
    persistent: false

The cooldown above will be removed when the server or plugin is restarted.

Notes​

  • Commands execute in the order they are defined.
  • Requirement names (not types) (permission, level, balance, etc.) are only identifiers and may be named anything.
  • message supports MiniMessage/color codes the same way as the rest of the plugin.
  • Placeholder requirements require PlaceholderAPI to be installed.
  • Console commands execute without player permissions.
  • Do not prefix commands with /.

Key Configuration Notes:​

  1. Placeholder variables like %voidchest%, %type%, %filter%, and %player% are dynamically replaced at runtime
  2. Menu positions are defined using slot numbers (0-53 for 6-row inventories)
  3. Animation types ("wave") and color gradients can be customized
  4. Actions starting with voidchest: trigger plugin-specific functionality
  5. Player head textures use Base64 encoded skull properties
  6. Structure is a list of strings that define the inventory layout
tip

Use the defaultAction parameter to define fallback behavior for unconfigured slots, and bottomInventoryAction to handle player inventory interactions.

danger

Caution Please avoid using item specific actions in the defaultAction or bottomInventoryAction parameters, as they may break the menu functionality.

danger

Caution Please avoid using item/menu specific actions in different menus, as they may break the menu functionality.

info

Animations fade wave rainbow pulse typing sparkle glitch

Remember to maintain proper indentation in YAML files and test menu configurations after making changes.