.profile/README.md

Runic Gateway

A website platform for game communities, wired to the live game.

Runic Gateway gives a game community a public site, wiki, and admin panel — and bridges it to the running game server, so the site can show live status, economy, player activity, per-character detail and more, while staff push commands back the other way. Players get the same public content and self-service on the web or a native Android app.

The platform itself knows nothing about any particular game. Everything game-specific — routes, tables, pages, navigation, notifications — arrives as an installable module, installed from the admin panel with nothing to build. Ultima Online (ServUO) is the first game, and one installer sets up its shard side.

---

The pieces

Runic Gateway is eight repositories that deploy together but build independently.

The platform — the same for every game:

Repo	Language	What it is
website	JavaScript (Node + React)	The full-stack app — Express REST API + MariaDB + a React/Vite SPA (public site, wiki, admin panel), plus the module loader that game support plugs into. This is the thing players and staff actually visit, and the single backend every client talks to.
Android-app	Kotlin (Jetpack Compose)	The native Android client — public content + player self-service, purely an API client of the website backend. Same features as the browser client minus every admin console. Never touches a game server.
docs	Markdown	All project documentation — design docs, the module contract, the wire-protocol spec, the integration guide, the Android plan, research. Start here when you want the why.
Integration-kit	Markdown + a buildable template	How to put a different game on a Runic Gateway site. A four-chapter book and a module template that builds and loads. Read this if your game is not Ultima Online.

Ultima Online support — the first game, and the worked example everything else is measured against:

Repo	Language	What it is
Module-uo	JavaScript (Node + React)	The UO module — every UO-specific route, table, page and notification the site serves: shard status, economy, IDOCs, character sheets, a player-vendor marketplace, a bestiary built from the shard's own spawn tables, and the staff control consoles. Installed into a website; released as a versioned bundle.
link	Rust	The uo-link sidecar. Runs next to the shard, terminates a loopback link from the game, persists what the game says, and exposes the authenticated WebSocket + REST API the website consumes. The only network-facing half of the bridge.
servuo-plugins	C#	The ServUO plugin — the shard side of the bridge. Compiled by ServUO at boot; dials the sidecar over loopback and emits game events / accepts commands.
installer	Rust	The installer — one binary per OS that deploys the plugin and the sidecar onto a shard host as a matched, protocol-checked pair, registers the service, and hands you the values the website needs. How you set a shard up.

How they fit together

                                                              ┌─▶ browser       same-origin JSON / SSE
ServUO shard  ──loopback TCP,──▶  uo-link sidecar  ──WS + REST──▶  website backend ─┤
(servuo-plugins) newline-JSON      (link, Rust)      bearer-auth   (+ Module-uo)    └─▶ Android app   REST + push (ntfy)

Three layers, and the shape is the same for any game:

1. A game-side plugin feeds a sidecar without ever letting the sidecar stall the game — a bounded drop-oldest queue and a dedicated writer thread.
2. A sidecar owns the connection to the game and the durable copy of what it said. It is the listener: the game is never exposed to the internet and only dials 127.0.0.1. The sidecar persists before it forwards, so a website that is down or mid-deploy loses nothing and a page shows the last thing the game said instead of going blank.
3. A website module turns that feed into routes, tables and pages. The website process never opens a connection to a game server — that is a rule in the module contract, not a style preference.

• The website backend ingests a live event stream from the sidecar (logins, vitals, economy, vendor sales, deaths, IDOC decay, staff audit…) and makes point-in-time REST calls for rosters and character sheets. It then fans that out to browsers over Server-Sent Events — a public channel (safe kinds only) and an admin channel (everything).
• The Android app is just another client of the website backend — it speaks the same public REST API and never talks to the sidecar or the game. It self-configures its server URL on first run, so one build works against any site, and receives push notifications through the self-hosted ntfy relay (no Google Play Services required).
• Players link a game account to a website account with a one-time in-game code, which is what authorizes character reads. Staff can push town-crier messages and control commands back into the game.
• Accounts are hardened out of the box — TOTP two-factor with trusted devices, optional SSO (Google / Discord / any OIDC provider, link-only: an external identity must already belong to an account), bot scoring with automatic IP bans, and rate limiting.
• Who sees which game data is configurable, not hardcoded: an admin panel decides the audience for each surface, and the public SSE channel can never carry a sensitive event kind.

The connection between website and sidecar (URL, shared-secret token, protocol version) is admin-managed in the database, not env — the installer prints those values and you paste them once into the site's Admin → Shard panel. If the sidecar is absent or the game is down, every game surface degrades gracefully.

---

Quick start

A live site is three things: the website, a module for your game, and the game side — for Ultima Online, the sidecar plus the plugin, which the installer deploys in a single run on the machine that hosts your ServUO server. The Android-app is an optional client you point at your running website.

1. Website — the site + admin panel

Prereqs: Node.js 20+ and Docker (for MariaDB).

git clone https://gitea.whitlocktech.com/RunicGateway/website.git
cd website

# Start a MariaDB the backend can reach
docker run -d --name rg-db -p 3306:3306 \
  -e MARIADB_DATABASE=runic_gateway -e MARIADB_USER=runic \
  -e MARIADB_PASSWORD=devpass -e MARIADB_ROOT_PASSWORD=rootpass mariadb:11

# Configure + start the backend (terminal 1)
cp server/.env.example server/.env
#   set DB_HOST=127.0.0.1, DB_PORT=3306, DB_USER=runic, DB_PASSWORD=devpass,
#       JWT_SECRET=<anything>, ADMIN_USERNAME=admin, ADMIN_PASSWORD=<your password>
npm run install-server
npm run server            # nodemon → http://localhost:3000

# Start the frontend (terminal 2)
npm run install-client
npm run client            # Vite → http://localhost:5173

Open http://localhost:5173, sign in at /admin/login with the admin credentials you set, then flip Maintenance → Live on the Dashboard. Tables, defaults, and the first admin are created automatically on first boot.

Production (Docker Compose): the website ships a production-shaped docker-compose.yml that pulls prebuilt app + bot images and serves the built SPA from Express — cp .env.example .env, fill it in, then docker compose pull && docker compose up -d. See the website README for the full options.

2. Your game — install a module

Nothing to build and no core release needed. In Admin → Modules, paste the URL of a module release's install manifest; the site downloads the bundle it names, verifies its sha256, unpacks it onto the modules volume, and offers you the restart that loads it. For Ultima Online that manifest is module-uo-<version>.json from the Module-uo releases:

https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases/download/v0.3.0/module-uo-0.3.0.json

A compose-managed host can declare the set instead of clicking, with MODULES=uo@0.3.0=<that URL> — resolution at container start is idempotent and offline-safe, so a restart with the network down brings the site up exactly as it was.

The module system is landing: it lives on the website's edge branch and reaches main as one cutover at the end of the current workstream. A main checkout today serves the Ultima Online features from core directly and has no Modules screen — same site, same URLs, nothing to install.

A game that is not Ultima Online? That is what the Integration-kit is for — a module template that builds and loads, and a book covering all three layers: the website module, the sidecar, and the game-side plugin.

3. The shard side — one installer run

Prereqs: a working ServUO install, currently stopped, and Administrator/root. Nothing to build and no Gitea account needed. Grab a binary and SHA256SUMS from the installer releases — releases are unsigned, so the checksum is the trust anchor:

sha256sum -c SHA256SUMS --ignore-missing
chmod +x runicgateway-installer-linux-x86_64
sudo ./runicgateway-installer-linux-x86_64 install

# Windows, from an elevated PowerShell
.\runicgateway-installer-windows-x86_64.exe install

It resolves a published bundle — an exact sidecar + plugin pair CI has checked speak the same protocol, rather than "latest of each" — syncs the plugin overlay into your server tree, offers the optional stock-file patch tier, installs the sidecar and registers it as a service under an unprivileged account, and finishes by printing the four values to paste into Admin → Shard:

Base URL          http://<shard-host>:8080
WebSocket URL     ws://<shard-host>:8080/ws
Protocol version  3
Auth token        4f9c…

Keep that binary — it does not install itself, and doctor, update and uninstall are run from it later. Start ServUO, then ./runicgateway-installer-… doctor checks the deployment end to end, through to "has the shard actually dialed in?" — the only check that tells a working bridge from copied files.

Installing by hand is supported too — INSTALL.md Appendix A is the same deployment with curl, tar and systemctl, for a host that cannot run the binary or for developing on the bridge from a source tree. The full operator guide is docs/installer/INSTALL.md.

4. Android-app — the native client (optional)

Prereqs: JDK 17 and the Android SDK. A single build works against any site — the app prompts for your website's URL on first run.

git clone https://gitea.whitlocktech.com/RunicGateway/Android-app.git
cd Android-app
./gradlew assembleDebug        # debug APK → app/build/outputs/apk/debug/
./gradlew installDebug         # install on a connected device / emulator

Kotlin + Jetpack Compose (Material 3), min SDK Android 10 (API 29). It surfaces the same public content and player self-service as the browser — home/status, news, wiki, the shard hub, account linking, character sheets — and opts into push notifications through the self-hosted ntfy relay. See the Android-app README and the design contract in docs/android/PLAN.md.

---

Where to go next

• Putting a new game on the platform → Integration-kit — the template, and the book: the website module, the sidecar, the game-side plugin.
• The module contract → docs/website/MODULE_API.md — normative: module.json, what a module is handed, the registries, the client chunk, the rules a loader enforces. MODULE_SYSTEM.md is the why.
• Setting up a shard → docs/installer/INSTALL.md — the operator guide: what the run asks, where it writes, the patch tier, doctor / update / uninstall, troubleshooting, and the by-hand path.
• Running / customizing the site → website README (tech stack, API endpoints, env vars, security, branding, Swagger at /api/docs).
• The Android client → Android-app README and docs/android/PLAN.md — the authoritative design contract, milestones, and the push-notification architecture.
• The bridge internals → docs — design docs, the canonical wire-protocol spec, and the integration guide.
• Working on the sidecar or plugin → link README and servuo-plugins — building from source, the loopback protocol, and the compatibility rules.

_{Runic Gateway · whitlocktech@gmail.com}