🏹 HungerGamesSSS

Hunger Games plugin for Paper 1.21 — arena management, 45 legendary weapons, procedural dungeons, team play, lifesteal, veinminer, SQLite/MySQL persistence, a developer API, and deep per-arena configuration.

Current version: 4.5.7

📋 Table of contents

Requirements
Quick start
Arena system
Match lifecycle
Game modes
Legendary weapons
Crafting legendary items
Dungeons
Cornucopia builder
Feast event
Teams
Scoreboard
Holograms
Loot tables
Structure system
Persistence — SQLite / MySQL
Localisation
Performance tools
Commands reference
Permissions reference
Configuration reference
Developer API
Credits

⚙️ Requirements

Dependency	Type	Version
📄 Paper	Required	1.21+
☕ Java	Required	21+
📊 PlaceholderAPI	Optional	Any
💰 Vault	Optional	Any
🔧 ProtocolLib	Optional	Any
🌍 FastAsyncWorldEdit	Optional	Any (enables `.nbt` / `.schem` structure placement)

🚀 Quick start

1. Drop HungerGamesSSS-4.5.1.jar into plugins/
2. Start the server — default config files are generated automatically.
3. Stand at the world spawn (or wherever you want the arena centre).
4. /hg create <arenaName>
5. Walk to the Cornucopia centre → /hg setcornucopia <arenaName> classic
6. Walk to each player spawn point → /hg addspawn <arenaName>  (repeat 2–24 times)
7. /hg setlobby  (stand in the lobby you want players to return to after a match)
8. /hg start <arenaName>

The arena is now ready. Players join with /hg join <arenaName>.

🏟️ Arena system

Each arena is a fully self-contained world managed by ArenaManager. Arenas persist across restarts via the database — you never need to re-run setup.

Per-arena toggles (changed live with /hg setuparena <arenaName> <flag>):

Flag	Default	What it does
⚔️ `pvp`	on	Enable / disable PvP damage
❤️ `lifesteal`	off	Players drop heart items on death
💀 `hardcore`	off	Eliminated players cannot spectate
⛏️ `veinminer`	off	Sneak + break to chain-mine ore veins
🔥 `nether`	on	Isolated Nether world per arena
🌌 `theend`	on	Access to The End dimension
🔵 `border <size> <shrinkTime>`	—	Set a shrinking world border
✅ `enable` / ❌ `disable`	—	Toggle the arena in/out of the player pool

Legendary spawn points — admins mark exact block locations where legendary items spawn at match start:

/hg setlegendary <arenaName> <itemId>   — mark your feet position as a spawn
/hg deletelegendary <arenaName>         — remove the nearest spawn (within 5 blocks)

Holograms float above each spawn point showing the item name.

⏱️ Match lifecycle

WAITING → STARTING → PLAYING → DEATHMATCH → ENDED

Phase	Notes
⏳ Waiting	Players join the lobby; minimum player count check runs every second
🔢 Starting	Countdown; players are teleported into glass cages around the Cornucopia
⚔️ Playing	Grace period (no PvP) → main phase → feast event → border shrink
💥 Deathmatch	Final surviving players are moved to a small arena or the border closes entirely
🏆 Ended	Winners announced; arena reset; players returned to the lobby world

If a player disconnects mid-match, their session is preserved. On reconnect they are teleported back to their last known in-arena location with their inventory and game mode restored automatically.

🎮 Game modes

❤️ Lifesteal

When lifesteal is enabled, killing a player drops a heart item — pick it up to increase your maximum HP (capped at lifesteal-max-health, default 40 ♥). Players can convert hearts back to items with /withdraw <amount>.

💀 Hardcore

When hardcore is enabled, eliminated players are kicked from the server immediately (after a short delay) instead of being moved to spectator mode.

⛏️ Veinminer

When veinminer is enabled, sneaking while breaking an ore block chain-mines the entire connected vein in one swing. The maximum vein size is configurable in config.yml as veinminer-max-size and hot-reloads with /perf reload.

⚡ Legendary weapons

45 legendary weapons, each with unique active and/or passive abilities. All stats are tunable in plugins/HungerGamesSSS/legend-items/<id>.yml.

🗡️ Swords & melee

Item	Ability summary
☁️ Cloud Sword	Walk on cloud blocks; full fall immunity; armor shred on hit
💛 Midas Sword	Gains +1 damage per kill (stacks to cap); golden particle on kill
💎 Emerald Blade	Deposit emeralds to upgrade damage; sneak+click opens upgrade GUI
🌑 Shadow Blade	Sneak: Shadow Step behind target; click: true invisibility + Speed III
💀 Reaper Scythe	On hit: steal active buffs from target and heal; right-click: AOE sweep
🐉 Dragon Katana	Passive Speed I; right-click: launch Dragon Fireball that scales with distance
✨ Excalibur	Right-click: 5 s true invincibility (blocks all damage); passive 50% reflect + projectile deflect
🪨 Golem Hammer	Right-click: leap into air then shockwave on landing; passive knockback resistance
🌋 Magma Club	Right-click: lava pillar AOE; sneak+click: volcanic eruption
⛏️ Warpick	On hit: small explosion; sneak+click: plant a proximity mine
🖤 Obsidian Dagger	Sneak+click: Obsidian Shield (Resistance V); click: summon meteor; passive resistance at low HP
☠️ Death Scythe	Execute enemies below 20% HP; collect 10 souls to block one death
🔴 Crimson Chainsword	Right-click: rev up for 1.5× damage hit; on hit: AOE + bleed (5 ticks)
👻 Soul Gauntlet	Collect 5 souls on hit; right-click: Soul Blast (3 souls); sneak+click: Ground Slam (5 souls)
🪝 Harpoon Launcher	Fires a harpoon that hooks and pulls a target toward you

🏹 Bows & ranged

Item	Ability summary
🌙 Artemis Bow	Passive Speed I; fires 5 homing arrows; sneak+click: Sky Strike (lightning on nearest enemy)
👁️ Phantom Longbow	Grants invisibility on fire; arrow is invisible, passes through blocks, inflicts Darkness
🌀 Ender Bow	Sneak+click: Void Dash (6-block blink); arrow hit: swap positions with target
🧪 Toxic Crossbow	Fires a high-velocity green arrow; leaves a poison cloud on impact
🦾 Warden Crossbow	Launches a Sonic Boom projectile; converts blocks to Sculk on impact
🌑 Corrupted Crossbow	Fires a spread of bolts; each bolt applies Poison + Weakness
🔱 Guardian Cannon	Passive Dolphins Grace in water; fires a continuous stasis laser
🐡 Pufferfish Cannon	Launches a bouncing pufferfish that explodes with Poison + Nausea

🔮 Staves & magic

Item	Ability summary
🧊 Lich Staff	4 ammo ice balls (Freeze + Slowness); 30 s reload; passive Frost Walker
🌌 Void Staff	Left-click to toggle modes; Portal Mode (place/connect portals); Shulker Mode (tracking bullet)
🐛 Hypnosis Staff	Raycast beam to hypnotise a mob (up to 5 minions); minions target whoever you attack
💥 Villager Wand	Aim at a block → explosive slime bomb grows and detonates
📓 Death Note	Passive raycast charges a progress bar; at 800 ticks summons a Warden on the target
🌑 Sculkweaver's Lantern	Throw a sculk bomb that lingers and applies Darkness + Slowness
❄️ Horn of Winter	Summons a blizzard — continuous Freeze + Slowness in a large radius
🔔 Ghastly Whistle	Spawns a spectral Ghast that fires 8 guided fireballs at the nearest enemy

🌊 Tridents, launchers & special

Item	Ability summary
🔱 Poseidon's Trident	Passive Conduit Power + Dolphins Grace near water / during rain; bonus lightning damage in water
🌀 Wither Sickles	Auto dual-wield offhand copy; right-click throws sickle (CD 7 s); on hit AOE Wither + lifesteal
⚡ Mjolnir	Right-click: throw (visible ItemDisplay flies and returns); on melee hit: lightning
🦏 Ravager Horn	Right-click: mount a Ravager; sneak+click: Stampede wave
🔬 Shrink Ray	Left-click: shrink target; right-click: enlarge target (scale attribute)
🔴 Armadillo Detonator	Shoots a rolling armadillo projectile that explodes with spike damage
🐝 Beehive Blaster	Launches a bee-swarm ball that releases 5 angry bees on impact
🌿 Ribbit Reel	Crossbow tongue — hit a block: pull yourself; hit an entity: pull them to you
🌊 Aiglos	Trident that explodes on impact: Freeze + Slowness III AOE

🛡️ Armor pieces

Item	Slot	Ability summary
🪖 Hades' Helm	Head	Passive Night Vision + Invisibility while sneaking; fire aura; sneak+click: Underworld Blink; on hit received: Wither attacker
👟 Hermes Boots	Feet	Passive Speed II + Jump Boost; right-click: Hermes Dash; full fall damage immunity
🪂 Reinforced Elytra	Chest	Passive trail particles while gliding; sneak while gliding: Sonic Boom boost; landing explosion

💊 Utility / healing

Item	Ability summary
💧 Fountain of Youth	AOE regeneration field for 5 s — heals all teammates within radius

🔨 Crafting legendary items

Legendary items are crafted at a Cornucopia crafting station using ingredients defined in each legend-items/<id>.yml. The XP level cost is set globally in config.yml:

legendary:
  crafting-xp-cost: 15
  excluded-ids: []   # list item IDs here to remove them from the pool

Each item file defines:

name: "&e&lArtemis Bow"
material: "BOW"
cooldown: 12000          # milliseconds
xp-cost: 40              # XP levels consumed on craft
heart-cost: 0            # lifesteal hearts consumed on craft
custom-model-data: 3
ingredients:
  netherite_ingot: 1
  diamond_block: 32
  bow: 1
enchantments:
  power: 3
lore:
  - "&7Fire 5 homing arrows at once."

All files live in plugins/HungerGamesSSS/legend-items/ and are hot-reloaded with /perf reload — no restart needed.

🏰 Dungeons

11 dungeon types spawn randomly across the arena during a match. Each is built procedurally in-world — no external schematic files required (though custom .nbt / .schem files are supported when allow-custom-structure: true).

Dungeon	Terrain	Notable mobs
🕷️ Spider Nest	Cobweb-filled cave	Spider, Cave Spider
💀 Crypt	Stone Brick underground chamber	Zombie, Skeleton
⛏️ Gold Mine	Mineshaft-style tunnels	Husk, Stray
🔥 Lava Temple	Nether-brick surface structure	Blazes, Magma Cubes
🧊 Ice Temple	Packed Ice biome structure	Strays, Drowned
🏛️ Surface Temple	Sandstone above-ground ruin	Mixed
🗼 Surface Outpost	Pillager-style watchtower	Mixed
🌤️ Sky Island	Floating grass island	Mixed
🏯 Floating Castle	Stone castle 30 blocks in the air	Mixed
🌑 Underground Dungeon	(alias → Crypt)	—
🌑 Ancient Mineshaft	(alias → Gold Mine)	—

Each dungeon contains locked chests with loot pulled from the configured loot table. Dungeon mobs have configurable HP multipliers. All dungeon blocks are restored to their original state after the match ends.

Per-type config:

dungeons:
  mob-hp: 60.0
  boss-hp: 100.0
  spawn-chance: 0.1
  lava-temple:
    enabled: true
    mob-hp: 40.0
    fire-ticks: 100

🌽 Cornucopia builder

The Cornucopia is built procedurally from 13 different preset themes:

ultimate · speedsilver · classic · ancient · void · royal · industrial · modern · crystal · jungle · end · nether · grand

/hg setcornucopia <arenaName> <theme>

The builder clears a configurable radius (default 100 blocks), places the structure, and populates chests according to the Cornucopia loot table. The centre location is stored in the database and restored on restart.

🎁 Feast event

A timed feast spawns 8 high-tier chests at the Cornucopia centre after a configurable number of minutes (default 20). Announcements are broadcast at configurable intervals before the event.

arena:
  feast:
    enabled: true
    time-minutes: 20
    radius: 10
    chest-count: 8
    announce-minutes: [15, 10, 5, 3, 2, 1]

Feast chests use their own loot table tier for higher-value items. All feast chests are removed when the arena resets.

👥 Teams

Players form teams before or during a match. Teams share chat, see each other on the scoreboard, and legendary weapons respect friendly fire rules.

/team create <n>          — create a team (you become leader)
/team invite <player>     — send an invite (expires after 60 s)
/team join <n>            — accept an invite or join an open team
/team leave               — leave your current team
/team open                — toggle open/invite-only
/team disband             — disband your team (leader only)
/tc <message>             — team chat

Teams persist across matches and are saved to the database. Max team size and available colors are configurable:

teams:
  max-players-per-team: 4
  max-teams: 50
  allow-team-chat: true
  available-colors: [RED, BLUE, GREEN, YELLOW, AQUA, LIGHT_PURPLE, WHITE]

📊 Scoreboard

A per-player animated scoreboard updates every second (configurable). Displays:

⏱️ Match timer / phase name
👤 Remaining player count
🛡️ Your team name and colour
❤️ Your current health (with heart symbols)
⚔️ Kill count this match

Fully customisable via plugins/HungerGamesSSS/scoreboard.yml — change any line, add PlaceholderAPI placeholders, or disable it entirely.

🪧 Holograms

Floating text holograms mark every configured legendary spawn point in the arena. They show the item name and are updated automatically when spawns are added or removed. No external hologram plugin is required.

📦 Loot tables

All chest loot is defined in plugins/HungerGamesSSS/loot.yml. Three tiers — common, uncommon, and rare — each specify material, min, and max amounts. Changes apply immediately with /perf reload.

Rarity probabilities at the edge of the arena radius (no bonus):

Tier	Base chance
🟫 Common	70 %
🟦 Uncommon	25 %
🟨 Rare	5 %

Chests closer to the Cornucopia receive a distance bonus of up to +20 % uncommon / +15 % rare.

loot:
  common:
    - { material: BREAD, min: 2, max: 6 }
  uncommon:
    - { material: GOLDEN_APPLE, min: 1, max: 1 }
  rare:
    - { material: DIAMOND, min: 1, max: 2 }

🗺️ Structure system

The optional structure system places .nbt or .schem files from plugins/HungerGamesSSS/structures/ into the arena world. Requires FastAsyncWorldEdit and allow-custom-structure: true in config.

/hg wand                 — get the selection wand (left/right click to set corners)
/hg save cornucopia      — save selected region as the Cornucopia structure
/structure reset         — remove all placed structures for the current arena
/structure stats         — list placed structures and their locations
/locate <structureName>  — find the nearest structure of a given type

Placed structure locations are tracked and all blocks are restored when the arena resets.

💾 Persistence — SQLite / MySQL

All arena state, player statistics, team data, and match history are stored in a relational database.

Tables: arenas · players (kills, wins) · teams · team_members · arena_players · arena_spawns · arena_legendaries

Switch between backends in config.yml:

database:
  type: sqlite          # or "mysql"
  sqlite-file: database.db
  mysql:
    host: localhost
    port: 3306
    database: hungergames
    username: root
    password: password

All database writes are async. Schema migrations run automatically on startup — new columns are added non-destructively so existing data is never lost.

🌐 Localisation

The plugin ships with 10 language files:

🇬🇧 en · 🇻🇳 vi · 🇷🇺 ru · 🇩🇪 de · 🇫🇷 fr · 🇪🇸 es · 🇵🇹 pt · 🇯🇵 ja · 🇰🇷 ko · 🇨🇳 zh

Set the global default in config.yml:

language: en

Players can choose their own language in-game:

/hg lang <code>

Custom translations go in plugins/HungerGamesSSS/languages/<code>.yml. All messages — including legendary weapon names and descriptions — are fully translatable.

⚡ Performance tools

/perf stats       — live TPS, memory, active arenas, entity counts
/perf optimize    — run a garbage-collection pass and chunk unload sweep
/perf reload      — hot-reload config.yml, loot.yml, scoreboard.yml, legend-items/
/perf gc          — force JVM GC (use sparingly)
/perf chunks      — unload unused chunks across all arena worlds
/perf monitor     — toggle per-tick performance monitoring to console

Notable performance decisions baked into the plugin:

🔄 A single UnifiedPassiveTicker (20-tick period) replaces per-weapon BukkitRunnables
🧹 DungeonManager task tracking prevents leaked async tasks on arena reset
🎯 Raytrace-heavy abilities (Death Note) throttled to a 3-tick period
💾 All database writes are async with per-arena and per-player save chains
🧱 Block restoration uses batched processing (max-blocks-per-tick: 5000)

📜 Commands reference

`/hg` — main command

Sub-command	Permission	Description
`join <arena>`	`hoplitebr.hg`	🚪 Join an arena lobby
`leave`	`hoplitebr.hg`	🚶 Leave the current arena
`create <n>`	`hoplitebr.admin`	➕ Create a new arena
`delete <arena>`	`hoplitebr.admin`	🗑️ Delete an arena and its data
`start <arena> [countdown]`	`hoplitebr.admin`	▶️ Force-start a match
`setcornucopia <arena> <theme>`	`hoplitebr.admin`	🌽 Set and build the Cornucopia
`addspawn <arena>`	`hoplitebr.admin`	📍 Add a player spawn at your feet
`setuparena <arena> <flag>`	`hoplitebr.admin`	🔧 Toggle arena flags
`setlegendary <arena> <id>`	`hoplitebr.admin`	⚡ Mark legendary spawn at your feet
`deletelegendary <arena>`	`hoplitebr.admin`	❌ Remove nearest legendary spawn
`setlobby`	`hoplitebr.admin`	🏠 Set the post-match lobby at your location
`reload`	`hoplitebr.admin`	🔄 Reload all configuration files
`admin give <player> <item>`	`hoplitebr.admin`	🎁 Give a legendary item
`wand`	`hoplitebr.admin`	🪄 Get the structure selection wand
`save cornucopia`	`hoplitebr.admin`	💾 Save selected region as Cornucopia
`border <arena> <size> [time]`	`hoplitebr.admin`	🔵 Set arena world border
`lang <code>`	`hoplitebr.hg`	🌐 Change your language

Other commands

Command	Permission	Description
`/team <create\|invite\|join\|leave\|open\|disband>`	`hoplitebr.team`	👥 Team management
`/tc <message>`	`hoplitebr.tc`	💬 Team chat
`/withdraw <amount>`	`hoplitebr.withdraw`	❤️ Withdraw lifesteal hearts as items
`/perf <stats\|optimize\|reload\|gc\|chunks\|monitor>`	`hoplitebr.admin`	⚡ Performance tools
`/structure <reset\|stats>`	`hoplitebr.admin`	🗺️ Structure management
`/locate <n>`	`hoplitebr.hg`	🔍 Locate a placed structure
`/migrate`	`hoplitebr.admin`	🔄 Migrate legacy PDC tags on legend items
`/debug`	`hoplitebr.admin`	🐛 Dump plugin debug info to console

🔑 Permissions reference

Node	Default	Description
`hoplitebr.hg`	`true`	🚪 Basic game commands (join, leave, lang)
`hoplitebr.team`	`true`	👥 Team commands
`hoplitebr.tc`	`true`	💬 Team chat
`hoplitebr.withdraw`	`true`	❤️ Lifesteal heart withdrawal
`hoplitebr.admin`	`op`	🔧 All admin / setup commands

🛠️ Configuration reference

`config.yml`

language: en                       # Default language code
debug: false

arena:
  max-players: 24
  cornucopia-radius: 100
  lifesteal-max-health: 40.0
  feast:
    enabled: true
    time-minutes: 20
    radius: 10
    chest-count: 8
    announce-minutes: [15, 10, 5, 3, 2, 1]

dungeons:
  mob-hp: 60.0
  boss-hp: 100.0
  spawn-chance: 0.1
  lava-temple:
    enabled: true

legendary:
  crafting-xp-cost: 15
  excluded-ids: []

database:
  type: sqlite                     # "sqlite" or "mysql"
  sqlite-file: database.db
  mysql:
    host: localhost
    port: 3306
    database: hungergames
    username: root
    password: password

scoreboard:
  enabled: true
  update-interval: 20

teams:
  max-players-per-team: 4
  available-colors: [RED, BLUE, ...]

resource-pack:
  url: ""
  hash: ""
  required: false
  prompt: ""

performance:
  block-processing:
    max-blocks-per-tick: 5000
    batch-delay: 1

🔌 Developer API

// Get the arena a player is in (null if not in one)
Arena arena = HopliteAPI.getPlayerArena(player);

// Access the plugin directly
Main plugin = HopliteAPI.getPlugin();

Custom events you can listen to:

Event	Fired when
▶️ `ArenaStartEvent`	A match transitions from STARTING → PLAYING
🏁 `ArenaEndEvent`	A match ends (winner declared)
💀 `PlayerEliminatedEvent`	A player is eliminated from a match
🏰 `DungeonSpawnEvent`	A dungeon is procedurally generated

🙏 Credits

Author: Duong2012G — Modrinth

Several weapon mechanics were inspired by DemoRaHoplite Weapons by Demora: VoidStaff dual-mode system, Excalibur true invincibility, WitherSickles dual-wield, and LichStaff ammo balancing. No source code was copied — only the gameplay concept was referenced.

🔗 DemoRaHoplite Weapons: https://modrinth.com/plugin/demorahopliteweapons

🔨 Building from source

git clone <repo-url>
cd HungerGamesSSS
mvn clean package -DskipTests
# Output: target/HungerGamesSSS-4.5.1.jar