Skip to content

Mod Examples

Reference implementations for each of the eight ModKind variants, demonstrating the mod lifecycle from manifest to installation.

1. Discord Bridge (ProcessService)

A Node.js bot that syncs game chat with Discord channels. Runs as a managed systemd service with auto-restart and health monitoring.

discord-bridge/
├── qs-mod.toml
├── package.json
├── discord-bridge.js        # Entry point
└── lib/
    ├── stdb-client.js       # SpacetimeDB subscription
    └── discord-client.js    # Discord.js bot

Behaviour: - Subscribes to ChatLog table in the game module's STDB database - On onInsert → posts message to configured Discord channel - On Discord message → calls send_chat reducer - Health endpoint at http://localhost:${PORT}/health

Lifecycle: Gateway creates systemd unit → ExecStart=/opt/qs-mods/{server_id}/discord-bridge/discord-bridge.js → environment injected from ModConfigValue → auto-restart on crash → port allocated from 8900-9899 range.

2. Faction PvP (StdbExtension)

Adds faction warfare tables to a game module's STDB database. Compiled into the game's WASM module at build time.

faction-pvp/
├── qs-mod.toml
├── Cargo.toml
└── src/
    └── lib.rs               # Tables + reducers

Tables added: - FactionWar — active wars between factions (attacker, defender, score, deadline) - WarObjective — capture points, resource nodes, territory flags - WarParticipant — individual contribution tracking (kills, captures, points) - Leaderboard — season rankings with Elo-style ratings

Reducers: declare_war, accept_war, capture_objective, surrender, end_season

Lifecycle: At STDB module build time, the extension's tables and reducers are merged into the game module's WASM binary. No runtime overhead — it's compiled in.

3. Hardcore Mode (ConfigPack)

Applies a preset configuration for hardcore survival gameplay. No code — just config overrides.

hardcore-mode/
├── qs-mod.toml
└── config/
    ├── game.json            # Game settings overrides
    └── spawn.json           # Spawn rate modifiers

config/game.json:

{
  "permadeath": true,
  "loot_multiplier": 0.3,
  "zombie_damage_multiplier": 2.5,
  "hunger_rate": 1.8,
  "thirst_rate": 1.5,
  "crafting_time_multiplier": 1.5
}

Lifecycle: Config files are applied to the target server's configuration directory. Changes take effect on server restart. Uninstalling restores the original configuration from backup.

4. Custom Loot Tables (DataPack)

Modifies drop rates and adds new item configurations. Pure data — no code execution.

custom-loot/
├── qs-mod.toml
└── data/
    ├── loot/
    │   ├── residential.json
    │   ├── military.json
    │   └── industrial.json
    └── items/
        └── custom-items.json

Lifecycle: Data files are placed in the game server's data directory (/opt/qs-mods/{server_id}/custom-loot/data/). The game module reads them on startup or via hot-reload if supported.

5. Economy Dashboard (PanelExtension)

A React component bundle that adds economy visualisation pages to the admin panel.

economy-dashboard/
├── qs-mod.toml
├── package.json
├── vite.config.ts
└── src/
    ├── index.ts             # ESM entry point (exports routes)
    ├── pages/
    │   ├── EconomyOverview.tsx
    │   ├── TradeHistory.tsx
    │   └── MarketPrices.tsx
    └── components/
        ├── PriceChart.tsx
        └── TradeTable.tsx

src/index.ts:

// PanelExtension entry — exports route definitions
export const routes = [
  { path: '/economy', component: EconomyOverview, label: 'Economy', icon: 'mdi-chart-line' },
  { path: '/economy/trades', component: TradeHistory, label: 'Trade History' },
  { path: '/economy/market', component: MarketPrices, label: 'Market Prices' },
];

Lifecycle: Built with Vite as an ESM bundle. Panel dynamically imports from /opt/qs-panel-ext/economy-dashboard/dist/index.js and registers the routes. Updates require re-uploading the bundle.

6. Auto-Restart (ProcessService)

A lightweight service that monitors server health and triggers restarts on schedule or memory threshold.

auto-restart/
├── qs-mod.toml
├── auto-restart             # Compiled Go binary
└── README.md

qs-mod.toml:

[mod]
name = "Auto-Restart"
slug = "auto-restart"
description = "Scheduled restarts and memory threshold triggers."
author = "QS-Bridge Team"

[mod.kind]
type = "ProcessService"
entry = "auto-restart"
health_check = "http://localhost:${PORT}/health"

[mod.resources]
memory_max = "64M"
cpu_quota = "5%"

[[mod.config]]
key = "schedule"
type = "String"
label = "Restart Schedule (cron)"
description = "Cron expression for scheduled restarts."
default = "0 4 * * *"

[[mod.config]]
key = "memory_threshold_mb"
type = "Integer"
label = "Memory Threshold (MB)"
description = "Restart if game server RSS exceeds this. 0 = disabled."
default = 0

[[mod.config]]
key = "warning_minutes"
type = "Integer"
label = "Warning Minutes"
description = "Minutes of in-game warnings before restart."
default = 5

7. Shared AI Library (Library)

A shared .so providing common AI routines used by multiple game modules.

ai-library/
├── qs-mod.toml
├── CMakeLists.txt
└── src/
    ├── pathfinding.cpp
    ├── perception.cpp
    └── behaviour_tree.cpp

Lifecycle: Placed in /opt/qs-mods/lib/. Game module .so files link against it at runtime via LD_LIBRARY_PATH. Versioned independently from game modules.

8. Engine Adapter (EngineAdapter)

An engine adapter .so that teaches QS-Bridge how to hook into a specific game engine.

ue5-adapter/
├── qs-mod.toml
├── CMakeLists.txt
└── src/
    ├── ue5_adapter.cpp      # EngineAdapter implementation
    ├── ue5_hooks.cpp         # UE5-specific vtable hooks
    └── ue5_memory.cpp        # UE5 memory layout definitions

Lifecycle: Placed alongside libqsbridge.so. Bridge auto-detects and loads the appropriate engine adapter based on the game server binary. One adapter per engine version.

Summary

Example ModKind Language Runtime Managed by
Discord Bridge ProcessService Node.js Systemd Platform
Faction PvP StdbExtension Rust WASM (compile-time) SpacetimeDB
Hardcore Mode ConfigPack JSON Files Game server
Custom Loot DataPack JSON Files Game module
Economy Dashboard PanelExtension React/TS ESM import Panel
Auto-Restart ProcessService Go Systemd Platform
AI Library Library C++ Shared lib Game module
UE5 Adapter EngineAdapter C++ LD_PRELOAD Bridge