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

Creating a raid from scratch#

There are three supported ways to build a raid:

1. In-game admin flow — recommended while learning and for location-sensitive settings.
2. Direct YAML — best for advanced stages/waves/bosses and version-controlled configuration.
3. UltimateRaids Builder — visual web workflow for raids, kits, loot tables and skills.

The most reliable production process combines them instead of choosing only one.

Step 1 — create a stable raid ID#

/uraid create ancient_crypt

The ID becomes the raid file name and is referenced by other systems. Prefer IDs like:

ancient_crypt
ancient_crypt_hard
weekend_boss
clan_catacombs

Avoid spaces and avoid renaming a production raid unless you also review schedulers, NPCs/signs, prerequisites and external integrations.

Useful lifecycle commands:

/uraid clone ancient_crypt ancient_crypt_hard
/uraid rename ancient_crypt ancient_crypt_v2
/uraid disable ancient_crypt
/uraid enable ancient_crypt

Deletion is destructive and uses the plugin confirmation flow.

Step 2 — open the admin editor#

/uraid edit ancient_crypt

You can jump directly to an editor area:

/uraid edit ancient_crypt general
/uraid edit ancient_crypt entry
/uraid edit ancient_crypt participation
/uraid edit ancient_crypt loadout
/uraid edit ancient_crypt environment
/uraid edit ancient_crypt border
/uraid edit ancient_crypt locations
/uraid edit ancient_crypt access
/uraid edit ancient_crypt stages
/uraid edit ancient_crypt rewards
/uraid edit ancient_crypt display
/uraid edit ancient_crypt actions
/uraid edit ancient_crypt validation

The editor aliases include labels such as arena/world/kit/inventory/requirements/cooldowns/waves/skills. If you are unsure where a value lives, open the main editor first instead of guessing a raw path.

Step 3 — choose the raid design#

Do this before creating stages. A recommended planning table is:

Entry:          NORMAL or MINIGAME
Participation: SOLO / PUBLIC / GROUP / COMPETITIVE
Loadout:        PLAYER or KIT
Progression:    STANDARD or DISCOVERY
Environment:    OPEN_WORLD / DYNAMIC / REGION / ARENA / INSTANCE
Instance:       WORLD / SCHEMATIC / VOID (INSTANCE only)
Main goal:      waves / boss / survive / defend / destroy / reach / collect / interact / capture / escort

See Raid types and designs for examples.

Step 4 — set identity#

A minimal header:

id: ancient_crypt
name: '<primary>Ancient Crypt</primary>'
description: 'Fight through the crypt and defeat its guardian.'
enabled: false

Keep it disabled while building on a public server.

Step 5 — configure entry and participation#

A simple two-to-eight player normal raid:

entry:
  mode: NORMAL

participation:
  mode: PUBLIC
  group-provider: INTERNAL
  min-players: 2
  max-players: 8
  allow-late-join: false
  leader-only-queue: false

A solo test raid:

participation:
  mode: SOLO
  group-provider: SOLO
  min-players: 1
  max-players: 1
  ready-join:
    enabled: false

When learning, SOLO is useful because it removes queue/group variables from the first test.

Step 6 — choose loadout#

For normal equipment:

loadout:
  mode: PLAYER

For a controlled kit:

loadout:
  mode: KIT
  kit: crypt

Create the kit before validating the raid:

/uraid kit create crypt
/uraid kit save crypt
/uraid kit view crypt

Step 7 — choose progression#

Use STANDARD unless you deliberately want room discovery:

progression:
  mode: STANDARD

For a walking dungeon:

progression:
  mode: DISCOVERY
  discovery:
    stage-entry:
      requirement: ANY_PLAYER
      percentage: 100
    lock-future-stages: true
    teleport-back: true

Every discovery stage that should be entered physically needs a meaningful area.

Step 8 — choose environment and origin#

The simplest setup:

environment:
  mode: OPEN_WORLD

Then stand at the raid reference point:

/uraid location origin ancient_crypt

For INSTANCE raids, configure the instance source first and then verify runtime-relative locations. See Environments and instances.

Step 9 — capture lobby, spawn, spectator, exit and bounds#

Use current player position:

/uraid location lobby ancient_crypt
/uraid location spawn ancient_crypt
/uraid location spectator ancient_crypt
/uraid location exit ancient_crypt

For hard bounds:

/uraid location pos1 ancient_crypt
/uraid location pos2 ancient_crypt

Or open:

/uraid location gui ancient_crypt

After capturing locations, inspect the generated values and confirm whether RELATIVE or absolute behavior is appropriate for your environment.

Step 10 — define player death/finish behavior#

For a forgiving dungeon:

players:
  death:
    mode: RESPAWN
    respawn-delay: 3
    respawn-location: PLAYER_SPAWN
  disconnect:
    reconnect: true
    grace-time: 60
    remove-after-grace: true
  finish:
    return-to-entry-location: true
    restore-gamemode: true
    complete-delay: 5
    fail-delay: 5

For a limited-life encounter, use LIVES and configure lives plus elimination behavior.

Step 11 — create one minimal stage#

Do not begin with a complex boss. First prove that the raid can start, progress and finish:

stages:
  '1':
    id: entrance
    name: 'Crypt Entrance'
    timeout: 60
    completion: OBJECTIVE
    objective:
      type: SURVIVE
      amount: 15

Then:

/uraid validate ancient_crypt
/uraid start ancient_crypt

If the raid returns the player correctly after 15 seconds, the lifecycle is working.

Step 12 — replace the test objective with real gameplay#

Example wave clear:

completion: BOTH
objective:
  type: KILL_ENTITIES
  target: crypt_zombie
  amount: 5
waves:
  '1':
    delay: 1
    wait-for-clear: true
    groups:
      zombies:
        entity-id: crypt_zombie
        provider: DEFAULT
        type: ZOMBIE
        amount: 5
        health: 24

The KILL_ENTITIES target is the entity-id, not ZOMBIE.

Step 13 — add a second stage#

Add a boss or new room only after stage 1 completes consistently.

A common layout:

Stage 1: clear entrance mobs
Stage 2: defend/capture room
Stage 3: boss
Stage 4: escape/reach location

Each stage should have a unique ID and a timeout appropriate to the task.

Step 14 — add rewards#

Start with visible feedback:

rewards:
  completion:
    - type: EXPERIENCE
      amount: 100
    - type: MESSAGE
      message: '%tag% <success>Ancient Crypt completed.</success>'

Then move complex reward pools into reusable loot tables.

Step 15 — add displays/actions#

A stage should communicate its purpose. Use messages, title/actionbar and sounds on start/complete, especially when the objective is not obvious from the map.

Step 16 — validate semantics#

/uraid validate ancient_crypt

Validation can catch issues such as:

• no stages;
• invalid min/max player/group relationships;
• missing/invalid group provider;
• invalid minigame combinations;
• missing KIT;
• bad INSTANCE template/schematic/provider;
• invalid or unmatched objective targets;
• reward/provider problems;
• stage/boss configuration inconsistencies.

Do not ignore validation errors because the YAML “looks correct”.

Step 17 — test normal start and player join#

Admin test:

/uraid start ancient_crypt

Player flow:

/raid join ancient_crypt

For MINIGAME, the queue/lobby is the normal flow. force is for deliberate administration/testing.

Step 18 — test the negative paths#

Force situations that commonly break production raids:

• leave in lobby;
• leave during active stage;
• die/lose all lives;
• disconnect/reconnect;
• let a stage timeout;
• stop with /uraid stop;
• fail the objective;
• fill inventory before rewards;
• for KIT: verify original inventory returns;
• for INSTANCE: verify runtime world cleanup.

Step 19 — automate only after manual testing#

When the raid is stable, add:

• availability windows;
• scheduler;
• dynamic signs;
• EntityWizard join NPC;
• minigame persistent/reopen behavior;
• external API/addon entry points.

Example production development order#

Create shell
→ SOLO + PLAYER + OPEN_WORLD
→ one SURVIVE test stage
→ validate/start/finish
→ real waves/objective
→ second stage
→ boss
→ rewards
→ KIT (if needed)
→ INSTANCE (if needed)
→ Ready/vote/group flow
→ scheduler/NPC/sign
→ production test

This order prevents five different systems from being debugged at the same time.