HungerGames/TODO.md

🎮 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
• Player Spawning
• Chest System
• World Border
• Combat & Gameplay
• End Game
• Commands
• Stats System
• 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)

---