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

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,9 +96,7 @@ 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
@@ -140,7 +139,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 +150,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
@@ -394,6 +392,27 @@ How to use it:
 - **Every host accepts at least 64 KiB** (`SAVE_BYTES`). 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.onMerge((merged) => restore(merged.state)); // 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
+  where there are none.
+
 | Error | Meaning |
 |---|---|
 | `unsupported` | This host has nowhere to store saves (`available` is `false`). |
@@ -518,7 +537,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 +622,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`);
+
+ctx.font = `20px 'My Font', sans-serif, ${sdk.input.font}`;           // on a canvas
+ctx.fillText(`Press ${sdk.input.glyph('shoot')} to shoot`, x, y);
+```
 
-sdk.input.on((now, previous) => redrawPrompts());   // now and previous: { mapping, scheme }
-sdk.input.scheme;   // 'keyboard' | 'mouse' | 'touch' | 'gamepad': what the player is using
+```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 +673,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 +833,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 +854,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