---

📖 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

Category	Count	Examples
Swords & Melee	15	Cloud Sword, Excalibur, Dragon Katana
Bows & Ranged	8	Artemis Bow, Phantom Longbow, Warden Crossbow
Staves & Magic	8	Void Staff, Lich Staff, Hypnosis Staff
Tridents & Special	9	Aiglos, Mjolnir, Ravager Horn
Armor	3	Hades' Helm, Hermes Boots, Reinforced Elytra
Utility / Healing	2	Fountain of Youth, Warpick

✔️ 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

Type	Terrain
🕷️ Spider Nest	Cobweb cave
💀 Crypt	Stone brick chamber
⛏️ Gold Mine	Mineshaft tunnels
🔥 Lava Temple	Nether-brick structure
🧊 Ice Temple	Packed-ice biome
🏛️ Surface Temple	Sandstone ruin
🗼 Surface Outpost	Watchtower
🌤️ Sky Island	Floating grass
🏯 Floating Castle	Castle 30 blocks up

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

---

📈 Match Lifecycle

WAITING → STARTING → PLAYING → DEATHMATCH → ENDED

Phase	Description
⏳ Waiting	Players queue in lobby
🔢 Starting	Countdown; players teleport into cages
⚔️ Playing	Grace period → main phase → feast → border shrink
💥 Deathmatch	Border closes; final players fight
🏆 Ended	Winner announced; arena fully reset

✔️ 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

Component	Version
Java	21+
Paper	1.21+
PlaceholderAPI	Optional
Vault	Optional
ProtocolLib	Optional
FastAsyncWorldEdit	Optional (.nbt / .schem support)

---

🚀 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>):

Flag	Default	What it does
pvp	on	Enable / disable PvP damage
lifesteal	off	Players drop heart items on death
hardcore	off	Eliminated players are kicked
veinminer	off	Sneak + break to chain-mine ores
nether	on	Isolated Nether world per arena
theend	on	Access to The End dimension

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

Item	Ability
☁️ Cloud Sword	Walk on clouds; fall immunity; armor shred on hit
💛 Midas Sword	+1 damage per kill (stacks); golden particle on kill
💎 Emerald Blade	Deposit emeralds to upgrade damage; sneak+click GUI
🌑 Shadow Blade	Sneak: teleport behind target; click: invisibility + Speed III
💀 Reaper Scythe	On hit: steal buffs and heal; right-click: AOE sweep
🐉 Dragon Katana	Passive Speed I; right-click: Dragon Fireball dash
✨ Excalibur	5s true invincibility (all damage cancelled); 50% reflect
🪨 Golem Hammer	Leap + shockwave on landing; passive knockback resistance
🌋 Magma Club	Lava pillar AOE; sneak+click: volcanic eruption
⛏️ Warpick	On-hit 3×3 explosion; on critical hit: armor durability shred
🖤 Obsidian Dagger	Sneak+click: Resistance V shield; click: meteor strike
🔴 Crimson Chainsword	Shred stacks passive; right-click: Chainsaw Rampage burst
👻 Soul Gauntlet	Collect souls on hit; right-click: Soul Blast; sneak: Ground Slam
🪝 Harpoon Launcher	Fires a harpoon that hooks and pulls the target toward you

🏹 Bows & Ranged

Item	Ability
🌙 Artemis Bow	5 homing arrows; lightning proc; Sky Strike sneak ability
👁️ Phantom Longbow	Invisible arrow; caster invisible on fire; target gets Darkness
🌀 Ender Bow	Sneak: Void Dash; arrow hit: swap positions with target
🧪 Toxic Crossbow	High-velocity bolt; poison cloud on impact
🦾 Warden Crossbow	Sonic Boom projectile; converts blocks to Sculk on hit
🌑 Corrupted Crossbow	Tick-based poison cloud bolt; Multishot enchant support
🔱 Guardian Cannon	Passive Dolphins Grace in water; continuous stasis laser
🐡 Pufferfish Cannon	Bouncing pufferfish; explodes with Poison + Nausea

🔮 Staves & Magic

Item	Ability
🧊 Lich Staff	4 ammo ice balls; 30s reload; passive Frost Walker
🌌 Void Staff	Toggle Portal / Shulker Mode; independent cooldowns per mode
🐛 Hypnosis Staff	Hypnotise up to 5 mobs; minions target your enemies
💥 Villager Wand	Aim at block → explosive slime bomb detonates
📓 Death Note	/dn <player>: instant kill (3 uses, per-target cooldown 25s)
🌑 Sculkweaver's Lantern	Sculk bomb: Darkness + Slowness lingering zone
❄️ Horn of Winter	Blizzard: continuous Freeze + Slowness in large radius
🔔 Ghastly Whistle	Rideable Ghast companion; auto-fireball every 2s; 20s duration

🌊 Tridents, Launchers & Special

Item	Ability
🔱 Aiglos	Trident: explosive throw + AOE freeze; melee stats via attributes
🌀 Wither Sickles	Auto dual-wield offhand; throw (CD 7s); AOE Wither + lifesteal on hit
⚡ Mjolnir	Throw (returns); melee hit: lightning strike
🦏 Ravager Horn	Mount a Ravager; sneak+click: Stampede wave
🔬 Shrink Ray	Left-click: shrink target; right-click: enlarge target
🔴 Armadillo Detonator	Shoot up to 3 armadillos; left-click: detonate all
🐝 Beehive Blaster	Launches 4 angry bees that auto-target nearest enemy
🌿 Ribbit Reel	Hit block: pull yourself; hit entity: pull them to you
💧 Fountain of Youth	Passive +1 HP/s while held; right-click: 30s healing zone for allies

🛡️ Armor

Item	Slot	Ability
🪖 Hades' Helm	Head	Night Vision; invisibility while sneaking; fire aura; Wither attacker on hit received
👟 Hermes Boots	Feet	Speed II + Jump Boost; Hermes Dash; full fall immunity
🪂 Reinforced Elytra	Chest	Particle trail while gliding; Sonic Boom boost; landing explosion

---

🏰 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

Command	Description
/team create <name>	Create a team (you become leader)
/team invite <player>	Send an invite (expires 60s)
/team join <name>	Join an open team
/team leave	Leave your team
/team open	Toggle open / invite-only
/team disband	Disband team (leader only)
/tc <message>	Team chat

---

⌨️ Commands

/hg — Main Command

Sub-command	Permission	Description
join <arena>	hoplitebr.hg	Join an arena lobby
leave	hoplitebr.hg	Leave the current arena
lang <code>	hoplitebr.hg	Change your language
create <name>	hoplitebr.admin	Create a new arena
start <arena>	hoplitebr.admin	Force-start a match
setcornucopia <arena> <theme>	hoplitebr.admin	Set and build the Cornucopia
addspawn <arena>	hoplitebr.admin	Add player spawn at your feet
setuparena <arena> <flag>	hoplitebr.admin	Toggle per-arena flags
setlegendary <arena> <id>	hoplitebr.admin	Mark legendary spawn
setlobby	hoplitebr.admin	Set post-match lobby location
admin give <player> <item>	hoplitebr.admin	Give a legendary item
reload	hoplitebr.admin	Reload all config files

Other Commands

Command	Permission	Description
/withdraw <amount>	hoplitebr.withdraw	Convert lifesteal hearts to items
/perf <stats|optimize|reload|gc|chunks>	hoplitebr.admin	Performance tools
/structure <reset|stats>	hoplitebr.admin	Structure management
/locate <name>	hoplitebr.hg	Locate a placed structure
/migrate	hoplitebr.admin	Migrate legacy legendary PDC tags
/debug	hoplitebr.admin	Dump debug info to console
/dn <player>	hoplitebr.dn	Death Note kill command

---

🔐 Permissions

Permission	Default	Description
hoplitebr.hg	true	Basic game commands
hoplitebr.team	true	Team commands
hoplitebr.tc	true	Team chat
hoplitebr.withdraw	true	Lifesteal heart withdrawal
hoplitebr.dn	true	Death Note kill command
hoplitebr.admin	op	All admin / setup commands

---

🔧 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:

Event	Fired when
ArenaStartEvent	Match transitions STARTING → PLAYING
ArenaEndEvent	Match ends (winner declared)
PlayerEliminatedEvent	A player is eliminated
DungeonSpawnEvent	A dungeon is generated

---

🔍 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.