Skip to content

Configuration.md

Jump to bottom
Fragmer2 edited this page Apr 8, 2026 · 4 revisions

Configuration Guide

File Location

plugins/SpawnChestPlugin/config.yml

The file is generated automatically on first run. After editing, run /reloadchestconfig to apply changes.

Language

language: en

Options: en ru ua es de fr zh pt pl it

Language files live in plugins/SpawnChestPlugin/lang/. You can edit them or create new ones.

Main Settings

Spawn timer

settings:
  spawn-interval-seconds: 14400   # 4 h between chests

Live change: /setchesttimer 3600

Batch spawning

settings:
  chest-count-per-interval: 1     # how many chests spawn each interval
  chest-spawn-delay-seconds: 5    # seconds between each chest in a batch

When chest-count-per-interval is greater than 1, each chest finds its own random location. The plugin waits for the previous spawn to finish before starting the next one.

Chest lifetime

settings:
  chest-disappear-minutes: 30
  • Unopened chest — disappears after this many minutes from spawn time.
  • Opened chest — gets a fresh chest-disappear-minutes from the moment it was opened.
  • Set to 0 to keep chests forever (not recommended for busy servers).

Chest tier chances

settings:
  chest-chances:
    common:    0.50
    rare:      0.35
    legendary: 0.15

Values can be any decimals — they do not have to sum to exactly 1.0.

Worlds

settings:
  enabled-worlds:
    - "world"

Remove entries to add worlds. An empty list allows all worlds.

Spawn Zone

settings:
  spawn-zone:
    min-distance: 400              # minimum blocks from 0,0
    max-distance: 2000             # maximum blocks from 0,0
    min-distance-from-center: 100  # hard floor — never below this
    min-height: 50                 # minimum Y
    max-height: 200                # maximum Y
    bury-in-ground: false          # true = chest replaces ground block

    exclude-surfaces:
      water:      true    # lakes, rivers, oceans
      lava:       true    # lava pools and nether lakes
      leaves:     true    # tree canopy
      ice:        true    # ICE, PACKED_ICE, BLUE_ICE
      magma:      true    # magma blocks in the nether
      cactus:     true    # desert cactus
      sand:       false   # desert / beach sand — allowed
      gravel:     false   # gravel — allowed
      netherrack: false   # nether floor — allowed

exclude-surfaces.bedrock and exclude-surfaces.barrier are always blocked regardless of config.

Pre-Open Timer

Chests start locked. The first player to right-click starts a countdown. Only after it ends can anyone open the chest.

pre-open-timer:
  enabled: true
  duration-seconds: 30
  announce-at-seconds:
    - 30
    - 20
    - 10
    - 5
    - 3
    - 2
    - 1
  show-in-bossbar: true
  bossbar-color: PINK      # PINK  RED  YELLOW  GREEN  BLUE  PURPLE  WHITE
  notify-radius: 20.0      # countdown messages visible within this range (blocks)

The chest-disappear timer starts fresh after the chest unlocks, not from spawn time.

Chest Protection Zone

Blocks around an active chest are protected from breaking and placing by non-op players. The zone is removed automatically when the chest disappears or is opened.

chest-protection-zone:
  enabled: true
  radius: 5                           # 5 = 11×11 area  |  2 = 5×5  |  8 = 17×17
  use-worldguard: true                # create a real WG region if WorldGuard is installed
  worldguard-region-prefix: "spawnchest"   # region name: spawnchest_x_y_z
  notify-players: true                # message players when blocked

Features

Guardians

features:
  guardians:
    enabled: true
    common-count:    1    # Zombie
    rare-count:      2    # Skeleton
    legendary-count: 3    # Wither Skeleton

Toggle: /togglefeature guardians

Effects

features:
  effects:
    particles:              true
    lightning-on-legendary: true
    sounds:                 true
    chest-glow-particles:   true
    chest-beacon-beam:      true

Toggle: /togglefeature particles · /togglefeature sounds · /togglefeature lightning

Broadcasts

features:
  broadcasts:
    chest-spawn-announcement:  true
    title-on-spawn:            true
    countdown-warnings:        true
    resurrection-announcement: true
    achievement-announcement:  true

Toggle: /togglefeature announcements · /togglefeature titles

BossBar

features:
  bossbar:
    enabled: false                    # opt-in — disabled by default
    show-countdown: true
    countdown-show-minutes-before: 5  # 0 = show entire time between spawns
    show-active-chest: true
    active-chest-show-minutes: 0      # 0 = show for full chest lifetime
    color-countdown: YELLOW
    color-soon:      RED              # when < 60 s before spawn
    color-active:    GREEN

Color options: PINK RED YELLOW GREEN BLUE PURPLE WHITE

Protection Plugin Integration

Chests skip claimed or protected areas automatically. Detected at startup — no extra setup needed.

protection:
  enabled: true
  check-worldguard:       true
  check-grief-prevention: true
  check-grief-defender:   true
  check-lands:            true
  max-protection-retries: 20     # extra attempts when locations are protected

Supported: WorldGuard · GriefPrevention · GriefDefender · Lands

Summoner Apples

Four apple types. Each can drop inside chests independently.

summoner-apple:

  random:                        # spawns a random-tier chest
    enabled: true
    spawn-guardians: true
    spawn-effects:   true
    drop-in-common:    false
    drop-in-rare:      false
    drop-in-legendary: true
    drop-chance:       0.05

  common:                        # always spawns a Common chest
    enabled: true
    drop-in-common:    false
    drop-in-rare:      false
    drop-in-legendary: false
    drop-chance:       0.05

  rare:                          # always spawns a Rare chest
    enabled: true
    drop-in-common:    false
    drop-in-rare:      false
    drop-in-legendary: false
    drop-chance:       0.03

  legendary:                     # always spawns a Legendary chest
    enabled: true
    drop-in-common:    false
    drop-in-rare:      false
    drop-in-legendary: false
    drop-chance:       0.01

World Apple Drop

When enabled, a Summoner Apple spawns as a physical item in the world with each chest. Players see coordinates in chat and race to pick it up. The item never despawns until collected.

world-apple-drop:
  enabled: false
  apple-type: random            # random  common  rare  legendary
  spawn-method: near-chest      # near-chest  near-player  with-chest
  radius: 15                    # blocks (used by near-chest and near-player)
  announce-coordinates: true
  persist-until-pickup: true

Spawn methods:

  • near-chest — random spot within radius blocks of the chest
  • near-player — random spot within radius blocks of the nearest online player
  • with-chest — completely separate random world location using the same algorithm as chest spawning

Proximity Sounds

proximity-sounds:
  enabled: true
  max-distance:   50            # beyond this distance no sound plays
  min-distance:   5             # closer than this = loudest
  sound:          "BLOCK_NOTE_BLOCK_CHIME"
  interval-ticks: 40            # 20 ticks = 1 second

Statistics & Achievements

statistics:
  enabled: true
  achievements:
    enabled: true

XP rewards are configured under statistics.achievements.list.<id>.xp-reward in config.

Legendary Items

legendary-items:
  enabled: true    # master switch for all legendary items

Each item shares this structure:

  dragon-slayer-sword:
    enabled:             true
    bonus-damage:        4.0    # extra hearts per hit
    fire-duration-ticks: 100    # how long the target burns (5 seconds)
    cooldown-ms:         3000   # ms between ability uses

  master-pickaxe:
    enabled:            true
    auto-smelt:         true
    double-drop-chance: 0.5     # 50% chance
    cooldown-ms:        1000

  titan-axe:
    enabled:            true
    bonus-damage:       3.0
    tree-felling:       true
    combat-cooldown-ms: 4000
    tree-cooldown-ms:   6000

  void-shovel:
    enabled:      true
    area-size:    3             # NxN excavation area (hold Shift)
    auto-collect: true
    cooldown-ms:  5000

  storm-hammer:
    enabled:            true
    bonus-damage:       5.0
    lightning-effect:   true
    area-damage-radius: 3.0
    area-damage-amount: 4.0
    cooldown-ms:        8000

  guardian-bow:
    enabled:       true
    double-shot:   true
    homing-arrows: true
    homing-range:  5.0
    cooldown-ms:   2000

  wisdom-book:
    enabled: true

  phoenix-feather:
    enabled:                true
    resurrection:           true
    fire-immunity-passive:  true
    full-heal-on-resurrect: true
    cooldown-ms:            300000   # 5 minutes

  poseidon-trident:
    enabled:          true
    rain-radius:      5
    lightning-on-hit: true
    lightning-damage: 6.0
    cooldown-ms:      10000

Toggle all: /togglelegendary
Toggle one: /togglelegendary dragon-slayer-sword

Custom Potions

custom-potions:
  enabled: true

Individual potions are configured in the custom-potions.potions section. See [Custom Loot](https://github.com/Fragmer2/ChestSpawn/wiki/Custom%E2%80%90Loot.md) for details.

Warning Times

warning-times:
  - 72000   # 60 min
  - 36000   # 30 min
  - 12000   # 10 min
  - 6000    #  5 min
  - 2400    #  2 min
  - 1200    #  1 min
  - 200     # 10 sec
  - 60      #  3 sec
  - 40      #  2 sec
  - 20      #  1 sec

Values are in ticks (20 ticks = 1 second). Add or remove entries freely.

Example Configurations

Beginner-friendly server

settings:
  spawn-interval-seconds: 300
  chest-chances:
    common:    0.70
    rare:      0.25
    legendary: 0.05

pre-open-timer:
  duration-seconds: 60         # more time to run

features:
  guardians:
    enabled: false             # no guardians

abilities:
  pvp-protection: true

Hardcore server

settings:
  spawn-interval-seconds: 3600
  chest-disappear-minutes: 10
  chest-chances:
    common:    0.10
    rare:      0.30
    legendary: 0.60

features:
  guardians:
    common-count:    5
    rare-count:      10
    legendary-count: 20

legendary-items:
  dragon-slayer-sword:
    bonus-damage: 10.0
    cooldown-ms:  10000

abilities:
  pvp-protection: false

Event server

settings:
  spawn-interval-seconds: 120
  chest-count-per-interval: 5  # 5 chests at once
  chest-disappear-minutes: 5
  chest-chances:
    common:    0.00
    rare:      0.00
    legendary: 1.00

world-apple-drop:
  enabled: true
  spawn-method: near-chest

features:
  bossbar:
    enabled: true

Applying Changes

  1. Edit config.yml
  2. Run /reloadchestconfig
  3. Check console for errors
  4. Test with /chestnow

To reset to defaults: stop the server, delete config.yml, and restart.

Clone this wiki locally