Wiki Release: 2026.09.8 · UltimateRaids: 0.12.0 · Documentation branch: 1

Stages, waves and objectives#

Stages are the main gameplay timeline of a raid. Each stage can have its own area, timeout, border, objective, rewards, actions and waves.

Stage anatomy#

A practical stage:

stages:
  '1':
    id: entrance
    name: 'Crypt Entrance'
    delay: 0
    timeout: 180
    next-stage-delay: 3
    cleanup-on-complete: true
    completion: BOTH
    objective:
      type: KILL_ENTITIES
      target: crypt_zombie
      amount: 5
    waves:
      '1':
        delay: 0
        wait-for-clear: true
        groups:
          zombies:
            entity-id: crypt_zombie
            provider: DEFAULT
            type: ZOMBIE
            amount: 5

The stage id must be unique inside the raid. Use readable IDs because logs, discovery areas and debugging are easier to understand.

Stage completion modes#

OBJECTIVE#

Complete when the objective processor reports completion.

Use for SURVIVE, CAPTURE, REACH_LOCATION, COLLECT and similar goals that do not necessarily depend on clearing all waves.

WAVES#

Complete when the configured waves are considered cleared.

Use for pure horde/wave encounters.

BOTH#

Require both objective and wave conditions. This is useful when the objective is explicitly tied to entities spawned by the stage.

Example: spawn five crypt_zombie and require KILL_ENTITIES amount: 5.

EITHER#

Either the objective or wave side can complete the stage. Use carefully: a fast objective can finish while entities remain unless cleanup behavior is intentional.

AUTO#

Engine/config-driven advancement without requiring the normal objective/waves pair. Use only when you understand the stage design that depends on it.

Waves#

A stage can contain several waves:

waves:
  '1':
    delay: 0
    wait-for-clear: true
    groups: ...
  '2':
    delay: 3
    wait-for-clear: true
    groups: ...

wait-for-clear: true is the normal choice when the next wave should not start until the current raid entities are cleared.

Spawn groups#

A wave can spawn multiple groups. Important fields:

provider: DEFAULT
entity-id: crypt_zombie
type: ZOMBIE
amount: 5
name: '<error>Crypt Raider</error>'
health: 24
spawn: ...

• provider chooses the registered entity provider.
• type is the provider entity type/id.
• entity-id is the raid tracking ID used by objectives such as KILL_ENTITIES.
• amount creates multiple tracked entities from the group.

Spawn spread#

Do not spawn ten mobs on exactly one block. Configure spread:

spread:
  radius: 4
  safe-ground: true
  vertical-search: 8
  attempts: 12
  y-offset: 0

This asks the spawning system to distribute entities around the configured point and look for valid ground.

Objective catalog#

NONE#

No active objective processor. Usually paired with wave/automatic behavior rather than completion: OBJECTIVE.

KILL_ENTITIES#

Counts tracked raid entity deaths matching target.

objective:
  type: KILL_ENTITIES
  target: crypt_zombie
  amount: 5

target must match entity-id from a spawn group.

KILL_BOSS#

Counts death of the tracked boss with matching boss.id.

objective:
  type: KILL_BOSS
  target: crypt_guardian
  amount: 1

target is not the mob material/type and does not have to equal the group key.

SURVIVE#

Progresses over time until amount is reached. Good for timed defense/survival stages.

objective:
  type: SURVIVE
  amount: 30

DEFEND#

Tracks a target raid entity/group/boss and progresses while it is alive. By default, once the target has been seen, target death can fail the objective.

Useful for protecting an NPC/guardian while enemies spawn around it.

DESTROY#

Counts matching block breaks by active participants. It can match a material/target and optionally restrict breaking to an objective location/radius.

Use for crystals, generators, seals or destructible dungeon objects. Remember to allow the necessary block-break behavior and consider regeneration/INSTANCE cleanup.

REACH_LOCATION#

Completes/progresses when active participants reach the configured objective location. Use for escape points, room exits and traversal objectives.

INTERACT#

Tracks interaction with the configured target/location. Use for levers, ritual points or interactable objectives supported by the objective configuration.

COLLECT#

Counts picked-up items. It can match:

• Bukkit material;
• custom item resolved through a registered item provider.

Use for keys, fragments and scavenger stages.

CAPTURE#

Counts time while enough active participants are inside the objective location.

Useful options include:

• minimum-players;
• reset-on-empty;
• decay.

This supports “hold this room for 30 seconds” gameplay rather than a one-time trigger.

ESCORT#

Tracks one or more matching raid entities arriving at the configured destination. UltimateRaids tracks arrival and failure-on-death; entity movement/AI is owned by the native/provider entity system.

Objective amount#

amount means different things according to objective type:

• kills for kill objectives;
• seconds/ticks of progress for timed hold/survive behaviors as implemented by the objective;
• item count for COLLECT;
• targets reached/destroyed/interacted with for the relevant processor.

Use a small value while testing so you can quickly confirm the stage progresses.

Stage areas#

Stage areas are especially important for DISCOVERY:

area:
  enabled: true
  pos1: { mode: RELATIVE, x: -3, y: -3, z: -3 }
  pos2: { mode: RELATIVE, x: 3, y: 4, z: 3 }

Design areas with enough vertical range that normal player movement does not accidentally leave the area.

Stage borders#

A stage can temporarily override/shrink the raid border:

border:
  enabled: true
  size: 11
  transition: 5s

Useful for boss rooms and shrinking final arenas.

Stage actions#

Stage start/complete/fail events can run actions such as message, title, sound, particle or reusable skill. Use them to tell players what changed.

Stage rewards#

A stage can grant rewards separate from the overall raid completion. Keep stage rewards smaller if the raid can be retried/farmed and use progression/cooldowns where appropriate.

Building a three-stage dungeon#

A reliable pattern:

Stage 1 — clear mobs#

BOTH + KILL_ENTITIES + wave

Stage 2 — hold room#

OBJECTIVE + CAPTURE

while optional waves continue spawning attackers.

Stage 3 — boss#

BOTH + KILL_BOSS + boss wave

This produces varied gameplay without needing custom code.

Debugging stage progression#

If a stage never completes:

1. Check completion.
2. Check whether the objective itself is progressing.
3. For KILL_ENTITIES, compare objective.target with entity-id.
4. For KILL_BOSS, compare target with boss.id.
5. For WAVES/BOTH, verify spawned raid entities actually clear/die.
6. Check timeout/failure logs.
7. Run /uraid validate <raid> after every target/ID edit.