Skip to content

QS-Bridge Platform Overview

The game-agnostic infrastructure layer — 12 STDB tables, 24 reducers, API gateway, and admin panel.

The QS-Bridge Platform is the foundational infrastructure layer of the QS-Bridge ecosystem. It provides a unified, game-agnostic backbone for managing multi-server game environments — handling server registration, player administration, cross-server logistics, and real-time operational telemetry through a single SpacetimeDB WASM module.

Architecture

QS-Bridge follows a layered separation of concerns model:

Layer Responsibility Storage
Platform Server registry, bans, whitelist, admin roles, presence, transfers, events, vault Core WASM module (this layer)
Game Hook Game-specific schemas — inventories, characters, buildings, economy Separate sub-databases per game
Panel Web-based administration dashboard Subscribes to platform tables

The platform layer is intentionally game-agnostic. It knows nothing about specific game mechanics, item definitions, or character stats. Game-specific data lives in dedicated sub-databases that extend the platform through SpacetimeDB's subscription model. This design allows a single QS-Bridge deployment to support multiple game titles, modes, or modded configurations without schema conflicts.

Core Components

Tables (12)

The platform defines 12 tables that collectively manage the full lifecycle of a multi-server game cluster:

# Table Scope Purpose
1 ServerRegistry 🌍 Global Master registry of all servers in the cluster
2 ServerConfig 🔵 Local Per-server configuration (name, password, MOTD)
3 BanEntry 🌍 Global Cluster-wide ban records
4 WhitelistEntry 🌍 Global Cluster-wide whitelist
5 AdminRole 🌍 Global Role-based access control for administrators
6 PanelSession 🌍 Global Active admin panel sessions
7 PanelAuditLog 🌍 Global Immutable audit trail of admin actions
8 ModuleConfig 🌍 Global Singleton — stores the module owner identity
9 PlayerServerPresence 🌍 Global Tracks which server each player is on
10 GlobalVault 🌍 Global Cross-server item storage
11 ServerTransferQueue 🌍 Global Player character transfer pipeline
12 CrossServerEvent 🌍 Global Scheduled and active cluster-wide events

Reducers (24)

The platform exposes 24 reducers — the callable mutation functions in SpacetimeDB — organized into four groups:

  • Admin Reducers (12): Direct administrative operations — bans, kicks, whitelist management, role grants, configuration changes.
  • Panel Reducers (11): Wrapper reducers invoked by the web panel. These validate panel session state before delegating to admin reducers, providing an additional authorization layer.
  • Server Reducer (1): The server_heartbeat reducer, called periodically by game servers to report liveness.

For full reducer documentation, see Reducers.

Subscriptions

SpacetimeDB's reactive subscription model drives real-time synchronization across the platform. Game hooks and the admin panel subscribe to different table subsets based on their operational needs.

For subscription architecture details, see Subscriptions.

Design Principles

Game-Agnostic Core

The platform layer contains zero game-specific logic. There are no references to specific item IDs, character classes, crafting recipes, or game mechanics anywhere in the 12 platform tables. This separation means:

  • A single platform module can manage servers across different games.
  • Game updates, patches, or modding changes never require platform schema migrations.
  • The admin panel works identically regardless of the underlying game.

Global-First Data Model

Eleven of the twelve platform tables have global scope (🌍). This is by design — the platform's primary value proposition is cluster-wide consistency. Bans are global. Whitelist entries are global. Admin roles are global. The only local-scope table is ServerConfig, which stores per-server settings that intentionally vary between nodes.

Identity Duality

Every registered server carries two identifiers:

Identifier Type Purpose
server_id String Human-readable label (e.g., "us-east-pvp-1")
stdb_identity Identity Cryptographic identity assigned by SpacetimeDB

This dual-identity strategy allows human-friendly references in configuration and UI while maintaining cryptographic authentication for inter-server communication. See Multi-Server Architecture for details.

Module Lifecycle

The platform module follows a defined initialization and runtime lifecycle:

  1. Deployment: The compiled Rust WASM module is published to a SpacetimeDB instance.
  2. Initialization: The init reducer fires once, capturing ctx.sender() as the owner_identity in the ModuleConfig singleton.
  3. Server Registration: Game servers call server_heartbeat to register themselves in the ServerRegistry.
  4. Subscription Binding: Game hooks and panel clients subscribe to their respective table sets.
  5. Steady State: Reducers process mutations; subscriptions push changes in real time.

For details on module initialization and the is_gateway() guard pattern, see SpacetimeDB Module.