Gladiators

# Gladiators PvP gladiator plugin for Paper 1.21 featuring ranked and normal queues, Elo rating and eight distinct kits. This guide walks server admins through setup, configuration, and daily operation. ## Requirements - Paper/Purpur 1.21.x (API version 1.21) - Java 21 (compiler target) - Write access to the server folder to create `plugins/Gladiators` and its data/config files. ## Installation 1. **Download the release JAR** and place it in `plugins/` . 2. **Start the server once** to generate `config.yml` and `player-data.yml`. 3. **Adjust config**: Edit worlds, spawn points, and hazards in `plugins/Gladiators/config.yml` (see “Configuration” below). 4. **Elo data**: Persistent values are stored in `plugins/Gladiators/player-data.yml`. ## Quickstart (arena & queues) 1. **Prepare worlds**: List your arena worlds in `arena.worlds`. Missing worlds are created/loaded on startup via `WorldCreator`. 2. **Set spawn points**: Define at least two entries under `arena.spawnpoints`. 3. **Optional hazards**: Tweak `ravagers` or remove to disable the events. 4. **Start the server** and test with `/gladiators ranked` or `/gladiators normal`. 5. **Check the kit GUI**: In a match, the selection GUI opens automatically for both players. ## Commands & permissions | Command | Purpose | Permission | | --- | --- | --- | | `/gladiators ranked` | Join ranked queue with Elo matchmaking | – | | `/gladiators normal` | Join unranked queue | – | | `/gladiators elo` | Show top-10 Elo | – | | `/gladiators leavequeue` | Leave current queue | – | ### Queue signs A sign containing “`ranked`” or “`normal`” on its front lets players join that queue via right-click. ## Configuration (`config.yml`) Key sections (values apply per world when multiple arena worlds are listed): - **`arena.worlds`**: Up to four worlds used as arenas. - **`arena.spawnpoints`**: At least two spawn points with `x/y/z/yaw/pitch`. - **`arena.ravagers`**: Enables ravager waves; controls spawn points, `wave-size`, and `respawn-seconds`. Remove the section to disable. - **`durations.kit-selection-seconds`**: Time for kit selection before each round. - **`durations.fight-seconds`**: Round duration before hazards/Sudden Death decide the fight. - **`elo.*`**: Default Elo, K-factor, matchmaking range (`start-range`, `range-step`, `expand-every-seconds`, `max-range`), and reward scaling (`scale-per-100-diff`, `max-multiplier`). - **`kits`**: Display names, icons, and descriptions for the GUI. Ability effects live in code; localize descriptions here. ### Example snippet ```yaml arena: worlds: [arena, arena1] spawnpoints: - {x: 131, y: 23, z: 297, yaw: -90, pitch: 0} - {x: 221, y: 23, z: 296, yaw: 90, pitch: 0} ``` ## Match flow & features - **Queues**: Separate ranked/normal queues; ranked expands Elo range every `expand-every-seconds` until `max-range` is reached. - **Kit selection**: Before each round, a GUI shows all kits plus the opponent’s head with Elo/stats. - **Rounds**: Defaults are 15s kit select and 60s fight time; hits, hazards, or Sudden Death resolve afterward. - **Sudden Death**: Kits adjust durations/effects automatically. - **Healing bread**: Tagged bread heals 5 hearts on consume. - **Elo & stats**: Wins/losses, most-played kit, and rating are persisted; `/gladiators elo` shows the top 10. ## Kit overview (defaults) - **Retiarius** – Trident + net throw: root/slow, Speed passive, no shields. - **Secutor** – Gladius + shield, dash with bonus hit, half root duration, Speed after root. - **Murmillo** – Projectile resistance, permanent Slow, kick with Slow II, heavy shield. - **Dimachaerus** – Dual swords, combo bonus, flurry (Strength/Speed) then weakness. - **Thraex** – Curved sword + shield, reduced roots/slows, periodic bleed, shield bash stun. - **Veles** – Three javelins with Slow, Speed while javelins remain, Weakness when empty. - **Hoplomachus** – Heavy armor, Resistance I but Slow I; “Turtle Stance” gives high resistance briefly. - **Sagittarius** – Ranged bonus, melee weakness, “Aimed Shot” after 1.2s wind-up, extra arrows in Sudden Death. ## Admin tips - Ensure arena worlds are loaded and **PvP enabled**. - Use separate arenas per match to avoid overlap; the plugin picks free arenas sequentially. - Remove hazard sections in the config for classic duels without extra mechanics. - Reserve enough space for sand-collapse radii so the outer ring stays inside the arena. - Back up `player-data.yml` before resetting or migrating ratings. ## Support For questions or change requests, feel free to DM **aic1x** on Discord.