Skip to content

Mod Manifest

Every QS-Bridge mod declares its identity, kind, compatibility, and configuration schema through a structured manifest.

Manifest File

Each mod contains a qs-mod.toml manifest at its root:

[mod]
name = "Discord Bridge"
slug = "discord-bridge"
description = "Bidirectional chat sync between game servers and Discord channels."
author = "QS-Bridge Team"
license = "MIT"
homepage = "https://wiki.qs-zuq.com/en/modding/examples"
repository = "https://github.com/example/discord-bridge"

[mod.kind]
type = "ProcessService"
entry = "discord-bridge"           # Executable name
health_check = "http://localhost:${PORT}/health"

[mod.compatibility]
platform_min = "0.2.0"            # Minimum QS-Bridge platform version
engines = ["*"]                    # All engines, or ["ue4", "ue5"]
games = ["*"]                      # All games, or ["humanitz"]

[mod.resources]
memory_max = "256M"                # ProcessService: systemd MemoryMax
cpu_quota = "25%"                  # ProcessService: systemd CPUQuota

[[mod.config]]
key = "discord_token"
type = "Secret"
label = "Discord Bot Token"
description = "The bot token from the Discord Developer Portal."
required = true

[[mod.config]]
key = "channel_id"
type = "String"
label = "Chat Channel ID"
description = "Discord channel ID for game chat sync."
required = true

[[mod.config]]
key = "embed_colour"
type = "Color"
label = "Embed Colour"
description = "Colour for Discord embed messages."
default = "#d4915c"

[[mod.config]]
key = "sync_joins"
type = "Boolean"
label = "Announce Joins/Leaves"
description = "Post player join/leave events to Discord."
default = true

[[mod.config]]
key = "prefix"
type = "String"
label = "Command Prefix"
description = "Prefix for bot commands in Discord."
default = "!"

[mod.version]
version = "2.0.0"
changelog = """
- Added bidirectional chat sync
- Added embed colour configuration
- Improved reconnection handling
"""

Manifest Fields

[mod] — Identity

Field Required Type Description
name ✅ String Human-readable mod name
slug ✅ String URL-safe identifier ([a-z0-9-]+)
description ✅ String Short description (max 500 chars)
author ✅ String Author name or organisation
license Optional String SPDX license identifier
homepage Optional URL Documentation or landing page
repository Optional URL Source code repository

[mod.kind] — Type Declaration

Field Required Type Description
type ✅ ModKind One of the 8 mod kinds
entry Varies String Entry point (executable, .so, WASM path, ESM bundle)
health_check Optional String Health check URL template (ProcessService only)

Entry Points by ModKind

ModKind entry Field Example
GameModule .so filename libqsbridge-humanitz.so
EngineAdapter .so filename libqsbridge-ue4.so
ProcessService Executable name discord-bridge
StdbExtension Crate path src/lib.rs
PanelExtension ESM bundle dist/index.js
ConfigPack Config directory config/
DataPack Data directory data/
Library .so filename libqs-common.so

[mod.compatibility] — Requirements

Field Required Type Description
platform_min ✅ Semver Minimum QS-Bridge version
engines Optional Array Compatible engines (["*"] for all)
games Optional Array Compatible games (["*"] for all)

[mod.resources] — Resource Limits (ProcessService only)

Field Required Type Description
memory_max Optional String Systemd MemoryMax (e.g., "256M")
cpu_quota Optional String Systemd CPUQuota (e.g., "25%")

[[mod.config]] — Configuration Schema

Each [[mod.config]] entry defines one configurable field:

Field Required Type Description
key ✅ String Unique field identifier
type ✅ FieldType See Dynamic Configuration
label ✅ String Human-readable label for panel UI
description Optional String Help text shown below the input
required Optional Boolean Whether the field must be set (default: false)
default Optional Any Default value if not configured
validation_pattern Optional String Regex pattern for String fields
options Optional Array Options for Select/MultiSelect fields

[mod.version] — Current Release

Field Required Type Description
version ✅ Semver Version string (e.g., "2.0.0")
changelog Optional String Markdown changelog for this version

Publishing

1. Validate Manifest

# Validate manifest structure (future CLI tool)
qs-bridge mod validate

2. Package

# Create distributable archive
qs-bridge mod pack
# → discord-bridge-2.0.0.tar.gz

3. Upload

# Publish to registry
qs-bridge mod publish --server https://api.qs-zuq.com

Or via the REST API directly:

curl -X POST https://api.qs-zuq.com/registry/v1/publish \
  -H "Authorization: Bearer $API_KEY" \
  -F "manifest=@qs-mod.toml" \
  -F "archive=@discord-bridge-2.0.0.tar.gz"

4. Install

Server operators install from the admin panel or via API:

curl -X POST https://api.qs-zuq.com/registry/v1/install \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"server_id": "server-01", "project_slug": "discord-bridge", "version": "2.0.0"}'

Manifest Examples by ModKind

GameModule

[mod.kind]
type = "GameModule"
entry = "libqsbridge-humanitz.so"

ConfigPack

[mod.kind]
type = "ConfigPack"
entry = "config/"

[[mod.config]]
key = "difficulty"
type = "Select"
label = "Difficulty Preset"
options = ["Easy", "Normal", "Hard", "Nightmare"]
default = "Normal"

DataPack

[mod.kind]
type = "DataPack"
entry = "data/"
# No config needed — just data files