The Integration Kit

The Integration Kit is a separate repository whose entire job is teaching someone outside this project how to put a different game on the platform.

The kit describes itself as a draft, and so do we

In its own words: 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.

We are not going to describe it as finished before that happens. If you are the person who tries it, the places you get stuck are the most valuable thing the repository can receive — open an issue saying where you left the kit and what you did next.

What it covers

Three things, because the reasons live in the joins between them:

your game server  ──dials out──▶  your sidecar  ──HTTP + WS──▶  website core
(plugin: bounded queue,           (owns the socket,             (loads your module,
 writer thread)                    persists, then forwards)      serves the pages)

Part	What it is
The website module	A bundle core loads at boot. The bulk of the work, and the only part every module needs
The sidecar	A small service owning the connection to your game server, and the durable copy of what the game said. Not optional
The game-side plugin	Whatever runs inside your game and feeds the sidecar, without ever letting the sidecar stall the game

The four chapters

#	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	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

Before any of them, the kit points at the Rust dry run — a complete module designed on paper for a second game, and the shortest honest picture of the whole job.

The template is built, not just quoted

Chapters 1 and 2 quote template/, a real module that CI builds against a pinned core. The code in those chapters 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 number, deliberately: those repositories move for their own reasons, and a line number in a book is wrong the moment they do.

The kit never re-specifies a contract

This is its governing rule, and it is the same one this site follows.

Nothing in these chapters is normative. Where a chapter and one of these documents disagree, the document is right and the chapter has a bug.

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

The chapters teach the order to do things in, the reasoning, and the mistakes that cost this project time.

The pin that forces a re-read

ci/core-ref.json pins the exact core commit the kit is written against, and CI asserts that the version template/module.json declares equals that core’s MODULE_API_VERSION.

Equality, not “satisfies”. That is the mechanism, not a bug: a contract bump in the website repository is meant to turn the kit red, so that someone re-reads the chapters before the pin moves.

It has already earned its keep

Writing the chapters against 1.6.0 found that core’s inverted-slot fills named three of module-uo’s slots literally — so the mechanism worked for that one module and silently did nothing for any other game, producing an empty page with nothing logged.

That is exactly the class of defect a book written for an audience outside this org exists to catch, and it was fixed in core before the pin moved.

Running its checks

Dependency-free Node scripts, from the repository root — which is also how a reader runs them:

node scripts/checkLinks.js          # every relative link resolves; no commit permalinks
node scripts/checkRenameSites.js    # the rename checklist matches the template tree
node scripts/checkChapterPaths.js   # every path a chapter names in backticks still exists