MSRdungeons

MSRDungeons

MSRDungeons is a Paper/Purpur plugin for resettable wave-based dungeons with MythicMobs integration, team participation rules, rewards, cooldowns, and schematic restore.

Built for Minecraft 1.21.x.

Features

- Dungeon lifecycle states: - `IDLE`, `WAITING`, `ACTIVE`, `COMPLETED`, `FAILED`, `RESETTING`, `COOLDOWN` - Manual dungeon start/stop/reset commands - Entry window before run starts (participant lock after timer) - Wave system from config (including boss as regular MythicMob wave) - MythicMobs spawn tracking by UUID - Team rules: - only participants can damage dungeon mobs - participants leaving active region fails the run - disconnect during active run counts as death - Tier behavior: - `EASY`: dead player is removed, others continue - `HARDCORE`: one death fails the whole team - Time limit per dungeon (`timeLimitSeconds`) - Rewards on success: - command rewards with `%player%` - token rewards stored in `players.yml` - Full reset flow: - teleport participants to safe location - remove remaining tracked mobs - restore schematic - clear runtime state - apply cooldown

Runtime Region Behavior

Inside dungeon region:

- When dungeon is not running (`WAITING` or `ACTIVE`): - players get normal survival interaction (build/use/interact) - When dungeon is not running: - build and interactions are blocked - PvP is allowed

Dependencies

Required

- MythicMobs (mob spawning) - WorldGuard (region checks)

Required for schematic restore

- WorldEdit or FAWE

Installation

1. Install dependencies on your Paper/Purpur server. 2. Put `MSRDungeons-<version>.jar` into `plugins/`. 3. Start server once. 4. Configure: - `plugins/MSRDungeons/config.yml` - `plugins/MSRDungeons/schematics/<your_file>.schem` 5. Reload plugin: - `/msrdungeons reload`

Commands

- `/msrdungeons reload` - `/msrdungeons start <id>` - `/msrdungeons stop <id>` - `/msrdungeons reset <id>` - `/msrdungeons cooldown <id>` - `/msrdungeons info <id>` - `/msrdungeons tokens [player]`

Aliases: - `/msrd` - `/msrdungeon`

Permissions

- `msrdungeons.admin.reload` - `msrdungeons.admin.start` - `msrdungeons.admin.stop` - `msrdungeons.admin.reset` - `msrdungeons.admin.cooldown` - `msrdungeons.admin.info` - `msrdungeons.tokens`

Config Example

```yml dungeons: crypt_01: displayName: "Forgotten Crypt" tier: EASY region: "crypt_01_region" schematic: "crypt_01.schem" entryWindowSeconds: 45 timeLimitSeconds: 600 cooldownSeconds: 3600 minPlayers: 1 maxPlayers: 5 allowBlockBreak: true allowBlockPlace: true

startLocation: world: "world" x: 100 y: 64 z: 100

safeLocation: world: "world" x: 120 y: 64 z: 120

spawnPoints: spawn_1: world: "world" x: 105 y: 64 z: 105 spawn_2: world: "world" x: 110 y: 64 z: 110 boss_spawn: world: "world" x: 115 y: 64 z: 115

rewards: tokens: 20 commands: - "eco give %player% 100" - "give %player% diamond 2"

tokenRewards: defaultPerKill: 0 byMob: CryptZombie: 1 CryptSkeleton: 2 CryptLord: 10

waves: 1: delaySeconds: 3 mobs: - mythicMob: "CryptZombie" amount: 8 spawnPoints: ["spawn_1", "spawn_2"] 2: delaySeconds: 5 mobs: - mythicMob: "CryptSkeleton" amount: 6 spawnPoints: ["spawn_1", "spawn_2"] 3: delaySeconds: 10 mobs: - mythicMob: "CryptLord" amount: 1 spawnPoint: "boss_spawn" ```

Notes: - `spawnPoints` (list) is supported and recommended. - Legacy single `spawnPoint` is still supported.

Configuration Reference

Root

- `dungeons`: map of dungeon IDs. - Example ID: `crypt_01` - This ID is used in commands (`/msrdungeons start crypt_01`)

Dungeon Basic Settings

- `displayName` Name shown in plugin messages.

- `tier` One of: - `EASY` - `HARDCORE`

- `region` WorldGuard region ID used for dungeon boundary checks.

- `schematic` File name inside `plugins/MSRDungeons/schematics/`. - Example: `crypt_01.schem`

- `entryWindowSeconds` Time before participants are locked and run starts.

- `timeLimitSeconds` Total active run limit. - `0` = disabled - `>0` = fail run if time expires and enemies are still alive

- `cooldownSeconds` Per-dungeon cooldown after completion/failure.

- `minPlayers` / `maxPlayers` Participant bounds for run start.

- `allowBlockBreak` / `allowBlockPlace` Legacy toggles from earlier logic. Current runtime mode is controlled by dungeon state: - running (`WAITING`/`ACTIVE`): vanilla-like interaction - not running: protected mode

Locations

- `startLocation` Team is teleported here when run enters `ACTIVE`.

- `safeLocation` Teleport destination after completion/failure/reset.

- `spawnPoints` Named coordinates used by wave mob entries.

Rewards

- `rewards.tokens` Flat completion token reward per winner.

- `rewards.commands` Console commands run per winner. - `%player%` placeholder is supported.

Kill Token Rewards

- `tokenRewards.defaultPerKill` Fallback token reward for any dungeon mob kill not listed in `byMob`.

- `tokenRewards.byMob.<MythicMobId>` Token reward for killing that specific MythicMob.

Reward formula on completion: - `totalTokensForPlayer = rewards.tokens + sum(tokenRewards for player's kills)`

Waves

Each wave key is numeric (`1`, `2`, `3`, ...).

- `delaySeconds` Delay before spawning that wave.

- `mobs` entries: - `mythicMob`: MythicMobs internal ID - `amount`: spawn count - `spawnPoints`: list of named spawn points (recommended) - `spawnPoint`: single point (legacy fallback)

Spawn distribution: - if `spawnPoints` has multiple values, mobs are distributed round-robin.

Configuration Patterns

1) Casual Public Dungeon

- `tier: EASY` - `entryWindowSeconds: 45-90` - `timeLimitSeconds: 900+` - `minPlayers: 1`, `maxPlayers: 6-10` - moderate waves with many weak mobs

2) Squad Challenge

- `tier: EASY` - `entryWindowSeconds: 20-40` - `timeLimitSeconds: 480-720` - `minPlayers: 3`, `maxPlayers: 5` - mixed waves, stronger elites in wave 2+

3) Hardcore Raid

- `tier: HARDCORE` - `entryWindowSeconds: 15-30` - `timeLimitSeconds: 300-480` - `minPlayers: 4`, `maxPlayers: 6` - lower mob count but high damage/survivability

State-Based Behavior

Dungeon running (`WAITING`/`ACTIVE`)

- participants are collected in entry window - participants are teleported to `startLocation` at active start - dungeon mob combat rules are enforced - active region exit by alive participant = immediate fail - after successful clear, chat shows per-player kill stats and kill token totals

Dungeon not running (`IDLE`/`COOLDOWN`)

- build/interactions are blocked in dungeon region - PvP is allowed in dungeon region

Common Misconfigurations

- Wrong MythicMob ID Symptom: wave fails to spawn, run fails. Fix: verify IDs in `plugins/MythicMobs/Mobs/*.yml`.

- Wrong region name Symptom: participants not detected, run flow breaks. Fix: ensure `region` exactly matches WorldGuard region ID.

- Missing schematic file Symptom: start fails with schematic restore error. Fix: put file in `plugins/MSRDungeons/schematics/`.

- Spawn point name typo Symptom: part of wave does not spawn. Fix: make sure every wave `spawnPoints` value exists in `spawnPoints:` map.

Notes for Admins

- On `/msrdungeons start <id>`, schematic restore is performed before opening entry window. - If a participant leaves the active dungeon region, run fails immediately. - If time limit expires while enemies are still alive, run fails.

Compatibility

- Paper 1.21.x - Purpur 1.21.x