Skip to content

Platform Overview

QS-Bridge is a SpacetimeDB-backed server management platform that transforms how game servers are operated, modded, and scaled. It sits between a game server process and a SpacetimeDB instance, intercepting engine state at the native level and offloading it to a purpose-built relational database — replacing fragile, file-based server tooling with a real-time, queryable data layer.

In one sentence: QS-Bridge turns every game server into a managed, moddable, observable service — without touching the game's source code.

Three Ways to Think About QS-Bridge

1. A Platform

QS-Bridge provides a complete operational stack for running game servers on a VPS:

  • React Admin Panel — a modern dashboard for server owners and administrators to manage players, view live state, configure mods, and monitor health.
  • API Gateway — a Hono-based TypeScript service that authenticates users via Steam OpenID 2.0, authorises actions, and proxies requests to SpacetimeDB.
  • Multi-Server Architecture — a single SpacetimeDB instance serves N game servers simultaneously. One account can own and operate many servers from a single panel.
  • Mod Registry — a curated catalogue of server-side mods (8 ModKind variants, 10 tables, 30+ reducers) that can be selectively enabled per server.

2. A Server-Side Modding SDK

Game developers and modders author game modules — C++ translation units that register tables, reducers, and hooks against a specific engine. QS-Bridge provides the framework:

Layer Responsibility
BSATN Codec Binary encoding/decoding for SpacetimeDB's wire format (18 header-only files)
STDB Client WebSocket transport, subscription management, reducer dispatch
Bridge Core Lifecycle management, table registry, sync scheduler, identity resolution
Engine Adapter Engine-specific glue (e.g., Unreal Engine 4.27 actor replication)
Game Module Per-game tables and reducers (e.g., HumanitZ: 49 tables, 117 reducers)

The C++17 shared library (libqsbridge.so, ~8.6 MB) is injected into the game server via LD_PRELOAD. No engine source modifications are required.

3. A Performance Engine

The core technical insight behind QS-Bridge is a fundamental change in how state synchronisation scales.

The Replication Problem

Unreal Engine 4's built-in actor replication uses a model where the server iterates over every net-relevant actor for every connected client on every tick. The cost grows as:

\[ C_{\text{replication}} = O(n_{\text{actors}} \times n_{\text{clients}}) \]

In practice this is O(n²) because both actor count and client count grow with server population. At scale, replication dominates the server frame budget and becomes the binding constraint on player capacity.

The SpacetimeDB Model

SpacetimeDB replaces this with subscription-based change propagation. When a row changes, only the subscriptions whose query matches that row are notified:

\[ C_{\text{sync}} = O(n_{\text{changed\_rows}} \times \log(n_{\text{subscriptions}})) \]

This is a logarithmic relationship. Doubling the number of connected clients does not double the sync cost — it adds a negligible log factor. The result is near-linear scaling with server population, unlocking player counts that are impractical under the traditional replication model.

Key takeaway: QS-Bridge does not "optimise" UE4 replication. It replaces the replication model entirely for managed state, delegating it to a purpose-built database engine.

How Game Servers Connect

graph TD
    GS1["Game Server (UE4)<br/>+ libqsbridge"] -->|ws://| STDB
    GS2["Game Server (UE4)<br/>+ libqsbridge"] -->|ws://| STDB
    GS3["Game Server (UE4)<br/>+ libqsbridge"] -->|ws://| STDB

    subgraph STDB["SpacetimeDB Instance"]
        PM["Platform Module<br/>(12 tables)"]
        MR["Mod Registry Module<br/>(10 tables)"]
    end

Every game server is identified by a unique server_id (a human-readable string like "us-east-1-pvp") and a stdb_identity (a cryptographic identity assigned by SpacetimeDB). When libqsbridge.so initialises:

  1. It reads QSB_SERVER_ID and QSB_STDB_URI from the environment.
  2. It opens a WebSocket connection to the SpacetimeDB instance.
  3. It registers the server's identity and subscribes to the tables relevant to that server.
  4. It begins the background sync loop, pushing state changes to STDB and receiving subscription updates asynchronously.

All servers share a single STDB instance. Table rows are partitioned by server_id, so each server sees only its own data. The platform module (12 tables, 24 reducers) manages cross-cutting concerns: accounts, permissions, audit logs, and server metadata.

Architecture Principles

VPS-Only Deployment

QS-Bridge is designed exclusively for bare-metal or VPS environments. It is not a containerised, serverless, or cloud-native application. This is a deliberate choice:

  • Game servers require predictable latency and direct hardware access.
  • LD_PRELOAD injection requires control over the process environment.
  • systemd provides robust process supervision, port allocation, and health monitoring without orchestration overhead.

See Requirements & Prerequisites for hardware and OS recommendations.

Stateless Frontend

The React admin panel and API gateway are stateless. They hold no server state of their own — all persistent state lives in SpacetimeDB. This means:

  • The panel can be restarted, redeployed, or scaled horizontally without data loss.
  • Multiple panel instances can serve the same STDB backend.
  • Frontend crashes never corrupt server state.

Separate API Layer

The API gateway is a distinct process from both the game server and the admin panel. It:

  • Authenticates users via Steam OpenID 2.0.
  • Enforces role-based access control (RBAC) before forwarding requests.
  • Translates HTTP REST semantics into SpacetimeDB reducer calls.
  • Provides a stable API surface that insulates the panel from STDB schema changes.

Background Sync

State synchronisation between the game server and SpacetimeDB is asynchronous and non-blocking. The bridge maintains an internal write queue and flushes changes on a configurable interval. This ensures:

  • Game server frame rate is never blocked by network I/O.
  • Transient network interruptions are absorbed by the queue.
  • Bulk state changes (e.g., world saves) are batched efficiently.

One Account → Many Servers

A single QS-Bridge account (linked to a Steam identity) can own and administer multiple game servers. The admin panel provides a server selector, and all management actions are scoped to the selected server. This enables hosting companies to offer multi-server packages without per-server account provisioning.

Per-Server Mod Selection

Mods are registered in the Mod Registry (a dedicated STDB module) and enabled on a per-server basis. Server owners can browse available mods, enable or disable them, and configure mod-specific settings — all from the admin panel. The 8 ModKind variants cover the full spectrum of server-side modifications:

Variant Description
Gameplay Rules, mechanics, difficulty adjustments
Economy Trading, currency, marketplace systems
Social Chat, clans, reputation systems
Admin Moderation tools, logging, anti-cheat
World Map modifications, POI management, weather
Spawning Entity spawn rules, loot tables, population control
Events Scheduled events, challenges, seasonal content
Utility Quality-of-life, diagnostics, automation

Test Coverage

QS-Bridge maintains 860+ test assertions across 7 test suites, covering the BSATN codec, client transport, bridge lifecycle, engine adapter, platform module, mod registry, and end-to-end integration. All tests run in CI on every commit.