@hopple/sdk 1.0.0-next.1 → 1.0.0-next.5

package/README.md

@@ -99,8 +99,10 @@ relative, as above: Hopple serves a game at the root of its own origin, and a ho
 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';
@@ -359,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
@@ -375,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
@@ -384,13 +428,18 @@ 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),
@@ -403,19 +452,23 @@ const sdk = await init({
     merge: (mine, theirs) => ({ version: 2, state: combine(mine.state, theirs.state) }),
   },
 });
-sdk.save.onMerge((merged) => restore(merged.state)); // merged while playing: play on from this
+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 `onMerge` listeners, and waits for the next load
+  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`). |
@@ -496,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
 ```
 
@@ -511,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.
 
@@ -673,8 +732,44 @@ 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