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

Complete UltimateRaids administrator guide#

This guide follows the same order an administrator normally uses when building a raid for a live server. You do not need to configure every feature. Start with a small working raid, then add complexity one layer at a time.

1. Decide what players are supposed to experience#

Before touching YAML, answer five questions:

  1. How do players enter? On demand (NORMAL) or through an always-available queue (MINIGAME)?
  2. Who plays together? One player (SOLO), unrelated players (PUBLIC), one party/clan (GROUP), or multiple groups (COMPETITIVE)?
  3. Where does the raid run? In the normal world, a fixed arena, or an isolated temporary instance?
  4. What equipment do players use? Their own items (PLAYER) or a controlled kit (KIT)?
  5. What is the victory condition? Clear waves, kill a boss, survive, defend, destroy, reach, collect, interact, capture, escort, or a sequence of several stages?

If you are unsure, read Raid types and designs first.

2. Create the raid shell#

Create a stable ID:

/uraid create ancient_crypt

Use lowercase IDs with _ or - and avoid changing them after you connect schedulers, NPCs, signs or external systems to the raid.

Then open the main editor:

/uraid edit ancient_crypt

The editor is the safest way to learn the available sections. Advanced administrators can also edit raids/ancient_crypt.yml directly or use the UltimateRaids Builder.

3. Configure identity and enable state#

At minimum, give the raid a readable name and description:

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

Keep the file disabled while building if players already have access to /raid list or join NPCs.

4. Choose the entry mode#

NORMAL#

Use NORMAL when the raid is opened only when someone deliberately joins/starts it or when a scheduler opens it. This is the simplest model for dungeons, clan content and admin-started events.

entry:
  mode: NORMAL

MINIGAME#

Use MINIGAME for an activity that should behave like a permanent game mode: persistent queue, automatic Ready/start flow, automatic reopening and optional concurrent matches.

entry:
  mode: MINIGAME
  minigame:
    persistent-lobby: true
    reopen-after-finish: true
    auto-start: true
    auto-ready: true
    concurrent-matches: 1
    reopen-delay: 8

MINIGAME requires PUBLIC, GROUP or COMPETITIVE participation. Dynamic signs are only active for MINIGAME, and persistent join NPCs are intended for MINIGAME or DISCOVERY raids.

5. Choose participation#

SOLO#

Best for personal challenges and tutorials.

participation:
  mode: SOLO
  group-provider: SOLO
  min-players: 1
  max-players: 1

PUBLIC#

Independent players enter the same queue and raid.

participation:
  mode: PUBLIC
  min-players: 2
  max-players: 8

GROUP#

One logical group enters together. This can use the built-in party provider or an installed integration/provider.

participation:
  mode: GROUP
  group-provider: INTERNAL
  min-players: 1
  max-players: 8
  min-groups: 1
  max-groups: 1
  leader-only-queue: true

COMPETITIVE#

Use when multiple groups share the event. Configure both player and group limits carefully.

participation:
  mode: COMPETITIVE
  group-provider: INTERNAL
  min-players: 2
  max-players: 32
  min-groups: 2
  max-groups: 8
  leader-only-queue: true

For external clan/group integrations, run:

/uraid debug implementations

and confirm the desired group provider is actually registered before referencing it.

6. Configure Ready, waiting and vote behavior#

Public/group lobbies can wait for players and Ready state instead of starting immediately.

participation:
  ready-join:
    enabled: true
    countdown: 15
    require-all: false
    waiting:
      minimum: 20
      vote-after: 45
      start-when-full: true
    vote:
      enabled: true
      minimum-players: 1
      duration: 20
      required-percent: 60
      minimum-yes: 1
      countdown: 10
      retry: 30
      manual-start: true

Player controls:

/raid ready
/raid vote start
/raid vote yes
/raid vote no
/raid vote status

For a first test raid, disable Ready/voting. Add them only after the base encounter starts and ends correctly.

7. Choose the loadout#

PLAYER#

Players keep their own inventory:

loadout:
  mode: PLAYER

Use this for RPG/progression servers where equipment is part of the challenge.

KIT#

Use a controlled raid kit:

loadout:
  mode: KIT
  kit: crypt

Prepare the inventory/armor/effects you want and create/save the kit:

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

UltimateRaids snapshots the player state before applying the kit and restores it when the managed lobby/raid lifecycle ends. See Kits and loadouts before using KIT on production.

8. Choose progression#

STANDARD#

Stages advance when their configured completion condition is met.

progression:
  mode: STANDARD

DISCOVERY#

Stages can be unlocked by physically entering configured stage areas.

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

Use DISCOVERY for corridor/dungeon exploration where players should move through rooms instead of being teleported from one stage to the next.

9. Choose the environment#

OPEN_WORLD#

Runs in the normal world. Good for world bosses and shared-map encounters.

DYNAMIC#

Uses a runtime origin. Good when the encounter is designed relative to wherever it is opened.

REGION / ARENA#

Use fixed locations/bounds in an existing world. Good for repeatable arenas where you do not need a cloned world.

INSTANCE#

Creates an isolated runtime world. Choose a source:

  • WORLD — clone an existing full world/template;
  • SCHEMATIC — create a world and paste a .schem with WorldEdit/FAWE;
  • VOID — create an empty world for fully dynamic/custom content.

Read Environments and instances before production INSTANCE use.

10. Capture locations in-game#

Stand at each point and use the location command:

/uraid location origin ancient_crypt
/uraid location lobby ancient_crypt
/uraid location spawn ancient_crypt
/uraid location spectator ancient_crypt
/uraid location exit ancient_crypt
/uraid location pos1 ancient_crypt
/uraid location pos2 ancient_crypt

You can also open the location GUI:

/uraid location gui ancient_crypt

Think of origin as the reference point for RELATIVE coordinates. If a location should move with a dynamic/instance origin, use RELATIVE coordinates. If it is tied to one real-world position, use an absolute/world-aware location.

11. Configure environment rules#

Decide what players may do during the encounter:

environment:
  rules:
    pvp: false
    block-break: false
    block-place: false
    explosions: false
    item-drop: false
    item-pickup: true
    hunger: false
    outsiders-damage-raid-entities: false
    mob-drops: false
    mob-experience: false
    commands:
      mode: BLACKLIST
      list: [spawn, home, warp]

For dungeons and minigames, restricting teleport/home commands prevents players from bypassing the lifecycle.

12. Configure player death and recovery behavior#

Examples include:

  • RESPAWN — respawn and continue;
  • LIVES — limited lives before elimination;
  • SPECTATOR — death transitions to spectator behavior;
  • REMOVE — remove the player from the raid.

A common lives setup:

players:
  death:
    mode: LIVES
    lives: 3
    respawn-delay: 3
    respawn-location: ORIGIN
    spectator-after-elimination: true
    keep-inventory: false
    keep-level: false
  disconnect:
    reconnect: true
    grace-time: 60
    remove-after-grace: true
  wipe:
    fail-raid: true
  finish:
    return-to-entry-location: true
    restore-gamemode: true
    complete-delay: 5
    fail-delay: 5

13. Add requirements and cooldowns#

Use requirements to decide who may join:

  • PERMISSION
  • LEVEL
  • ITEM
  • GROUP_SIZE
  • RAID_COMPLETED
  • MONEY

Example progression gate:

requirements:
  - type: RAID_COMPLETED
    raid: crypt_normal
    completions: 1

Cooldowns can apply to PLAYER, GROUP and GLOBAL, and trigger on START or COMPLETE.

14. Build the first stage#

Start with one simple stage before adding waves/bosses:

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

Run /uraid validate ancient_crypt, then start the raid. If this works, the core lifecycle, location and player return flow are already proven.

15. Add waves#

A wave contains one or more spawn groups:

waves:
  '1':
    delay: 1
    wait-for-clear: true
    groups:
      zombies:
        entity-id: crypt_zombie
        provider: DEFAULT
        type: ZOMBIE
        amount: 5
        health: 24
        spawn:
          mode: RELATIVE
          x: 3
          y: 0
          z: 0
          spread:
            radius: 4
            safe-ground: true
            vertical-search: 8
            attempts: 12

Use a non-zero spread radius when spawning several entities from one group.

16. Match objectives to spawned targets#

For KILL_ENTITIES, objective.target must match the spawn group entity-id:

objective:
  type: KILL_ENTITIES
  target: crypt_zombie
  amount: 5

For KILL_BOSS, it must match boss.id, not the mob type or group key.

objective:
  type: KILL_BOSS
  target: crypt_guardian
  amount: 1

This is one of the most common configuration mistakes and is caught by validation.

17. Add a boss only after normal waves work#

A boss is attached to a spawn group and can add:

  • boss ID;
  • target selection;
  • incoming/outgoing damage multipliers;
  • maximum incoming hit;
  • immunities;
  • equipment;
  • health-based phases;
  • timed/health enrage;
  • reusable skills;
  • minions.

Keep the first boss simple. Confirm KILL_BOSS completes, then add phases/enrage/minions.

18. Add rewards and loot#

Use direct rewards for predictable outcomes and loot tables for reusable/randomized reward pools.

Built-in rewards:

COMMAND, ITEM, EXPERIENCE, MESSAGE, MONEY, MONEY_PENALTY, LOOT_TABLE.

Loot tables support CHANCE or WEIGHTED selection and PERSONAL or SHARED distribution.

19. Add displays and feedback#

Use titles, actionbar, bossbar, scoreboard, sounds, particles and actions to make state changes clear. Good raids tell players what is happening instead of requiring them to guess why a stage has not advanced.

20. Add NPCs/signs only after the raid is stable#

For MINIGAME, you can expose the queue through persistent signs and EntityWizard NPCs. DISCOVERY raids may also use join NPCs. These are entry surfaces; they do not replace validation or the underlying lobby configuration.

21. Add scheduler/availability last#

First prove the raid works manually. Then add:

  • availability windows — when players are allowed to enter;
  • scheduler — when the server automatically opens or force-starts the raid.

Test a scheduler immediately with:

/uraid scheduler run <id>

before waiting for the real clock time.

22. Validate before every live test#

/uraid validate ancient_crypt
/uraid status raid ancient_crypt
/uraid debug implementations

Fix errors before starting. Warnings may be intentional, but they should be understood.

23. Test failure, stop and restart paths#

A production raid is not ready after one successful completion. Test:

  • normal completion;
  • player death/elimination;
  • /raid leave;
  • administrator stop;
  • disconnect/reconnect;
  • failure/timeout;
  • KIT restoration;
  • INSTANCE cleanup;
  • server restart/recovery in a staging environment.

This is especially important for KIT and INSTANCE designs because player state and runtime worlds must be cleaned safely.

24. Publish the player entry point#

Once the raid is stable, expose it through the appropriate method:

  • /raid join <raid>;
  • player GUI;
  • MINIGAME sign;
  • EntityWizard join NPC;
  • scheduler;
  • external API/addon integration.

Do not expose a half-configured raid just because enabled: true passes basic parsing.

Production checklist#

Before calling a raid finished, verify:

  • [ ] Raid validates without unexplained errors.
  • [ ] Entry mode matches the desired player flow.
  • [ ] Participation/group provider is registered and tested.
  • [ ] Player spawn/lobby/exit locations are correct.
  • [ ] Bounds/border prevent unintended escape if required.
  • [ ] PLAYER/KIT behavior is intentional.
  • [ ] Every stage can complete.
  • [ ] Objective target IDs match spawned entities/boss IDs.
  • [ ] Failure/timeout path works.
  • [ ] Rewards are granted exactly once as intended.
  • [ ] Inventory/gamemode is restored.
  • [ ] INSTANCE worlds are cleaned or retained intentionally.
  • [ ] Scheduler/availability is tested separately.
  • [ ] NPC/sign entry displays the correct state.
  • [ ] Console has no recurring warnings related to providers or cleanup.
Wiki Release 2026.09.8 · Canonical TribeCraft documentation.