stijn/HungerGames
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
HungerGames/TODO.md

8.4 KiB
Raw Blame History

🎮 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

  • 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 started
  • ALIVE — actively in the round
  • DEAD — eliminated, waiting in the safe room
  • DISCONNECTED — left the server mid-round
  • SPECTATING — admin/non-participant 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 /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)