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

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