# 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][dryrun] 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](01-first-module.md) | Copy the template, rename it, build it, install it, see a page. No theory. |
| 2 | [The website module](02-website-module.md) | 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](03-sidecar.md) | 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](04-game-plugin.md) | The least code and the highest stakes: never block the game thread. |
| 5 | [Making your module event-capable](05-events.md) | 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][issues]:

| Authority | For |
| --- | --- |
| [`MODULE_API.md`][api] | Everything a module may do. |
| [`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 game↔sidecar wire protocol, as one real sidecar implements it. |
| [`EVENTS.md`][events] | 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.

[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