Skip to content

Quick Start Guide

This guide walks you through deploying QS-Bridge from scratch: building the C++ bridge, publishing the SpacetimeDB modules, bootstrapping your first admin account, starting the admin panel, and connecting a game server. By the end, you will have a fully operational QS-Bridge deployment managing a game server.

Prerequisites: Ensure all dependencies are installed before proceeding. See Requirements & Prerequisites for the full checklist.

Step 1: Clone the Repository

git clone https://github.com/QS-Zuq
cd qs-bridge

The repository structure:

qs-bridge/
├── bridge/            # C++ shared library (libqsbridge.so)
├── modules/
│   ├── platform/      # Rust — Platform STDB module (12 tables, 24 reducers)
│   ├── mod-registry/  # Rust — Mod Registry module (10 tables, 30+ reducers)
│   └── humanitz/      # Rust — HumanitZ game module (49 tables, 117 reducers)
├── api/               # TypeScript — Hono API gateway
├── ui/                # TypeScript — React admin panel
├── scripts/           # Utility scripts (bootstrap, deploy, etc.)
└── docs/              # Documentation

Step 2: Build the Bridge

The C++ bridge compiles into libqsbridge.so, the shared library that gets injected into the game server process.

cd bridge

# Configure the build
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build (use -j to parallelise)
cmake --build build -j$(nproc)

On success, the output binary is located at:

bridge/build/libqsbridge.so   (~8.6 MB)

Build options:

CMake Option Default Description
CMAKE_BUILD_TYPE Debug Set to Release for production builds.
QSB_ENABLE_TESTS ON Build the test suites (860+ assertions).
QSB_GAME_MODULE humanitz Which game module to compile into the library.

To run the test suite after building: 

cd build && ctest --output-on-failure

Step 3: Deploy SpacetimeDB Modules

Ensure your SpacetimeDB instance is running (see Requirements), then publish the modules:

# Publish the platform module
cd modules/platform
spacetime publish qs-bridge --clear-database

# Publish the mod registry module
cd ../mod-registry
spacetime publish qs-bridge-mods --clear-database

# Publish the game module (e.g., HumanitZ)
cd ../humanitz
spacetime publish qs-bridge-humanitz --clear-database

⚠ Warning: The --clear-database flag wipes all existing data in the module. Only use it on first deployment or when you intentionally want to reset state. For subsequent deployments, omit this flag to preserve data.

Verify the modules are published:

spacetime list

You should see qs-bridge, qs-bridge-mods, and qs-bridge-humanitz in the output.

Step 4: Bootstrap the First Admin

Before the admin panel can be used, you need to create the first administrator account. The bootstrap script creates an account record in SpacetimeDB and grants it the owner role.

cd scripts

# Bootstrap with your Steam ID
./bootstrap-admin.sh \
  --stdb-uri ws://localhost:3000 \
  --module qs-bridge \
  --steam-id YOUR_STEAM_ID_64

Replace YOUR_STEAM_ID_64 with your 64-bit Steam ID (a 17-digit number, e.g., 76561198012345678). You can find your Steam ID at steamid.io.

Expected output:

✓ Connected to SpacetimeDB at ws://localhost:3000
✓ Created account for Steam ID 76561198012345678
✓ Granted 'owner' role
✓ Bootstrap complete — sign in via the admin panel to continue.

Note: The bootstrap script only needs to be run once. Additional administrators can be promoted from the admin panel after the first sign-in.

Step 5: Start the Admin Panel

The admin panel consists of two services: the API gateway and the UI dev server. Both must be running.

5a. Install Dependencies

# Install API gateway dependencies
cd api
npm install

# Install UI dependencies
cd ../ui
npm install

5b. Configure Environment

Create .env files for both services:

api/.env 

QSB_STDB_URI=ws://localhost:3000
QSB_HMAC_SECRET=your-secret-key-at-least-32-characters-long
QSB_STEAM_API_KEY=your-steam-web-api-key
QSB_GATEWAY_PORT=3001
QSB_CORS_ORIGIN=http://localhost:3002

ui/.env 

VITE_API_URL=http://localhost:3001

Security: Never commit .env files to version control. Both api/.env and ui/.env are listed in .gitignore by default.

5c. Start the Services

Open two terminal sessions (or use a process manager like pm2):

Terminal 1 — API Gateway: 

cd api
npm run dev

Expected output: 

  API Gateway listening on http://localhost:3001
  Steam OpenID 2.0 endpoint: /auth/steam
  Connected to SpacetimeDB at ws://localhost:3000

Terminal 2 — Admin Panel UI: 

cd ui
npm run dev

Expected output: 

  VITE v6.x.x  ready in 500ms

  ➜  Local:   http://localhost:3002/
  ➜  Network: http://192.168.x.x:3002/

Step 6: Configure the Game Server

QS-Bridge injects into the game server via the LD_PRELOAD mechanism. You need to set environment variables that tell the bridge where to find SpacetimeDB and how to identify this server.

Option A: Direct Environment Variables

export LD_PRELOAD=/path/to/libqsbridge.so
export QSB_SERVER_ID="my-first-server"
export QSB_STDB_URI="ws://localhost:3000"
export QSB_LOG_LEVEL="info"

Create a systemd service that wraps the game server:

# /etc/systemd/system/game-server.service
[Unit]
Description=Game Server with QS-Bridge
After=network.target spacetimedb.service
Requires=spacetimedb.service

[Service]
Type=simple
User=gameserver
WorkingDirectory=/opt/gameserver

Environment="LD_PRELOAD=/opt/qsbridge/libqsbridge.so"
Environment="QSB_SERVER_ID=my-first-server"
Environment="QSB_STDB_URI=ws://localhost:3000"
Environment="QSB_LOG_LEVEL=info"
Environment="QSB_SYNC_INTERVAL_MS=100"

ExecStart=/opt/gameserver/GameServer.sh
Restart=always
RestartSec=10

WatchdogSec=60
NotifyAccess=all

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable game-server

Step 7: Start the Game Server

With systemd (Production)

sudo systemctl start game-server

# Check status
sudo systemctl status game-server

# View bridge logs
journalctl -u game-server -f | grep "\[qsbridge\]"

Without systemd (Development)

LD_PRELOAD=/path/to/libqsbridge.so \
QSB_SERVER_ID="my-first-server" \
QSB_STDB_URI="ws://localhost:3000" \
QSB_LOG_LEVEL="debug" \
./GameServer.sh

You should see bridge initialisation messages in the game server's stdout:

[qsbridge] QS-Bridge v1.0.0 initialising...
[qsbridge] Server ID: my-first-server
[qsbridge] Connecting to SpacetimeDB at ws://localhost:3000...
[qsbridge] Identity authenticated (stdb_identity: 0x7f3a...)
[qsbridge] Subscribed to 49 tables
[qsbridge] Background sync started (interval: 100ms)
[qsbridge] Ready.

Step 8: Open the Admin Panel

Navigate to the admin panel in your browser:

http://localhost:3002

You will see the QS-Bridge login screen.

Step 9: Sign In with Steam

  1. Click "Sign in with Steam" on the login screen.
  2. You will be redirected to the Steam login page.
  3. Sign in with the Steam account whose ID you used in Step 4.
  4. Steam redirects back to the admin panel.
  5. The API gateway validates the OpenID assertion, matches your Steam ID to the bootstrapped account, and issues a JWT session token.
  6. You are now signed in as the owner of the deployment.

First sign-in: On your first sign-in, the dashboard will show your server (my-first-server) with live status indicators. If the game server is running and the bridge is connected, you will see a green "Connected" badge.

Deployment Summary

After completing all steps, your deployment looks like this:

Service Address Status
SpacetimeDB ws://localhost:3000 Running
API Gateway http://localhost:3001 Running
Admin Panel http://localhost:3002 Running
Game Server udp://*:7777 Running with libqsbridge.so injected 
graph TD
    Browser --> Panel[":3002 (Admin Panel)"]
    Panel --> GW[":3001 (API Gateway + Steam Auth)"]
    GW --> STDB[":3000 (SpacetimeDB)"]
    GameServer["Game Server + libqsbridge.so"] --> STDB

Now that your deployment is running:

  • Add more servers — set a different QSB_SERVER_ID for each game server instance and start them against the same SpacetimeDB. They will appear automatically in the admin panel.
  • Enable mods — browse the Mod Registry from the admin panel and enable mods on a per-server basis.
  • Promote administrators — use the admin panel's user management page to grant roles to other Steam accounts.
  • Set up production TLS — place Nginx or Caddy in front of the API gateway and admin panel with TLS certificates.

Troubleshooting

Symptom Likely Cause Fix
[qsbridge] Connection refused SpacetimeDB not running or wrong URI Verify spacetime start and check QSB_STDB_URI
[qsbridge] Module not found STDB module not published Re-run spacetime publish (Step 3)
[qsbridge] Identity mismatch Credential file from a different STDB instance Delete ~/.qsbridge/credentials.json and restart
Steam sign-in redirects to error Invalid Steam API key Verify QSB_STEAM_API_KEY in api/.env
Panel shows "No servers" Game server not started or bridge not connected Check systemctl status game-server and bridge logs
LD_PRELOAD: cannot open shared object Wrong path to libqsbridge.so Use absolute path; verify file exists and is readable

Reference