SpawnChestPlugin

Automatic treasure chest events with custom loot, legendary items, guardians, and a full visual loot editor.

GitHub | Discord | Wiki

---

Features

• Automatic chest spawns with configurable timer and batch spawning
• Visual loot editor — drag and drop items directly in a GUI
• Three chest tiers with different loot and guardian counts
• Nine legendary items with unique abilities (optional)
• Pre-open countdown timer — first click starts a race to the chest
• Chest protection zone — blocks cannot be broken near an active chest
• Four summoner apple types — force a specific tier on demand
• World apple drops — physical item that spawns in the world with coordinates
• Protection plugin integration — chests skip claimed territories automatically
• Permission-based broadcasts — fine control over who sees what
• BossBar HUD — countdown and active chest timer
• Statistics, achievements, and leaderboards
• 10 language translations

---

---

Compatibility

| Platform | Support |
|---|---|
| Spigot | Full support |
| Paper | Full support + async chunk loading |
| Purpur | Full support |
| Pufferfish | Full support |
| Folia | Full support |

Minecraft 1.18 – 1.21.x and 26.1 / 26.1.1 (Mojang's new versioning). Server type and version are detected automatically at startup.

---

---

Chest Tiers

| Tier | Chance | Guardians | Guardian Type |
|---|---|---|---|
| Common | 50% | 1 | Zombie |
| Rare | 35% | 2 | Skeleton |
| Legendary | 15% | 3 | Wither Skeleton |

All chances are configurable. Guardians can be disabled entirely.

---

Spawn System

• Distance from 0,0: 400–2000 blocks (configurable)
• Height range: Y 50–200 (configurable)
• Surface exclusions: block chests from spawning on water, lava, ice, leaves, and more
• Auto-despawn after 30 minutes if unopened (configurable)
• Batch spawning — spawn multiple chests per interval with a delay between each

settings:
  chest-count-per-interval: 3   # spawn 3 chests at once
  chest-spawn-delay-seconds: 5  # 5 s between each

---

Pre-Open Timer

Chests start locked after spawning. The first player to right-click starts a configurable countdown visible in chat and BossBar. Only after it ends can anyone open the chest — giving everyone a chance to run for it.

• Countdown messages sent only to players within a configurable radius
• Chest-disappear timer starts fresh after the chest is opened
• Fully optional — disable with pre-open-timer.enabled: false

pre-open-timer:
  enabled: true
  duration-seconds: 30
  notify-radius: 20.0

---

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.

• Uses real WorldGuard regions when WorldGuard is installed
• Falls back to built-in BlockBreakEvent / BlockPlaceEvent blocking otherwise
• Radius is configurable

chest-protection-zone:
  enabled: true
  radius: 5   # 11×11 area around the chest

---

Protection Plugin Integration

Chests never spawn inside claimed or protected areas. Detected automatically at startup — no extra configuration required.

Supported: WorldGuard · GriefPrevention · GriefDefender · Lands

---

---

Custom Loot Editor

Open with /putintothechest. Configure loot visually without touching any YAML.

• Drag and drop items directly into the chest GUI
• Toggle between single (27 slots) and double (54 slots) chest
• Drop rate control: All · 1/2 · 1/3 · 1/4 … 1/10
• Per-tier configuration (Common / Rare / Legendary)
• Two-step reset confirmation — items drop at your feet on reset
• Preserves enchantments, custom names, lore, and NBT data

Drop Rate Examples

| Rate | Items Saved | Items per Spawn |
|---|---|---|
| 1/3 (default) | 30 | 10 random |
| 1/2 | 30 | 15 random |
| All | 30 | All 30 |

---

Summoner Apples

Four distinct apple types, each forcing a specific chest tier or picking one at random. All four can be given via command, obtained through /getlegendaryitems, and configured to drop inside chests independently.

| Command | Result |
|---|---|
| /giveapple random <player> | Random-tier chest |
| /giveapple common <player> | Always Common |
| /giveapple rare <player> | Always Rare |
| /giveapple legendary <player> | Always Legendary |

World Apple Drop

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

world-apple-drop:
  enabled: false
  spawn-method: near-chest   # near-chest | near-player | with-chest
  radius: 15

---

BossBar

Optional HUD showing next chest countdown or active chest information. Switches between three states automatically:

• Yellow — countdown to next spawn (shows during last N minutes)
• Pink — pre-open countdown (first player activated the chest)
• Green — active chest: tier, coordinates, time until despawn
• Grey — chest was opened, showing despawn timer

features:
  bossbar:
    enabled: false   # opt-in
    countdown-show-minutes-before: 5

---

Permission-Based Broadcasts

All announcements check individual permission nodes. On servers where all permissions are denied by default, grant the spawnchest.notify.* nodes to the default group.

| Permission | Controls | Default |
|---|---|---|
| spawnchest.notify.spawn | Spawn announcement + title | true |
| spawnchest.notify.coordinates | Coordinates in announcement | true |
| spawnchest.notify.disappear | Disappear announcement | true |
| spawnchest.notify.countdown | Countdown warnings | true |
| spawnchest.notify.bossbar | BossBar visibility | true |

Players without spawnchest.notify.coordinates still receive the spawn message — coordinates are just omitted.

---

Legendary Items

Nine unique items with special abilities. Entirely optional — disable the whole system or individual items in config.

| Item | Ability | Cooldown |
|---|---|---|
| Dragon Slayer | +4 damage, ignites targets | 3s |
| Master Pickaxe | Auto-smelt, 50% double drops | 1s |
| Titan Axe | Tree felling, +3 combat damage | 4–6s |
| Void Shovel | 3×3 area excavation, auto-collect | 5s |
| Storm Hammer | +5 damage, lightning, AoE shockwave | 8s |
| Guardian Bow | Double shot, homing arrows | 2s |
| Book of Ancient Wisdom | Enchant all gear in inventory | One use |
| Phoenix Feather | Auto-resurrect, passive fire immunity | 5 min |
| Poseidon's Trident | Lightning on hit, rain aura | 10s |

All items include Mending and max-level enchantments. All cooldowns, damage values, and behaviours are configurable.

---

Custom Potions

Entirely optional — disable the whole system or individual items in config.

| Potion | Effect | Duration | Tier |
|---|---|---|---|
| Strength III | +6 Attack | 2 min | Rare, Legendary |
| Haste II | Mining Speed | 3 min | Rare, Legendary |
| Luck II | Loot Boost | 5 min | Legendary |
| Dolphin's Grace | Swim Speed | 3 min | Rare, Legendary |
| Turtle Master Extended | Resistance III + Slowness IV | 1 min | Legendary |
| Wither Resistance | Regen II + Resistance II | 30–60s | Legendary |

---

---

Statistics & Achievements

Tracked Stats

• Chests opened (total and per tier)
• Legendary items found
• Guardians killed
• Summoner Apples used

Achievements

| Achievement | Requirement | XP |
|---|---|---|
| First Find | Open 1 chest | 50 |
| Treasure Hunter | Open 10 chests | 200 |
| Chest Master | Open 50 chests | 500 |
| Legendary Finder | Find a legendary item | 300 |
| Guardian Slayer | Kill 25 guardians | 400 |

---

Commands

Player Commands

| Command | Aliases | Description |
|---|---|---|
| /nextchest | /nc | Time until next spawn |
| /mystats | /stats | View your statistics |
| /leaderboard | /lb, /top | Server leaderboard |
| /cooldowns | /cd | Legendary item cooldowns |

Admin Commands

| Command | Description |
|---|---|
| /chestnow | Spawn a chest immediately (respects batch count) |
| /setchesttimer <seconds> | Change spawn interval |
| /resettimer | Reset timer — chest spawns in 10 seconds |
| /reloadchestconfig | Reload config and language files |
| /giveapple <random\|common\|rare\|legendary> <player> [amount] | Give a Summoner Apple |
| /getlegendaryitems | Receive all legendary items |
| /togglelegendary [item] | Toggle legendary items on/off |
| /togglefeature <feature> | Toggle features on/off |
| /chestconfig get/set/toggle/reload/list | Modify config live |
| /putintothechest | Open custom loot editor |
| /cheststats | View current plugin status |
| /testchestzone | Preview 5 random spawn coordinates |

---

Permissions

| Permission | Description | Default |
|---|---|---|
| spawnchest.use | Player commands | Everyone |
| spawnchest.legendary | Receive legendary items | Everyone |
| spawnchest.apple | Use Summoner Apple | Everyone |
| spawnchest.admin | All admin commands | OP |
| spawnchest.config | /chestconfig, /togglelegendary, /togglefeature | OP |
| spawnchest.bypass | Bypass item cooldowns | OP |
| spawnchest.notify.* | Announcement visibility nodes | Everyone |

---

Localization

10 languages included. Edit files in plugins/SpawnChestPlugin/lang/

| Code | Language |
|---|---|
| en | English |
| ru | Русский |
| ua | Українська |
| es | Español |
| de | Deutsch |
| fr | Français |
| zh | 中文 |
| pt | Português |
| pl | Polski |
| it | Italiano |

---

Installation

1. Download the latest JAR
2. Place it in your plugins/ folder
3. Start or restart the server
4. Edit plugins/SpawnChestPlugin/config.yml if needed
5. Run /reloadchestconfig to apply changes
6. Configure custom loot with /putintothechest

---

Links

• Wiki: Full Documentation
• Issues: Report Bugs
• Discord: Get Support