HungerGameSSS

---

📖 Table of Contents

• Features
• Requirements
• Installation
• Arena System
• Match Lifecycle
• Game Modes
• Legendary Weapons
• Dungeons
• Cornucopia Builder
• Feast Event
• Teams
• Persistence
• Localisation
• Commands & Permissions
• Developer API
• Troubleshooting
• Credits

---

Features

🏟️ Arena System

• Multi-arena support — run unlimited concurrent arenas in separate worlds
• Per-arena toggles — PvP, lifesteal, hardcore, veinminer, nether, end
• Glass cage countdown — players locked in cages at spawn until the match begins
• Auto-reset — arena world and all blocks fully restored after each match
• Legendary spawn points — holograms float above each marked item location

---

⚡ 45 Legendary Weapons

Each weapon has unique active + passive abilities
All stats tunable in legend-items/<id>.yml
Hot-reload with /perf reload — no restart needed

---

🏰 Procedural Dungeons

No external schematics required
Loot configurable per dungeon type
All blocks restored after match ends

---

📈 Match Lifecycle

WAITING → STARTING → PLAYING → DEATHMATCH → ENDED

Disconnect/reconnect mid-match restores last location, inventory, and scoreboard

---

🎮 Game Modes

❤️ Lifesteal

Kill a player → they drop a heart item. Pick it up to raise your max HP. Convert hearts back with /withdraw <amount>.

💀 Hardcore

Eliminated players are kicked instead of moved to spectator mode.

⛏️ Veinminer

Sneak + break an ore → chain-mines the entire vein. Max vein size is hot-configurable.

---

🌽 Cornucopia Themes

13 procedural themes for the arena centrepiece:

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

---

🌐 Localisation

10 built-in language files:

en · vi · ru · de · fr · es · pt · ja · ko · zh

Players change language in-game with /hg lang <code>.

---

💾 Persistence — SQLite / MySQL

All arena state, player stats, team data, and match history persist across restarts. Switch 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 writes are async
Auto schema migration on startup — no data loss

---

Requirements

---

Installation

1. Download the .jar
2. Drop it into plugins/
3. Start the server — configs generate automatically
4. Stand at the centre of your arena → /hg create <name>
5. /hg setcornucopia <name> classic
6. Walk to each spawn point → /hg addspawn <name> (repeat 2–24×)
7. Stand in your lobby → /hg setlobby
8. /hg start <name>

Players join with /hg join <name>.

---

Arena System

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

Legendary spawn points:

/hg setlegendary <arena> <itemId>   — mark spawn at your feet
/hg deletelegendary <arena>         — remove nearest spawn (within 5 blocks)

---

Legendary Weapons

🗡️ Swords & Melee

🏹 Bows & Ranged

🔮 Staves & Magic

🌊 Tridents, Launchers & Special

🛡️ Armor

---

Dungeons

Dungeons spawn procedurally during a match — no schematic files needed.

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

---

Feast Event

High-tier chests spawn at the Cornucopia after a configurable timer.

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

---

Teams

---

Commands

/hg — Main Command

Other Commands

---

Permissions

---

Configuration

Config files:

• config.yml — global settings, arena defaults, database, performance
• loot.yml — chest loot tiers (common / uncommon / rare)
• scoreboard.yml — scoreboard layout and update interval
• legend-items/<id>.yml — per-weapon stats, recipe, lore, enchantments
• dungeons.yml — dungeon type toggles and mob HP
• cornucopia.yml — Cornucopia build presets
• languages/<code>.yml — message translations

---

Developer API

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

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

Custom Events:

---

Troubleshooting

Legendary abilities not working

• Confirm the player is in an active arena (PLAYING or DEATHMATCH)
• Check hoplitebr.admin permission — OP always bypasses ability checks
• Run /debug and check console for [Ability] log lines with debug: true

Countdown cancels immediately on start

• Fixed in 4.5.5 (BUG-CD-01)
• Update to latest version

Feast never spawns in second match

• Fixed in 4.5.5 (BUG-FM-01)
• Update to latest version

Stats reset to zero on every join

• Fixed in 4.5.7 (BUG-JOIN-02)
• Update to latest version

Ability listeners fire twice

• Fixed in 4.5.7 (BUG-REG-01)
• Was caused by registerEvents() in ability constructors

Italic text on legendary item names

• Fixed in 4.5.4 (BUG-FONT-01)
• Paper 1.20.5+ changed the default rendering style for custom item names

Players not teleported to centre at Deathmatch start

• Fixed in 4.6.2 (BUG-1 / GameTask FSM bypass)
• GameTask was calling arena.setState(DEATHMATCH) directly, bypassing MatchService.transition(). The teleport and border-collapse logic inside scheduleDeathmatchTask() never ran.

World border ignores my config values — always uses 1000 blocks

• Fixed in 4.6.2 (BUG-2 / mismatched config keys)
• GameTask was reading game.initial-border-size and game.border.initial-size (wrong keys). The canonical key is game.border-initial-size. The game-loop always fell back to the hardcoded default of 1000.

Border flickers / jumps every second during PLAYING phase

• Fixed in 4.6.2 (BUG-4 / dual border control)
• MatchService.scheduleBorderTask() and GameTask.handleWorldBorder() both wrote to the WorldBorder simultaneously. The per-tick recalculation overrode the smooth periodic animation every second. scheduleBorderTask() has been removed; GameTask is now the sole border authority.

Legendary item hologram shows material name (e.g. "WOODEN_SWORD") instead of weapon name

• Fixed in 4.6.2 (BUG-5 / legacy display-name API)
• Arena.getActiveLegendaryLocations() called meta.getDisplayName() (legacy API) which always returns "" for items using the Adventure Component API. The fallback of recipe.getType().name() was always reached.

Game doesn't end when a full team is the last survivor

• Fixed in 4.6.2 (BUG-6 / checkWin team logic)
• checkWin() only ended the game when aliveCount == 1. If the last 2+ survivors were all on the same team, the game continued and forced teammates to kill each other. Now checks if all alive players share a team.

Arena doesn't reset properly after double `/hg start`

• Fixed in 4.6.2 (BUG-3 / BUG-8 — countdown tasks not tracked)
• Both startMatch(Arena, int) and startCountdown() created countdown BukkitRunnables without storing the task reference. cancelAllTasksFor() could not cancel them, leading to two countdown timers running concurrently and startArena() being called twice.

/reload breaks the plugin

• Always restart the server — never use /reload

---

FAQ

Can I run multiple arenas at once?

Yes — each arena is fully isolated in its own world instance.

Do I need FastAsyncWorldEdit?

No. It is only required if you want to paste custom .nbt / .schem structures.

Can players on the same team damage each other?

No — all legendary weapons include friendly-fire checks.

How do I add a custom language?

Create languages/<code>.yml — copy en.yml as a base and translate. Players switch with /hg lang <code>.

Does it support Spigot?

No — Paper 1.21+ is required.

---

Credits

Author: Duong2012G — Modrinth

Several weapon mechanics were inspired by DemoRaLegendary Weapons by Demora (Apache 2.0 licence).
No source code was copied — only gameplay concepts were referenced.

DemoRaLegendary Weapons: https://modrinth.com/plugin/demoralegendaryweapons

Open source — contributions welcome.