Dungeons (Instances)

The Dungeon plugin turns any existing world map (or a region of it) into a private, timed challenge. A player (or a whole party, led by its leader) enters through a bound NPC (or the L hotkey), gets a private instance of the map region, and must kill every monster including the boss before the timer ends. Clearing a level in time grants the reward bag and unlocks the next level; clearing every level of a tier unlocks the next tier. Progress is per character and permanent.

File Location#

Data/Plugins/Dungeons/

Each dungeon ladder is its own .xml file. There is no master switch file; drop files in, remove them to retire a dungeon.

Dependencies#

How Files Are Loaded#

• The folder is scanned for *.xml at startup and on plugin reload.
• The dungeon index comes from the leading 3-digit number of the filename: 000 - Forgotten Depths.xml is dungeon 0. Valid indices are 0 to 15.
• Progress is stored by dungeon index, tier index and level index. Renaming a file to a different number, or reordering tiers / levels, changes what a player's stored clears point at.
• A file with a broken <Dungeon> root or an invalid index is skipped with a log line; the others still load.

Dungeon Structure#

<Dungeon Name="..." NpcClass="..." MinLevel="..." InstanceItemLifetimeSec="..." ClearedGraceSec="...">
  <Schedule Mode="Always|Windows">
    <Window Day="-1" StartHour="18" EndHour="22"/>
  </Schedule>
  <Tier Name="Normal">
    <Level Index="1" Map="4" SpawnX="20" SpawnY="20" TimeLimitSec="600" DeathFails="0"
           FeeZen="500000" RewardBag="1" RewardMode="inventory">
      <Area X1="2" Y1="5" X2="57" Y2="60"/>
      <Monster Class="34" Count="25" Boss="0" ItemBag="-1"/>
      <Monster Class="38" Count="1"  Boss="1" ItemBag="-1" Spot="40,45" Dis="3"/>
    </Level>
  </Tier>
</Dungeon>

Dungeon#

Schedule#

Each <Window>:

A closed schedule only blocks new entries. A run that is already in progress continues.

Tier#

Up to 3 tiers per dungeon, in ladder order. Name (23 chars) is the tab label in the browser.

Tier scaling#

Set on <Tier>; a <Level> may set any of the same keys to override its tier. Percent of the Monster.xml value, 100 = unchanged.

The party size is counted when the run starts; players who join later do not rescale the monsters. A Bosses.xml boss inside a dungeon starts its own player scaling from the dungeon-scaled values. The browser shows the scaling under Monsters and the EXP / drop bonus under Rewards.

<Tier Name="Heroic" Life="160" Damage="130" Defense="120" Exp="150" Drop="130" PartyLife="50" PartyDamage="10" PartyDrop="10">

Level#

Up to 5 levels per tier. Index must be contiguous from 1.

Area#

One or more boxes in tile coordinates. The player cannot walk outside them while in the run; map collision still applies inside. Draw one box around a whole isolated floor and no wall is ever felt.

Monster#

Important Behavior#

• Sealed teleports: inside a run, every way out except Leave is refused: map portals, the Move window (M), /move, town portal scrolls, a Dark Lord's party summon and event teleports. The player sees "Teleports are sealed during a run. Use Leave to exit." Only the level's ExitGate works. Teleport skills inside the run's areas still work. GMs are not blocked.
• Isolation: a run is a private instance channel of the real map. Other players on the same tiles are invisible to the runner and the runner's monsters, and vice versa. Aggro, area skills and item pickup all respect this.
• Progress rule (fixed): clear tier T level N in time -> level N+1 unlocks. Clear every level of tier T -> tier T+1 level 1 unlocks. Cleared levels can be run again.
• Timer expiry: no reward bag and no unlock. Everyone in the run is moved out after ExpiredGraceSec (default 15 s, time to pick up loot).
• Clear: reward is granted, the unlock is saved immediately, and the player has ClearedGraceSec to loot before being returned.
• Entry checks in order: license, valid indices, not already in a run, party leader (see below), progress loaded, schedule open, MinLevel, level unlocked, alive, server headroom, every party member, fees. The fee is charged last and refunded if the spawn fails.
• Party runs: in a party, only the leader can start a run, and the whole party goes in with them.
  • Every other member must be on the leader's map within PartyRange tiles, alive, not in another run, at MinLevel or higher, and have that level unlocked. The first member who fails stops the entry, and the leader sees who and why.
  • The leader pays the fee once for the whole party.
  • A party member outside can press Enter to join the leader's run while it is still going (same checks, without the distance, no fee).
  • Dying (with DeathFails="1"), Leave, disconnecting, warping out or leaving the party takes only that member out. The run ends for everyone when the leader leaves it.
  • On a clear, every member still inside gets the unlock and their own roll of RewardBag. Kill drops can be picked up by every party member.
  • Party EXP is only shared with members inside the same run.
• Reload: the plugin reload re-reads the folder; a run already in progress keeps a snapshot of its level and is not affected.
• Players open the browser by talking to NpcClass or with the L hotkey. The window lists lock / open / cleared state per level. The selected level shows four blocks: Dungeon (map, time limit, monsters, death rule), Monsters (tier and party scaling), Requirements (level, unlock, zen fee, fee item with have / need, party range - green border = met, red = missing) and Rewards (reward bag, EXP and drop bonus, what clearing unlocks). Every entry has a tooltip. The last entry result shows under them.

Entry Result Messages#

GM Commands#

Examples#

<?xml version="1.0" encoding="UTF-8"?>
<Dungeon Name="Spider Nest" NpcClass="253" MinLevel="10">
  <Schedule Mode="Always"/>
  <Tier Name="Normal">
    <Level Index="1" Map="0" SpawnX="140" SpawnY="130" TimeLimitSec="300" RewardBag="2">
      <Area X1="120" Y1="110" X2="170" Y2="160"/>
      <Monster Class="3" Count="20" ItemBag="-1"/>
      <Monster Class="2" Count="1" Boss="1"/>
    </Level>
    <Level Index="2" Map="0" SpawnX="140" SpawnY="130" TimeLimitSec="300" RewardBag="2">
      <Area X1="120" Y1="110" X2="170" Y2="160"/>
      <Monster Class="3" Count="40" ItemBag="-1"/>
      <Monster Class="2" Count="2" Boss="1"/>
    </Level>
  </Tier>
</Dungeon>

<?xml version="1.0" encoding="UTF-8"?>
<Dungeon Name="Night Vault" NpcClass="253" MinLevel="300" ClearedGraceSec="90">
  <Schedule Mode="Windows">
    <Window Day="-1" StartHour="19" EndHour="23"/>
  </Schedule>
  <Tier Name="Heroic">
    <Level Index="1" Map="4" SpawnX="100" SpawnY="180" TimeLimitSec="540" DeathFails="1"
           FeeZen="2000000" FeeItemType="14" FeeItemIndex="13" FeeItemCount="5"
           RewardBag="7" RewardMode="drop">
      <Area X1="80" Y1="165" X2="135" Y2="250"/>
      <Monster Class="40" Count="50"/>
      <Monster Class="49" Count="1" Boss="1" Spot="110,240" Dis="2"/>
    </Level>
  </Tier>
</Dungeon>

Common Issues#