docs(kit): pin core 1.17.0; teach 1.13.0 to 1.17.0 and one module per site
Some checks failed
PR Checks / template (pull_request) Failing after 12s
PR Checks / prose (pull_request) Successful in 14s

The pin moves from 0a37a44 (1.12.0) to 6890a74 (1.17.0, website#220),
past 1.13.0 to 1.16.0, which reached main in the same cutover. The
chapters were read again for all five versions:

- Chapter 5: a lease's example, an option row's note, a param's
  duration (1.13.0) and multiple (1.14.0), a retry's retryAfterMs
  (1.15.0), a dry run's warnings (1.16.0), and a new section on
  templates (1.13.0). "What to build, in order" gains a template as
  step 8.
- Chapter 2: a new section on the identity-link hooks and
  ctx.identities.list (1.17.0). The call count is corrected to
  nineteen; it said twelve, which was already stale at 1.10.0.
- Two core changes in that cutover carried no version bump, and both are
  taught. Chapter 1 now says a site runs one game module and the loader
  refuses the others, since a reader copying the template onto a UO or
  Rust core is the one it surprises. Chapter 5 now covers a resource's
  `until`, which reconcile reads.

The template declares none of the new members, so nothing it does
changed meaning. template/module.json's coreApi becomes ^1.17.0 for the
equality check.

Checks run at the new pin:
- checkCoreApi, links, rename sites and chapter paths all pass, and so
  do the script tests (10 and 11).
- The template's imports, build, externals and swagger checks pass.
- Tests pass: server 82, client 20.
- The template was loaded as `examplegame` into a real core of this code
  through core's own loader, and it registered. Loaded again beside
  module-uo, examplegame started and uo was refused with the reason
  chapter 1 quotes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
This commit is contained in:
2026-10-23 02:01:26 -05:00
parent 2b84d79bd1
commit 5b3f5a5d54
5 changed files with 132 additions and 6 deletions

View File

@@ -89,6 +89,7 @@ api.registerEventLeases([{
id: 'examplegame.rate.gather',
label: 'Gather rate',
type: 'float', min: 0.5, max: 5,
example: 2, // optional, 1.13.0: the value box's placeholder
maxDurationMs: 48 * 60 * 60 * 1000,
async read() { /* the live baseline */ },
@@ -167,6 +168,13 @@ second code path is a dry run of the second path. Validate everything you can
reach without writing, then stop. Answering `{ ok: true }` unconditionally makes
the dry run worthless in the one situation it exists for.
**A dry run may also advise** (MODULE_API 1.16.0). `{ ok: true, detail: { warnings:
["…"] } }` shows each line to the author as a warning on that step, and it never
fails the dry run. Use it for what is true of the world now and may not be when the
run starts: *"the spot is refused now: a player is within 50 m"*. Strings only, at
most ten per step, each cut at 500 characters. What would make the step fail
whenever it ran is not advice; answer that as a refusal.
**`progress` is read by strangers, so it answers for one reader** (MODULE_API 1.12.0).
While a run is live, core asks it how its step stands and puts the answer on the
event's public page and in the app.
@@ -189,6 +197,48 @@ unreconstructable afterwards by anybody who did not write the action.
another module) registered. A source that refuses degrades its field to free text
with a warning and never blocks the form — so resolve from live data and return
`[]` on failure, rather than defending with a hardcoded list that will be wrong.
A row may carry a `note` (1.13.0), a sentence the editor shows under the field
while that row is chosen. It is advice about the value; nothing on the save path
reads it.
Two more things a param can say, both for the editor's sake:
- **`duration: 'minutes'`** (1.13.0), on an `int` or `float` that is a length of
time. The editor then knows the step holds something for that long, and sees to
it that the phase it sits in lasts at least as long. Declare it on every param
that is a duration; the editor has no other way to tell.
- **`multiple: true`** (1.14.0), with an optional `max` (1 to 100, 20 by default),
on a `string` or `int`. The author picks several values, and `perform()` and
`cost()` receive an array. A bare value arrives as a list of one, so a spec
written by hand still works. Price the whole list in `cost()`: three kits given
are three gives.
## Templates: a shortcut past the editor
A fifth declaration, `api.registerEventTemplates` (MODULE_API 1.13.0), gives an
author a named starting point for a new event: "A kit weekend", built from a kit
and two dates.
```js
api.registerEventTemplates([{
id: 'examplegame.beacon-night',
label: 'Beacon night',
description: 'Light the beacons at dusk, put them out at dawn.',
inputs: [ /* params, as an action's are, at most 8 */ ],
async build({ inputs }) { return { title, summary, spec: { phases } } },
}])
```
**A template is never a second way to make an event.** What `build()` returns is
checked as a spec and opened as an ordinary unsaved draft, and the author saves it
through the same route and the same checks as one they typed. So a template cannot
make an event the save path would refuse, and nothing about it is stored: changing
or removing one touches no event it ever made. When the inputs make no sense,
answer `{ ok: false, error }` with a sentence for the author; anything you throw
stays in the log.
Build one last, once your actions and leases are right. It is a convenience over
them, never a replacement for them.
---
@@ -233,6 +283,13 @@ silence and the operator sees `"<action id> refused"`. Writing this chapter's
template is how that was found — its first draft used `detail`, and every refusal
it produced was anonymous.
**A retry may say when** (MODULE_API 1.15.0). Core retries a failed step after a
flat minute. If your game knows better, as with a thing that is warming up for ten
minutes, answer `{ ok: false, retry: true, retryAfterMs }`. Core clamps it to one
to thirty minutes rather than refusing it, and it still counts as one attempt of
the step's few: it changes *when*, never *how many*. So a hint is not a way to wait
for something that may take an hour; refuse that, and say why in `error`.
## 2. Pass the idempotency key through, and put it on a command rather than a question
Core hands `perform()` an `idempotencyKey` derived from the step's identity — never
@@ -315,6 +372,13 @@ time is up), call `ctx.events.expired({ kind, ref })` when it does. Core then ma
row `expired`: finished as planned, never taken back at teardown. Left to `reconcile`,
the same thing would turn up `orphaned` and read as something that went wrong.
**And report its deadline when you make it.** A resource in `perform()`'s answer may
carry `until`, the instant the game will end it by itself (an ISO string or epoch
milliseconds). After an outage, core's reconcile can run before the game's own "it
ended" has reached it. A resource gone past its `until` is then filed `expired`, as
`ctx.events.expired()` would have filed it, instead of `orphaned`. Without `until`,
the same outage turns every timed thing your event made into an operator's alarm.
**You say WHEN to reconcile, because core cannot.** Core has no concept of the game
being up — it sees `{ ok: false, retry: true }` and cannot tell a wedged sidecar
from a game that rebooted and lost everything an event made. So it asks once, at
@@ -379,6 +443,8 @@ Four things a second module's author reaches for and should not.
Its absence is merely a lower standard rather than a broken promise.
7. **`progress`**, if a visitor would want to watch the step happen. It is the only
one an outsider reads, so build it once the ledger it counts from is right.
8. **A template**, if authors keep building the same event by hand. It saves them
typing and adds no power, so it comes last.
Then read your own `revert` again, and ask what it answers when the game is down.