@hopple/sdk 0.1.0-rc.2 → 1.0.0-next.1

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
@@ -42,23 +43,25 @@ Both are named in the project's hopple config (`hopple.config.ts`, `.js` or
 like. `npx hopple create my-game` sets up the recommended way (Vite, with the
 config in TypeScript); see [`hopple create`](https://docs.hopple.app/cli.md#hopple-create).
 
-The host loads the page into a frame sandboxed with only `allow-scripts` and
-`allow-pointer-lock`. That has some consequences you need to plan for:
-
-- **One file to publish.** `hopple publish` uploads only the page, so
-  everything the game needs (scripts, styles, images, sounds) must be inside
-  it, and it refuses a page that loads anything from beside itself. During
-  development `hopple dev` also serves the other files in the page's
-  directory, but a published game can't rely on them.
-- **No network.** A game can't fetch, open a socket or load anything from a
-  URL, on any host. It may load only from its own page and from `data:` and
-  `blob:` URLs. Anything the game could send out could carry what it knows
-  about the player. During development `hopple dev` lets the game load the
-  files beside its page, and nothing else.
-- **Inline your scripts.** Inline scripts run, classic or module, and a
-  published game's scripts are inline anyway.
-- **No `localStorage`, cookies or IndexedDB.** They are unavailable on an
-  opaque origin. Use [`sdk.save`](#save) instead.
+The host loads the page into a frame sandboxed with only `allow-scripts`,
+`allow-same-origin` and `allow-pointer-lock`, every version on an origin of
+its own. That has some consequences you need to plan for:
+
+- **Its output directory is published.** `hopple publish` uploads the
+  directory the page is in, with the page as its `index.html`, and it refuses
+  a page that loads a file the directory doesn't hold. Refer to files
+  relatively. A page beside its config is published alone.
+- **No network.** A game can't fetch, open a socket or load anything from
+  another host. It may load its own files, and `data:` and `blob:` URLs.
+  Anything the game could send out could carry what it knows about the
+  player.
+- **No `localStorage`, `sessionStorage`, IndexedDB, Cache Storage or
+  cookies.** Whatever a game stored would be cleared every time its page
+  loads, so the runtime makes each of them throw an error naming
+  `Hopple.save`, and `hopple check` refuses a game that uses them. Use
+  [`sdk.save`](#save) instead.
+- **Every address relative, no `<base>`, and UTF-8 pages.** `hopple check`
+  refuses the rest.
 - **No `alert`, `confirm` or `prompt`.** They are blocked in the sandbox.
 - **Sound may need a tap inside the game first.** Browsers only allow audio
   after a user gesture in the frame. Sound routed through
@@ -67,15 +70,33 @@ The host loads the page into a frame sandboxed with only `allow-scripts` and
 
 ## Getting started
 
-The SDK becomes part of your page; nothing loads it at runtime.
+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/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. 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):
-  `npm install @hopple/sdk` and import it. Types come with it, and so does
-  every doc comment, in `node_modules/@hopple/sdk/index.d.ts`.
-- **Without one:** paste `node_modules/@hopple/sdk/hopple-sdk.min.js` into a
-  classic `<script>` before your own, and use the global `Hopple`
-  (`await Hopple.init(…)` in a module script or an async function). Its first
-  line says which SDK version it is, for your manifest's `sdk`.
+  `npm install @hopple/sdk` and import it. The package is the SDK's types,
+  with every doc comment, in `node_modules/@hopple/sdk/index.d.ts`, and a
+  stub of a few lines that forwards each import to `Hopple`: your bundle
+  carries the stub, never the SDK. Set your bundler to write relative
+  addresses (Vite: `base: './'`).
+- **Without one:** use the global `Hopple` directly
+  (`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.
 
 A `hopple.config.json` can point its `"$schema"` at
 `./node_modules/@hopple/sdk/config.schema.json` for an editor to check it; a
@@ -118,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
@@ -127,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
@@ -372,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`). |
@@ -496,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
@@ -579,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`);
 
-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);
 ```
 
-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).
+```css
+body { font-family: 'My Font', sans-serif, hopple-keys; }
+```
+
+`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
 
@@ -612,6 +676,36 @@ sdk.input.controls.showing;        // whether controls are actually visible
 - 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.
 
+### 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
 
 If your game draws its own text input (on a canvas, for example), call
@@ -703,6 +797,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.
@@ -716,15 +818,19 @@ 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.
-- [ ] Publish a single self-contained HTML file.
+- [ ] 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
 
-MIT; see `LICENSE`. The SDK is built into every game, so a game carries its
-one-line notice, `/*! @hopple/sdk | Copyright (c) 2026 The Hopple authors | MIT License */`.
+MIT; see `LICENSE`. A game carries the stub, which carries its one-line
+notice, `/*! @hopple/sdk <version> | Copyright (c) 2026 The Hopple authors | MIT License */`.
 Bundlers keep comments that start with `/*!` unless they minify them away:
 with Vite, set `build.rolldownOptions.output.comments.legal` to `true`, as a
-`hopple create` project does. The license covers the code, not the Hopple name or logo.
+`hopple create` project does. The runtime, which is the SDK itself, is MIT
+too, and is served beside the game rather than carried in it. The license
+covers the code, not the Hopple name or logo.