wtclaude
ad37cade6e
The integration kit's share of the Asset Bridge, and the whole of it: one section in the sidecar chapter, teaching the pattern rather than re-specifying anything. `docs/link/v8.md` stays normative and is linked out to, as every chapter does. The problem is general even though our instance of it is not. Most games keep content on the host that a website wants to show -- sprites, icons, portraits, localisation tables, map definitions -- and the tempting answer is to make it the operator's problem: export it on a desktop with a third-party tool, upload the result, repeat after every patch. It works once and rots immediately. The four design notes are the ones that cost us real time to learn: content rides request/reply and never events (a sidecar that persists and broadcasts every event would write megabytes of sprite into its store and fan it out to every client); serve one at a time and put "busy" in the protocol so a caller treats it as flow control; two stages, so the common case -- a restart that changed nothing -- costs one small round trip; and version your DERIVATION separately from the protocol, because improving how you read a file changes your bytes while the file's hash stays put. Plus the operational note that surprises people: do not import on boot. Based on `main` rather than `edge` deliberately -- the kit's chapter 5 and the §2a it follows are on main only, so this section has nowhere to sit on edge. 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.