🌐 Multi-Server Raids

RaidNetwork connects multiple UltimateRaids servers into the same network.

Each backend can have one of three roles:

• HOST — Stores and runs the actual Raids.
• CLIENT — Acts as a lobby or entry server and does not host Raids.
• HYBRID — Can both host Raids and send players to other servers.

Servers only communicate with other RaidNetwork servers using the same server group.

⭐ Main Features

• Redis-based network synchronization
• HOST / CLIENT / HYBRID server roles
• Remote Raid catalog
• No duplicated Raid YAML files required on lobby servers
• Automatic on-demand Raid opening
• MINIGAME and NORMAL Raid entry modes
• Automatic player reservations before server transfer
• Persistent Raid session synchronization
• Live OPEN / WAITING / STARTING / RUNNING status
• Automatic return to the previous server when leaving
• Optional previous-location restoration
• Remote NPC entry points
• Remote sign entry points
• Direct command entry
• Automatic standard /raid join interception
• Multiple routing strategies
• Automatic stale-session cleanup
• Redis offline fail-safe mode
• Automatic HOST Raid discovery

🧭 Remote Raid Catalog

One of the main advantages of RaidNetwork is that your lobby does not need copies of every Raid.

Example:

LOBBY
RaidNetwork: CLIENT

plugins/UltimateRaids/raids/
(empty)


RANKUP
RaidNetwork: HOST

plugins/UltimateRaids/raids/
├── raid1.yml
├── raid2.yml
└── raid3.yml

The HOST automatically publishes its available Raids through Redis.

The CLIENT discovers:

raid1 → rankup
raid2 → rankup
raid3 → rankup

No duplicated Raid configuration is required.

⚡ On-Demand Raid Creation

A Raid does not need to already be running before a player tries to join.

When a player executes:

/raid network join raid1

RaidNetwork first searches for an existing joinable session.

If no session exists, the CLIENT automatically requests a compatible HOST to open the Raid.

Player
   ↓
Lobby CLIENT
   ↓
Search existing session
   ↓
No session available
   ↓
Find HOST advertising the Raid
   ↓
Open Request
   ↓
Reserve player
   ↓
Transfer to HOST
   ↓
UltimateRaids starts the correct Raid flow

The actual Raid continues to follow its normal UltimateRaids configuration, including environments, stages, objectives, bosses, kits, loot and player rules.

🎮 MINIGAME Support

RaidNetwork fully understands UltimateRaids MINIGAME lobbies.

entry:
  mode: MINIGAME

Waiting lobbies are published as network sessions and their state remains synchronized.

OPEN
↓
WAITING
↓
STARTING
↓
RUNNING
↓
WAITING

Persistent MINIGAME lobbies can remain available for future players after a match finishes.

⚔ NORMAL Raid Support

NORMAL Raids can also be started remotely.

entry:
  mode: NORMAL

If no instance currently exists, RaidNetwork can select a HOST and bootstrap the Raid when the player arrives.

No permanent MINIGAME lobby is required.

🔁 Automatic Return

RaidNetwork remembers where network players came from.

lobby
  ↓
rankup
  ↓
Raid
  ↓
/raid leave
  ↓
lobby

Return handling also works when players leave a MINIGAME waiting lobby or an active Raid.

Previous location restoration can be enabled in the configuration.

🧑 NPC Entry

NPCs are optional entry points and can reference Raids that only exist on remote HOST servers.

/uraid network npc create raid_npc raid1

The NPC automatically displays live RaidNetwork information and sends players through the normal network routing flow when clicked.

List NPCs:

/uraid network npc list

Remove an NPC:

/uraid network npc remove raid_npc

🪧 Sign Entry

Look directly at a sign and use:

/uraid network sign create raid1

RaidNetwork will register that sign as a remote entry point for the selected Raid.

Remove the sign while looking at it:

/uraid network sign remove

List registered signs:

/uraid network sign list

🧠 Routing Strategies

When multiple HOST servers can run the same Raid, RaidNetwork can automatically choose where the player should go.

Available strategies include:

• MOST_POPULATED
• LEAST_POPULATED
• RANDOM
• ROUND_ROBIN
• LOWEST_LOAD

routing:
  strategy: MOST_POPULATED

🚀 Quick Setup

1. Install RaidNetwork

Install RaidNetwork together with UltimateRaids on every backend that will participate in the Raid network.

All servers must be connected through the same proxy network and must be able to access the same Redis server.

2. Configure the Lobby

Example CLIENT:

server:
  id: lobby
  group: main
  role: CLIENT

redis:
  host: 127.0.0.1
  port: 6379
  username: ''
  password: ''
  database: 0
  ssl: false
  key-prefix: 'uraids:raidnetwork'

The server.id must match the backend server name configured in your proxy.

3. Configure the Raid Server

Example HOST:

server:
  id: rankup
  group: main
  role: HOST

redis:
  host: 127.0.0.1
  port: 6379
  username: ''
  password: ''
  database: 0
  ssl: false
  key-prefix: 'uraids:raidnetwork'

Both servers must use the same group and Redis connection.

4. Add Raids Only to the HOST

Example:

rankup/plugins/UltimateRaids/raids/
├── raid1.yml
├── raid2.yml
└── raid3.yml

Do not copy these files to the CLIENT lobby.

RaidNetwork automatically publishes the HOST Raid catalog.

5. Verify the Network

Run:

/uraid network status

Example:

Redis: CONNECTED
Role: CLIENT
Online servers: 2
Network sessions: 0
Advertised Raids: 3

You can also inspect the connected servers:

/uraid network servers

And the available Raids:

/uraid network raids

6. Join a Remote Raid

From the CLIENT server:

/raid network join raid1

RaidNetwork will automatically:

1. Discover the HOST
2. Find or request a Raid session
3. Reserve the player
4. Transfer the player
5. Enter the UltimateRaids flow

⌨ Commands

/raid network
/raid network join <raid>

/uraid network status
/uraid network servers
/uraid network raids
/uraid network redis
/uraid network reload

/uraid network npc create <id> <raid>
/uraid network npc remove <id>
/uraid network npc list

/uraid network sign create <raid>
/uraid network sign remove
/uraid network sign list

🔧 Important Configuration Options

network:
  heartbeat-seconds: 5
  server-timeout-seconds: 15
  session-ttl-seconds: 21600
  session-freshness-seconds: 6
  catalog-ttl-seconds: 30
  open-request-timeout-seconds: 8

  reservations:
    timeout-seconds: 15

  return:
    ttl-seconds: 21600
    restore-location: true
    recover-if-host-offline: true

join:
  intercept-standard-command: true
  prefer-local: true

routing:
  strategy: MOST_POPULATED

📡 Network Status & Safety

RaidNetwork continuously tracks server heartbeats, advertised Raids and active sessions.

CLIENT servers are never allowed to publish Raid sessions as HOSTs, and stale sessions are automatically ignored when their HOST stops refreshing them.

If Redis becomes unavailable, RaidNetwork enters an offline network mode instead of interrupting the normal UltimateRaids lifecycle.

Preview: