🏹 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.1
📋 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 - 🧹
DungeonManagertask 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: </plugins/demorahopliteweapons>
🔨 Building from source
git clone <repo-url>
cd HungerGamesSSS
mvn clean package -DskipTests
# Output: target/HungerGamesSSS-4.5.1.jar
