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
The book
Five chapters, in the order the work happens. The first four are the job; the fifth is optional and comes after you have one.
Read the dry run before any of them — a complete module designed on paper for a second game, and the shortest honest picture of the whole job.
| # | Chapter | What it covers |
|---|---|---|
| 1 | Your first module in twenty minutes | Copy the template, rename it, build it, install it, see a page. No theory. |
| 2 | The website module | The bulk of the work: module.json, register(ctx, api), the schema fragment, the client chunk, packaging, and what a module must never do. |
| 3 | The sidecar | Why the website never talks to a game server, what "persist before you forward" means, and what a thin sidecar is. |
| 4 | The game-side plugin | The least code and the highest stakes: never block the game thread. |
| 5 | Making your module event-capable | Optional, and the first thing here that can do damage: letting a scheduled event on the website change your live world, and get it back. |
Chapters 1, 2 and 5 quote template/, which CI builds against a pinned core, so
their code is a tree that is proved rather than prose that looks like one. Chapters
3 and 4 cite uo-link and servuo-plugins by file and identifier rather than by
line, on purpose: those repositories move for their own reasons and a line number in
a book is wrong the moment they do.
Chapter 5 is the one you can stop before. Chapters 1 to 4 get a game onto the platform and everything in them moves one way — out of the game and onto a page. Chapter 5 is the other direction, and a deployment that never reads it still has a working event engine over core's own verbs. Chapters 3 and 4 each carry one section that only matters if you are going there (§2a and "A command that changes the world runs at most once"); both say so at the top.
What is normative, and what is here
Nothing in these chapters is. Where a chapter and one of these disagree, the document is right and the chapter has a bug — say so:
| Authority | For |
|---|---|
MODULE_API.md |
Everything a module may do. |
MODULE_SYSTEM.md |
Why the module system is shaped this way, and how a module is installed and removed. |
link/PLAN.md + INTEGRATION.md |
The game↔sidecar wire protocol, as one real sidecar implements it. |
EVENTS.md |
The event system: what an event is, what a module declares, and what core owns. |
The chapters teach: the order to do things in, the reasoning, and the mistakes that cost this project time.