# instance-dungeons

> Develops instanced dungeon systems with progression, stage-based combat, and rewards.
Use when: creating new dungeons, modifying stage behavior, configuring time windows, adding rewards, debugging dungeon entry/progression, or integrating instance isolation.

- Author: valeriybaranyshyn-pixel
- Repository: valeriybaranyshyn-pixel/Tales-of-Aden
- Version: 20260202145225
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/valeriybaranyshyn-pixel/Tales-of-Aden
- Web: https://mule.run/skillshub/@@valeriybaranyshyn-pixel/Tales-of-Aden~instance-dungeons:20260202145225

---

---
name: instance-dungeons
description: |
  Develops instanced dungeon systems with progression, stage-based combat, and rewards.
  Use when: creating new dungeons, modifying stage behavior, configuring time windows, adding rewards, debugging dungeon entry/progression, or integrating instance isolation.
allowed-tools: Read, Edit, Write, Glob, Grep, Bash
---

# Instance Dungeons Skill

Implements time-gated, VIP-exclusive instanced PvE dungeons with multi-stage progression. Uses template-based design from XML, shared instancing from tournament system, and database tracking for per-time-window cooldowns.

## Quick Start

### Adding a New Dungeon (XML Only)

```xml
<!-- Files/game/data/xml/dungeons.xml -->
<dungeon id="3" name="Elite Challenge" players="2" rewards="6622,5;57,100000" rewardHtm="NULL">
    <stage order="1" loc="173192,-85688,-7216" teleport="true" minutes="5">
        <mob npcId="501" locs="173656,-86216,-7216;173704,-85736,-7216"/>
    </stage>
    <stage order="2" loc="173192,-76554,-7219" teleport="true" minutes="3">
        <mob npcId="502" locs="173368,-77144,-7216;173592,-77128,-7216"/>
    </stage>
</dungeon>
```

### Configuring Time Windows

```properties
# Files/game/config/events/DungeonEvent.properties
DungeonEventEnabled = true
DungeonEventInterval = 14:00,18:00,22:00
DungeonDurationMinutes = 30
```

## Key Concepts

| Concept | Purpose | File |
|---------|---------|------|
| `DungeonTemplate` | Immutable dungeon definition (stages, rewards, player count) | `dungeon/DungeonTemplate.java` |
| `DungeonStage` | Single stage config (mobs, location, time limit) | `dungeon/DungeonStage.java` |
| `Dungeon` | Active session state machine (spawning, timers, rewards) | `dungeon/Dungeon.java` |
| `DungeonManager` | Singleton orchestrating lifecycle, entry validation, DB sync | `dungeon/DungeonManager.java` |
| `InstanceHolder` | Isolates dungeon players from main world | `event/tournament/InstanceHolder.java` |

## Common Patterns

### Entry Flow

```
Player → L2DungeonManagerInstance (NPC) → DungeonManager.enterDungeon()
    ├── Validate: VIP, time window, party size, cooldown
    ├── Create Dungeon instance with template
    ├── Create InstanceHolder via InstanceManager
    └── Mark players: player.setDungeon(this)
```

### Stage Progression Flow

```
beginTeleport() → 10s countdown → teleportPlayers() → beginStage()
    ├── Spawn L2DungeonMobInstance mobs
    ├── Start timer display (bottom-right)
    ├── Schedule cancel task (timeout = fail)
    └── onMobKill() → all dead? → revive players → next stage or reward
```

### Restriction Integration

Dungeons block logout, restart, /unstuck, and being summoned. See `Die.java`, `RequestRestart.java`, `Logout.java`, `Escape.java`, `SummonFriend.java`.

## See Also

- [patterns](references/patterns.md) - Design patterns and anti-patterns
- [workflows](references/workflows.md) - Step-by-step implementation guides

## Related Skills

- See the **java** skill for code style and singleton patterns
- See the **xml-data** skill for XML parsing conventions
- See the **mariadb** skill for database schema management
- See the **l2j-gameserver** skill for Player and NPC integration
- See the **ai-system** skill for mob death callbacks
- See the **pvp-events** skill for shared InstanceManager usage