Skip to content

ServerRegistry

The ServerRegistry table is the master directory of all game servers in a QS-Bridge cluster. Every server that participates in the platform — regardless of game title, mode, or region — must have a row in this table. It is the central "glue" that enables cross-server features including global ban synchronization, player presence tracking, character transfers, and live dashboard metrics.

Scope

🌍 Global — All servers, panel clients, and the gateway can read and subscribe to this table. There is exactly one ServerRegistry row per active server across the entire cluster.

Schema

Column Type Constraints Description
server_id String Primary Key Human-readable unique identifier (e.g., "us-east-pvp-1")
stdb_identity Identity Unique Cryptographic identity assigned by SpacetimeDB
display_name String — User-facing server name shown in UI and panel
region String — Geographic region code (e.g., "us-east", "eu-west")
game_module String — Identifier of the game-specific sub-database module
game_mode String — Game mode descriptor (e.g., "pvp", "pve", "creative")
hosting_id String — External hosting provider reference ID
status String — Current server status ("online", "offline", "restarting")
last_heartbeat Timestamp — Timestamp of the most recent heartbeat from this server
version String — Server software version string
max_players u32 — Maximum concurrent player capacity
online_count u32 — Current number of connected players
wipe_schedule String — Wipe cadence descriptor (e.g., "weekly", "monthly", "none")
config_template_id String — Reference to a configuration template for server provisioning

Rust Definition

#[spacetimedb::table(public, name = server_registry)]
pub struct ServerRegistry {
    #[primary_key]
    pub server_id: String,
    #[unique]
    pub stdb_identity: Identity,
    pub display_name: String,
    pub region: String,
    pub game_module: String,
    pub game_mode: String,
    pub hosting_id: String,
    pub status: String,
    pub last_heartbeat: Timestamp,
    pub version: String,
    pub max_players: u32,
    pub online_count: u32,
    pub wipe_schedule: String,
    pub config_template_id: String,
}

Dual Identity Strategy

Each server carries two distinct identifiers:

Identifier Type Example Purpose
server_id String "au-sydney-pve-2" Human-readable; used in configs, UI, logs
stdb_identity Identity (32-byte crypto hash) Machine-verifiable; used for authentication

The server_id is chosen by the operator during provisioning and must be unique across the cluster. The stdb_identity is assigned by SpacetimeDB when the server's client SDK first connects. The unique constraint on stdb_identity prevents any single SpacetimeDB identity from registering as multiple servers.

For detailed discussion of the identity model, see Multi-Server Architecture.

Usage Patterns

Server Registration and Heartbeat

Servers do not have a dedicated "register" reducer. Instead, the server_heartbeat reducer performs an upsert — inserting a new row on first call and updating the existing row on subsequent calls:

// Simplified heartbeat logic
#[spacetimedb::reducer]
pub fn server_heartbeat(ctx: &ReducerContext, server_id: String, /* ... */) {
    if let Some(mut entry) = ServerRegistry::filter_by_server_id(&server_id) {
        entry.last_heartbeat = ctx.timestamp;
        entry.online_count = online_count;
        entry.status = "online".to_string();
        ServerRegistry::update_by_server_id(&server_id, entry);
    } else {
        ServerRegistry::insert(ServerRegistry {
            server_id,
            stdb_identity: ctx.sender(),
            // ... remaining fields
        });
    }
}

Staleness Detection

The last_heartbeat column enables the panel and gateway to detect unresponsive servers. A server whose last_heartbeat is older than a configured threshold (typically 60–90 seconds) can be marked as "offline" by the gateway or flagged in the dashboard.

Population Monitoring

The online_count column is updated with each heartbeat, providing a near-real-time view of player distribution across the cluster. The panel subscribes to ServerRegistry and renders this data as a live population dashboard.

Region and Mode Filtering

The region and game_mode columns allow the panel and matchmaking systems to filter servers by geography and play style. For example, a player in Europe looking for PvE servers can query:

SELECT * FROM server_registry WHERE region = 'eu-west' AND game_mode = 'pve'
Reducer Relationship
server_heartbeat Creates or updates the server's row in this table
Subscriber Query Purpose
Admin Panel SELECT * FROM server_registry Live server dashboard, population metrics
Gateway SELECT * FROM server_registry Routing, staleness checks, provisioning

For full subscription architecture, see Subscriptions.