Added todo file (roadmap)

TODO.md

@@ -0,0 +1,157 @@
+# 🎮 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)
+
+---
+
+## 🔄 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
+
+---
+
+## 🧭 Commands
+
+### `/hg stuck`
+- [ ] Teleport player to the nearest safe grass block
+- [ ] Require minimum height threshold to prevent abuse (configurable)
+- [ ] Launch fireworks at the destination on use
+- [ ] Configure firework count/type
+- [ ] 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)
+
+---