Skip to content

Modding

QS-Bridge treats mods as first-class citizens — not file-drop hacks. Eight distinct mod kinds cover everything from game logic to panel extensions to data packs, all managed through the Mod Registry with per-server installation tracking and dynamic configuration.

What is a QS-Bridge Mod?

A mod is any package that extends, configures, or enhances a QS-Bridge deployment. Unlike traditional game mods (which typically replace files), QS-Bridge mods are typed, versioned, and runtime-managed. The platform knows what kind of mod it is, how to install it, how to start/stop it, and how to configure it — because every mod declares its ModKind.

The Eight Mod Kinds

Each ModKind has different lifecycle semantics:

ModKind Runtime Install Method Example
GameModule .so via LD_PRELOAD Place in server mod directory, configure preload chain HumanitZ module
EngineAdapter .so via LD_PRELOAD Place library, update bridge configuration UE4 adapter, UE5 adapter
ProcessService Standalone process Systemd unit, auto-start, health monitoring Discord bot, monitoring agent
StdbExtension WASM (compile-time) Merge into game's STDB module at build time Faction PvP tables, economy system
PanelExtension React ESM Unpack bundle to /opt/qs-panel-ext/ Economy dashboard, custom analytics
ConfigPack Configuration files Apply config presets to target mod/server Hardcore mode, PvE preset
DataPack Data files Place in game data directory Custom loot tables, spawn configs
Library Shared library Place in /opt/qs-mods/lib/ Shared utilities, common AI library

Mod Registry

The Mod Registry is a Rust STDB WASM module with 10 tables and 30+ reducers. It stores mod metadata in SpacetimeDB and mod files in MinIO (S3-compatible object storage).

Registry Tables

Table Purpose
ModProject Mod identity — name, slug, author, description, mod_kind
ModVersion Versioned releases with semver, changelog, compatibility
ModFile File references (MinIO keys), checksums, sizes
ModReview User reviews with ratings (1-5)
ReviewVote Helpfulness votes on reviews
ModDownload Download analytics
InstalledMod Per-server installation tracking (server_id × project_id)
ModConfigField Dynamic config schema — field type, label, default, validation
ModConfigValue Per-install config values (server_id × project_id × field_key)
RegistryConfig Registry-wide settings (review moderation, upload limits)

REST API

The registry exposes a REST API at /registry/v1/*:

Method Endpoint Description
GET /registry/v1/mods List all published mods (paginated, filterable)
GET /registry/v1/mods/:slug Get mod details + versions
GET /registry/v1/mods/:slug/versions/:version Get specific version
POST /registry/v1/publish Upload new mod version (authenticated)
POST /registry/v1/install Install mod on server
DELETE /registry/v1/install/:server_id/:slug Uninstall mod
GET /registry/v1/installed/:server_id List installed mods for server

Installation Flow

1. Admin clicks "Install" on mod in panel
2. POST /registry/v1/install { server_id, project_id, version_id }
3. Gateway creates InstalledMod row: status = Downloading
4. Download mod files from MinIO → /opt/qs-mods/{server_id}/{slug}/
5. Per-ModKind install logic executes
6. InstalledMod status → Installing → Installed
7. If ProcessService: generate systemd unit, start service
8. Panel sees real-time status update via subscription

Per-Server Mod Selection

Each server independently chooses which mods to run. The same mod can be installed on multiple servers with different versions and configurations:

graph TD
    subgraph A["Server A"]
        A1["HumanitZ Module v1.2"]
        A2["Discord Bridge v2.0"]
        A3["Hardcore Mode"]
        A4["Custom Loot Tables"]
    end

    subgraph B["Server B"]
        B1["HumanitZ Module v1.3"]
        B2["Discord Bridge v2.0 (different config!)"]
        B3["Economy Dashboard"]
    end

The InstalledMod table tracks the relationship:

server_id project_id version status assigned_port
server-a humanitz 1.2.0 Installed —
server-a discord-bridge 2.0.0 Running 8901
server-b humanitz 1.3.0 Installed —
server-b discord-bridge 2.0.0 Running 8902

Dynamic Configuration

Mods declare configurable fields via the ModConfigField table. The admin panel renders configuration forms dynamically — no hardcoded UI per mod.

Supported Field Types

Type Input Example
String Text input Server name, webhook URL
Integer Number input Max players, spawn rate
Float Number input (decimal) Damage multiplier
Boolean Toggle switch Enable/disable feature
Select Dropdown Difficulty preset
MultiSelect Multi-select Enabled features
Color Colour picker Team colour
Json Code editor Custom configuration
Secret Password input API keys, tokens