CastelChest

Castel

Castel is a minigame plugin for Minecraft servers (Paper/Spigot). The concept: a castle filled with chests, barrels, and other containers, where players fight in close combat to be the last standing, or to win via another objective depending on the chosen mode. Every opened container can provide an advantage, a trap, or both at once. Gameplay centers around sword combat within a dedicated castle environment (ramparts, corridors, rooms).

The plugin manages multiple independent arenas simultaneously on the same server, each with its own region, containers, and settings. Everything is configured in-game without editing configuration files manually, using commands and graphical user interfaces (GUIs).

No external database is required. All configuration data (arenas, chests, statistics) is saved to a local server file. This means the plugin operates without an external network connection or central database, though data is not shared across different servers.

How a Game Works

Players join an arena and wait in a queue. An administrator launches the game once enough players are present. The world state is saved (a block-by-block snapshot), chests are filled, all players are teleported, a countdown displays, and combat begins. Depending on the mode, victory is achieved by eliminating everyone, holding a zone, or defending/killing a designated target. At the end, the world resets to its exact prior state, even if explosions occurred.

Game Modes

Only one mode is active per arena at a time, directly determining the victory condition. It can be changed via /castel arena mode <lastman|koth|siege>, or through the Settings GUI under the "Game Mode" option.

LASTMAN (Default Mode): The classic format where the last surviving player or team wins. No extra setup is required; it serves as the base layer for all other modifiers.

KOTH (King of the Castle): Rather than eliminating everyone, players win by holding a designated zone longer than their opponents. Every second spent inside the capture zone (the "hill") awards points to the occupying player or team. Points stack if multiple teammates stand inside simultaneously. Combat is primarily used to push opponents out of the zone.

To set up KOTH, select the target area using WorldEdit (//pos1 and //pos2), then run /castel arena sethill. Afterwards, switch the arena mode using /castel arena mode koth.

Key settings include:

• /castel arena kothpoints <n> sets points awarded per second per occupying player (default: 1).
• /castel arena kothlimit <points> sets the score required for an immediate win (default: 100; set to 0 to disable).
• /castel arena kothtime <seconds> sets the maximum match length; the highest score wins if time expires (default: 300 seconds).

Important: Even in KOTH mode, if only one player or team remains alive, elimination overrides the score or timer for an instant win.

SIEGE (Attack/Defense): Activating SIEGE forces play into two teams (Red and Blue). Two variants exist, toggled via /castel arena siegemode <single|dual>:

The "Single Lord" variant (default) is asymmetrical: Red defends, Blue attacks. At match start, a random Red player becomes the Lord, gaining extra health (+4 hearts) and a permanent glowing outline visible from a distance. Blue has no Lord; their sole objective is to kill the Red Lord. Blue wins immediately upon the Lord's death. Red wins by eliminating all attackers or by keeping their Lord alive until the timer expires.

Team sizes are adjusted independently via /castel arena siegedefenders <n> (default: 2) and /castel arena siegeattackers <n> (default: 4).

The "Dual Lord" variant is symmetrical: each team protects its own Lord with identical buffs. The first team whose Lord dies loses. If time runs out with both Lords alive, the match ends in a draw. This variant relies on standard team size settings rather than separate attacker/defender values.

Shared settings: /castel arena siegetime <seconds> sets the maximum duration (default: 600 seconds). Team-specific spawns should be configured with /castel arena setspawn <team> (using RED or BLUE), typically placing defenders inside the castle and attackers outside.

Arena Setup

Administrators work on one arena at a time, designated as the "active arena":

• /castel arena create <name> creates a new arena and selects it.
• /castel arena select <name> switches the active arena.
• /castel arena list displays all arenas with summary stats (chests, region, spawns, player limits, match status).
• /castel arena delete <name> permanently deletes an arena.
• /castel arena finish exits editing mode.
• /castel arena info displays all settings for the active arena.
• /castel arena stats displays cumulative arena statistics.

To define the playable boundaries: create a WorldEdit selection with //pos1 and //pos2 covering the entire area including walls (ensure both points have different heights), then run /castel setregion.

Chests and Loot

Once a region is set, /castel scan automatically detects all chests, trapped chests, barrels, copper chests, and ender chests within the area. Re-scanning a smaller room does not erase chests configured elsewhere. Double chests are tracked as single units with shared storage. Copper chests are automatically waxed to prevent further oxidation. A floating numerical tag appears over each tracked container during editing.

Running /castel gui opens the container management menu to configure individual chests:

• Container type cycling (Barrel, Chest, Trapped Chest, Copper Chest, Ender Chest).
• Custom loot tables via a drag-and-drop editor matching container dimensions (27 slots for singles, 54 for doubles).
• Optional opening bonuses and penalties.
• A "vanish after trigger" setting that turns the chest into air once activated.
• An option to remove the chest from tracking.

Chests also feature a power tier setting: Low, Medium (default), or High. This scales effect duration (0.6x for Low, 1.0x for Medium, 1.5x for High) and adjusts potion effect amplifier levels where applicable.

/castel fill populates all tracked containers with their exact configured loadout. /castel empty clears all tracked containers at once.

To edit individual containers without a full scan: /castel addchest [type] tracks the targeted container (up to 6 blocks away), and /castel removechest stops tracking it.

Random Loot Shuffle: Found in the Settings menu. When enabled, each /castel fill randomly swaps predefined loot tables among containers of the same type. Disabled by default.

Ender Chests: Vanilla ender chests present individual player inventories. Castel intercepts right-clicks on tracked ender chests to open a shared 27-slot virtual container handled in server memory. Its inventory does not persist across server restarts.

In-Game Auto-Refill: Configured via /castel arena refill on|off and /castel arena refilldelay <seconds> (default: 45 seconds). Completely emptied containers automatically restock their loot after the set delay, notifying remaining players in chat.

Opening Effects: Buffs and Traps

Each container can hold a buff, a trap, or both, configured in the chest editor. Effects trigger once per match on opening and reset whenever the arena is filled or refilled.

Buffs:

• SPEED: Grants a Speed effect.
• STRENGTH: Grants a Strength effect.
• REGENERATION: Grants a Regeneration effect.
• INVISIBILITY: Grants temporary invisibility.
• STEAL: Grants the Thief's Glove (right-click near an opponent to empty their inventory within a set radius; fails on teammates).
• HEARTS: Grants extra Absorption hearts.
• RESURRECTION: Grants a one-time death prevention buff similar to a Totem of Undying.
• FURY: Combines Haste and Resistance for immediate offensive/defensive power.
• CRITICAL: Guarantees a critical strike (+50% damage) on the next hit.
• KNOCKBACK_BOOST: Increases knockback on subsequent hits.
• SECOND_WIND: Instantly restores missing health.
• DASH: Lunges the player forward.
• FEATHER_FALL: Grants temporary slow falling.
• ENDER_PEARL: Gives one or two ender pearls.
• SHIELD_CHARGE: Grants an instant-use shield with no cooldown.
• NIGHT_VISION: Grants temporary night vision.
• SATURATION: Fully restores hunger.
• DECOY: Spawns an armor-stand decoy to distract pursuers.
• BERSERK: Grants Strength and Speed, but increases incoming damage by 25%.
• VAMPIRIC: Restores health equal to half the damage dealt on the next 1 to 3 attacks.

Traps:

• EXPLOSION: Triggers a localized explosion that deals damage without breaking blocks.
• EXPLOSION_TOTALE: Triggers an explosion that destroys surrounding blocks (rebuilt on reset).
• POISON: Inflicts Poison.
• DARKNESS: Applies the Darkness effect.
• WEAKNESS: Inflicts Weakness.
• MARKER: Reveals player coordinates/glow to remaining opponents for a set duration.
• CONFUSION: Applies Nausea.
• FEU: Sets the player on fire for several seconds.
• SWAP: Teleports the player to a random arena spawn point.
• FRAGILE: Combines Weakness and Bad Luck.
• DISARM: Forces the player to drop their held weapon.
• BLEED: Deals repeated damage ticks over time without a potion status icon.
• ROOT: Roots the player with extreme slowness.
• LAUNCH: Launches the player into the air (negates fall damage).
• MAGNET: Pulls nearby players toward the container.
• BLINDNESS: Applies full Blindness.
• DEAF_SOUND: Plays a loud, disorienting sound without status effects.
• FAKE_ITEM: Replaces a hotbar item with an unusable decoy item for a few seconds.
• CURSE_LOOT: Drops a portion of the player's inventory onto the ground.

Unimplemented: SILENCE_ALERT (removes player footstep audio and particles).

Effect Settings:

• Steal radius (STEAL): /castel arena stealradius <blocks>.
• Marker duration (MARKER): /castel arena markerseconds <seconds>.
• Absorption hearts (HEARTS): /castel arena heartsamount <n>.

Teams

Configured via GUI or commands. Players are assigned colors across up to 10 distinct teams. Team colors display above player names and in the tab list. Friendly fire is permanently blocked.

• /castel join <arena> [team]: Join an arena or request a specific team.
• /castel arena teams on|off: Toggle team mechanics.
• /castel arena teamcount <n>: Set team count (2 to 10).
• /castel arena teamsize <n>: Set players per team.
• /castel arena teamprefix on|off: Adds team name prefixes to usernames (off by default).

Arena capacity limits update automatically when team sizes or counts are modified.

Starting Classes

Enabled by an admin via /castel arena classes on. When enabled, players in the queue choose an archetype using /castel class <chevalier|eclaireur|pillard>:

• Chevalier (Knight): 12 hearts instead of 10, but receives a Slowness debuff.
• Eclaireur (Scout): Receives a Speed buff, but starts with only 7 hearts.
• Pillard (Raider): Starts with a stone sword and bonus food in inventory.

Treasure Mode (Crown Capture)

Toggled with /castel arena treasure on and timed using /castel arena treasuredelay <seconds> (default: 90 seconds). Once the delay passes, a tracked chest is randomly chosen to hold the Crown.

The first player to open the container receives the Crown directly into their inventory. While holding it, the carrier gains permanent Strength and Regeneration, but is highlighted with a glowing outline visible through walls. If killed, the Crown drops on the ground and can be picked up by others.

Optional Wither Boss

Configured through the Wither menu or commands. Three activation triggers are available: "Time" (fixed delay), "Survivors" (player count threshold), or "Start" (spawns immediately with PvP disabled; killing the boss immediately enables PvP).

• Spawn point: /castel arena setwitherspawn (uses admin's current position).
• Warning timer: /castel arena witherwarn <seconds> (action bar countdown, default: 10 seconds).
• Bonus drop: /castel arena witherdrop on|off guarantees an unbreakable Netherite sword (Sharpness V, Fire Aspect II, Unbreaking III).
• Cleanup: The Wither despawns if the match concludes before it is killed, and it is automatically pushed inward if a shrinking border passes it.

Shrinking Border

Uses a virtual per-player world border via Paper's API, centered on the arena region. Damage is applied directly by the plugin (default: 2 damage per second outside the zone).

• /castel arena shrink on|off: Toggle border mechanic.
• /castel arena shrinkdamage <points>: Set out-of-bounds damage per second (0 to disable).
• /castel arena shrinkdelay <seconds>: Wait time before border contraction begins (default: 60 seconds).
• /castel arena shrinkduration <seconds>: Contraction duration (default: 60 seconds).
• /castel arena shrinksize <blocks>: Final border diameter (default: 10 blocks).
• /castel arena shrinkwarning <seconds>: Title alert warning length (default: 15 seconds).
• /castel arena shrinkdoors on|off: Replaces outer doors, trapdoors, and gates with iron bars when fully closed (restored at match end).

Custom Matches

Allows temporary parameter overrides for the next match without editing persistent arena configurations:

• /castel customgame opens a setup GUI with options to modify settings, reset values, or start immediately.
• /castel customgame set <setting> <value> overrides a specific property via command.
• /castel customgame reset clears staged modifications.

Once the match concludes (or is aborted with /castel stop), the arena's standard configuration is restored automatically.

Match Logs and Arena Statistics

At the end of every round, the chat displays a chronological kill feed and identifies the single most lethal container of that match.

Running /castel arena stats displays lifetime arena data: total matches completed, average player survival time, and the historically most fatal chest.

World Backup and Restoration

Every block is recorded at /castel start. When the match finishes, the region resets: broken blocks are restored, loose ground items are cleared, and tracked chests are instantly repopulated to prepare for the next round.

General Game Logic

Players outside an active game (queueing, spectating, or editing) cannot take damage. Dying turns a player into a spectator. Disconnecting or running /castel leave counts as a forfeit.

Core commands:

• /castel join <arena> [team]: Join the queue.
• /castel leave: Leave queue or forfeit an ongoing match.
• /castel arena setspawn [team]: Set a global or team-specific spawn point.
• /castel arena clearspawns: Clear all arena spawns.
• /castel arena minplayers <n> and /castel arena maxplayers <n>: Adjust capacity.
• /castel start: Validates setup, snapshots the world, fills chests, teleports players, and starts the match.
• /castel stop: Forces match termination, restores players to survival mode, and resets the arena.
• /castel setlobby: Sets the server-wide return point for finished matches or departures.

In-Game UI

• Health displays below player names.
• Team names and colors show above player heads and in the player list.
• A boss bar tracks remaining survivors, configurable with /castel arena bossbar on|off, /castel arena bossbarafter <seconds>, and /castel arena bossbarplayers <n>.
• A minimal sidebar displays the arena name and survivor count.
• Titles announce match start, victory/defeat, PvP activation, and border alerts.

Dependencies

• WorldEdit: Required for region definitions.
• ProtocolLib: Optional; eliminates visual block-breaking animations on protected blocks.