Update README.md

2026-04-14 05:07:56 +02:00
parent da23a13357
commit 50a8a4efe7
1 changed files with 301 additions and 104 deletions
--- a/README.md
+++ b/README.md
@@ -1,126 +1,323 @@
-# 🎮 HardcoreGames (HG) – Projektdokumentation
+# SpeedHG

-## ⚙️ Allgemeine Mechaniken & Einstellungen
-* **Teams:** Maximal To2 (Teams of 2). Spieler müssen sich über den `/team` Command zusammenschließen.
-* **Kompass:** Zeigt über der Actionbar in die Richtung des nächsten Gegners (`< Next Enemy in Direction: %direction% >`). Es werden keine Spielernamen preisgegeben.
-* **Hit-Cooldown:** Der Standard-HitCooldown ist entfernt.
-* **Ressourcen:** Vor dem Feast kann kein Eisen abgebaut werden. Nach dem Feast greift ein "Iron-Nerf".
-* **Auto-Pickup:** Automatisches Aufsammeln von Items ist aktiv. Speziell beim Start gehen Pilze, Kakaobohnen und Kakteen beim Abbauen direkt ins Inventar.
-* **Kills & XP:** Ein "Pro Kill" gewährt ein halbes XP-Level.
+> **A Spigot / Paper plugin for the *SpeedHG* Hunger-Games variant by McScrims Network.**  
+> Built with Kotlin · Paper API 1.21 · Version `1.0.0`

 ---

-## ⏳ Spielphasen
-1.  **Lobby:**
-    * *Dauer:* Bis 8 Spieler in der Runde sind, ansonsten Start via `/start` Command.
-2.  **Invincibility (Schutzzeit):**
-    * *Dauer:* 3 Minuten.
-    * *Effekte:* Spieler erhalten Speed & Haste bis zum Ende dieser Phase.
-3.  **Battle:**
-    * *Dauer:* Bis nur noch ein Spieler lebt.
-    * *Events:*
-        * **Feast:** Startet ab Minute 10.
-        * **Pit:** Im normalen Spiel ab Minute 30; bei einem Event ab Minute 45.
-        * **Deathmatch:** Gibt es ab 4 Spielern ein "Loot Feast" beim Deathmatch.
-    * *Maximale Dauer:* Normales Spiel = 1 Stunde; Event = 1 Stunde 15 Minuten.
-4.  **End:**
-    * *Dauer:* 1 Minute.
+## Table of Contents
+
+- [Overview](#overview)
+- [Dependencies](#dependencies)
+- [Game Flow](#game-flow)
+- [Configuration](#configuration)
+- [Kits](#kits)
+- [Perks](#perks)
+- [Commands](#commands)
+- [Permissions](#permissions)
+- [Architecture](#architecture)
+- [Adding a New Kit](#adding-a-new-kit)
+- [Adding a New Perk](#adding-a-new-perk)
+- [Runtime Configuration via `SPEEDHG_CUSTOM_SETTINGS`](#runtime-configuration-via-speedhg_custom_settings)

 ---

-## 📈 Level- & Ranking-System
-* **Leveling:** Spieler starten bei Level 1 und können bis Level 100 aufsteigen. Höhere Level schalten bestimmte Extras frei, um schwächeren Spielern das Spiel zu erleichtern.
-* **Einranken:** Es werden 5 Spiele benötigt, um einen Rang zu erhalten. Das Ergebnis berechnet sich aus *Performance + Letzter Rang*.
-* **Punktevergabe:** Nach jedem Spiel erhalten Spieler je nach Performance entweder Punkteabzug (`-5 bis -15 RR`) oder Punktezuwachs (`+10 bis +30 RR`).
+## Overview
+
+SpeedHG is a competitive Hunger-Games game-mode where every player selects a **Kit** (with an Aggressive or Defensive playstyle) and up to **2 passive Perks** before the round starts. The world border steadily shrinks, disasters trigger, and a feast spawns mid-game to force confrontation.
+
+Key features at a glance:
+
+- 17 fully-implemented Kits, each with 2 Playstyles (Aggressive / Defensive)
+- 14 passive Perks with persistent DB-backed selection
+- Hit-charge system for active abilities (configurable hits-to-charge per kit)
+- Dynamic WorldBorder shrink, Feast, and Pit events
+- Anti-runner detection, soup-based healing, team support
+- Lunar Client integration (waypoints, scoreboard)
+- Discord webhook for game results
+- MySQL-backed stats, ranking, and leaderboard
+- Fully i18n-able via `en_US.yml` (MiniMessage format)

 ---

-## 🌪️ Spiel-Systeme
+## Dependencies

-### Perks-System
-Spieler können anstelle von "Sidekits" verschiedene Perks wählen (2 Perks pro Spieler), welche das Spielerlebnis beeinflussen. Man kann so verschiedene Abilities kombinieren.
-* **Allgemeine Passive Perks:** Gegner wegkicken oder sich zu einem Gegner teleportieren.
-* **Orakel-Perk:** Ähnlich wie der Assassine. Zeigt Kit und Entfernung des nächsten Gegners an. *Sonderfall:* Wenn das Spielo-Kit ausgewählt ist, zeigt das Orakel an, ob der nächste Gamble gut oder schlecht wird.
+| Dependency      | Role                                |
+|-----------------|-------------------------------------|
+| `WorldEdit`     | Arena construction for GladiatorKit |
+| `Apollo-Bukkit` | Lunar Client integration            |
+| `Kup`           | Internal rank/permission bridge     |

-### Naturkatastrophen-System
-In jedem Biom können verschiedene Katastrophen auftreten:
-* **Mesa:** Tornado, Erdbeben
-* **Savanne:** Meteore
-* **Generell (bei hoher Bauhöhe):** Donner (Blitze)
+All three must be present on the server; the plugin will not load without them.

 ---

-## 🛡️ Kit-System
-**Grundregel für Fähigkeiten:** Nach dem Start der Runde hat jeder Spieler *einen* freien Use seiner Abilities. Danach werden die weiteren Uses erst ab einer bestimmten Anzahl an ausgeteilten Hits freigeschaltet. *Wichtig:* Vor der Kitauswahl wird der PlayStyle auf Null gesetzt, um Fehler zu vermeiden. Verlässt ein Spieler das Inventar ohne Wahl, wird der PlayStyle standardmäßig auf **DEFENSIVE** gesetzt.
+## Game Flow

-Hier sind alle dokumentierten Kits und ihre Fähigkeiten:
+```
+LOBBY → STARTING → INVINCIBILITY → INGAME → ENDING
+```

-* **Goblin [Fertig]**
-    * *Aggressive (Steal):* 60 Sekunden lang aktiv. Kopiert das Kit des Gegners und gibt eine minimale Chance, Suppen zu klauen.
-    * *Passive (Bunker):* Spawnt bei Aktivierung einen Bunker um den Spieler herum.
-* **Venom [Fertig]**
-    * *Aggressive (Wither):* Bei Aktivierung: Lohen-Sound + Beam + Blindness I (5 Sek.) + Instant Damage (2 Herzen) + Wither I.
-    * *Passive (Shield of Darkness / Dunklerpanzer):* 8 Sekunden aktiv. Lohen-Sound + Smoke + Barriere. Die Barriere blockt Projektile (Schneebälle, Eier, Pfeile) und reflektiert Tränke. Sie bricht ab 15 normalem Schaden. Der Spieler erhält nur 1 Herz Damage (1.5 bei Crits) und nur Schaden von Gegnern wird übertragen. Bricht die Barriere, ertönt ein Wither-Sound.
-* **Eismagier (IceMage) [Fertig]**
-    * *Aggressive:* Speed I in Eisbiomen. Angriffe auf Gegner haben eine Chance auf Slowness.
-    * *Passive (Schneeball):* Ein geworfener Schneeball explodiert in alle Richtungen (360°). Getroffene Gegner erhalten Freeze (3 Sek.) und Slowness II (2 Sek.).
-* **Backup [Fertig]**
-    * Kann sich zu jeder beliebigen Zeit in der Runde ein Kit aussuchen.
-* **Ninja [Fertig]**
-    * *Aggressive (Teleport):* Wenn der Spieler sneakt, teleportiert er sich hinter den Gegner (der in den letzten 10 Sekunden geschlagen wurde).
-    * *Passive (Smoke):* Erzeugt Rauch um den Spieler. Laufen Gegner hinein, bekommen sie Blindness I und Slowness I.
-* **Spielo [Fertig]**
-    * *Aggressive (Höheres Risiko):* Gambeln auf Knopfdruck ("Automat"). Gibt Random Items oder löst ein Event aus.
-    * *Passive (Sicherer):* Inventar mit Slot-Automat (wenn kein Spieler in der Nähe ist). Der Spieler kann keine Dia-Armor bekommen, hat dafür aber keinen Instant Death zu befürchten.
-* **Tesla [Fertig]**
-    * *Aggressive:* Es erscheinen zufällige Blitze im Umkreis von 5 Blöcken (1,5 Herzen Schaden).
-    * *Passive:* Gegner in der Nähe werden weggeknockt und bekommen Brandschaden. *Einschränkung:* Funktioniert ab einer Höhe von 50 Blöcken nicht mehr.
-* **Rattlesnake [Fertig]**
-    * Modus, bei dem man Speed II bekommt. Läd sich durch Sneaken auf (je länger, desto weiter springt man; 3 bis 10 Blöcke).
-    * *Hit:* Wenn man einen Gegner anspringt (Vor Feast 1x, danach 3x nötig), bekommt dieser Poison II (8 Sek.).
-    * *Miss:* Wenn der Sprung nicht trifft, erhält der Gegner verschiedene andere Effekte (Nausea, Slowness).
-* **Armorer [Fertig]**
-    * Bekommt alle 2 Kills bessere Rüstung (Schuhe & Brustplatte).
-    * Falls der Spieler bereits ein Teil besitzt, wird dieses durch das aktuelle Rüstungslevel ersetzt, sobald es zerbricht.
-* **Voodoo [Fertig]**
-    * *Aggressive:* 20% Wahrscheinlichkeit, getroffenen Gegnern den Wither-Effekt zu geben. Hat der Gegner unter 50% Leben, kann er für 5 Sekunden festgehalten werden.
-    * *Passive:* Spieler kann Gegner in der Nähe mit einem Fluch belegen (gibt negative Effekte). Während der Gegner verflucht ist, erhält der Voodoo-Spieler temporäre Buffs.
-* **Black Panther [Fertig]**
-    * *Aggressive:* 12 Sekunden lang 6,5 Damage (3,25 Herzen) mit der Faust. Pusht Gegner in der Nähe weg (Partikel fliegen hinterher, Enderperlen machen extra Schaden).
-    * *Passive ("Wakanda Forever!"):* Springt auf Gegner und macht Instant Damage (3 Herzen) plus eine Explosion mit Krater (ähnlich wie Meteor).
-* **Dreizack (Trident) [Fertig]**
-    * *Aggressive:* 3x Charges hoch und runter springen zu können. Beim runter springen schlägt ein Blitz ein
-    * *Defensive:* Falls der Dreizack in der Hand oder Offhand ist, gibt es eine 20% Chance, dass Gegner beim Schlagen abprallen und Slowness I für 2 Sekunden bekommen
-* **Anchor [Fertig]**
-    * Eingeschränktes NoKnockback. Baut man den Anchor ab, ertönt der Eisengolem-Sterbesound.
-    * *Aggressive:* 5-Block-Radius, aus dem man sich nicht bewegen kann, aber man macht 0,5 Herzen mehr Schaden.
-    * *Passive:* Größerer Radius (vermutlich 7,5 - 10 Blöcke).
-* **Blitzcrank [Fertig]**
-    * *Offensive:* Hook.
-    * *Defensive:* Stun.
-    * *Ult (Beide Styles):* Flächenschaden im Umkreis.
-* **Puppet (basiert auf Fiddlesticks) [Fertig]**
-    * *Aggressive:* Saugt für 2 Sekunden Leben von nahen Gegnern (Pro Spieler: 4 Herzen/Sekunde; Max 8 Herzen Heilung). Die Fähigkeit kann abgebrochen werden.
-    * *Defensive:* Gegner in der Nähe bekommen Blindness und Slowness für 4 Sekunden.
-* **TheWorld [Fertig]**
-    * *Aggressive:* Welle in alle Richtungen mit Partikeln. Teleportiert in Blickrichtung bei Aktivierung (Max 3).
-    * *Defensive:* Welle in alle Richtungen mit Partikeln. Friert Gegner in der Nähe für 10 Sekunden ein. Maximal 5 Hits gegen gefrorene Gegner möglich.
-* **Gladiator [Fertig]** *(Fähigkeiten nicht näher erläutert).*
+| Phase           | Description                                                                              |
+|-----------------|------------------------------------------------------------------------------------------|
+| `LOBBY`         | Waiting for `min-players`. Every 15 s an idle message is broadcast.                      |
+| `STARTING`      | Countdown (`lobby-time` seconds). Aborts if player count drops.                          |
+| `INVINCIBILITY` | Players are teleported, kits & perks applied, Speed I + Haste I active. No damage dealt. |
+| `INGAME`        | Combat enabled, WorldBorder shrinks, timer counts up, Feast & Pit events fire.           |
+| `ENDING`        | Winner announced, server shuts down after a short delay.                                 |
+
+Default timing values (overridable in `config.yml`):
+
+| Setting            | Default    |
+|--------------------|------------|
+| Min players        | 8          |
+| Lobby time         | 120 s      |
+| Invincibility time | 120 s      |
+| Border start       | 600 blocks |
+| Border end         | 150 blocks |
+| Border shrink time | 900 s      |

 ---

-## ✅ Checklisten-Status (Stand: 28.03.2026)
+## Configuration

-**Abgeschlossene Systeme:**
-* [x] Compass
-* [x] Start (Speed, Haste, Auto-Pickup)
-* [x] Phasen (Lobby, Invis, Battle, End)
-* [x] Level (Elo- / Rank-System)
-* [x] Perks-System
-* [x] Kit-System
-* [x] Naturkatastrophen-System
-* [x] Map-System
-* [x] Teams-System
+### `config.yml`

-**Noch Offen:**
-* [ ] Custom World-Generation
+```yaml
+game:
+  beta: true
+  min-players: 2
+  lobby-time: 60
+  invincibility-time: 120
+  border-start: 600.0
+  border-end: 100.0
+  border-shrink-time: 900   # seconds
+  max-radius-teleport: 50.0
+  ranked: false
+
+teams:
+  enabled: false
+  preset-count: 10
+  max-size: 2
+
+anti-runner:
+  enabled: false
+
+discord:
+  enabled: false
+  webhook-url: "YOUR_WEBHOOK_URL"
+
+database:
+  host: "localhost"
+  port: 3306
+  name: "speedhg"
+  username: "speedhg_user"
+  password: "your_password"
+  use-ssl: false
+  pool:
+    max-size: 10
+    min-idle: 2
+```
+
+### `SPEEDHG_CUSTOM_SETTINGS` Environment Variable
+
+For production overrides without touching `config.yml`, pass a JSON blob via environment variable (see [Runtime Configuration](#runtime-configuration-via-speedhg_custom_settings)).
+
+---
+
+## Kits
+
+Players select a kit in the lobby and choose a **Playstyle** (Aggressive `[AGG]` / Defensive `[DEF]`).  
+Active abilities are triggered by right-clicking the kit item. Most abilities require a configurable number of hits to charge first (`global_hits_required`, default: 15).
+
+| Kit              | Aggressive Active                                              | Defensive Active                                        | Passive (AGG)                                | Passive (DEF)                                   |
+|------------------|----------------------------------------------------------------|---------------------------------------------------------|----------------------------------------------|-------------------------------------------------|
+| **Anchor**       | Summon Iron Golem anchor — no-knock + bonus damage in radius   | ← same                                                  | Partial knockback resistance                 | Partial knockback resistance                    |
+| **Armorer**      | —                                                              | —                                                       | Strength I on kill                           | Protection I on armor                           |
+| **Backup**       | —                                                              | —                                                       | —                                            | —                                               |
+| **BlackPanther** | Wakanda Leap — leap forward, hit enemies on land               | ← same                                                  | —                                            | —                                               |
+| **Blitzcrank**   | Rocket Grab — pull nearest enemy to you                        | ← same                                                  | —                                            | —                                               |
+| **Gladiator**    | Sky arena 1v1 duel (glass cage, Wither IV after 180 s)         | ← same                                                  | —                                            | —                                               |
+| **Goblin**       | Steal enemy kit for 60 s                                       | Spawn a bunker for cover                                | —                                            | —                                               |
+| **IceMage**      | Ice Spike Burst — cone of freezing projectiles                 | Freeze Burst — 16 snowballs in circle                   | Speed in cold biomes, slowness chance on hit | 33 % slowness proc on being hit                 |
+| **Ninja**        | Vanish + backstab: teleport behind last-hit enemy              | Shadow Step: teleport to nearest enemy                  | Last-hit tracking                            | —                                               |
+| **Puppet**       | Puppet Trap — summon entity traps                              | ← similar                                               | —                                            | —                                               |
+| **Rattlesnake**  | Pounce — sneak-charge then leap, applies Poison II             | —                                                       | Poison II on pounce hit                      | 25 % reflect Poison II on being hit             |
+| **Spielo**       | —                                                              | —                                                       | —                                            | —                                               |
+| **Tesla**        | Lightning strike AoE                                           | ← same                                                  | —                                            | Knock-back + ignite reflect on being hit        |
+| **TheWorld**     | Shockwave + 3× Blink forward                                   | Shockwave + Freeze nearby enemies (10 s, 5-hit cap)     | —                                            | Frozen enemies have a 5-hit break cap           |
+| **Trident**      | Dive — launch up, lightning on landing (charge-based)          | —                                                       | —                                            | Parry — chance to bounce + Slowness on attacker |
+| **Venom**        | Venom Blast — Blindness I + Wither I + 2 hearts instant damage | Barrier — absorbs up to 15 damage, reflects projectiles | —                                            | —                                               |
+| **Voodoo**       | Curse — apply Glowing + delayed damage to nearby enemies       | ← similar                                               | 20 % Wither proc on hit                      | Speed + Regen while cursed enemies are nearby   |
+
+### Kit Item
+
+Each kit provides its signature item in the player's inventory at game start. Items are tracked in `cachedItems` (UUID → `List<ItemStack>`) and cleaned up on `onRemove`.
+
+---
+
+## Perks
+
+Players may equip **up to 2 Perks** before the round starts. Selections are persisted to the database per-player UUID.
+
+| Perk              | Effect                                                                              |
+|-------------------|-------------------------------------------------------------------------------------|
+| **Adrenaline**    | Dropping below 3 hearts → Speed II for 5 s (30 s cooldown)                          |
+| **Berserker**     | Below 4 hearts → deal 15 % more melee damage                                        |
+| **Bloodlust**     | On kill: Speed I + Regen I for 5 s                                                  |
+| **Enderblood**    | Ender Pearl landings deal no fall damage                                            |
+| **Evasion**       | 15 % chance to dodge incoming projectiles                                           |
+| **Featherweight** | Full immunity to fall damage                                                        |
+| **Ghost**         | Invisible to compass tracking and the Oracle perk                                   |
+| **Gourmet**       | Consuming soup → Regen I + Speed I for 2 s                                          |
+| **Last Stand**    | Taking damage below 3 hearts → Resistance II + Absorption I for 4 s (60 s cooldown) |
+| **Momentum**      | Sprint for 4 s without combat → Speed I                                             |
+| **Oracle**        | Shows kit + distance to the nearest enemy on sneak / compass                        |
+| **Pyromaniac**    | Immune to fire, lava, magma blocks, and burn ticks                                  |
+| **Scavenger**     | Every kill drops an extra Golden Apple at the corpse                                |
+| **Vampire**       | 10 % chance on melee hit to heal ½ heart                                            |
+
+---
+
+## Commands
+
+| Command                                    | Alias            | Permission              | Description                       |
+|--------------------------------------------|------------------|-------------------------|-----------------------------------|
+| `/kit <name> <playstyle>`                  | —                | —                       | Select a kit via command          |
+| `/kitinfo <id>`                            | `/perkinfo <id>` | —                       | Show name + lore of a kit or perk |
+| `/perks`                                   | —                | —                       | Open the Perk Selector GUI        |
+| `/leaderboard`                             | —                | —                       | View the top 10 players           |
+| `/timer <time>`                            | —                | `speedhg.admin.timer`   | Change the current game timer     |
+| `/ranking <toggle\|status\|rank [player]>` | —                | `speedhg.admin.ranking` | Manage the ranking system         |
+| `/help`                                    | —                | —                       | Show the help screen              |
+
+---
+
+## Permissions
+
+| Node                    | Default | Description                    |
+|-------------------------|---------|--------------------------------|
+| `speedhg.bypass`        | `false` | Join while the game is running |
+| `speedhg.admin.timer`   | `op`    | Change the game timer          |
+| `speedhg.admin.ranking` | `op`    | Manage ranking                 |
+| `speedhg.admin.staff`   | `false` | Staff flag for Lunar Client    |
+
+---
+
+## Architecture
+
+```
+SpeedHG (main class)
+├── GameManager          – state machine, game loop, compass, win check
+├── KitManager           – kit registry, player selections, hit-charge state
+├── PerkManager          – perk registry, player selections, DB persistence
+├── KitEventDispatcher   – single Listener delegating all kit events
+├── PerkEventDispatcher  – single Listener delegating all perk events
+├── ScoreboardManager    – sidebar scoreboard
+├── TablistManager       – tab list (Lunar Client / Volcano rank)
+├── AntiRunningManager   – cave-aware anti-runner detection
+├── DisasterManager      – periodic in-game disasters
+├── FeastManager         – mid-game feast event
+├── PitManager           – pit event
+├── RankingManager       – ELO / rank logic
+├── StatsManager         – kill/death/win tracking (MySQL)
+├── DatabaseManager      – HikariCP connection pool
+├── LanguageManager      – MiniMessage i18n
+├── LunarClientManager   – Lunar Client waypoints, scoreboard
+├── DiscordWebhookManager– post-game Discord messages
+├── WorldManager         – map archive extraction & world loading
+├── DataPackManager      – biome overrides via datapack
+└── CustomGameManager    – SPEEDHG_CUSTOM_SETTINGS JSON parsing
+```
+
+### Thread Safety
+
+All per-player state maps use `ConcurrentHashMap`. `BukkitTask` references are canceled and removed in every `onRemove` / `onDeactivate` hook.
+
+### Kit Charge System
+
+When a player's kit is applied, a `PlayerChargeData` object is stored in `KitManager`. Each confirmed melee hit (≥ 90 % attack strength) increments the charge counter. When it reaches `hitsRequired`, the state transitions to `READY` and the player receives an ActionBar notification. Hitting right-click with the ability item triggers `ActiveAbility.execute()` and resets the charge.
+
+`hitsRequired` priority: **kit-specific override** > **global_hits_required** > **hardcoded default**.  
+Kits that use an internal cooldown instead (e.g. TridentKit Dive) set `hardcodedHitsRequired = 0`.
+
+---
+
+## Adding a New Kit
+
+1. Create `src/main/kotlin/.../kit/impl/YourKit.kt` extending `Kit()`.
+2. Implement all abstract members (`id`, `displayName`, `lore`, `icon`, `cachedItems`, `giveItems`, `getActiveAbility`, `getPassiveAbility`).
+3. Create `private inner class` for each ability (Active & Passive, for each Playstyle).
+4. Put magic numbers in a `companion object` with `UPPER_SNAKE_CASE` constants.
+5. Wire configurable values through `override().getLong("key") ?: DEFAULT_*`.
+6. Add language keys under `kits.<id>.*` in `src/main/resources/languages/en_US.yml`.
+7. Register in `SpeedHG.registerKits()`:
+   ```kotlin
+   kitManager.registerKit( YourKit() )
+   ```
+
+---
+
+## Adding a New Perk
+
+1. Create `src/main/kotlin/.../perk/impl/YourPerk.kt` extending `Perk()`.
+2. Implement `id`, `displayName`, `lore`, `icon`.
+3. Override only the event hooks you need (`onActivate`, `onDeactivate`, `onHitEnemy`, etc.).
+4. Clean up all state in `onDeactivate`.
+5. Add language keys under `perks.<id>.*` in `en_US.yml`.
+6. Register in `SpeedHG.registerPerks()`:
+   ```kotlin
+   perkManager.registerPerk( YourPerk() )
+   ```
+
+---
+
+## Runtime Configuration via `SPEEDHG_CUSTOM_SETTINGS`
+
+Pass a JSON blob as an environment variable to override game and kit settings without redeploying:
+
+```json
+{
+  "game": {
+    "min_players": 4,
+    "lobby_time": 45,
+    "invincibility_time": 60,
+    "border_start": 500.0,
+    "border_end": 50.0,
+    "border_shrink_time": 720
+  },
+  "kits": {
+    "global_hits_required": 12,
+    "kits": {
+      "ninja": {
+        "hits_required": 10,
+        "extras": {
+          "cooldown_ms": 8000,
+          "backstab_damage": 6.0
+        }
+      },
+      "gladiator": {
+        "arena_radius": 11,
+        "arena_height": 7,
+        "wither_after_seconds": 180
+      },
+      "trident": {
+        "extras": {
+          "max_dive_charges": 3,
+          "sequence_cooldown_ms": 12000,
+          "lightning_radius": 4.0,
+          "lightning_damage": 4.0,
+          "parry_chance": 0.35,
+          "parry_slowness_ticks": 60
+        }
+      }
+    }
+  }
+}
+```
+
+Kit-level `extras` keys are free-form strings resolved at runtime via `KitOverride.getLong()`, `.getInt()`, and `.getDouble()` with the kit's own hardcoded defaults as fallback.
+
+---
+
+*McScrims Network · play.mcscrims.club*