Clustering & multi-realm

Splintertree is a cluster from day one. The orchestrator runs splintertree-world as one process per (map_id, instance_id) and hot-spawns / drains them based on player load — every map can scale horizontally without restarting the realm.

High availability for the orchestrator

splintertree-orchestrator itself runs N replicas behind a NATS queue group. PostgreSQL advisory locks coordinate spawn decisions; the instance registry (characters.instances, characters.player_assignments) is the single source of truth so any orchestrator replica can take over without state loss.

Multi-realm

A single deployment hosts multiple realms at once. Realms are grouped into pools (cluster.realm_pools) for cross-realm features:

Cross-realm matchmaking

Battleground queues, arena teams, and LFR / LFG pools key on (pool_id, activity_id) so players from any realm in the pool fill the same match. Wired through splintertree-matchmaking.

Cross-realm transfers

World::move_player_to_instance carries a cross_realm flag; the orchestrator routes the player through splintertree-orchestrator/src/player_transfer.rs, releases state on the source instance, rewrites player_assignments, and re-spawns on the target. The client sees a normal SMSG_TRANSFER_PENDING + SMSG_NEW_WORLD.

Connected realms

Multiple auth.realmlist rows can share a cluster.realm_game mapping so they read the same world.* schema while keeping separate populations and economies.

Multi-game cluster

The same primitives let Classic, TBC, and Wrath co-exist via cluster.games. Each game has its own world.* schema; realms map to one game; the gateway routes by realm.

Per-realm patches

Patch chains live in cluster.patches and are applied per realm. The launcher resolves each realm's ancestor chain at sync time; the activator pulls and caches mods on activation. Patches roll forward and back without realm downtime.

Per-instance metrics (Prometheus), per-realm authentication, and per-realm patch chains all flow from the same multi-tenant primitives.

The full design rationale and rollout phases live in the engineering notes under docs/multi-realm-design.md.