wtclaude
f89044b42e
The fifth chapter, and the template code it teaches out of. Events is the first
thing in the book that goes the other way — chapters 1-4 move data out of the
game and onto a page; an event changes a live world on a schedule, unattended.
**Chapter 5** covers the four declarations (budgets, option sources, leases,
actions), leads with the lease because EVENTS.md §H is right that it is the
primitive that travels and the spawn is the special case, and gives one section
each to the four things that are invisible until an outage: the envelope's
failure default, the idempotency passthrough, recording a resource before
confirming it, and under-declaring `cost`.
**Chapters 3 and 4 gain one section each** for the command plane, because
without them chapter 5 teaches a module to send an idempotency key to a sidecar
the book never told anyone to build a command path in. Both say at the top that
they are skippable until you want chapter 5.
**The template ships one of each declaration**, with `server/sidecarClient.js`
as the near end — a real timeout, a real key passthrough, a simulated transport
in one function marked for replacement. That file is named for the filename
`noGameConnection.test.js` already anticipated, so the test stays green now and
fires correctly the moment `deliver()` becomes a request.
Two things writing it found, both now in the chapter and beside the code:
* **An idempotency key belongs on a command, never on a question.** The first
draft keyed every call including the reads; an at-most-once store then
answers every future read with the first one's reply, forever. The lease
applied correctly and the module could no longer see it. Hence `ask` and
`send` as two functions.
* **A refusal's reason goes in `error`; core reads no other name.** The first
draft used `detail`, on the strength of the one place EVENTS.md §H mentions
it, and every refusal it produced was anonymous on the run console.
Proved by running the template's real declarations through core's real registry
at `edge` (all four accepted) and its real envelopes through the real
`events/dispatch.js` classifier.
**CI is RED on `checkCoreApi` and that is the mechanism working.** The template
now declares `coreApi: ^1.10.0` and `ci/core-ref.json` pins the engagement
cutover, where `main` is still 1.9.0. Equality is the check, a bump is meant to
turn this repo red until someone re-reads the chapters, and the pin move rides
in the events cutover (EVENTS_PLAN.md P16) as its own commit. Do not "fix" it.
Refs EVENTS_PLAN.md Phase 15, EVENTS.md §F, MODULE_API.md 1.10.0.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
116 lines
6.3 KiB
Markdown
116 lines
6.3 KiB
Markdown
# Runic Gateway — Integration Kit
|
|
|
|
**How to put a game on a Runic Gateway site.**
|
|
|
|
Runic Gateway is a website platform for game communities. Core knows nothing about
|
|
any particular game: everything game-specific — routes, tables, pages, navigation,
|
|
notifications — arrives as an installable **module**, and an operator installs one
|
|
from an admin panel without building anything. [`module-uo`][module-uo] is the
|
|
first module and serves an *Ultima Online* shard. This kit is how you write the
|
|
second one.
|
|
|
|
> ### 🚧 This is a draft
|
|
>
|
|
> The kit is finished when **someone outside this project builds a working module
|
|
> for a new game by following it alone, without reading core's source.** That has
|
|
> not happened yet, so treat every chapter as untested on you. If you are that
|
|
> person: the places you get stuck are the most valuable thing this repo can
|
|
> receive — [tell us][issues], and please say where you left the kit and what you
|
|
> did next.
|
|
|
|
---
|
|
|
|
## What you are building
|
|
|
|
Three things, and the kit is one book rather than a page in three repos because
|
|
the reasons live in the joins between them:
|
|
|
|
| # | Part | What it is |
|
|
| --- | --- | --- |
|
|
| 1 | **The website module** | A bundle core loads at boot: server routes, a schema fragment, a prebuilt client chunk, navigation. The bulk of the work, and the only part every module needs. |
|
|
| 2 | **The sidecar** | A small service that owns the connection to your game server, and owns the durable copy of what the game said. **Not optional** — see below. |
|
|
| 3 | **The game-side plugin** | Whatever runs inside your game and feeds the sidecar, without ever letting the sidecar stall the game. |
|
|
|
|
```
|
|
your game server ──dials out──▶ your sidecar ──HTTP + WS──▶ website core
|
|
(plugin: bounded (owns the socket, (loads your module,
|
|
queue, writer thread) persists to its own serves the pages)
|
|
store, then forwards)
|
|
```
|
|
|
|
**The website process never opens a connection to a game server.** That is a rule
|
|
in the contract ([`MODULE_API.md`][api] §2.7, `MODULE_API_VERSION` 1.4.0), not a
|
|
style preference, and chapter 3 is mostly about why. The short version: the
|
|
website is the internet-facing process and your game is not; the sidecar persists
|
|
before it forwards, so a website that is down or mid-deploy loses nothing; and a
|
|
game must never block on a web request. A game that genuinely delivers events on a
|
|
surface of its own needs a *thin* sidecar, not none — but check that it delivers
|
|
events rather than answering questions, because a channel built for an operator
|
|
typing commands can only be polled, and polling turns "someone left at 14:02" into
|
|
"the count was different at 14:03".
|
|
|
|
## Start here
|
|
|
|
1. **[The dry run][dryrun]** — a complete module designed on paper for a second
|
|
game, *Rust*, chosen for how little it shares with Ultima Online. Read it first.
|
|
It is the shortest honest picture of the whole job, and it names the one thing
|
|
the contract cannot do yet.
|
|
2. **`template/`** — a module that builds and loads, doing almost nothing. Copy it,
|
|
rename it, and you have a running module before you have read a chapter.
|
|
3. **The book** — [`book/`](book/), five chapters, in the order the work happens.
|
|
The first four are the job. The fifth is optional and comes after you have a
|
|
working module: what to declare if you want a scheduled event on the website to
|
|
be able to change your live world, and get it back afterwards.
|
|
|
|
## The one rule this kit follows
|
|
|
|
**It never re-specifies a contract.** These documents are normative, and where the
|
|
kit and one of them disagree, they win and the kit has a bug:
|
|
|
|
| Authority | For |
|
|
| --- | --- |
|
|
| [`MODULE_API.md`][api] | Everything a module may do: `module.json`, `ctx`, the `register*` calls, the client registry, the UI kit, schema-fragment rules, the loader's obligations. |
|
|
| [`MODULE_SYSTEM.md`][system] | Why the module system is shaped this way, and how a module is installed and removed. |
|
|
| [`link/PLAN.md`][linkplan] + [`INTEGRATION.md`][linkint] | The shard↔sidecar wire protocol, as one real sidecar implements it. |
|
|
| [`EVENTS.md`][events] | The event system: what an event is, what a module declares, what core owns, and every rule chapter 5 explains the reasoning behind. |
|
|
|
|
The kit *teaches*: the order to do things in, the reasoning, worked examples, and
|
|
the mistakes that cost this project time. Where it must show a member list it
|
|
quotes with a pointer rather than copying, because a guide that restates a
|
|
contract diverges from it silently — and a reader who follows the divergent copy
|
|
gets a module that fails validation for reasons the guide cannot explain.
|
|
|
|
## What this repo contains
|
|
|
|
```
|
|
book/ the chapters
|
|
template/ a module that builds — copy this
|
|
scripts/ the checks CI runs over both
|
|
```
|
|
|
|
CI clones core at a **pinned commit**, asserts the version the template declares
|
|
still matches that core's `MODULE_API_VERSION`, builds the template and runs its
|
|
guards, checks every link in the book, holds the template's rename checklist
|
|
against the template's own tree, and checks that every path a chapter names is
|
|
still there. So a change to the contract breaks this repo's build loudly instead
|
|
of leaving a chapter quietly wrong.
|
|
|
|
None of that can tell you whether a paragraph has become untrue about a file that
|
|
still exists. That is a reviewer's job on every pull request, and a
|
|
`MODULE_API_VERSION` bump is when it is owed in full.
|
|
|
|
## Licence
|
|
|
|
GPL-3.0-or-later, like every Runic Gateway repo — see [LICENSE.md](LICENSE.md).
|
|
The `template/` directory is meant to be copied and made yours; it carries the
|
|
same licence, and so does anything derived from it.
|
|
|
|
[module-uo]: https://gitea.whitlocktech.com/RunicGateway/Module-uo
|
|
[api]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md
|
|
[system]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_SYSTEM.md
|
|
[events]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md
|
|
[dryrun]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust-dryrun.md
|
|
[linkplan]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md
|
|
[linkint]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md
|
|
[issues]: https://gitea.whitlocktech.com/RunicGateway/Integration-kit/issues
|