Skip to content

Game Modules

Game-specific logic plugs into QS-Bridge through the Game Module system — keeping the platform universal and each game's concerns isolated.

What is a Game Module?

A game module is a self-contained package that teaches QS-Bridge how to manage a specific game. The platform handles identity, bans, admin roles, audit logging, and server lifecycle. The game module handles everything else — player positions, inventories, buildings, vehicles, AI, crafting, quests, chat, and any other game-specific state.

graph TD
  subgraph Platform["QS-Bridge Platform"]
    PlatformServices["ServerRegistry · BanEntry · AdminRole · AuditLog<br/>WhitelistEntry · PanelSession · ModuleConfig · ..."]
  end

  subgraph ModA["Game Module A — HumanitZ"]
    A1["49 tables<br/>117+ reducers<br/>UE4 engine adapter"]
  end

  subgraph ModB["Game Module B — Future Game"]
    B1["N tables<br/>M reducers<br/>UE5/Unity/Godot adapter"]
  end

  Platform --- ModA
  Platform --- ModB

Architecture

Each game module has two halves:

Component Language Runtime Location
STDB Sub-Database Rust SpacetimeDB WASM Separate STDB module with game tables + reducers
Bridge .so Plugin C++ LD_PRELOAD into game server Engine adapter + game hooks in libqsbridge.so

The STDB sub-database is a complete SpacetimeDB module with its own tables, reducers, and scheduled tasks. It communicates with the platform module through cross-database reducer calls and shared table subscriptions.

The bridge plugin runs inside the game server process, intercepting engine calls, reading game state from memory, and routing it to SpacetimeDB.

Module Responsibilities

Platform provides:

  • Server identity and registration
  • Player authentication (Steam ID → identity)
  • Ban/whitelist enforcement (cluster-wide)
  • Admin role checks
  • Audit trail logging
  • Cross-server vault and character transfers
  • Panel authentication and sessions

Game module provides:

  • Game-specific tables (positions, inventories, buildings, etc.)
  • Game-specific reducers (craft item, place building, etc.)
  • Engine hooks (which RPCs to intercept, what memory to read)
  • Optimisation layers (AI improvements, spawn management, etc.)
  • Game-specific panel pages (optional, via PanelExtension)

Data Flow

graph TD
  GSP["Game Server Process"]

  subgraph Engine["Engine — UE4/UE5/Unity/Godot"]
    E1["Tick loop → Bridge intercepts"]
    E2["RPC calls → Bridge hooks"]
    E3["State changes → Bridge reads memory"]
  end

  subgraph Bridge["Bridge — .so via LD_PRELOAD"]
    EA["Engine Adapter<br/>(UE4 vtable hooks, etc.)"]
    GMH["Game Module hooks<br/>(game-specific intercepts)"]
    STDB["STDB Client<br/>(WebSocket, BSATN protocol)"]
  end

  STDB --> PlatformMod["Platform STDB Module<br/>(register, heartbeat, ban check)"]
  STDB --> GameDB["Game STDB Sub-Database<br/>(positions, vitals, buildings)"]

  Vanilla["Vanilla game continues running<br/>(rendering, physics, networking — unchanged)"]

  GSP --- Engine
  GSP --- Bridge
  GSP --- Vanilla

Current Modules

Module Game Engine Status Tables Reducers
HumanitZ HumanitZ UE4 4.27 Active 49 117+
Future TBD UE5/Unity/Godot Planned — —