Overview

Each VoidChest type is configured using its own YAML file.

VoidChest configurations are stored in:

./plugins/VoidChest/voidchests/

By default, VoidChest includes a default.yml configuration. You can create custom VoidChest types by copying this file and renaming it.

Example:

default.yml
gold.yml
diamond.yml

Each configuration can have its own:

• Block type
• Selling behavior
• Limits
• Upgrades
• Holograms
• Economy settings
• Protection rules
• Appearance

This allows you to create different VoidChest tiers with unique behavior.

---

Mechanics

The Mechanics section controls the main functionality of a VoidChest.

Example:

Mechanics:
  block: CHEST
  booster: 1.0

---

Block

block: CHEST

Defines the block that represents the VoidChest when placed.

Example:

block: BARREL

Players will place and interact with the VoidChest using this block.

---

Booster

booster: 1.0

Controls the default money multiplier applied when selling items.

The final value is calculated using:

Item Price × Booster × Other Multipliers

Example:

booster: 2.0

A 2.0 booster doubles the generated income.

---

Interaction Behavior

VoidChests can perform different actions when a player interacts with them.

Available actions:

Value	Description
MENU	Opens the VoidChest menu
CHEST	Opens the VoidChest storage inventory
CONTAINER	Opens the block inventory
NONE	No action is performed

---

Shift Right Click

shift click open: CHEST

Controls the action performed when a player sneaks and right-clicks a VoidChest.

Example:

shift click open: MENU

---

Right Click

right click open: MENU

Controls the action performed when a player normally right-clicks a VoidChest.

Example:

right click open: CHEST

---

Offline Owner

enable when owner offline: true

Determines whether the VoidChest continues operating while its owner is offline.

If this option is not specified, the value from:

options.yml

will be used.

---

VoidChest Links

links: false

Enables the VoidChest linking system.

When enabled, VoidChests can collect items from linked containers.

Example:

links: true

Players can connect nearby containers to the VoidChest depending on their link limit.

---

Protection Settings

The prevent section controls restrictions related to placement and interaction.

Example:

prevent:
  chest near voidchests: false
  voidchests near chests: false

---

Prevent Chests Near VoidChests

chest near voidchests: false

Prevents players from placing normal chests close to VoidChests.

---

Prevent VoidChests Near Chests

voidchests near chests: false

Prevents players from placing VoidChests near normal chests.

---

Same Chunk Limit

placing voidchests in same chunk: true

Prevents multiple VoidChests from being placed inside the same chunk.

Useful for preventing chunk-based farming setups.

---

Creative Mode Protection

creative mode interaction: true

Blocks players in Creative mode from interacting with VoidChests.

---

Explosion Protection

voidchest from exploding: false

Controls whether explosions can destroy VoidChests.

Example:

voidchest from exploding: true

The VoidChest will survive explosions.

---

Breaking Settings

The break section controls what happens when a player breaks a VoidChest.

Example:

break:
  successful: true
  permission deny: true
  failed other: true

---

Available Options

Option	Description
successful	Message/action when successfully breaking your own VoidChest
permission deny	Message/action when lacking break permission
failed other	Message/action when attempting to break another player's VoidChest

---

Stored Data

VoidChests can save their progress when broken.

Example:

store stats: false
store upgrades: false
store charge: false

When enabled, the saved data is restored when the VoidChest is placed again.

Option	Stores
store stats	Generated money and item statistics
store upgrades	Purchased upgrades
store charge	Remaining fuel time

Example:

store charge: true

A player can break and replace the VoidChest without losing remaining fuel.

Placement Settings

The place section controls placement-related behavior.

Example:

place:
  limit: 5
  delay check: false

---

Placement Limit

limit: 5

Defines the maximum number of VoidChests a player can place.

Example:

limit: 1

Players can only have one VoidChest of this type placed at a time.

---

Placement Delay Check

delay check: false

Adds a small delay before checking placement restrictions.

This can be useful on servers with many protection checks or integrations.

---

Default Features

These options define which features are enabled automatically when a new VoidChest is created.

Example:

auto sell: true
purge items: true
chunk collector: true
charge: true

---

Auto Sell

auto sell: true

Automatically sells collected items when the VoidChest processes items.

When disabled, players must manually sell items through the VoidChest menu.

---

Purge Items

purge items: true

Automatically removes items that cannot be sold.

Example:

• Item has no shop price
• Item is disabled by filters
• Item cannot be processed by the economy system

---

Chunk Collector

chunk collector: true

Enables item collection from chunks.

When enabled, the VoidChest can collect dropped items depending on the configured collector mode.

---

Charge System

charge: true

Enables the VoidChest fuel system.

When enabled, VoidChests require charge/fuel to operate.

If disabled:

• No fuel is consumed
• Charge upgrades are unavailable
• The VoidChest runs permanently

---

Holograms

hologram: true

Creates a hologram above the VoidChest.

The hologram can display information such as:

• Owner
• Generated money
• Remaining charge
• Items sold

---

Bank System

bank: false

Controls where generated money is stored.

When enabled:

• Money is stored inside the VoidChest bank
• Players must withdraw money manually

When disabled:

• Money is sent directly to the player's balance

---

Options

The Options section contains general VoidChest settings.

Example:

Options:
  sell interval: 10

---

Sell Interval

sell interval: 10

Defines how often the VoidChest attempts to sell items.

The value is measured in seconds.

Example:

sell interval: 60

The VoidChest will process selling every 60 seconds.

---

Profit Calculator

profit calculator:
  - "VoidChest:1"

Defines which economy systems are used to calculate item prices.

Available calculators:

Calculator	Description
VoidChest	Uses the built-in VoidChest shop
ShopGUIPlus	Uses ShopGUIPlus prices
Essentials	Uses Essentials worth values
CMI	Uses CMI economy values
EconomyShopGUI	Uses EconomyShopGUI prices
DynamicShop	Uses DynamicShop prices

---

Calculator Priority

Each calculator has a priority weight.

Example:

profit calculator:
  - "VoidChest:1"
  - "ShopGUIPlus:2"

Lower numbers have higher priority.

The priority order is:

1. Lowest weight
2. Highest calculated profit if weights are equal

Example:

VoidChest:1
ShopGUIPlus:1

If both calculators have the same priority, VoidChest will use the calculator that provides the highest profit.

---

Sounds

The sound section controls sounds played during VoidChest actions.

Example:

sound:
  place: LEVEL_UP
  break: ANVIL_BREAK

Available actions depend on the configured VoidChest events.

Common examples:

Option	Trigger
place	When placing a VoidChest
break	When breaking a VoidChest

---

Global Link Limit

links: 3

Defines the maximum number of containers that can be linked to a VoidChest.

Example:

links: 10

Allows up to 10 linked containers.

If an upgrade system is enabled, upgrade limits can override this value.

---

Force Disable Features

These options disable specific features for all VoidChests of this type.

Example:

auto sell force disable: true

---

Auto Sell

auto sell force disable: false

When enabled:

auto sell force disable: true

Auto selling is disabled permanently.

---

Purge Items

purge items force disable: false

When enabled, item purging cannot be used.

---

Bank

bank force disable: false

When enabled, the bank system is unavailable.

---

⛏️ Chunk Collector Settings

Controls how VoidChests collect dropped items.

Example:

chunk collector:
  mode: CHUNK

---

Collector Mode

mode: CHUNK

Available modes:

Mode	Description
CHUNK	Collects items from the current chunk
BOUNDINGBOX	Uses the range provided by upgrades

---

Transfer Non-Sellable Items

transfer non sellables: false

Controls what happens with items that cannot be sold.

When enabled:

• Items are transferred instead of removed

When disabled:

• Items remain untouched or are handled normally

---

Filters

filters: false

Enables item filtering.

When enabled, players can control which items the VoidChest accepts.

---

Charge Settings

The charge section controls VoidChest fuel behavior.

Example:

charge:
  max time: 172800
  renewal time: 3600
  price: 20000

---

Maximum Charge Time

max time: 172800

Defines the maximum amount of fuel a VoidChest can store.

Value is measured in seconds.

Example:

172800 seconds = 48 hours

---

Renewal Time

renewal time: 3600

Defines how much charge is added when refueling.

Example:

3600 seconds = 1 hour

---

Recharge Price

price: 20000

Defines the cost to recharge the VoidChest.

Example:

price: 50000

Players pay 50,000 currency to add charge.

---

Hologram Settings

The hologram section controls the appearance and content of VoidChest holograms.

Example:

hologram:
  height: 3.9

---

Hologram Height

height: 3.9

Controls the vertical distance above the VoidChest block.

Higher values move the hologram upwards.

---

Hologram Text

text:
  - '&c&l%voidchest% VoidChest'

Defines the lines displayed in the hologram.

Supports:

• Legacy color codes
• MiniMessage
• Placeholders

Example:

text:
  - '&6%owner%'
  - '&aMoney: %money%'

---

Available Placeholders

Placeholder	Description
%owner%	VoidChest owner name
%booster%	Current booster multiplier
%money%	Generated money
%items_sold%	Total sold items
%items_purged%	Removed items
%timeleft%	Remaining charge time
%charge_hologram%	Charge status display

---

Item Settings

The item section controls how the VoidChest item appears when stored in inventories, dropped, or given to players.

Example:

item:
  name: '&c&l%voidchest% VoidChest'
  lore:
    - '&7Automatically sells items'

---

Item Drop Behavior

Drop Directly to Inventory

drop straight to inventory: false

Controls what happens when a player breaks a VoidChest.

When enabled:

drop straight to inventory: true

The VoidChest item is added directly to the player's inventory.

When disabled:

• The item drops naturally on the ground.
• Normal Minecraft item pickup rules apply.

---

Item Name

name: '&c&l%voidchest% VoidChest'

Defines the display name of the VoidChest item.

Supports:

• Legacy color codes (&c, &l, etc.)
• MiniMessage formatting
• Placeholders

Example:

name: '<red><bold>Diamond VoidChest</bold></red>'

---

Item Lore

lore:
  - '&7Automatically sell items'

Defines the lore displayed on the VoidChest item.

Supports:

• Legacy colors
• MiniMessage
• Placeholders

Example:

lore:
  - '&7Tier: &6Gold'
  - '&7Multiplier: &ax2'

---

Inventory Appearance

Controls how VoidChest inventories are displayed.

---

Custom Inventory Name

inventory custom name: false

Determines whether the VoidChest's custom name is used as the inventory title.

Example:

inventory custom name: true

A VoidChest named:

Gold VoidChest

will display:

Gold VoidChest

as the inventory title.

---

Default Inventory Name

inventory default name: "⚡ VoidChest ⚡"

Defines the default inventory title.

Supports:

• Unicode characters
• Legacy colors
• MiniMessage formatting

Examples:

inventory default name: "&6&lGold VoidChest"

or:

inventory default name: "<gold><bold>Gold VoidChest</bold></gold>"

---

Inventory Lore

inventory lore:
  - '&7Generated money: %money%'

Controls the lore displayed on VoidChest inventory items.

Supports:

• Legacy colors
• MiniMessage
• Placeholders

Example:

inventory lore:
  - '&7Owner: &f%owner%'
  - '&7Items sold: &a%items_sold%'

---

🔗 Link Inventory

Controls the appearance of linked VoidChests inside the linking menu.

Example:

inventory links lore:
  - '&7Location: %location_world%'

---

Link Inventory Placeholders

The following placeholders are available:

Placeholder	Description
%location_world%	World name
%location_x%	X coordinate
%location_y%	Y coordinate
%location_z%	Z coordinate

Example:

inventory links lore:
  - '&7World: &f%location_world%'
  - '&7Location: &f%x% %y% %z%'

---

Disabled Worlds

disabled worlds: [ ]

Defines worlds where VoidChests cannot operate.

Example:

disabled worlds:
  - world_nether
  - world_the_end

When a world is disabled:

• Players cannot place VoidChests
• Existing VoidChests will not function
• VoidChest actions are blocked

World names must exactly match the Bukkit world name.

Example:

Correct:

disabled worlds:
  - survival_world

Incorrect:

disabled worlds:
  - Survival World

---

Complete Example Configuration

The following example creates a basic automatic selling VoidChest with:

• A chest block as the VoidChest
• 1.5x income multiplier
• Automatic selling enabled
• Fuel system enabled
• Hologram enabled
• Container linking enabled
• Stored statistics/upgrades/charge
• A 5 VoidChest placement limit

Mechanics:
  block: CHEST

  # Income multiplier
  booster: 1.5

  # Interaction behavior
  shift click open: MENU
  right click open: CHEST

  # Continue operating while owner is offline
  enable when owner offline: true

  # Allow linking containers
  links: true

  prevent:
    # Protection settings
    chest near voidchests: false
    voidchests near chests: false
    placing voidchests in same chunk: true
    creative mode interaction: true
    placing other voidchests near: false
    voidchest from exploding: false

  break:
    # Breaking messages/actions
    failed other: true
    permission deny: true
    successful: true

    # Store data when broken
    store stats: true
    store upgrades: true
    store charge: true

    # Drop item after explosion
    drop voidchest on explosion: false

  place:
    permission deny: true
    successful: true

    # Placement delay check
    delay check: false

    # Maximum placed VoidChests
    limit: 5

  # Default features for newly created VoidChests
  auto sell: true
  purge items: true
  chunk collector: true
  charge: true
  hologram: true
  bank: false


Options:
  # Sell interval in seconds
  sell interval: 10

  profit calculator:
    - "VoidChest:1"
    # - "ShopGUIPlus:2"
    # - "Essentials:3"

  sound:
    place: 'LEVEL_UP'
    break: 'ANVIL_BREAK'

    upgrade:
      success: 'ORB_PICKUP'
      failure: 'VILLAGER_NO'

  # Maximum container links
  links: 3

  # Force disable systems
  auto sell force disable: false
  purge items force disable: false
  bank force disable: false

  chunk collector:
    mode: CHUNK
    force disable: false

    transfer non sellables: false
    filters: false

  charge:
    force disable: false

    hologram:
      no fuel: 'No Fuel'

    placeholder:
      no fuel: 'No Fuel'

    # Maximum stored charge time
    max time: 172800

    # Added charge per refill
    renewal time: 3600

    # Recharge cost
    price: 20000

  hologram:
    force disable: false

    height: 3.9

    text:
      - '&c&l%voidchest% VoidChest'
      - ''
      - '&fOwner: &c%owner%'
      - '&fBoost: &b%booster%x'
      - '&fMoney made: &a$%money%'
      - '&fItems sold: &3%items_sold%'
      - '&fItems purged: &3%items_purged%'
      - '&7VoidChest timeleft: &e%timeleft%'
      - '&7VoidChest charge: &e%charge_hologram%'

  item:
    # Give directly to inventory when broken
    drop straight to inventory: false

    name: '&c&l%voidchest% VoidChest'

    lore:
      - '&7Automatically sell and clear items'
      - '&7while generating income.'

    # Inventory appearance
    inventory custom name: false

    inventory default name: "⚡ <gradient:gold:yellow><bold>%voidchest%</bold></gradient> ⚡"

    inventory lore:
      - ""
      - "<gradient:gold:yellow><bold>Location:</bold></gradient> <white>%location_world%</white>"
      - "<gray>» <gold>Left-Click</gold> to open menu."
      - "<gray>» <gold>Right-Click</gold> to open links."
      - ""

    # Link inventory
    inventory links custom name: false

    inventory links lore:
      - ""
      - "<gradient:gold:yellow><bold>Location:</bold></gradient>"
      - "<gray>Click to open this link."
      - ""

  # Worlds where VoidChest is disabled
  disabled worlds:
    - world_nether
    - world_the_end

Result

This configuration creates a VoidChest that:

• Uses a chest block
• Gives 1.5x income
• Works while the owner is offline
• Automatically sells items
• Removes invalid items
• Requires charge/fuel
• Supports container links
• Saves progress when broken
• Displays a hologram
• Allows up to 5 placed VoidChests per player
• Is disabled in the Nether and End

Configuration Tips

Creating Multiple VoidChest Types

You can create different tiers by duplicating the configuration:

voidchests/
├── default.yml
├── iron.yml
├── gold.yml
└── diamond.yml

Example differences:

Tier	Booster	Links	Charge
Iron	1.0x	1	24 hours
Gold	2.0x	5	48 hours
Diamond	5.0x	10	7 days

---

Recommended Setup

For public servers:

auto sell: true
charge: true
purge items: true

This provides:

• Automatic income generation
• Controlled economy balancing
• Protection against unwanted items