# 🎮 HungerGames Plugin — Development Checklist A Minecraft survival/PvP plugin with configurable loot, shrinking world border, stats tracking, and structured round management. --- ## 🗂️ Table of Contents - [Core Round Flow](#-core-round-flow) - [Player Spawning](#-player-spawning) - [Chest System](#-chest-system) - [World Border](#-world-border) - [Combat & Gameplay](#-combat--gameplay) - [End Game](#-end-game) - [Commands](#-commands) - [Stats System](#-stats-system) - [Configuration](#-configuration) - [Player Registration](#-player-registration--session-management) --- ## 🔄 Core Round Flow - [ ] Implement round state machine (`LOBBY` → `COUNTDOWN` → `ACTIVE` → `ENDGAME` → `FINISHED`) - [ ] Configurable countdown duration (default: 10 seconds) - [ ] Broadcast countdown in chat each second - [ ] Freeze all players during countdown (prevent movement/interaction) - [ ] Unfreeze players and start round on countdown end - [ ] Announce round start in chat - [ ] Track round number and persist across restarts --- ## 🧍 Player Spawning - [ ] Spawn players in a configurable radius around a center point - [ ] Ensure each player spawns on top of a solid block - [ ] Freeze players in place until round starts (prevent movement, block breaking, PvP) - [ ] Teleport dead players to a designated "spectator room" (configurable location) - [ ] Prevent dead/spectating players from interacting with the game world --- ## 📦 Chest System - [ ] Define two chest tiers: **Center** and **Normal** - [ ] Each tier has its own loot table configuration - [ ] Items grouped by **rarity** (e.g. common, uncommon, rare, legendary) - [ ] Configurable number of items per rarity group in each chest tier - [ ] Configurable max stack size / quantity per item type - [ ] Randomly select items from rarity groups when populating chests - [ ] Chests can only be **opened once per game** (track opened chests per round) - [ ] Chests automatically refill/reset between rounds - [ ] Better loot scaling in later game stages (e.g. after border shrink events, or after X players remain) - [ ] Optionally mark opened chests visually (particle effect, different block state, etc.) --- ## 🌐 World Border - [ ] Set initial world border size at round start (configurable) - [ ] Configure a schedule of shrink events (size → duration pairs) - [ ] Announce each upcoming shrink in chat: `"Border shrinking to {size} over {duration}s"` - [ ] Show shrink progress on a **boss bar** (label + progress percentage) - [ ] Remove/reset boss bar when shrink completes - [ ] Final stage: when 4 players remain, teleport them to a **preset arena position** - [ ] Lock border to a small configured size during final 4 stage so players cannot escape --- ## ⚔️ Combat & Gameplay - [ ] Disable hunger loss and saturation drain during rounds - [ ] Grant **Speed II** to all players at round start (configurable duration, default: 60s) - [ ] Track damage dealt per player per round - [ ] Broadcast **death messages** in chat: `"{killer} killed {victim}"` - [ ] Handle non-PvP deaths gracefully in death messages (fall, void, etc.) - [ ] Award kill credit correctly for kills via fire, poison, knockback, etc. --- ## 🏁 End Game - [ ] Detect when only 1 player remains alive - [ ] Broadcast winner message in chat: `"{player} wins the round!"` - [ ] Persist winner data (store per-round winner in stats) - [ ] Show **locator bar** (action bar or boss bar) for all remaining alive players during endgame stages - [ ] Locator bar only displays players still in the game (not spectators) - [ ] End-game locator updates in real time as players die --- ## 👥 Player Registration & Session Management ### Registration - [ ] Expose a command (e.g. `/hg join `) callable by other plugins/console to register a player into the upcoming round - [ ] Maintain a registered player list per round (separate from online players) - [ ] Reject registration if round is already ACTIVE or past COUNTDOWN - [ ] Confirm registration with a chat message to the player: `"You have been entered into the round!"` - [ ] Allow `/hg leave ` to remove a player before the round starts - [ ] Allow `/hg kick ` (admin) to force-remove a player mid-round (counts as death/DNF, no kill credit) ### Player States Track each registered player in one of these states: - [ ] `REGISTERED` — signed up or in game (depending on round state) - [ ] `DISCONNECTED` — left the server mid-round - [ ] `SPECTATING` — non-participant/dead observer ### Disconnect Handling - [ ] On disconnect during COUNTDOWN: remove from round, free their spawn slot - [ ] On disconnect during ACTIVE round: treat as death (no kill credit), teleport handling skipped since they're offline - [ ] Store disconnect state so if they reconnect before round ends, they are placed in the safe room (not back into the game) - [ ] On reconnect mid-round: teleport to safe room, restore DEAD state, notify them the round is ongoing - [ ] On reconnect after round ends: restore their normal state ### Join Game Handling - [ ] On registration: set player gamemode survival - [ ] Teleport player to a configurable lobby/waiting area within the event world on registration - [ ] Assign spawn points randomly from the available pool at countdown start — no two players share a point - [ ] Teleport all REGISTERED players to their assigned spawn points when countdown begins - [ ] Notify player they joined the game ### Safe Room - [ ] Command to re-teleport all players not in the game to the safe room - [ ] Configurable safe room location (world, x, y, z, yaw, pitch) in config - [ ] Teleport eliminated players to safe room immediately on death - [ ] Teleport disconnected players to safe room on reconnect (if round still active) - [ ] Players in safe room: no PvP, no hunger, no fall damage - [ ] Optionally show a live scoreboard or action bar in the safe room (remaining players, kills leaderboard) - [ ] Teleport all players out of safe room to a configurable post-round location when round ends ### Round Cleanup - [ ] On round end: clear all player states - [ ] Restore player inventory, gamemode, health, hunger, potion effects to pre-round state (or a clean default) - [ ] Clear any active boss bars, action bars, speed effects from all participants - [ ] Reset registered player list ready for next round --- ## 🧭 Commands ### `/hg stuck` - [x] Teleport player to the nearest safe grass block - [x] Require minimum height threshold to prevent abuse (configurable) - [x] Launch fireworks at the destination on use - [x] Configure firework count/type - [x] Optional cooldown to prevent spam ### `/hg stats [player]` - [ ] Show overall stats for the specified player (or self if no argument) - [ ] Stats viewable by anyone for anyone ### `/hg round start` / `/hg round stop` / `/hg reload` - [ ] Admin commands to manually control round state - [ ] Reload config without restart --- ## 📊 Stats System ### Per-Round Stats (stored each round) - [ ] Kills - [ ] Deaths - [ ] Damage dealt - [ ] Damage taken - [ ] Placement (survival order) - [ ] Whether the player won ### Overall / Lifetime Stats (aggregated) - [ ] Total kills - [ ] Total deaths - [ ] Total damage dealt - [ ] Total damage taken - [ ] Total wins - [ ] Total rounds played - [ ] K/D ratio (computed) ### Storage - [ ] Stats persist across server restarts (flat-file per round) - [ ] Per-round history accessible --- ## ⚙️ Configuration All values in `config.yml` unless noted. - [ ] `countdown-duration` (seconds, default: 10) - [ ] `speed-boost-duration` (seconds, default: 60) - [ ] `spawn-radius` (blocks from center) - [ ] `spectator-room-location` (world, x, y, z, yaw, pitch) - [ ] `stuck-min-height` (minimum Y for `/stuck` teleport) - [ ] `stuck-firework-count` - [ ] `world-border.initial-size` - [ ] `world-border.shrink-schedule` (list of `{size, duration}` entries) - [ ] `world-border.final-four-location` (teleport coords for top 4) - [ ] `world-border.final-four-border-size` - [ ] `chests.center.items-per-rarity` (map of rarity → count) - [ ] `chests.normal.items-per-rarity` - [ ] `chests.loot-tables` (grouped by rarity, list of item entries with optional quantity ranges) - [ ] `chests.late-game-loot-bonus` (threshold player count → loot tier multiplier) - [ ] `stats.storage-type` (`yaml` / `sqlite`) - [ ] `stats.round-history-limit` - [ ] `messages.*` (all chat messages customizable) ---