# 🏹 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** ![Paper](https://img.shields.io/badge/Paper-1.21%2B-brightgreen) ![Java](https://img.shields.io/badge/Java-21%2B-orange) ![Version](https://img.shields.io/badge/Version-4.5.7-blue) --- ## 📋 Table of contents 1. [Requirements](#requirements) 2. [Quick start](#quick-start) 3. [Arena system](#arena-system) 4. [Match lifecycle](#match-lifecycle) 5. [Game modes](#game-modes) 6. [Legendary weapons](#legendary-weapons) 7. [Crafting legendary items](#crafting-legendary-items) 8. [Dungeons](#dungeons) 9. [Cornucopia builder](#cornucopia-builder) 10. [Feast event](#feast-event) 11. [Teams](#teams) 12. [Scoreboard](#scoreboard) 13. [Holograms](#holograms) 14. [Loot tables](#loot-tables) 15. [Structure system](#structure-system) 16. [Persistence — SQLite / MySQL](#persistence--sqlite--mysql) 17. [Localisation](#localisation) 18. [Performance tools](#performance-tools) 19. [Commands reference](#commands-reference) 20. [Permissions reference](#permissions-reference) 21. [Configuration reference](#configuration-reference) 22. [Developer API](#developer-api) 23. [Credits](#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 5. Walk to the Cornucopia centre → /hg setcornucopia classic 6. Walk to each player spawn point → /hg addspawn (repeat 2–24 times) 7. /hg setlobby (stand in the lobby you want players to return to after a match) 8. /hg start ``` The arena is now ready. Players join with `/hg join `. --- ## 🏟️ 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 `): | 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 ` | — | 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 — mark your feet position as a spawn /hg deletelegendary — 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 `. ### 💀 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/.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/.yml`. The XP level cost is set globally in `config.yml`: ```yaml legendary: crafting-xp-cost: 15 excluded-ids: [] # list item IDs here to remove them from the pool ``` Each item file defines: ```yaml 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:** ```yaml 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 ``` 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. ```yaml 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 — create a team (you become leader) /team invite — send an invite (expires after 60 s) /team join — 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 — team chat ``` Teams persist across matches and are saved to the database. Max team size and available colors are configurable: ```yaml 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. ```yaml 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 — 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`: ```yaml 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`: ```yaml language: en ``` Players can choose their own language in-game: ``` /hg lang


```

Custom translations go in `plugins/HungerGamesSSS/languages/.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 ` | `hoplitebr.hg` | 🚪 Join an arena lobby |
| `leave` | `hoplitebr.hg` | 🚶 Leave the current arena |
| `create ` | `hoplitebr.admin` | ➕ Create a new arena |
| `delete ` | `hoplitebr.admin` | 🗑️ Delete an arena and its data |
| `start  [countdown]` | `hoplitebr.admin` | ▶️ Force-start a match |
| `setcornucopia  ` | `hoplitebr.admin` | 🌽 Set and build the Cornucopia |
| `addspawn ` | `hoplitebr.admin` | 📍 Add a player spawn at your feet |
| `setuparena  ` | `hoplitebr.admin` | 🔧 Toggle arena flags |
| `setlegendary  ` | `hoplitebr.admin` | ⚡ Mark legendary spawn at your feet |
| `deletelegendary ` | `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  ` | `hoplitebr.admin` | 🎁 Give a legendary item |
| `wand` | `hoplitebr.admin` | 🪄 Get the structure selection wand |
| `save cornucopia` | `hoplitebr.admin` | 💾 Save selected region as Cornucopia |
| `border   [time]` | `hoplitebr.admin` | 🔵 Set arena world border |
| `lang ` | `hoplitebr.hg` | 🌐 Change your language |

### Other commands

| Command | Permission | Description |
|---|---|---|
| `/team ` | `hoplitebr.team` | 👥 Team management |
| `/tc ` | `hoplitebr.tc` | 💬 Team chat |
| `/withdraw ` | `hoplitebr.withdraw` | ❤️ Withdraw lifesteal hearts as items |
| `/perf ` | `hoplitebr.admin` | ⚡ Performance tools |
| `/structure ` | `hoplitebr.admin` | 🗺️ Structure management |
| `/locate ` | `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`

```yaml
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

```java
// 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](https://modrinth.com/plugin/hungergamessss)

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: 

---

## 🔨 Building from source

```bash
git clone 
cd HungerGamesSSS
mvn clean package -DskipTests
# Output: target/HungerGamesSSS-4.5.1.jar
```

Duong2012G

Duong2012G

BackPackSSS ResourcePack