EpicDuels

[3.0.0] — 2026-07 · Gameplay Update

Added

- Kit Editor — every player can personalize the item layout of any kit for themselves: /duel kits [kit] or the new "Kit Editor" entry in the main menu opens a customize GUI (inventory, armor and offhand slots) where the kit's items can be rearranged, saved and reset. Layouts are pure rearrangements (nothing can be added, removed or modified), are stored per player in playerkits.yml, and are applied automatically in 1v1 duels, matchmaking, team duels and tournaments. If an admin edits the base kit, outdated personal layouts fall back to the default. New feature toggle features.kit-editor; new manager class PlayerKitManager. - Spectate GUI — /duel spectate without arguments (and a new Ender-Eye entry in the main menu) opens a paginated browser of all running 1v1 duels showing both players, kit, map, round and duration. One click starts spectating; the duel is re-validated on click in case it ended while browsing. Team duels are not listed yet (no outside-spectator mechanism there). - Localization — every player-facing message (~290 keys: chat, action bars, titles, clickable buttons) now lives in lang/messages_en.yml / lang/messages_de.yml (MiniMessage format), selected via the new language config key and reloadable with /duel reload. Missing keys fall back to the built-in English texts; player names are inserted tag-escaped (no MiniMessage injection). New class dev.epicduels.i18n.Messages. - PlaceholderAPI support (optional softdepend) — %epicduels_wins%, %epicduels_losses%, %epicduels_winrate%, %epicduels_score% and %epicduels_in_duel% via a new expansion that only registers when PlaceholderAPI is installed. - Match time limit & draws — configurable clock (duel.time-limit-seconds, default 300 s, 0 = off) with action-bar countdown. Time-up ends 1v1 and team duels in a draw (no win/loss recorded). Tournament matches resolve via a one-time sudden-death extension and/or coin flip (duel.tournament-draw, duel.sudden-death-seconds). - Best of 1 / 3 / 5 — new rounds-selection step in the challenge flow (player → kit → rounds → map). Rounds reuse the same arena instance: player-placed blocks are reset, players healed, re-kitted and counted down again. Score shown as titles and "Round N — X:Y" messages. The match clock pauses between rounds; a timeout with a round lead ends the match in the leader's favor. - Rematch — clickable [REMATCH] message for both players after every regular duel (30 s validity). Both accept (click or /duel rematch) → new duel with the same kit, arena and round mode. - `/duel forfeit` (aliases ff, leave) — give up the current 1v1 or team duel with a clickable 10-second confirmation. Counts as a loss. - Own Inventory (no-kit) duels — "Own Inventory" option in the kit selection (duel.allow-own-inventory). Inventories are saved to plugins/EpicDuels/inventories/ at duel start and restored afterwards — crash- and disconnect-safe (leftover backups restore on the next join). - `/duel toggle` — disable/enable incoming duel requests, persisted in toggles.yml. Blocked players are hidden from the challenge menu. - `/duel reload` — reload config.yml at runtime (epicduels.admin). - `lobby.handle-join` — config toggle for the join-time inventory wipe + lobby teleport (disable when EpicDuels runs alongside other gameplay). - Feature toggles — new features: config section: every player-facing feature (challenges, matchmaking, spectating, rematch, forfeit, best-of-N, own-inventory duels, parties, team duels, tournaments, leaderboards) can be disabled individually. Disabled features vanish from the GUIs (barrier icons) and their commands answer with a clear message. Missing entries default to enabled. - `duel.countdown-seconds` — configurable pre-fight countdown length (0–60 s, 0 = instant start). - `duel.broadcast-results` — choose between server-wide duel result announcements and participants-only messages (for survival/hub servers). - New manager classes: RematchManager, InventoryBackupManager, PlayerKitManager. - New data files: toggles.yml, inventories/, playerkits.yml, lang/.

Changed

- GUI internals refactored — plugin menus are now identified by a custom InventoryHolder (MenuHolder with menu type, kit context and page) and clicks are resolved through PersistentDataContainer keys on the button items instead of window-title and display-name parsing. Fixes potential collisions with other plugins' GUIs (or kits named like buttons), stops clicks in the player's own inventory from triggering menu actions, gives the arena list working pagination, and blocks drags onto the admin kit editor's control row. - build.gradle now mirrors the Maven build (PlaceholderAPI repo/dependency, jar version synced to the project version).

Fixed

- Duel-state guards — players already in a duel, team duel or tournament can no longer be pulled into a second match via accept, queue or challenge (central isBusy() check). - Concurrent duel requests — a second incoming challenge no longer silently overwrites the first; requests are tracked per sender and /duel accept|deny <player> disambiguate. - Stats thread safety — the remote stats fetch callback (Supabase/Firebase) now hops back to the main thread before mutating the stats map. - Projectile PvP bypass — lobby PvP protection now also blocks arrows, snowballs and other projectiles. - Arena-exit exploit — teleporting out of the arena world (e.g. another plugin's /spawn) now counts as a forfeit instead of leaving the duel running forever. - Stale template copies — the template world is saved before being copied into a duel instance. - Respawn flow — dead team-duel players respawn inside the arena as spectators; admins in template worlds keep their default respawn. - GUI state (challenge/party flow, random-map animation) is cleaned up when a plugin menu is closed. - Kit edit GUI: unused slots 41–52 are blocked so items placed there are no longer lost on save. - /duel queue <kit> switches queues instead of only leaving. - Kit serialization switched to Paper's version-upgrade-safe ItemStack.serializeItemsAsBytes (legacy kits.yml still loads). - plugin.yml: proper description/usage metadata; new epicduels.spectate permission.

v2.0.0 — Party System, Lobby Hardening & Stability

Date: May 2026 Minecraft: Paper 1.21.1+ Java: 21

Major Feature — Party System

EpicDuels now supports group play through a full party system. Create a party with /party create, invite friends with /party invite <player>, and launch a game with /party start. The party owner selects a kit once at the start; the arena is picked randomly per match. Supports 2–8 players. #### Mode 1 — Team Duel (2v2 / 3v3 / 4v4) - Teams are shuffled randomly at match start. - All teammates spawn at the same arena spawn point with small circular offsets so nobody overlaps. - Friendly fire is disabled — team members cannot damage each other. - Eliminated players automatically spectate the ongoing battle until their team is wiped. - The last team with a surviving member wins. #### Mode 2 — Single-Elimination Tournament - All party members compete in 1v1 bracket matches using the existing duel system. - Byes are inserted automatically for party sizes that are not a power of 2. - Eliminated players are auto-routed to spectate a random live tournament match so nobody is left waiting in the lobby. When their spectated match ends they are re-routed to another live match if one is still running. - The final winner is announced only to party members — no server-wide broadcast. #### Party Commands | Command | Alias | Description | Permission | |---|---|---|---| | /party create | /p create | Create a party | epicduels.party | | /party invite <player> | /p invite <player> | Invite a player | epicduels.party | | /party accept [player] | /p accept | Accept an invite | epicduels.party | | /party deny [player] | /p deny | Deny an invite | epicduels.party | | /party leave | /p leave | Leave your party | epicduels.party | | /party disband | /p disband | Disband (owner only) | epicduels.party | | /party list | /p list | Show members | epicduels.party | | /party start | /p start | Open mode-select GUI (owner only) | epicduels.party | #### New Permission | Permission | Description | Default | |---|---|---| | epicduels.party | Use all party commands | Everyone | #### New Files | File | Purpose | |---|---| | Party.java / PartyInvite.java / PartyMode.java / TeamSize.java | Party model layer | | TeamDuelInstance.java / Tournament.java / BattleInstance.java | Match model layer | | PartyManager.java | Invite, party lifecycle, member management | | TeamDuelManager.java | Team composition, arena spawn offsets, friendly fire, winner detection | | TournamentManager.java | Bracket generation, match scheduling, spectator routing | | FriendlyFireListener.java | Cancels damage between teammates during team duels | | PartyCommand.java / PartyTabCompleter.java | Command handling | ---

Major Change — Adventure Mode in Lobby

All players now join and stay in Adventure mode inside the lobby world. This prevents them from breaking or placing blocks — which is especially important for servers running external plugins like ImageFrame whose maps/images would otherwise be destroyed by any player in Survival/Creative. - Players are set to ADVENTURE on join and on return from a duel. - Spectators are also returned to ADVENTURE when they stop spectating. - Admins with epicduels.admin are unaffected — see "Per-Admin Bypass" below.

Major Feature — Item Frame & Armor Stand Protection

A new PlayerInteractEntityEvent handler prevents non-admin players from interacting with item frames and armor stands in the lobby, closing the last bypass that Adventure mode alone did not cover (right-clicking an item frame still works in Adventure mode without a tool).

Major Feature — Per-Admin Lobby Bypass

Admins can now switch their own lobby protections off temporarily for building without touching the global config or affecting other players. | Command | Description | |---|---| | /duel lobby off | Puts you in Creative mode and suspends all lobby protections for your session | | /duel lobby on | Restores your Adventure mode and re-enables all lobby protections for you | The bypass is per-player — every other player keeps full protections while an admin is in build mode.

Bug Fixes

#### Memory Leaks - BukkitTask references — DuelManager's request-expiration repeating task and QueueManager's matchmaking loop both lacked stored BukkitTask references. On plugin reload, these tasks kept running in the background, slowly eating RAM. Both now store their BukkitTask and cancel it on cleanupAll() / cleanup(). - Leftover instance worlds — Arena instance worlds (arena_instance_*) left behind by a previous crash or hard shutdown were never cleaned up. The plugin now scans for and deletes them on the first server tick after startup. - Ghost queue entries — Players who disconnected while in the matchmaking queue were previously skipped on the action-bar update but kept in the queue maps indefinitely. They are now removed immediately when the next tick detects they are offline. #### Supabase Sync - The plugin now runs a connection test on startup so misconfiguration (wrong URL or key) is caught immediately rather than silently failing on the first win. - PostgREST returns HTTP 204 No Content on a successful upsert; this was previously treated as an error and the push was silently dropped. Now accepted. - HTTP 401 / 403 responses print an actionable hint: `"Check your Row-Level Security policy in the Supabase dashboard"`. - StatsManager.pushAllToRemote() during onDisable now properly awaits all async futures (up to 15 s) so no stats are lost on shutdown.

Performance Improvements — Hologram Efficiency Rewrite

The HologramManager was re-written to eliminate the biggest source of entity churn on leaderboard servers: | Metric | Before | After | |---|---|---| | Update strategy | Delete all ArmorStands, re-spawn | Update text in-place | | Refresh interval | 200 ticks (10 s) | 1 200 ticks (60 s) | | Orphan scan scope | All loaded worlds | Hologram worlds only | | Player name lookups | Bukkit.getOfflinePlayer() per line every tick | Cached per refresh cycle | | Line spacing | 0.28 blocks (causes overlap at small fonts) | 0.30 blocks | The old approach spawned and killed 20 ArmorStand entities every 10 seconds per hologram. On a server with two holograms this meant 240 entity-create/destroy operations per minute — causing noticeable lag spikes. The new approach touches only existing entities' metadata.

Upgrade Notes

- Replace EpicDuels-1.0.0.jar with EpicDuels-2.0.0.jar. All existing config, arenas, kits, stats, and .yml files remain fully compatible. - No config changes are required — new features work out of the box. - The new epicduels.party permission defaults to true (all players). If you want to restrict party creation, add it to your permissions plugin. - Admins who had custom lobby protections toggled off in config.yml should review whether the per-player bypass (/duel lobby off) is a better fit.

v1.0.0 — Full Release: Leaderboards, Holograms & Polish

Date: April 2026 Minecraft: Paper 1.21.1+ Java: 21 This is the first stable release of EpicDuels. It brings a full leaderboard system with in-world holograms, two important stability fixes, and a long list of polished features carried over from the 0.2.x / 0.3.x series.

Major Feature — Leaderboards

EpicDuels now ships with a complete leaderboard system: - `/duel leaderboard wins` — shows the top 10 players by total wins in chat - `/duel leaderboard score` — shows the top 10 players by score in chat - Both read from the same StatsManager that powers the Stats GUI, so local + Supabase/Firebase-synced data is handled transparently. - Aliases: /duel lb, /duel top #### Score Formula The score rewards both activity and consistency:

score = wins × winrate = wins² / (wins + losses)

Example: a player with 21 wins / 9 losses → winrate 70%, score ≈ 14.7 ≈ 15. Pure grinders with a low winrate score lower than players with fewer but more decisive wins.

Major Feature — Leaderboard Holograms

Admins can place persistent in-world leaderboard holograms without installing any external plugin: - /duel leaderboard sethologram wins — places the Wins hologram at your head - /duel leaderboard sethologram score — places the Score hologram at your head - /duel leaderboard removehologram <wins|score> — deletes a hologram Under the hood: - Each hologram is a stack of invisible, marker, small ArmorStands tagged via the Persistent Data Container so the plugin can clean them up even after a crash or reload. - Positions are persisted in leaderboards.yml. - Holograms automatically refresh every 10 seconds from the StatsManager, so data stays fresh whether you're running local or remote stats. - Top 3 ranks are gold/gray/red, lines 4–10 are white. Each line shows #rank name — value.

Bug Fixes

- Duel accept no longer keeps you in the queue — When a player accepted a duel request while sitting in matchmaking, they stayed queued and could get matched into a second duel. startDuel() now proactively removes both players from the queue, cancels any pending outgoing/incoming challenge requests, and starts from a clean slate. Works for both challenge-based and queue-based duels. - Instant respawn in duels — The death screen's "Respawn" button is sometimes unresponsive on modded clients or when the server is briefly busy, which left players stuck in the void. PlayerDeathEvent for duel participants now schedules player.spigot().respawn() on the next tick, so the losing player is immediately teleported back to the lobby.

Carried Forward from 0.3.x / 0.2.x

All of the features from the 0.2.x and 0.3.x line are part of v1.0.0: - Multi-server stats — Supabase / Firebase REST-based sync, local YAML cache as fallback (0.3.0). - Direct menu commands — /duel duels, /duel matchmaking, /duel stats each open their sub-menu directly. - Kit & Arena rename — /duel kit rename <old> <new> and /duel arena rename <old> <new> (also renames the template world on disk). - /duel kit give — admin command to copy a saved kit into the admin's inventory for testing. - Lobby-only protections — 15 toggleable rules under lobby.protections.* (block break/place/interact, fall damage, void death, weather, item pickup/drop, hunger, mob spawning, fire spread, block burning, leaf decay, death messages, inventory movement). - Spectator mode — /duel spectate <player>. - Pagination — 28 items per page across all list GUIs. - GUI redesign — 27-slot main menu with Duels / Stats / Matchmaking sub-menus. - Queue / Matchmaking — Auto-match on same kit with action-bar time. - Random map animation — Slot-machine animation on random arena pick. - Async world copy — Every duel runs in its own disposable world. - Block protection — Per-duel original-block tracking.

Commands Added in v1.0.0

| Command | Alias | Description | Permission | |---|---|---|---| | /duel leaderboard wins | /d lb wins | Top 10 by wins | epicduels.stats | | /duel leaderboard score | /d lb score | Top 10 by score | epicduels.stats | | /duel leaderboard sethologram <wins\|score> | | Create/move hologram at your location | epicduels.admin | | /duel leaderboard removehologram <wins\|score> | | Remove a leaderboard hologram | epicduels.admin |

Data Files Added

| File | Contents | |---|---| | leaderboards.yml | Persistent hologram positions (per type) |

Upgrade Notes

- Simply replace EpicDuels-0.3.0.jar with EpicDuels-1.0.0.jar. All existing config, arenas, kits, stats and .yml files remain compatible. - Holograms are not created automatically — an admin must run /duel leaderboard sethologram wins and /duel leaderboard sethologram score once.

v0.3.0 — Multi-Server Stats (Supabase & Firebase)

Date: April 2026 Minecraft: Paper 1.21.1+ Java: 21

Major Feature: Remote Stats Backends

EpicDuels can now sync player statistics across multiple servers using Supabase (PostgreSQL) or Firebase Realtime Database. Configure the backend in config.yml:

stats:
  backend: "supabase"   # or "firebase" or "local" (default)

#### Supabase Setup 1. Create a player_stats table in your Supabase SQL editor:

   CREATE TABLE IF NOT EXISTS player_stats (
     uuid   TEXT PRIMARY KEY,
     wins   INTEGER NOT NULL DEFAULT 0,
     losses INTEGER NOT NULL DEFAULT 0
   );
   

2. Fill in config.yml:

   stats:
     backend: "supabase"
     supabase:
       url: "https://your-project.supabase.co"
       api-key: "your-anon-key"
       table: "player_stats"
   

#### Firebase Setup 1. Create a Firebase project and enable Realtime Database. 2. Fill in config.yml:

   stats:
     backend: "firebase"
     firebase:
       database-url: "https://your-project-default-rtdb.firebaseio.com"
       auth-token: ""   # optional database secret
   

How It Works

- Local cache is always active — stats.yml remains the primary cache. The plugin works normally even when the remote is unreachable. - Async sync — All remote reads/writes happen asynchronously and never block the main server thread. - Merge on fetch — When a player's stats are loaded from remote, the higher value for wins and losses is kept (local vs. remote), so no data is lost if two servers wrote different values. - Push on change — Every win/loss is pushed to the remote immediately after updating the local cache. - Push on shutdown — All cached stats are pushed to the remote during onDisable to ensure nothing is lost.

Architecture

StatsProvider (interface)
├── SupabaseProvider  — PostgREST upsert via java.net.http
└── FirebaseProvider  — Realtime Database REST via java.net.http

No external libraries required — uses Java 21's built-in HttpClient.

Other (included from v0.2.3)

- Redesigned 27-slot main menu with Duels / Stats / Matchmaking sub-menus - Pagination for all list GUIs (28 items per page) - Dedicated Stats menu - /duel spectate <player> command - Configurable lobby PvP protection - Duel item cleanup on rejoin

v0.2.1 — Patch Release

Date: April 2026 Minecraft: Paper 1.21.1+ Java: 21

Bug Fixes

- Fixed world generator startup error — Added load: STARTUP to plugin.yml so the plugin is loaded during the server startup phase (before worlds are created). Without this, Paper could not register the VoidWorldGenerator for the default lobby world and printed:

  Could not set generator for default world 'world': Plugin 'EpicDuels v0.2.0' is not enabled yet (is it load:STARTUP?)
  

Changelog

New Features

- Redesigned Main Menu GUI — The /duel menu now has three visual sections: - Left: Challenge a Player — opens player selection, then kit selection, then map selection - Middle: Stats — displays your wins, losses, win rate, and total duels directly in the GUI with your player head - Right: Queue / Matchmaking — join a kit-based queue to auto-match against opponents - Queue / Matchmaking System — New QueueManager enables automatic matchmaking: - Join a queue for any kit from the main menu or via /duel queue <kit> - Action bar shows real-time queue status with elapsed time - When two players queue for the same kit, they are automatically matched and teleported to a random arena - Players are removed from queue on disconnect - Random Map Animation — When selecting "Random Map" in the map selection GUI: - A slot rapidly cycles through all arena icons, gradually slowing down - Ends with the chosen arena and a level-up sound effect - Proceeds to send the challenge after the animation - Arena & Kit Icons — Admins can now set custom display icons: - /duel arena seticon <name> — hold any item, it becomes the arena's icon in GUIs - /duel kit seticon <name> — hold any item, it becomes the kit's icon in GUIs - Icons are persisted in arenas.yml and kits.yml - Default icons: arenas use GRASS_BLOCK, kits use CHEST - Architecture Documentation — Added a comprehensive comment block in the main plugin class explaining how all managers interact

Bug Fixes

- Block Placement & Breaking in Arena Instances — Players can now place AND break blocks during active duels inside instance worlds. However, original arena template blocks (the map itself) cannot be broken. When an instance world is created, all existing block positions are recorded; only player-placed blocks can be broken. - Arena Instance Deletion — Instance worlds are now properly unloaded with Bukkit.unloadWorld(world, false) and recursively deleted from disk using Files.walkFileTree(). Added error handling and warning logs if deletion fails. - Player Disconnect Mid-Duel — When a player disconnects during a duel, the duel ends immediately, the remaining player is declared winner and teleported to lobby, stats are updated, and the instance world is cleaned up.

Changes

- Removed Lobby Spawn Commands — Removed /duel setlobbyspawn1 and /duel setlobbyspawn2. Only /duel setlobby remains. All players teleport to the single lobby spawn on join and after duels. - Challenge Flow Reordered — The challenge flow is now: Select Player -> Select Kit -> Select Map (previously it was Player -> Map -> Kit). This feels more natural. - Improved GUIs — All GUIs now use the correct display icon for arenas and kits instead of hardcoded materials.

Commands Added

| Command | Description | Permission | |---|---|---| | /duel queue <kit> | Join matchmaking queue for a kit | epicduels.duel | | /duel queue leave | Leave the matchmaking queue | epicduels.duel | | /duel arena seticon <name> | Set arena display icon (hold item) | epicduels.admin | | /duel kit seticon <name> | Set kit display icon (hold item) | epicduels.admin |

Commands Removed

| Command | Reason | |---|---| | /duel setlobbyspawn1 | Replaced by single /duel setlobby | | /duel setlobbyspawn2 | Replaced by single /duel setlobby |