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

Environments and instance design#

The environment controls where the raid runs and how much isolation/reset behavior you get. Choose this early because locations, bounds, regeneration and instance assets depend on it.

OPEN_WORLD#

Runs in the existing server world around configured positions/origin.

Use it for:

• world bosses;
• adventure events built into the normal map;
• simple test raids;
• content where terrain changes are not expected.

Advantages: fastest setup, no runtime world cloning.

Risks: players/outside systems can interact with the same world unless rules/bounds protect the encounter. If the raid is destructive, use regeneration or an INSTANCE.

DYNAMIC#

Uses a runtime origin and resolves RELATIVE locations around that origin. This is useful when the same raid logic may be placed/prepared around different points or when DISCOVERY content is defined around a selected origin.

The bundled example_discovery.yml demonstrates DYNAMIC + DISCOVERY.

REGION#

A fixed region-style encounter in an existing world. Configure bounds and all relevant locations. Use when the raid should stay inside a known area but you do not need a disposable world.

ARENA#

A fixed repeatable arena style. It has the same “shared world” operational concerns as REGION: if players can alter blocks, decide whether regeneration or external arena reset logic is required.

INSTANCE#

Creates a dedicated runtime world for a raid instance. This is the preferred choice for isolated/destroyable dungeons and concurrent groups.

The instance can come from WORLD, SCHEMATIC or VOID.

INSTANCE + WORLD#

Example:

environment:
  mode: INSTANCE
  instance:
    source: WORLD
    template: crypt_template
    world-prefix: uraid_crypt_
    delete-on-finish: true

Use when the dungeon is a full Minecraft world rather than one pasted structure.

Template preparation#

A WORLD template must be a valid Minecraft world and contain a valid level.dat. Keep the template separate from disposable runtime clones. The runtime world names use the configured prefix plus an instance-specific suffix.

Good use cases#

• large dungeons;
• multi-room maps;
• terrain-heavy adventures;
• discovery raids that span a large map;
• maps that depend on normal world structure beyond a schematic paste.

INSTANCE + SCHEMATIC#

Example:

environment:
  mode: INSTANCE
  instance:
    source: SCHEMATIC
    schematic:
      file: crypt.schem
      paste:
        x: 0
        y: 64
        z: 0
      ignore-air: false
    world-prefix: uraid_crypt_
    delete-on-finish: true

Put the file in:

plugins/UltimateRaids/instances/schematics/crypt.schem

WorldEdit or FastAsyncWorldEdit must be available. UltimateRaids creates the runtime world, pastes the schematic, preloads configured chunks, then marks the instance ready.

Relative origin after paste#

A schematic can be pasted at one coordinate while the raid origin is another RELATIVE offset. Use the bundled schematic example as a reference and test the actual spawn before adding NPCs or complex stages.

INSTANCE + VOID#

Creates an empty runtime world. Use it when your runtime system/schematic/provider supplies everything needed or when you deliberately want an empty environment.

A void world has no natural safe floor. Configure a safe origin/player spawn or paste/build content before teleporting players.

Instance loading settings#

A typical block:

loading:
  minimum-seconds: 1
  timeout-seconds: 60
  preload-radius-chunks: 1
  chunks-per-tick: 4
  preload-future-stages: false
  stage-radius-chunks: 1

• minimum-seconds prevents an instant transition if you want a minimum preparation period.
• timeout-seconds prevents a broken instance preparation from waiting forever.
• preload radius/chunks-per-tick control initial chunk preparation work.
• future-stage preload can trade startup work for smoother later movement.

Runtime world settings#

difficulty: NORMAL
allow-monsters: true
allow-animals: false
exclusive-raid-mobs: true

exclusive-raid-mobs is useful when the instance should contain only entities intentionally created by the raid flow rather than unrelated natural spawns.

Locations in instances#

Prefer RELATIVE locations tied to the runtime origin:

player-spawn:
  mode: RELATIVE
  x: 0
  y: 0
  z: 0

This keeps a raid portable across cloned/pasted instances.

Bounds#

Bounds provide a cuboid gameplay area:

bounds:
  enabled: true
  teleport-back: true
  pos1: { mode: RELATIVE, x: -20, y: -5, z: -20 }
  pos2: { mode: RELATIVE, x: 20, y: 15, z: 20 }

Use bounds to prevent players leaving the intended dungeon area even if the visual border is disabled.

Borders#

A border can be:

• VISUAL
• PHYSICAL
• BOTH

Example:

border:
  enabled: true
  provider: AUTO
  mode: BOTH
  center: { mode: RELATIVE, x: 0, y: 0, z: 0 }
  size: 32
  teleport-back: true

Stage-specific borders can temporarily shrink/change the playable area and transition over time.

Regeneration vs disposable worlds#

For OPEN_WORLD/REGION/ARENA, use regeneration when block state should be restored after complete/fail/stop.

For INSTANCE, the usual model is delete-on-finish: true, because deleting the temporary world provides a clean reset. Do not rely on both mechanisms without understanding why both are needed.

Choosing the correct environment#

Testing an INSTANCE raid#

Before production:

1. /uraid validate <raid>.
2. Start it once with one player.
3. Watch instance preparation logs.
4. Verify player spawn is on safe ground.
5. Complete the raid.
6. Confirm player returns correctly.
7. Confirm runtime world is removed if delete-on-finish: true.
8. Repeat with failure/stop.
9. Test a staging-server restart to verify stale-instance recovery.

If players spawn in the void, troubleshoot the instance asset, paste/template, origin and player-spawn before changing unrelated stage settings.