config.yml

# ============================================================================
# VHoppers main configuration
# ----------------------------------------------------------------------------
# This file contains global behavior, safety rules, integrations, task timings,
# holograms, and container settings.
#
# Other configuration files:
# - messages.yml       = player-facing messages
# - database.yml       = storage backend and SQL settings
# - modules.yml        = module item appearance and glow colors
# - upgrades.yml       = upgrade levels, prices, and currencies
# - currencies.yml     = custom command-based currencies
# - prices.yml         = local Seller Module prices
# - compress.yml       = Compressor Module recipes
# - menus/*.yml        = GUI layouts and menu items
# ============================================================================

# Internal config format version. Used for future automatic config upgrades.
config-version: 1

# ============================================================================
# Diagnostics
# ============================================================================

# Enables verbose console logs for troubleshooting.
# Keep this false on production servers unless you are debugging an issue.
debug: false

# ============================================================================
# Update Checker
# ============================================================================

update-checker:
  # Checks the Maven metadata asynchronously when the plugin starts/reloads.
  enabled: true

# ============================================================================
# Integrations
# ============================================================================

# Select which stacked-item plugin VHoppers should hook into.
# Supported values:
# - none
# - VortexStacker
# - RoseStacker
# - WildStacker
#
# Use "none" if your server does not use a stacker plugin.
stacker: none

# ============================================================================
# General Gameplay Settings
# ============================================================================

hopper-item:
  # Material:
  #   Bukkit material name. Example: PAPER, FEATHER, DIAMOND
  #   You can also use HDB-12345 if HeadDatabase is installed.
  material: HOPPER

  # Name:
  #   Supports MiniMessage, hex colors, legacy colors and PlaceholderAPI.
  name: "&bVHopper"

  # Texture:
  #   Optional. Only works if material is PLAYER_HEAD.
  texture: ""

  lore:
    - "&7An upgradeable custom hopper."
    - "&7Can be expanded with modules."
    - ""
    - "&eRight-click after placing: &fOpen menu"

  unbreakable: false
  custom-model-data: -1
  tooltip-style: ""
  max-stack-size: -1
  glow: false
  attributes: {}
  enchantments: {}
  item-flags: []

settings:
  # If true, automation only works in chunks that are already loaded.
  # Recommended: true, to avoid loading chunks from module tasks.
  work-only-loaded-chunks: true

  # If false, modules can only link containers in the same world as the player.
  allow-cross-world-linking: false

  # Maximum distance between the player/module and a linked container.
  # Set to 0 or lower to allow any distance.
  max-link-distance: 64

  # Default maximum number of VHoppers a player may own.
  # Permission-based limit nodes can override this later.
  default-hopper-limit: 10

  # Maximum number of module slots a VHopper can use.
  # Current v1 GUI/storage supports 1-10 module slots.
  # This also caps the module-slots upgrade maximum at runtime.
  max-module-slots: 10

  # If true, only the owner can pick up a VHopper through the pickup menu.
  only-owner-can-pickup: true

  # If true, custom VHoppers cannot be used as vanilla hoppers.
  # This prevents inserting items, pulling from containers, or feeding them
  # through other hoppers.
  disable-vanilla-hopper-behavior: true

  # If true, custom VHoppers cannot be broken normally.
  # If false, breaking can return the VHopper item and module items.
  prevent-normal-breaking: true

  # If true, upgrades require economy payment.
  # If false, upgrades are free even when Vault or other currencies are installed.
  require-economy: true

  # Folia safety guard for module-linked inventories.
  # If the server is running Folia, linked containers must be in the same chunk
  # as the VHopper. This avoids unsafe cross-region inventory access.
  folia-require-linked-containers-same-chunk: true

# ============================================================================
# Protection Hooks
# ============================================================================

protection:
  # Prevents players from linking modules to containers in protected areas where
  # they do not have access.
  prevent-linking-protected-containers: true

  # Checks WorldGuard regions with the BUILD query.
  worldguard: true

  # Checks Towny plot permissions with SWITCH access on the linked container.
  towny: true

# ============================================================================
# Hologram
# ============================================================================

hologram:
  # Shows a TextDisplay hologram above placed VHoppers.
  enabled: true

  # Vertical offset above the hopper block.
  y-offset: 1.35

  # Maximum holograms refreshed per tick during reload/startup.
  refresh-batch-size: 50

  # TextDisplay background mode.
  # none    = no background
  # default = Minecraft default text background
  # custom  = use background-color below
  background-type: custom

  # Custom background color for background-type: custom.
  # Format: #AARRGGBB or #RRGGBB. If alpha is not provided, 80 is used.
  background-color: "#50000000"

  # Lines displayed above each VHopper.
  # Supports legacy color codes with &.
  # Available placeholders:
  # {owner} = VHopper owner name
  lines:
    - "&b&lVHopper"
    - "&7Owner: &f{owner}"
    - "&7Right-click to open"

# ============================================================================
# Module Tasks
# ============================================================================

collector:
  # Collector task interval in ticks.
  # 20 ticks = 1 second.
  interval-ticks: 20

  # Maximum active collector hoppers processed per collector tick.
  # Lower values spread the work over time on large servers.
  max-hoppers-per-cycle: 100

  # Base collector horizontal radius for level 1.
  # Upgrade levels use the plugin's collector-range upgrade table.
  base-radius-xz: 2

  # Base collector vertical radius for level 1.
  base-radius-y: 1

  # Legacy option. Collector now always tries safe partial stacked-item moves
  # when the selected stacker API supports changing the source stack amount.
  stacked-partial-mode: api-partial

  # Cooldown for repeated debug logs when a partial stacked item move is skipped.
  partial-skip-debug-cooldown-seconds: 30

dealer:
  # Dealer task interval in ticks.
  # Capacity upgrades increase moved amount; this should usually stay 8.
  interval-ticks: 8

  # Maximum active dealer/seller/smelter/compressor/void hoppers processed per dealer tick.
  # Lower values spread the work over time on large servers.
  max-hoppers-per-cycle: 100

  # Number of sample item slots in the dealer filter GUI.
  filter-size: 9

seller:
  # Selects where Seller Module prices come from.
  # Supported values:
  # - LOCAL          = use prices.yml
  # - ShopGUIPlus    = use ShopGUI+ sell prices
  # - EconomyShopGUI = use EconomyShopGUI/EconomyShopGUI-Premium sell prices
  backend: LOCAL

  # Currency used to pay players after items are sold.
  # Supports the same syntax as upgrades.yml:
  # Vault, CoinsEngine:<currency>, ExcellentEconomy:<currency>, Custom:<id>
  currency: Vault

  # Maximum item amount a single Seller Module may sell each dealer cycle.
  # Higher values are faster, but do more inventory/economy work per cycle.
  max-items-per-cycle: 64

  # Short cache for external shop price lookups.
  # This reduces repeated ShopGUIPlus/EconomyShopGUI calls when many sellers run.
  price-cache-millis: 5000

  # Maximum external shop price lookups a single seller module may do per cycle.
  # Cached prices do not need backend work; LOCAL prices are not affected.
  max-price-lookups-per-cycle: 16

vcontainer:
  # If true, VContainer inserts are checked with a before/after contents diff.
  # This is safer for debugging, but costs two getItems calls per insert.
  # Keep false on production unless you suspect VContainer add failures.
  verify-adds: false

# ============================================================================
# Containers
# ============================================================================

containers:
  # Materials that modules may link as valid containers.
  # The block must also expose a Bukkit Container inventory.
  supported:
    - CHEST
    - TRAPPED_CHEST
    - BARREL
    - HOPPER
    - DROPPER
    - DISPENSER