8.3 KiB
8.3 KiB
🎮 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
- Player Registration
🔄 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 <player>) 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 <player>to remove a player before the round starts - Allow
/hg kick <player>(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, round not yet startedIN_GAME— actively in the roundDISCONNECTED— left the server mid-roundSPECTATING— 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
- 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/stuckteleport)stuck-firework-countworld-border.initial-sizeworld-border.shrink-schedule(list of{size, duration}entries)world-border.final-four-location(teleport coords for top 4)world-border.final-four-border-sizechests.center.items-per-rarity(map of rarity → count)chests.normal.items-per-raritychests.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-limitmessages.*(all chat messages customizable)