> For the complete documentation index, see [llms.txt](https://docs.drakodevelopment.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drakodevelopment.net/drako-dungeons/features/zones-stages-and-areas.md).

# Zones, Stages & Areas

Each file in `plugins/DrakoDungeons/zones/` defines one zone. Zones are ordered progression chapters, stages are the unlockable steps inside a zone, and areas are the physical arena regions used by those stages.

## Zone structure

```yaml
schema-version: 1
id: mines
order: 1
next-stage-sequence: 3
display-name: '<gold>Mines</gold>'
world: world
multipliers: { health: 1.0, money: 1.0, souls: 1.0, essence: 1.0 }

areas:
  main_arena:
    display-name: '<yellow>Main Arena</yellow>'
    entry: 'world,100.5,65,200.5,90,0'
    bounds:
      minimum: 'world,90,60,190,0,0'
      maximum: 'world,120,80,220,0,0'
    spawns:
      centre:
        position: 'world,105.5,65,200.5,-90,0'
        hitbox-width: 1.0
        hitbox-height: 2.2

stages:
  '1':
    id: stage_1
    display-name: '<green>Stage 1</green>'
    areas: [main_arena]
    health-multiplier: 1.0
    reward-multipliers: { money: 1.0 }
    purchase: { currency: money, amount: 0 }
    completion: { money-earned: 10000 }
    completion-rewards: { money: 1000, souls: 10 }
```

## Stable IDs and ordering

* `id` is the persistent zone key and should match the filename.
* `order` controls zone progression and menu ordering. Orders must be unique and consecutive.
* `display-name` can be changed without changing player ownership keys.
* `next-stage-sequence` allocates future stable stage IDs. Never lower it after deleting a stage.
* Stage map keys are numeric positions starting at `1`; each stage also has its own stable `id`.

The first zone in order should be selected by `settings/gameplay.yml: progression.starting-zone`.

## Areas

An area controls where a player arrives, where private mobs appear, and when a session is active.

* `entry` uses `world,x,y,z,yaw,pitch`.
* `bounds` defines a deliberate cuboid and is required for packet-block themes.
* `activation-radius` can be used for an unbounded starter area.
* `spawns` defines local mob points and optional hitbox overrides.
* `afk: true` marks the area as AFK-only and requires `drakodungeons.afk`.
* `packet-blocks` contains optional client-only material replacements.

Several stages may reuse an area, and one stage may list several areas. Several zones may intentionally reuse identical physical bounds when each zone should show a different packet-block palette.

## Stages

Stages must remain consecutive.

| Key                       | Meaning                                                   |
| ------------------------- | --------------------------------------------------------- |
| `id`                      | Stable stage ownership key                                |
| `areas`                   | Area IDs available to the stage                           |
| `purchase`                | Currency and amount needed to unlock the stage            |
| `completion.money-earned` | Gross Money earned in this stage before it completes      |
| `completion-rewards`      | One-time configured currency rewards                      |
| `health-multiplier`       | Multiplies stage mob health                               |
| `reward-multipliers`      | Per-currency stage reward multipliers                     |
| `mobs`                    | Optional stage-specific mob pool overriding the zone pool |

Completion tracks gross Money earned in the stage. Spending Money does not reduce recorded stage progress.

## Setup commands

Use `/dga setup` for routine editing. The visual workflow performs transactional writes, validates the result, and rolls back rejected changes.

Direct lifecycle commands include:

```
/dga setup createzone <id> [name]
/dga setup clonezone <source> <new-id>
/dga setup renamezone <id> <name>
/dga setup deletezone <id> confirm
/dga setup <zone> createstage <id> [name]
/dga setup <zone> renamestage <stage> <name>
/dga setup <zone> deletestage <stage> confirm
/dga setup <zone> stagearea <stage> <addarea|removearea> <area>
```