module-uo — the Ultima Online module for Runic Gateway

The Runic Gateway website is becoming game-agnostic: core keeps accounts, sessions, the wiki, posts, branding, theming and the admin panel, and everything that knows what a shard is moves out into an installable module. This repo is that module — the first one, and the reference for every module that follows.

        RunicGateway/website  (core — game-agnostic)
                 │  loads modules at boot, synchronously, from the filesystem
                 ▼
        ┌───────────────────────────────────────────┐
        │  module-uo   (>>> HERE <<<)               │
        │  shard status · spawn atlas · marketplace │
        │  governors · cliloc · town crier · uo-link│
        └───────────────────────────────────────────┘
                 │  server half: routers, models, schema fragment
                 │  client half: prebuilt ESM chunk, SPA routes + nav
                 ▼
        the shard bridge (RunicGateway/link → RunicGateway/servuo-plugins)

The module's id is uo — that is what appears in module.json, in the installed_modules table, in the modules/<id>/ path on disk and in the URL segment (/uo/*, /admin/uo/*, /player/uo/*). Module-uo is the repository; module-uo is the module and its release artifact.

Status: the extraction is complete; this repo is the UO half of the site

The design of record is website/MODULE_SYSTEM.md and the normative contract is website/MODULE_API.md in the docs repo — read them before opening a PR here. Where the two differ, the contract wins.

Phase	Where it happens	State
0 — CI trigger fix, cut website edge, bootstrap this repo	website, here	✅ done
1 — module API contract (docs/website/MODULE_API.md) + the atlas spike	docs, website	✅ done
2 — core scaffolding: loader, installed_modules, registries, client registry	website	✅ done
3 — extract the UO half of the site into this repo	website, here	✅ done
4 — delivery: the admin Modules screen + the Docker path	website	⬜

Phase 3 moved the UO half of website/ here in six slices (MODULE_SYSTEM.md §2.7.1): the bundle skeleton, the whole server half, core's client extension slots, the whole client half, the de-UO of core's own copy, and this one — the artifacts that make the result installable and checkable. Each slice was one PR here that added and one in website that deleted, this one merging first, so website's edge branch served each feature from core right up to the moment core dropped it.

Neither half sliced by feature in the end, and for the same reason on both sides: a mount prefix is claimed whole and a shared leaf moves with its last consumer, so the closure of either half is the whole half.

What core serves and what this repo serves is now a fact you can read, not a claim: 72 URLs, in routes.manifest.json, derived by loading this module into a real core and diffing. Not one of core's own URLs moved — that is the promise MODULE_SYSTEM.md §1.2 makes to the shipped Android app and the Discord bot, and it is checked on every PR.

Working on it

npm ci --prefix server  && npm test --prefix server  && npm run check:imports --prefix server
npm run check:swagger --prefix server          # is swagger-fragment.json still current?
npm ci --prefix client  && npm test --prefix client  && npm run build --prefix client
npm run check:externals --prefix client        # asks the BUILT chunk, so it runs after the build

The check:* scripts are the contract's acceptance criteria rather than this module's own tests: no import may escape the module root (MODULE_API.md §5.1), no bare specifier may survive into the built chunk (§3.6), and the OpenAPI fragment core merges must describe the routes registered today (§2.8). The matching build failure — a shared dependency being bundled — comes from a guard inside vite.config.js.

Changed a route, or its #swagger annotations? npm run swagger --prefix server regenerates swagger-fragment.json; commit it. Core cannot generate it — core is a prebuilt image and this module mounts through a call no static parser can follow — so the file this repo commits is the one an operator's /api/docs shows.

Changed a mount prefix, or added a route? routes.manifest.json is regenerated by the frozen-manifest CI job, which clones core at the ref pinned in ci/core-ref.json, loads this module into it and takes the difference. To do it locally, check this repo out into that core as modules/uo (copy it — a symlink is silently skipped by the loader), run core's npm run routes:manifest with and without it, and hand both files to server/scripts/frozenManifest.js.

Running it against a real core means checking this repo out as website/modules/uo, building the client half, and booting core. The four-step browser smoke in MODULE_API.md §7.7 is the only thing that proves the client half works: its real failure modes are timing and module resolution, and neither has a shape a DOM-less test runner can see.

What it contains

One repo, one bundle: the server half and the client half live side by side and version together, so a route and the screen that calls it can never be mismatched.

module.json              id, version, coreApi range, mounts, extensions
swagger-fragment.json    generated · the OpenAPI core merges into /api/docs.json
routes.manifest.json     generated · the 72 URLs this module serves
ci/core-ref.json         the core commit the two above were proved against
server/index.js          the entry point — register(ctx, api), synchronous, no database
server/router/           routers + controllers, one directory per tier
server/model/            one directory per table family; nothing crosses the boundary
server/utils/            sidecar client, visibility, ingest, town crier, cliloc, atlas
server/config/           the push stream catalog
server/db/schema.sql     idempotent fragment, replayed by core's ensureSchema()
server/db/purge.sql      destructive; only ever run by an explicit purge
server/scripts/          the three checks: imports, the fragment, the frozen manifest
server/test/             node --test, with a fake ctx standing in for core
client/src/entry.jsx     the chunk's entry — registers routes, nav, slots, feature provider
client/src/shim/         react, react-dom, react-router-dom, jsx-runtime, from window.__rg
client/vite.config.js    the library build, the aliases, the not-bundled guard
client/dist/             PREBUILT ESM chunk, built by CI — never by an operator

The three generated files are committed on purpose. Two of them are what core reads instead of looking at this source — it never has it — and the third records which core they were proved against. A generated file nobody reviews is a generated file nobody notices going wrong, so each lands in a diff.

Release artifact: module-uo-<version>.tar.gz, plus module-uo-<version>.json carrying its sha256. See below.

How it reaches an operator

An operator never builds anything. Installing a module is the WordPress-plugin experience: an admin-panel action, or a directory mounted into the Docker container — never a build step, because production runs a prebuilt, pull-only image. That constraint is why the client half ships as a prebuilt ESM chunk that resolves React from a window.__rg global rather than an import map (an import map must be inline, and the site's CSP is script-src 'self').

The installer is not the delivery path. It deploys the shard side — the plugin overlay and the uo-link sidecar — and never contacts the website. Module delivery is website-side only.

Releases

A merge to main that leaves module.json at a version with no release yet publishes one. The version is declared, not computed from commit subjects: module.json's version is what core records in installed_modules and shows on the admin screen, and it sits beside the coreApi range a bump usually has to be weighed against — two sources for one number is how they drift. Bumping it is an ordinary reviewed PR.

Each release carries:

Asset	What it is
module-uo-<version>.tar.gz	the directory core expects at modules/uo/ — already assembled, with the chunk built and ws installed
module-uo-<version>.json	id, version, coreApi, the artifact's URL, size and sha256
SHA256SUMS	the same hash, in the shape every other repo here publishes

Releases are unsigned; the sha256 is the trust anchor, and the website verifies it before unpacking. That is the model installer's bundles already use, and a second trust model would be a second thing to get right.

The tarball is assembled from an include list, never an exclude list — an exclude list ships whatever it forgot. Tests, scripts, client/src and the dev dependencies are not in it.

Environment variables

Four, all optional, all read by this module rather than by core — which is why they are documented here and not in core's .env.example. In Docker they go in the Compose .env, since that is what reaches the container.

Var	Default	What
UOLINK_BASE_URL	—	Default sidecar base URL for a site with nothing saved yet. The admin panel's stored value wins.
UOLINK_WS_URL	—	Same, for the WebSocket URL.
UOLINK_PROTOCOL	3	Wire protocol this build speaks. Again only a fallback — set it lower only if you deliberately run an older sidecar.
TOWNCRIER_DURATION_SEC	3600	How long a published news post's in-game town-crier message stays up (≤ 86400).

The sidecar's auth token is deliberately not here. It is entered in Admin → Shard, encrypted at rest with core's SECRET_ENC_KEY, and write-only in the API — never returned to any client.

Compatibility

module.json declares a coreApi semver range, checked at boot against core's MODULE_API_VERSION. A mismatch fails loudly — the module is marked startup_failed and the site comes up without it, rather than mis-loading. This is a separate number from PROTOCOL_VERSION, which versions the shard wire protocol and says nothing about a website module.

A module that fails to load must never take the site down.

Related repos

Repo	What
this — RunicGateway/Module-uo	The UO module: the game-specific half of the website.
RunicGateway/website	Core — the site, admin panel and API that loads this module.
RunicGateway/link	The uo-link sidecar — the network-facing half of the game bridge this module talks to.
RunicGateway/servuo-plugins	The C# ServUO plugin that feeds the sidecar.
RunicGateway/installer	Deploys the shard side. Not the module delivery path.
RunicGateway/docs	All project documentation, including the module system design and this module's docs under modules/uo/.

Contributing

See CONTRIBUTING.md. Contributions are welcome, AI assistance must be disclosed, and security problems go to SECURITY.md rather than a public issue.

License

GNU General Public License v3.0 or later — see LICENSE.md.