docs(kit): pin core 1.17.0; teach 1.13.0 to 1.17.0 and one module per site
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:
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user