Bukkit

commands:
  rpg:
    description: Root command. Use /rpg help for everything.
    usage: /rpg help
  class:
    description: Choose or view RPG classes.
    usage: /class [name]
  stats:
    description: View your character sheet.
    usage: /stats
  allocate:
    description: Spend stat points.
    usage: /allocate <str|dex|int|vit> [amount]
    aliases: [addstat, spend]
  skill:
    description: Cast your class skill.
    usage: /skill
    aliases: [cast]
  soul:
    description: Unleash your charged Soul.
    usage: /soul
  hud:
    description: Toggle the RPG scoreboard HUD.
    usage: /hud
  rpgitem:
    description: Generate an RPG item with random affixes.
    usage: /rpgitem <common|magic|rare|unique> [weapon|helmet|chestplate|leggings|boots]
  dungeon:
    description: Dungeon floors, parties and runs.
    usage: /dungeon help
    aliases: [dungeons, catacomb]
  party:
    description: Group up before entering a dungeon.
    usage: /party [invite|accept|leave|disband]
    aliases: [p]
  essence:
    description: View your dungeon essence.
    usage: /essence
  catacombs:
    description: View your Catacombs and role levels.
    usage: /catacombs
    aliases: [cata]
  custommob:
    description: Create and edit custom mobs.
    usage: /custommob help
    aliases: [cmob, custommobs]
  spawnregion:
    description: Create and edit timed spawn regions.
    usage: /spawnregion help
    aliases: [sregion, spawnregions]

permissions:
  # ---- Umbrellas ----------------------------------------------------------
  # Granting ss2.play or ss2.admin still grants everything below it, via
  # children, exactly as before. The nodes underneath exist for servers that
  # want to hand out one command, or one subcommand, rather than the whole set.
  ss2.play:
    description: Allows using every standard player-facing RPG command.
    default: true
    children:
      ss2.command.class: true
      ss2.command.stats: true
      ss2.command.allocate: true
      ss2.command.skill: true
      ss2.command.soul: true
      ss2.command.hud: true
      ss2.command.rpg: true
      ss2.command.dungeon: true
      ss2.command.party: true
      ss2.command.essence: true
      ss2.command.catacombs: true
      ss2.rpg.reset: true
  ss2.admin:
    description: Allows every admin RPG, dungeon-building, and custom-mob command.
    default: op
    children:
      ss2.command.rpgitem: true
      ss2.command.custommob: true
      ss2.command.spawnregion: true
      ss2.class.secret: true
      ss2.stats.others: true
      ss2.rpg.reload: true
      ss2.rpg.setlevel: true
      ss2.rpg.addxp: true
      ss2.rpg.givesoul: true
      ss2.rpg.unlock: true
      ss2.dungeon.build: true
      ss2.dungeon.save: true
      ss2.dungeon.reload: true
      ss2.custommob.view: true
      ss2.custommob.spawn: true
      ss2.custommob.edit: true
      ss2.custommob.delete: true
      ss2.spawnregion.view: true
      ss2.spawnregion.create: true
      ss2.spawnregion.edit: true
      ss2.spawnregion.delete: true

  # ---- Whole-command gates --------------------------------------------------
  ss2.command.class:
    description: Use /class to view or choose a class.
    default: true
  ss2.command.stats:
    description: Use /stats to view your own character sheet.
    default: true
  ss2.command.allocate:
    description: Use /allocate to spend stat points.
    default: true
  ss2.command.skill:
    description: Use /skill to cast your class skill.
    default: true
  ss2.command.soul:
    description: Use /soul to unleash a charged Soul.
    default: true
  ss2.command.hud:
    description: Use /hud to toggle the sidebar.
    default: true
  ss2.command.rpg:
    description: Use the /rpg root command (help and its subcommands).
    default: true
  ss2.command.rpgitem:
    description: Use /rpgitem to generate affixed gear.
    default: op
  ss2.command.dungeon:
    description: Use the /dungeon root command (help and its subcommands).
    default: true
  ss2.command.party:
    description: Use /party to group up before a run.
    default: true
  ss2.command.essence:
    description: Use /essence to view essence balances.
    default: true
  ss2.command.catacombs:
    description: Use /catacombs to view Catacombs and role levels.
    default: true
  ss2.command.custommob:
    description: Use the /custommob root command at all.
    default: op
  ss2.command.spawnregion:
    description: Use the /spawnregion root command at all.
    default: op

  # ---- /class ---------------------------------------------------------------
  ss2.class.secret:
    description: Pick the secret class without needing /rpg unlock first.
    default: op

  # ---- /stats -----------------------------------------------------------------
  ss2.stats.others:
    description: View another player's character sheet.
    default: op

  # ---- /rpg subcommands -------------------------------------------------------
  ss2.rpg.reset:
    description: Wipe your own character with /rpg reset confirm.
    default: true
  ss2.rpg.reload:
    description: Reload the plugin configuration with /rpg reload.
    default: op
  ss2.rpg.setlevel:
    description: Set another player's level with /rpg setlevel.
    default: op
  ss2.rpg.addxp:
    description: Grant XP to another player with /rpg addxp.
    default: op
  ss2.rpg.givesoul:
    description: Fully charge another player's Soul with /rpg givesoul.
    default: op
  ss2.rpg.unlock:
    description: Unlock the secret class for another player with /rpg unlock.
    default: op

  # ---- /dungeon subcommands ---------------------------------------------------
  ss2.dungeon.build:
    description: Edit dungeon floors with /dungeon set.
    default: op
  ss2.dungeon.save:
    description: Save dungeon floors to disk with /dungeon save.
    default: op
  ss2.dungeon.reload:
    description: Reload dungeon floors from disk with /dungeon reload.
    default: op

  # ---- /custommob subcommands --------------------------------------------------
  ss2.custommob.view:
    description: View custom mob definitions with /custommob list and info.
    default: op
  ss2.custommob.spawn:
    description: Spawn instances of a custom mob with /custommob spawn.
    default: op
  ss2.custommob.edit:
    description: Create and edit custom mob definitions.
    default: op
  ss2.custommob.delete:
    description: Delete custom mob definitions.
    default: op

  # ---- /spawnregion subcommands -------------------------------------------------
  ss2.spawnregion.view:
    description: View spawn regions with /spawnregion list and info.
    default: op
  ss2.spawnregion.create:
    description: Create new spawn regions.
    default: op
  ss2.spawnregion.edit:
    description: Edit existing spawn regions with /spawnregion set.
    default: op
  ss2.spawnregion.delete:
    description: Delete spawn regions.
    default: op

# ============================================================
#  ShiningSoulRPG configuration
#  Canonical Shining Soul II formulas are the defaults:
#    Max HP = VIT * 3      Max SP = INT * 2
#    Physical attack = weapon base + STR
#    +4 stat points per level, level cap 200
# ============================================================

leveling:
  max-level: 200
  stat-points-per-level: 4
  # XP needed for a level = round(base * level ^ exponent)
  xp-base: 25.0
  xp-exponent: 1.85
  # Default XP for a mob type not listed below.
  default-mob-xp: 12
  mob-xp:
    ZOMBIE: 12
    SKELETON: 14
    SPIDER: 12
    CREEPER: 20
    ENDERMAN: 45
    WITCH: 40
    BLAZE: 35
    SLIME: 8
    ZOMBIE_PIGMAN: 18
    CAVE_SPIDER: 14
    SILVERFISH: 6
    PIG: 3
    COW: 3
    SHEEP: 3
    CHICKEN: 3

stats:
  hp-per-vitality: 3.0
  sp-per-intelligence: 2.0
  attack-per-strength: 1.0
  # Bow damage scales with DEX instead of STR.
  bow-base-damage: 6.0
  fist-base-damage: 1.0

defense:
  # Flat defense contributed by each point of VIT.
  per-vitality: 1.0
  # Damage reduction % = defense / (defense + constant). Higher = softer curve.
  constant: 100.0
  # Hard cap on incoming reduction (0.85 = at most 85% mitigated).
  max-reduction: 0.85

dodge:
  # Chance to fully dodge an incoming melee/projectile hit, per point of DEX.
  per-dexterity: 0.0025
  cap: 0.6

crit:
  base-chance: 0.05
  per-dexterity: 0.0015
  cap: 0.75
  multiplier: 2.0

regen:
  # Applied once per second.
  sp-per-second: 1.0
  # Out-of-combat only.
  hp-per-second: 2.0
  combat-tag-seconds: 6

soul:
  charge-per-hit: 3
  charge-per-kill: 10
  max-charge: 100
  base-damage: 25.0
  per-intelligence: 1.25
  radius: 6.0

skills:
  # cost = SP cost, cooldown in seconds.
  warrior:
    cost: 8
    cooldown: 6
    radius: 4.5
    damage-mult: 1.5
  archer:
    cost: 10
    cooldown: 8
    arrows: 5
    speed: 2.6
  sorceress:
    cost: 12
    cooldown: 5
    range: 18.0
    base-damage: 10.0
    int-mult: 1.5
  ninja:
    cost: 8
    cooldown: 7
    radius: 3.5
  dragonute:
    cost: 12
    cooldown: 9
    radius: 5.0
    damage-mult: 1.4
  priestess:
    cost: 14
    cooldown: 8
    radius: 6.0
    base-heal: 15.0
    int-mult: 2.0
  dark_wizard:
    cost: 20
    cooldown: 12
    radius: 6.0
    base-damage: 12.0
    int-mult: 2.0

mobs:
  # Shining Soul-style PvE: monsters get a level, an element and a rank,
  # which scale their health, damage, XP and loot.
  enabled: true
  # Only scale genuine hostiles. Leave true unless you really want leveled
  # cows and villagers; armor stands and tamed pets are always excluded.
  hostile-only: true
  # Monster level comes from distance to world spawn (i.e. "dungeon depth").
  min-level: 1
  max-level: 100
  blocks-per-level: 150.0
  # Random +/- variation so an area isn't perfectly uniform.
  level-jitter: 2
  # Health multiplier added per level, and a hard ceiling.
  hp-per-level: 0.09
  max-health: 800.0
  # A monster's own attack replaces the vanilla damage figure.
  base-damage: 4.0
  damage-per-level: 0.85
  # Extra XP per monster level.
  xp-per-level: 0.18
  # Chance a monster has an element at all (rest are Physical).
  element-chance: 0.45
  # Fire > Ice > Thunder > Fire, and Light <-> Dark.
  strong-multiplier: 1.5
  weak-multiplier: 0.7
  # Global scaling on loot drop chance (Elite 16%, Champion 45%, Boss 100%).
  drop-multiplier: 1.0
  show-names: true
  # Float the name above Elites and up at all times.
  names-always-visible: false
  # Also rename ordinary trash mobs (off by default to reduce clutter).
  name-normal-mobs: false

catacombs:
  # Dungeon progression, tracked separately from your RPG level.
  max-level: 50
  xp-base: 60.0
  xp-exponent: 1.75
  # Each dungeon role (Healer/Mage/Berserk/Archer/Tank) levels on its own.
  role-max-level: 50
  role-xp-base: 40.0
  role-xp-exponent: 1.70

database:
  # Where custom mobs and spawn regions are stored.
  # sqlite needs no setup; the file lives in this plugin's folder.
  type: sqlite
  sqlite:
    file: data.db
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    user: root
    password: ''

spawner:
  # Timed spawning of custom mobs inside regions.
  enabled: true
  # Spawning pauses entirely while TPS sits below this, so the spawner can
  # never be the thing that keeps a struggling server down.
  min-tps: 17.0
  # Hard ceiling on live region-spawned mobs across the whole server.
  global-cap: 200
  # Only this many regions are examined per second, so hundreds of regions
  # cost the same per tick as a handful.
  regions-per-cycle: 8

hud:
  # Show the sidebar by default for new players.
  default-enabled: true
  title: "&6&lShining Soul &eII"

messages:
  prefix: "&6&lSS2&r &8» &7"

# ShiningSoulRPG - dungeon floors
#
# Floors run on regions YOU build. Nothing here is generated, so the workflow is:
#
#   1. Build the floor somewhere (its own world is cleanest).
#   2. Stand at each point and run the setup commands:
#
#        /dungeon set F1 corner1          (stand at one corner of the region)
#        /dungeon set F1 corner2          (stand at the opposite corner)
#        /dungeon set F1 entrance         (where the party spawns in)
#        /dungeon set F1 exit             (where they are sent afterwards)
#        /dungeon set F1 boss             (boss + Gravekeeper arena)
#        /dungeon set F1 addspawn         (repeat at each monster spawn point)
#        /dungeon set F1 addsecret        (repeat at each hidden secret)
#        /dungeon set F1 mobtypes ZOMBIE,SKELETON,SPIDER
#        /dungeon set F1 moblevel 25
#
#   3. /dungeon save
#
# Every change saves automatically, so this file mostly documents itself once
# you've set a floor up in-game.
#
# Monster names come from the floor id: ENTRANCE, F1..F7 each have their own
# themed name pool (Bone Sentinel, Drowned Cantor, Shadow Reaver and so on).
# Ranks inside dungeons read as Greater / Dread / Warden rather than the
# overworld's Elite / Champion / Boss.

floors:
  ENTRANCE:
    display-name: 'The Threshold'
    master-mode: false
    region:
      world: world
      x1: 0.0
      y1: 0.0
      z1: 0.0
      x2: 0.0
      y2: 0.0
      z2: 0.0
    required-level: 5
    required-catacombs-level: 0
    max-party-size: 5
    mobs:
      level: 8
      waves: 3
      per-wave: 5
      types:
        - ZOMBIE
        - SKELETON
    boss:
      type: ZOMBIE
      name: 'Ossuary Warden'
      level: 15
      hp-multiplier: 1.5
    rewards:
      par-time-seconds: 240
      time-limit-seconds: 900
      essence-type: UNDEAD
      essence: 5
      catacombs-xp: 60

  F1:
    display-name: 'Bone Halls'
    master-mode: false
    region:
      world: world
      x1: 0.0
      y1: 0.0
      z1: 0.0
      x2: 0.0
      y2: 0.0
      z2: 0.0
    required-level: 15
    required-catacombs-level: 2
    max-party-size: 5
    mobs:
      level: 20
      waves: 5
      per-wave: 6
      types:
        - SKELETON
        - ZOMBIE
    boss:
      type: SKELETON
      name: 'Marrowlord Kaeth'
      level: 32
      hp-multiplier: 2.0
    rewards:
      par-time-seconds: 300
      time-limit-seconds: 1200
      essence-type: UNDEAD
      essence: 10
      catacombs-xp: 120

# ShiningSoulRPG

A Spigot plugin that recreates the core RPG mechanics of **Shining Soul II** (Game
Boy Advance, Sega) — classes, the four core stats, stat-point leveling, custom
stat-based combat, class skills, random item affixes, and the chargeable **Soul**
gauge — all rendered on a live sidebar HUD.

It is built against the **Spigot 1.8.8 API** with **no NMS**, so it stays portable.

Players who have **not** chosen a class stay 100% vanilla (lobby-friendly). Once a
player runs `/class`, RPG mechanics switch on for them.

### The four stats (Shining Soul II canon)

| Stat | Effect |
|------|--------|
| **STR** Strength | +1 physical attack per point |
| **DEX** Dexterity | hit chance, dodge/evasion, and bow damage |
| **INT** Intelligence | spell/skill damage and **SP** (Soul Power / mana) |
| **VIT** Vitality | **HP** and defense |

Derived pools use the game's own formulas: **Max HP = VIT × 3** and
**Max SP = INT × 2**.

### Leveling

Kill mobs to earn XP (the vanilla green XP bar is repurposed to show your RPG
level and progress). Each level grants **+4 stat points** (spend with `/allocate`).
Level cap is **200**. XP curve, per-mob XP, and everything below are tunable in
`config.yml`.

### Health model

Your real HP pool is tracked by the plugin; the heart bar is a proportional
mirror, so the HUD can show true numbers like `HP 128 / 150` while hearts still
animate on hit. Incoming damage is run through **dodge** (DEX) then **defense**
(VIT + gear), replacing vanilla armor mitigation entirely.

### Classes

| Class | STR/DEX/INT/VIT | Signature skill |
|-------|-----------------|-----------------|
| Warrior | 15/15/5/15 | Whirlwind (melee AoE) |
| Archer | 12/18/8/12 | Arrow Volley (arrow spread) |
| Sorceress | 9/9/23/9 | Blaze (targeted fire nuke) |
| Ninja | 12/16/12/10 | Shadow Step (dash + strike) |
| Dragonute | 16/8/6/18 | Ground Slam (AoE + knock-up + resist) |
| Priestess | 9/10/18/13 | Heal (self + allies) |
| Dark Wizard *(secret)* | 12/12/28/12 | Dark Nova (AoE dark nuke) |

The Dark Wizard is unlockable only via `/rpg unlock <player>`.

### Skills & the Soul

Cast your class skill with `/skill` **or by sneaking and right-clicking**. Skills
cost SP and have cooldowns.

Defeating enemies charges your **Soul** gauge. At 100% use `/soul` to unleash a
big elemental AoE blast that scales with INT.

### Monsters (PvE)

Vanilla mobs are converted into Shining Soul-style monsters. Every spawn gets:

- **A level**, derived from its distance to world spawn. This stands in for
  dungeon depth: the further out you fight, the deadlier the monsters and the
  better the rewards. Default is one level per 150 blocks, capped at 100.
- **An element** (45% of the time). Elemental advantage runs
  **Fire > Ice > Thunder > Fire**, with **Light and Dark** strong against each
  other. Hitting a weakness deals 1.5x; hitting a resistance deals 0.7x. This
  applies to both melee and skills, so class element matters when picking fights.
- **A rank**, which multiplies its health, damage, XP and drop chance:

| Rank | HP | Damage | XP | Drop chance |
|------|----|--------|----|-------------|
| Normal | 1x | 1x | 1x | 3% |
| Elite | 2.1x | 1.35x | 2.2x | 16% |
| Champion | 4x | 1.8x | 4.5x | 45% |
| Boss | 9x | 2.5x | 12x | 100% |

Elites and above are renamed (e.g. `[Lv34] Champion Zombie`) with the rank and
element colored in. Rare ranks get more common the deeper you go.

A monster's own level and rank set the damage it deals, replacing the vanilla
figure entirely, and its loot rolls through the same affix system as `/rpgitem`
with rarity weighted by rank and depth. Turn the whole system off with
`mobs.enabled: false` if you only want the player-side mechanics.

### Items & affixes

`/rpgitem <rarity> [slot]` generates gear with random affixes. Rarity
(Common → Magic → Rare → Unique) controls how many affixes roll. Bonuses are
written into the item's lore in a fixed format and read back when the item is
equipped, so **what you see on the tooltip is exactly what you get** — no NBT.
Affixes include the four stats, Defense, Max HP, Max SP, Critical Chance,
Life Steal, and elemental damage.

---

## Dungeons

A Catacombs-style dungeon layer sits on top of the RPG. Floors are **regions you
build yourself** rather than generated geometry, so the plugin owns the mechanics
and you own the architecture.

### Setting a floor up

Build the floor, then stand in each spot and run:

```
/dungeon set F1 corner1        # opposite corners of the region
/dungeon set F1 corner2
/dungeon set F1 entrance       # where the party spawns in
/dungeon set F1 exit           # where they land afterwards
/dungeon set F1 boss           # Gravekeeper + boss arena
/dungeon set F1 addspawn       # repeat at each monster spawn
/dungeon set F1 addsecret      # repeat at each hidden secret
/dungeon set F1 mobtypes ZOMBIE,SKELETON,SPIDER
/dungeon set F1 moblevel 25
/dungeon save
```

Every change saves immediately. `ENTRANCE` and `F1` ship pre-filled apart from
coordinates.

### Running one

`/party invite <player>` to group up (max 5), `/dungeon role <role>` to pick a
role, then the leader runs `/dungeon enter F1`.

A run goes: **waves** -> **the Gravekeeper** guarding the Blood Door -> **the
floor boss**. Clearing a wave spawns the next; killing the Gravekeeper opens the
door; killing the boss ends the run.

### Monsters

Dungeon monsters use exactly the same machinery as overworld ones (level,
element, rank, elemental advantage) but never reuse their names. Each floor has
its own themed pool, and ranks read differently:

| | Overworld | Dungeon |
|---|---|---|
| Rank names | Elite / Champion / Boss | Greater / Dread / Warden |
| Level source | distance from spawn | set per floor |

Floor pools: Threshold (Tomb Rat, Dust Shade), F1 Bone Halls (Bone Sentinel,
Marrow Knight), F2 Flooded Crypts (Drowned Cantor, Tidecaller), F3 Ember Vaults
(Cinder Warden, Emberfang), F4 Frostbound (Rime Warden, Glacier Fiend), F5 Shadow
Sanctum (Shadow Reaver, Nightbinder), F6 Thunder Spire (Storm Herald, Voltaic
Wraith), F7 Soul Throne (Soul Devourer, Wraith Sovereign).

### Roles

Picked per run and levelled separately from your class, which still decides your
skill and stats:

| Role | Effect |
|------|--------|
| Healer | Passive party regen, much faster revives |
| Mage | Cheaper skills |
| Berserk | +25% melee, takes more damage |
| Archer | +30% ranged |
| Tank | Heavy damage reduction |

### Downed, not dead

A lethal blow inside a dungeon downs you instead of killing you: you go
untargetable and immobile until a party member stands nearby long enough to
revive you. Each death costs 8 Skill score.

### Score and rewards

Four components as in Catacombs: **Skill** (clearing, minus deaths), **Explore**
(secrets found), **Speed** (against par time) and **Bonus** (no deaths, all
secrets, inside the limit). Totals map to **S+ / S / A / B / C / D**, and the
grade multiplies the payout: **Essence** (`/essence`), **Catacombs XP**
(`/catacombs`), role XP, and a loot roll weighted toward higher rarities.

Master mode (`/dungeon set <floor> master`) doubles monster level and rewards.

## Custom mobs and timed spawning

Monsters can be designed in-game and stored in a database, then used either as
dungeon floor rosters or spawned on a timer inside a region.

### Designing a mob

```
/custommob create bone_archer
/custommob edit bone_archer name &fBone Archer
/custommob edit bone_archer type SKELETON
/custommob edit bone_archer level 30
/custommob edit bone_archer element ICE
/custommob edit bone_archer tier ELITE
/custommob edit bone_archer health 240
/custommob edit bone_archer damage 12
/custommob edit bone_archer equip weapon BOW
/custommob edit bone_archer equip helmet IRON_HELMET
/custommob edit bone_archer effect add SPEED:1
/custommob edit bone_archer drop add BONE:3:0.5
/custommob edit bone_archer lootchance 0.2
/custommob spawn bone_archer 5
```

`/custommob list`, `info`, `delete` round it out. Health or damage of **0** means
"derive from level and tier", so you only override what you care about. Custom
mobs run through the same scaling as everything else, so elements, ranks,
dodge and defence all behave consistently.

### Timed region spawning

```
/spawnregion create graveyard
/spawnregion set graveyard corner1        # stand at one corner
/spawnregion set graveyard corner2        # and the opposite one
/spawnregion set graveyard addmob bone_archer 3
/spawnregion set graveyard addmob crypt_ghoul 1
/spawnregion set graveyard time 13000 23000   # night only
/spawnregion set graveyard interval 45
/spawnregion set graveyard maxalive 10
/spawnregion set graveyard batch 3
/spawnregion set graveyard radius 64
```

The mob table is weighted, so `bone_archer 3` appears three times as often as a
weight-1 entry. Use `time any` for round-the-clock spawning; night is roughly
13000-23000.

### How it stays cheap

The spawner is built so that adding regions doesn't degrade the server:

- **Nothing spawns unless a player is within the activation radius**, so a
  distant region costs one distance check per cycle and nothing else.
- **Per-region cap** (`maxalive`) and **per-cycle batch cap** (`batch`) bound
  how much can ever exist or appear at once.
- **Global cap** (`spawner.global-cap`, default 200) bounds the total across
  every region.
- **TPS backoff**: spawning pauses entirely below `spawner.min-tps` (default
  17), so the spawner can never be what keeps a struggling server down.
- **Only loaded chunks** are used as spawn targets, so spawning never pulls
  terrain into memory, and points inside solid blocks are rejected rather than
  suffocating a mob and wasting a cap slot.
- **Round-robin**: only `spawner.regions-per-cycle` regions are examined per
  second, so a hundred regions cost the same per tick as eight.
- Region mobs are allowed to **despawn naturally** once players leave.
- Definitions are **cached in memory**; spawning never touches the database,
  and edits are written back on an async thread.

### Custom mobs in dungeons

Give a floor a roster and it uses those instead of plain entity types, keeping
each floor's dungeon naming and rank titles:

```yaml
floors:
  F1:
    mobs:
      custom:
        - bone_archer
        - crypt_ghoul
    boss:
      custom-mob: marrowlord
```

### Storage

SQLite by default with no setup required (`data.db` in the plugin folder), or
MySQL via the `database` section of config.yml. If the JDBC driver is missing,
storage disables itself with a console warning and the rest of the plugin keeps
working normally.

## Commands

| Command | Description |
|---------|-------------|
| `/class [name]` | Choose or list classes |
| `/stats` | Your character sheet |
| `/allocate <str\|dex\|int\|vit> [amount]` | Spend stat points |
| `/skill` (`/cast`) | Cast your class skill |
| `/soul` | Unleash a fully charged Soul |
| `/hud` | Toggle the sidebar |
| `/rpg help` | Full command list |
| `/dungeon` | Floors, roles, entering, live score |
| `/party` | Group up before a run |
| `/catacombs` | Catacombs and role levels |
| `/essence` | Essence balances |
| `/custommob` | Create and edit custom mobs (admin) |
| `/spawnregion` | Create and edit spawn regions (admin) |

**Admin** (`ss2.admin`, default op):
`/rpgitem <rarity> [slot]`, `/rpg setlevel <player> <lvl>`,
`/rpg addxp <player> <amt>`, `/rpg givesoul <player>`, `/rpg unlock <player>`,
`/rpg stats <player>`, `/rpg reload`.

`/rpg reset confirm` wipes your own character.

Permissions: `ss2.play` (default true) and `ss2.admin` (default op).

---

## Quick start

1. `/class warrior`
2. `/stats` to see your sheet
3. Kill mobs to level up, then `/allocate str 4`
4. `/skill` (or sneak + right-click) to use your ability
5. Charge and fire `/soul`
6. `/rpgitem rare weapon` to try the item system
7. Travel away from world spawn to find higher-level monsters, Elites and Bosses

---

## Version range

The plugin avoids NMS entirely and every enum family that Mojang renamed is
resolved defensively at runtime, so a single build covers the range:

- **Sounds** - resolved by name with fallbacks (`util/Compat.java`), because
  every sound constant was renamed in 1.9.
- **Potion effects** - also resolved by name, covering the 1.20.5 renames
  (`SLOW` to `SLOWNESS`, `DAMAGE_RESISTANCE` to `RESISTANCE`).
- **Materials** - both naming eras are registered (`WOOD_SWORD` and
  `WOODEN_SWORD`, `GOLD_*` and `GOLDEN_*`), and names missing on the running
  server are skipped, so weapon damage tables work either way.
- **No `api-version`** in plugin.yml. That field was introduced in 1.13 and only
  accepts 1.13 or higher, so declaring one would break loading on the 1.8 floor.
  Omitting it makes modern servers load the plugin in legacy mode, which suits
  the 1.8-era names. Expect a "legacy plugin" warning in the console on 1.13+;
  that is normal and harmless.
- **API level** - bump `<spigot.version>` in `pom.xml` if you want to compile
  against a newer API for newer server features.

---

## Config highlights

All numbers live in `config.yml`: the XP curve (`xp-base`, `xp-exponent`), per-mob
XP, stat scaling (`hp-per-vitality`, `sp-per-intelligence`), defense/dodge/crit
curves, regen rates, Soul charge/damage, and per-class skill cost/cooldown/power.
Edit and run `/rpg reload`.