@hopple/sdk 0.1.0-rc.3 → 1.0.0-next.12

package/README.md

@@ -27,6 +27,7 @@ name and type is documented where it is declared, in the package's
 - [Input](#input)
 - [Audio](#audio)
 - [Pause](#pause)
+- [Match](#match)
 - [Checklist](#checklist)
 
 ## What a game is
@@ -73,16 +74,16 @@ The SDK is not part of your game. It is **the runtime**, which whatever runs
 the game serves beside it, and your page loads as its first script:
 
 ```html
-<script src="_rt/1/hopple.js"></script>
+<script src="_rt/hopple.js"></script>
 ```
 
 The runtime defines the global `Hopple`, holding everything this guide
 describes. Because it is served rather than built into the game, a fix to the
 SDK (input, on-screen controls, audio, layout, the loop, save) reaches every
-game without a rebuild. `_rt/1/` is the newest release of major 1; a change
-that would break games is a new major, which a game takes by changing its
-tag. Keep the address relative, as above: Hopple serves a game at the root of
-its own origin, and a host like itch.io under a path, with `_rt/` beside
+game without a rebuild. Which release a game gets is its track's: the major
+its manifest's `api` names, or `next`, built with the previews it declares. A change that would break games is a
+new major, which a game takes by changing its `api`. Keep the address
+relative, as above: Hopple serves a game at the root of its own origin, and a host like itch.io under a path, with `_rt/` beside
 `index.html` either way.
 
 - **With a bundler** (Vite, esbuild, webpack, Rollup, Parcel, Bun):
@@ -95,13 +96,13 @@ its own origin, and a host like itch.io under a path, with `_rt/` beside
   (`const sdk = await Hopple.init()` in a module script or an async function).
 
 `hopple check`, `hopple publish` and the server refuse a page that doesn't
-load the runtime first, or that carries a copy of the SDK. Games published
-before the runtime keep the SDK they bundled, and get no runtime fixes until
-they are rebuilt this way.
+load the runtime first, or that carries a copy of the SDK.
 
 A `hopple.config.json` can point its `"$schema"` at
-`./node_modules/@hopple/sdk/config.schema.json` for an editor to check it; a
-`hopple.config.ts` is checked by its type, `HoppleConfig`.
+`./node_modules/hopple/config.schema.json` for an editor to check it; a
+`hopple.config.ts` is checked by its type,
+`import type { HoppleConfig } from 'hopple'`. Both are the CLI's, which reads
+the config.
 
 ```ts
 import { init } from '@hopple/sdk';
@@ -140,7 +141,9 @@ Options for `init()`, all optional and rarely needed:
 
 | Option | Meaning |
 |---|---|
-| `onError` | Called with problems the game should know about but that don't reject a call: a refused analytics event, a shim that threw, a save value that JSON would silently change. Defaults to `console.error`. |
+| `onError` | Called with problems the game should know about but that don't reject a call: a refused analytics event, a save value that JSON would silently change. Defaults to `console.error`. |
+| `timeoutMs` | How long each request waits for the host. Default 10 s. The handshake always waits at least 10 s, whatever this says. |
+| `save` | How to merge two saves made on two devices: `{ merge }`. See [Save](#save). |
 
 The host is told about your errors too: from the moment `init()` is called,
 the SDK reports every exception nothing caught, every promise rejection nothing
@@ -149,9 +152,6 @@ handled, and everything it passes to `onError`, with its stack. That is how
 console. Nothing is suppressed: the console prints everything as before. An
 error thrown before `init()` is called, or a script that doesn't parse, can't
 be reported, so look in the browser console when a game never starts.
-| `timeoutMs` | How long each request waits for the host. Default 10 s. The handshake always waits at least 10 s, whatever this says. |
-| `transport` | A channel of your own. By default the SDK finds the host itself. |
-| `scope` | The window to use. For tests. |
 
 Everything else hangs off the returned object: `sdk.lifecycle`, `sdk.layout`,
 `sdk.save`, and so on. It also has `sdk.ping()` (resolves with the round-trip
@@ -361,6 +361,7 @@ sdk.save.available;                           // false where this host keeps no
 sdk.save.status;                              // what is stored, before you fetch it (see below)
 sdk.save.on((now, previous) => redraw(now));  // status changed: a read, a write or a clear
 const saved = await sdk.save.read();          // { version, state } | null
+sdk.save.onChange((now, why) => restore(now)); // the save changed under the game: play on from this
 await sdk.save.write(state, { version: 2 });  // resolves once the host says it is safely stored
 await sdk.save.clear();
 sdk.save.maxBytes;                            // the largest save this host accepts
@@ -377,6 +378,47 @@ sdk.save.maxBytes;                            // the largest save this host acce
 
 It follows the game's own reads, writes and clears.
 
+**Two ways to load.** A signed-in player's save comes from a server, which
+may take a moment:
+
+- **Wait for it:** `await sdk.save.read()` before the first frame. The host
+  waits for the server (a few seconds at most, and not at all offline) and
+  answers with the player's save.
+- **Start at once:** listen with `onChange`, call `read()` without awaiting
+  it, and apply whatever either hands over. The game plays from nothing, or
+  from this device's save, and takes the player's save when it comes.
+
+```ts
+const restore = (s: SaveState | null) => { progress = s ? (s.state as Progress) : fresh(); };
+sdk.save.onChange(restore);      // before read()
+sdk.save.read().then(restore);
+```
+
+**Listen with `onChange` either way.** The save can also change while the
+game plays: the server answered later than the host would wait, or a page left
+open hears that another device played on. `onChange(save, why)` hands the game
+the save to play on from then, and why:
+
+| `why` | What happened |
+|---|---|
+| `'arrived'` | Another device's save, built on what the game had. With a `merge`, merged with what the game last saved. |
+| `'merged'` | Two saves that went their own ways, made one by the game's `merge`. |
+| `'gone'` | Thrown away on another device, with nothing made here since. `save` is `null`. |
+
+To keep the game's own instead (progress it hasn't saved yet, or a New game
+the player chose a moment before a save arrived), write it from the listener:
+it takes the handed save's place.
+
+```ts
+sdk.save.onChange((now, why) => {
+  if (why === 'arrived' && justStartedNewGame) void sdk.save.write(progress);  // the New game wins
+  else restore(now);
+});
+```
+
+A game that does not listen is never written over: its next write is kept
+beside the save that arrived, for its `merge` or the player to settle.
+
 How to use it:
 
 - **Save as you go, not only at the end.** Nothing saves on your behalf, and a
@@ -386,17 +428,47 @@ How to use it:
 - **`version` is your own save format number.** It is stored next to the data,
   so you can check it before deciding whether to read an old save. There is no
   migration hook: write the `if` yourself.
-- **Strings are stored as they are; anything else goes through
-  `JSON.stringify`.** So a `Map`, a `Date` or a typed array won't come back
-  the way it went in. Inside `hopple dev`, the SDK warns (via `onError`) when
-  you save something JSON would change. For binary data, encode it as a
-  base64 string yourself.
-- **Every host accepts at least 64 KiB** (`SAVE_BYTES`). A larger save is
-  rejected with `too_large` before it is sent.
+- **Strings are stored as they are, and a `Uint8Array` as its bytes; anything
+  else goes through `JSON.stringify`.** Each comes back as it went in: a
+  string, a `Uint8Array`, or the parsed value. So a `Map`, a `Date` or a typed
+  array inside an object won't come back the way it went in. Inside
+  `hopple dev`, the SDK warns (via `onError`) when you save something JSON
+  would change.
+- **Bytes pack a big save small.** Write a `Uint8Array` with
+  [`@hopple/bytes`](https://www.npmjs.com/package/@hopple/bytes) (varints, floats, strings, and flags a
+  bit each), and it is stored and counted as those bytes.
+- **Every host accepts at least 64 KiB** (`SAVE_BYTES`), counted in UTF-8 for
+  a string or JSON and in bytes for a `Uint8Array`. A larger save is rejected
+  with `too_large` before it is sent.
+
+**Two devices.** A signed-in player's save follows them to every device. When
+two devices each saved without seeing the other's progress (one was offline),
+the host keeps both and asks the game to merge them, with the `merge` passed to
+`init()`:
+
+```ts
+const sdk = await init({
+  save: {
+    merge: (mine, theirs) => ({ version: 2, state: combine(mine.state, theirs.state) }),
+  },
+});
+sdk.save.onChange((now) => restore(now)); // merged while playing: play on from this
+```
+
+- `merge(mine, theirs)` is pure and answers with the save to keep in place of
+  both. Throw where the two can't be merged, and the host asks the player
+  which to keep, as it does for a game with no `merge`.
+- Asked while the game loads, the merge is what `read()` resolves with. Asked
+  while it plays, it goes to `onChange` listeners, and waits for the next load
+  where there are none.
+- A save that arrives while the game plays is merged with what the game last
+  saved too, where it has a `merge`, before `onChange` hears it.
+- Inside `hopple dev`, the SDK warns (via `onError`) when the save changed
+  while nothing listened with `onChange`.
 
 | Error | Meaning |
 |---|---|
-| `unsupported` | This host has nowhere to store saves (`available` is `false`). |
+| `unsupported` | This host has nowhere to store saves (`available` is `false`), or is too old to keep a `Uint8Array`. |
 | `too_large` | Over `sdk.save.maxBytes`. |
 | `rate_limited` | Saving too often, usually from inside the game loop. |
 | `bad_params` | The state can't be turned into JSON at all (a cycle, a `BigInt`). |
@@ -477,7 +549,8 @@ sdk.share.offer({
   meta: { level: 3, from: 'results-screen' },      // kept by the platform, never handed back
 });
 
-sdk.share.data;        // the data from the link that opened this run, or null
+sdk.share.data;        // the string from the link that opened this run, or null
+sdk.share.bytes;       // the Uint8Array from the link that opened this run, or null
 sdk.share.available;   // whether this host can make links at all
 ```
 
@@ -492,16 +565,21 @@ sdk.share.available;   // whether this host can make links at all
 - **Show your Share button from `sdk.share.available`**, never from
   `sdk.share.data`: `null` there only means this player didn't arrive by a
   link.
-- **Treat `sdk.share.data` as untrusted input.** It comes from outside your
-  game. Check it as strictly as you would any user input.
-- `data` must be a string, at most 512 bytes (`SHARE_BYTES`) on every host.
-  Put anything bigger in your save.
+- **Treat `sdk.share.data` and `sdk.share.bytes` as untrusted input.** They
+  come from outside your game. Check them as strictly as you would any user
+  input.
+- `data` is a string, which comes back as `sdk.share.data`, or a `Uint8Array`,
+  which comes back as `sdk.share.bytes`. Either way it is at most 512 bytes
+  (`SHARE_BYTES`) on every host. Bytes pack a board or a replay far tighter
+  than text: see [`@hopple/bytes`](https://www.npmjs.com/package/@hopple/bytes). Put anything bigger in
+  your save.
 - `meta` is any JSON object, at most 1024 bytes of JSON (`SHARE_META_BYTES`) on
   every host. No game ever reads it back.
 
 Errors go to `onError`: `too_large`, `rate_limited` (the host won't offer a
-link right now), `bad_params` (`data` isn't a string, or `meta` isn't a JSON
-object). On a host that can't make links, `offer` does nothing.
+link right now), `bad_params` (`data` isn't a string or a `Uint8Array`, or
+`meta` isn't a JSON object), `unsupported` (bytes, on a host too old to carry
+them). On a host that can't make links, `offer` does nothing.
 
 The website and the dev shell support sharing.
 
@@ -518,7 +596,9 @@ sdk.panel.available;        // false where there are none
 sdk.panel.open('scores');   // returns nothing: what happens arrives through sdk.panel.on
 ```
 
-The possible pages are `about`, `scores`, `achievements` and `input`.
+The possible pages are `about`, `scores`, `achievements` and `input`. A game
+that plays over the network also has `room`, the player's party, from
+[`@hopple/sdk-preview-network`](https://www.npmjs.com/package/@hopple/sdk-preview-network).
 
 - **Check `sdk.panel.pages` before drawing a button for a page.** It is known
   from the start, so you can decide while laying out your menu. If the host has
@@ -601,21 +681,42 @@ Call `read()` **once per frame**. It reports presses that started and ended
 since the previous call (so a tap shorter than a frame isn't lost), which means
 a second call in the same frame sees none of them.
 
-### Showing the right button names
+### Showing which button to press
 
 ```ts
-prompt.textContent = `Press ${sdk.input.mapping.shoot?.label ?? 'shoot'} to shoot`;
+prompt.textContent = `Press ${sdk.input.glyph('shoot')} to shoot`;   // written once
+prompt.setAttribute('aria-label', `Press ${sdk.input.describe('shoot')} to shoot`);
 
-sdk.input.on((now, previous) => redrawPrompts());   // now and previous: { mapping, scheme }
-sdk.input.scheme;   // 'keyboard' | 'mouse' | 'touch' | 'gamepad': what the player is using
+ctx.font = `20px 'My Font', sans-serif, ${sdk.input.font}`;           // on a canvas
+ctx.fillText(`Press ${sdk.input.glyph('shoot')} to shoot`, x, y);
+```
+
+```css
+body { font-family: 'My Font', sans-serif, hopple-keys; }
 ```
 
-Always print labels from `sdk.input.mapping[action].label`, never from your
-manifest. The label is what is written on whatever the player would press:
-`Z` on a keyboard, `A` on a gamepad, and the manifest's own `label` on an
-on-screen button. It follows the player's remapping. `sdk.input.on` fires when
-the player rebinds a key (`mapping` changed) or switches device (`scheme`
-changed).
+`sdk.input.glyph(action)` is one character, drawn by a font the SDK builds:
+every key or button bound to the action for the device in the player's hands —
+`[Z] / [Space]` as keycaps, a pad's face buttons as a diamond with the one to
+press filled, the same on every controller, the on-screen button on a touch
+screen. When the player rebinds the action or picks up another device the SDK
+swaps the font, so text in the DOM is right without being touched, and a canvas
+is right the next time it is painted (a canvas drawn once redraws on
+`sdk.input.on`). `glyph('pad.start')` draws a button that is none of your
+actions.
+
+**Name `hopple-keys` (`sdk.input.font`) last in every font stack that prints
+a glyph**, the canvas's included. A stack without it draws a box; one that
+names it first changes the line height of its text in some browsers. Children
+inherit a `body` rule, form controls don't unless they set `font: inherit`.
+Under `hopple dev` a glyph printed anywhere else is reported to `onError`.
+
+`sdk.input.describe(action)` is the same in words (`Z or Space`, `bottom face
+button`), for an `aria-label` and for text drawn without fonts.
+`sdk.input.mapping[action].label` still names one binding in text, and
+`sdk.input.scheme` is what the player is using: `'keyboard' | 'mouse' | 'touch'
+| 'gamepad'`. `sdk.input.on` fires when the player rebinds a key (`mapping`
+changed) or switches device (`scheme` changed).
 
 ### On-screen controls
 
@@ -631,8 +732,74 @@ sdk.input.controls.showing;        // whether controls are actually visible
 - Hiding them only stops drawing them; keys and gamepads keep working.
 - While shown, they appear in `sdk.layout.obstructions` as reserved
   rectangles, so code that avoids the host's buttons avoids them too.
-- They are drawn in a shadow root inside your frame, so your CSS can't affect
-  them and they don't appear in your DOM.
+- They are drawn in a shadow root inside your frame, so they don't appear in
+  your DOM and your CSS only reaches them where it is meant to: through
+  `hopple-controls::part(…)` and the `--hopple-pad-*` properties (see
+  [Styling them](#styling-the-on-screen-controls)).
+
+### Styling the on-screen controls
+
+```css
+hopple-controls {
+  --hopple-pad-tint: #2b1d0ecc;            /* a button's fill */
+  --hopple-pad-edge: #f5c542;              /* rims, the knob */
+  --hopple-pad-ink: #fff8e1;               /* labels and icons */
+  --hopple-pad-radius: 14px;
+  --hopple-pad-font: 700 16px/1 'My Font', sans-serif, hopple-keys;
+}
+hopple-controls::part(face pressed) { translate: 0 2px; }
+hopple-controls::part(face action-jump) { background: url(ui/jump.png) center / 70% no-repeat; }
+```
+
+```ts
+sdk.input.icon('jump', 'M12 3 4 13h5v8h6v-8h5z');   // a filled path in a 24×24 box, or null
+```
+
+- Parts: `face`, `label` and `icon` on a button; `group` behind a group of
+  buttons; `well`, `knob`, `groove` and `arrow` on a stick. Each also carries
+  `action-<id>` and `control-<id>`, and the states `pressed`, `held`,
+  `floating` and `resting`.
+- `<hopple-controls>` has `layout`, `sticks` and `look` attributes, and a
+  stick has `--hopple-stick-x` and `--hopple-stick-y` (−1 to 1) for a game to
+  read.
+- Sizes (`--hopple-pad-size`, `-stick`, `-track`, `-gap`, `-inset`) are held
+  between a size a thumb can press and one that leaves the game room. How big
+  one control is next to the others is its `scale` in the manifest. What a
+  part draws never changes where a touch lands.
+- A player can turn a game's look off, for every game or for one, and gets the
+  plain controls back: test that they still read well over the game.
+- Under `hopple dev`, a rule that names a part or a property the controls don't
+  have is reported to `onError`.
+
+### Several players on one device
+
+A manifest's `input.player` declares what each local player does, and
+`players.local` how many may play on one device: one set of actions every
+player has a copy of, bound once for every pad, and the parts of the keyboard
+players share (`keyboard`, each with a title and its keys).
+
+```ts
+sdk.input.joining = true;                       // the screen where players join
+sdk.input.onPlayers((players) => drawRoster(players));
+for (const player of sdk.input.players) {       // the first player is always there
+  const now = player.read();                    // once a frame, as sdk.input.read()
+  if (now.started('bomb')) dropBomb(player.slot);
+  label[player.slot].textContent = player.glyph('bomb');   // their own key or button
+}
+sdk.input.joining = false;                      // play starts
+```
+
+- **The first player hears every controller nobody claimed**, so a player
+  alone loses nothing between devices. Setting `joining` gives them the one
+  they last used; a join action pressed on a free pad or part of the keyboard
+  seats a new player with it, up to `mostPlayers`, and is nobody else's press.
+- **`slot`** is a player's place from 0, kept until `leave()`.
+  **`controller`** is what they hold, or `null` once their pad went away:
+  they keep their place, and the next free pad pressed is theirs again.
+- **`sdk.input.read()` and `onAction` answer for player actions too**, as
+  anybody pressing them, for menus any player may work.
+- **In a match**, the device tells the match how many play on it, and
+  `mostPlayers` takes no more than the match has room for.
 
 ### Text fields
 
@@ -725,6 +892,14 @@ sdk.pause.on(async (paused) => {   // the host asked; return a promise to make i
   });
   ```
 
+## Match
+
+Play over the network, in matches: `sdk.match`. It is a preview, not stable
+yet, so it is a package of its own,
+[`@hopple/sdk-preview-network`](https://www.npmjs.com/package/@hopple/sdk-preview-network), which
+the game installs and declares in its manifest as `previews.network`, at its
+revision. A game that does not declare it has no `sdk.match`.
+
 ## Checklist
 
 - [ ] Let a rejected `init()` through rather than catching it.
@@ -738,10 +913,11 @@ sdk.pause.on(async (paused) => {   // the host asked; return a promise to make i
 - [ ] Submit every run's score. Only show a rank when you get one.
 - [ ] Share and open the panel only from a player's press.
 - [ ] Validate `sdk.share.data` like any untrusted input.
-- [ ] Print button labels from `sdk.input.mapping`, and read input once per frame.
+- [ ] Print button prompts with `sdk.input.glyph` (and `sdk.input.describe` for words), and read input once per frame.
 - [ ] Route every sound through `sdk.audio.output` or `media`, or multiply it by `sdk.audio.volume(channel)`, and obey mute.
 - [ ] Keep `sdk.pause` up to date, separately from the loop.
-- [ ] Load the runtime as the page's first script, `<script src="_rt/1/hopple.js"></script>`, and import `@hopple/sdk` rather than bundling a copy.
+- [ ] For network play, install `@hopple/sdk-preview-network` and declare `previews.network`, leave the lobby and invites to the host, and start matches from a player's press.
+- [ ] Load the runtime as the page's first script, `<script src="_rt/hopple.js"></script>`, and import `@hopple/sdk` rather than bundling a copy.
 - [ ] Refer to every file relatively, and publish the output directory.
 
 ## License