RunicGateway/.profile
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: RunicGateway:159eb53e73e359b4de0d751b0518d2139db423e0
Branches Tags
RunicGateway:main
...
compare: RunicGateway:main
Branches Tags
RunicGateway:main

4 Commits
159eb53e73 ... main

Author SHA1 Message Date
Colby Whitlock
2719716c9c Merge pull request 'docs(readme): list the Rust repositories and runicgateway.com' (#7) from docs/repo-table-rust into main 
Reviewed-on: #7
 2026-09-30 02:05:40 +00:00
wtclaude
8f96dde7ee docs(readme): list the Rust repositories and runicgateway.com 
The landing page still said "eight repositories". The org has thirteen: add
Module-Rust, Rust-Link, Rust-Plugins and the new runicnpc-rust (RunicNPC,
docs/runicnpc/PLAN.md stage 0) as a Rust section beside the UO one, and
runicgateway.com with the platform repos. The intro names Rust as the second
game. The quick start is unchanged and still walks the UO path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
 2026-09-29 21:03:43 -05:00
Colby Whitlock
5deaf74049 Merge pull request 'docs(readme): the event system, protocol 7, and module-uo v1.2.2' (#6) from docs/events-system into main 
Reviewed-on: #6
 2026-09-10 04:28:33 +00:00
wtclaude
0a7d138daa docs(readme): the event system, protocol 7, and module-uo v1.2.2 
Phase 16c of the events plan. The landing page is updated when the shape of the
project changes, and a subsystem that lets staff schedule an unattended change to
a live game world is one.

* **A new bullet in "How they fit together"**, beside the engagement one it sits
  next to: an event is written once as phases and steps, published as an
  immutable version and executed unattended. What matters on a front page is the
  posture rather than the feature list — everything arrives switched off, caps are
  enforced in the database rather than in a role check, cleanup is generated from
  a ledger rather than authored, and an event does not edit the world but holds a
  **lease** the game restores on its own deadline even if the site never speaks to
  it again. The game keeps its own switch, separate from the staff write plane.
* **Protocol 5 → 7** in the four values the installer prints. That block is what a
  reader copies into Admin → Shard, so a stale number there is the one that costs
  somebody an afternoon.
* **module-uo v1.1.0 → v1.2.2** in the manifest URL and the `MODULES=` line.
* `docs/website/EVENTS.md` added to "Where to go next".

Verified against the platform rather than assumed: the protocol number is
`link/sidecar/src/main.rs` and `servuo-plugins/overlay.toml` on `main`, and
v1.2.2 is the current Module-uo release, whose own notes name
`module-uo-1.2.2.json` as the manifest to paste.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
 2026-09-09 22:04:39 -05:00
1 changed files with 26 additions and 5 deletions
Expand all files Collapse all files

31
README.md
View File

@@ -12,7 +12,7 @@ Players get the same public content and self-service on the web **or** a native
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.
first game, *Rust* (Oxide and Carbon) the second, and one installer sets up the game side of either.
</div>
@@ -20,7 +20,7 @@ first game, and one installer sets up its shard side.
## The pieces
Runic Gateway is eight repositories that deploy together but build independently.
Runic Gateway is thirteen repositories that deploy together but build independently.
**The platform** — the same for every game:
@@ -30,6 +30,7 @@ Runic Gateway is eight repositories that deploy together but build independently
| [**Android-app**](https://gitea.whitlocktech.com/RunicGateway/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**](https://gitea.whitlocktech.com/RunicGateway/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**](https://gitea.whitlocktech.com/RunicGateway/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. |
| [**runicgateway.com**](https://gitea.whitlocktech.com/RunicGateway/runicgateway.com) | Astro | The platform's own **public site** at [runicgateway.com](https://runicgateway.com) — what Runic Gateway is, how to install it, and the developer docs. Not a game site. |
**Ultima Online support** — the first game, and the worked example everything else is measured against:
@@ -40,6 +41,15 @@ Runic Gateway is eight repositories that deploy together but build independently
| [**servuo-plugins**](https://gitea.whitlocktech.com/RunicGateway/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**](https://gitea.whitlocktech.com/RunicGateway/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. |
**Rust support** — the second game, the same three layers, built from the Integration-kit:
| Repo | Language | What it is |
|------|----------|------------|
| [**Module-Rust**](https://gitea.whitlocktech.com/RunicGateway/Module-Rust) | JavaScript (Node + React) | The **Rust module** — everything that makes a site a site for Rust. Installed into a website as `modules/rust/`; released as a versioned bundle. |
| [**Rust-Link**](https://gitea.whitlocktech.com/RunicGateway/Rust-Link) | Rust | The **rust-link** sidecar — the Rust mirror of uo-link: terminates the game plugin's loopback link and serves the WebSocket + REST API the website consumes. Ships a Pterodactyl egg. |
| [**Rust-Plugins**](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins) | C# | The **bridge plugin** for Oxide and Carbon — the game side of the bridge. Dials the sidecar over loopback. |
| [**runicnpc-rust**](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust) | C# | **RunicNPC** — Runic Gateway's own NPC plugin for Rust: an API other plugins call and in-game admin commands, with NPCs equipped through Kits. Works on its own too. *In development.* |
## How they fit together
```
@@ -79,6 +89,16 @@ Three layers, and the shape is the same for any game:
the widest audience a rule may ever be given — so a sensitive game event cannot be mailed to
everyone by a misconfiguration. A module brings its own triggers: for Ultima Online that is
a house about to collapse, a vendor running out of gold, a champion spawn, a new governor.
- **Staff can put an event on the calendar and let it run itself.** An event is written once
as phases and steps, published as an immutable version, and executed unattended — announcing
itself, spawning what it needs, borrowing values the world already had, counting who took
part and publishing the results. Everything it may do arrives **switched off**, every run
spends against per-run caps enforced in the database rather than in a role check, and every
world write is ledgered so the undo is **generated rather than authored** and runs on
completion, cancellation and abort alike. An event does not edit the world; it holds a
**lease** the game restores on its own deadline — even if the site never speaks to it again.
The game keeps its own switch: scheduled events are off in `Bridge.cfg` until an operator
turns them on, separately from the staff write plane.
- **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.
@@ -142,11 +162,11 @@ Ultima Online that manifest is `module-uo-<version>.json` from the
[Module-uo releases](https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases):
```
https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases/download/v1.1.0/module-uo-1.1.0.json
https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases/download/v1.2.2/module-uo-1.2.2.json
```
A compose-managed host can declare the set instead of clicking, with
`MODULES=uo@1.1.0=<that URL>` — resolution at container start is idempotent and offline-safe,
`MODULES=uo@1.2.2=<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 shipped on 2026-08-12** and this is now simply how the site works — a
@@ -184,7 +204,7 @@ unprivileged account, and finishes by printing the four values to paste into **A
```
Base URL http://<shard-host>:8080
WebSocket URL ws://<shard-host>:8080/ws
Protocol version 5
Protocol version 7
Auth token 4f9c…
```
@@ -225,6 +245,7 @@ and the design contract in [`docs/android/PLAN.md`](https://gitea.whitlocktech.c
- **Setting up a shard** → [`docs/installer/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/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](https://gitea.whitlocktech.com/RunicGateway/website) (tech stack, API endpoints, env vars, security, branding, Swagger at `/api/docs`).
- **The Android client** → [Android-app README](https://gitea.whitlocktech.com/RunicGateway/Android-app) and [`docs/android/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs) — the authoritative design contract, milestones, and the push-notification architecture.
- **The event system** → [`docs/website/EVENTS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md) — the design of record: leases, the resource ledger, the caps, and the module seam an event's world verbs arrive through.
- **The bridge internals** → [docs](https://gitea.whitlocktech.com/RunicGateway/docs) — design docs, the canonical wire-protocol spec, and the integration guide.
- **Working on the sidecar or plugin** → [link README](https://gitea.whitlocktech.com/RunicGateway/link) and [servuo-plugins](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) — building from source, the loopback protocol, and the compatibility rules.