@wasm-gaming/rsdkv4-wasm 0.1.4 → 0.1.5

package/README.md

@@ -54,16 +54,77 @@ The launcher decides how Escape behaves and draws its own overlay. It should
 intercept Escape in the **capture phase** if it wants to repurpose it (the engine
 ships with `DevMenu=false`, so the native in-canvas menu stays suppressed).
 
+> ⚠️ A capture-phase listener on `window` that calls `stopPropagation()` also
+> stops the **bubble**-phase listener SDL registers there — i.e. it takes the
+> keyboard away from the game. Swallow only the keys you actually handle, and
+> only while your overlay is open. (This is exactly how the shared demo
+> template's pause menu used to kill the d-pad; see
+> [src/demo/components/esc-menu.html](src/demo/components/esc-menu.html).)
+
+### Start menu — the host can own that too
+`instance.game` exposes RSDKv4's Start Menu as data (the `web_*` embind functions
+in `WebGame.cpp`), so a host can draw its own save / character / options screens
+instead of the engine's in-canvas text menus. The logic mirrors
+`Debug.cpp` move for move — same globals, same `saveRAM`, same
+`InitStartingStage()` — so a game started this way lands in the state the native
+menu would have produced.
+
+```js
+const engine = await load({ canvas, assets: { data },
+  options: { skipStartMenu: true },     // hide the engine's own screens
+});
+
+engine.game.type();          // 1 = Sonic 1, 2 = Sonic 2
+engine.game.players();       // ["SONIC", "TAILS", "KNUCKLES", "SONIC AND TAILS"]
+engine.game.saveSlots();     // [{ slot, empty, character, lives, score, emeralds, list, zone }]
+engine.game.start(0, 1);     // slot 0 as Tails — a slot with data resumes it
+engine.game.start(null, 0);  // no-save mode
+engine.game.deleteSave(2);
+
+engine.game.options();               // the engine's GAME OPTIONS screen, as data
+engine.game.setOption('spindash', 1); // written through to the game's save file
+```
+
+`load()` resolves only once `Engine::Init` has run, so all of the above is safe to
+call the moment it returns. The demo's [start-screens.ts](src/demo/start-screens.ts)
+is a worked example.
+
+### Pausing has an owner
+`pause(owner?)` / `resume(owner?)` — the **first** caller to pause owns it, and only
+that owner's `resume()` lifts it. A pause overlay therefore can't resume a game a
+start screen (or the host) had already frozen:
+
+```js
+engine.pause('menu');     // overlay opens
+engine.resume('menu');    // …closes: only resumes if 'menu' was the one that paused
+```
+
+Pausing stops the **audio** too: `masterPaused` only freezes the logic loop, so
+without that the music kept playing over the overlay — and `destroy()` kept
+playing it after the host returned to its launcher.
+
 ### Options
 Engine-specific options are described in [src/rsdkv4.options.ts](src/rsdkv4.options.ts)
 (`Rsdkv4Options` type + `RSDKV4_OPTIONS_SCHEMA`, mirrored into
 [src/rsdkv4.manifest.ts](src/rsdkv4.manifest.ts)'s `options`). When the host doesn't pass an explicit
 `settings` asset, the SDK **generates `settings.ini` from `config.options`**
-(`devMenu`, `engineDebugMode`, `vsync`, `startingCategory/Scene/Player`).
+(`devMenu`, `engineDebugMode`, `vsync`, `skipStartMenu`,
+`startingCategory/Scene/Player`).
+
+> `startingCategory/Scene/Player` default to **255 = unset**, which is what the
+> engine reads as "boot normally". Any other value — *including 0* — makes
+> `Engine::Init` skip the start-menu flow and force that stage.
 
 ### Other niceties
 - **Canvas id guard** — forces `canvas.id = "canvas"` because Emscripten's SDL2
   port locates the canvas via `querySelector('#canvas')`.
+- **Stale-engine self-heal** — `rsdkv4.js`/`.wasm` are big and most static hosts
+  send nothing but `Last-Modified`, so browsers keep a build for hours. Fresh SDK
+  against a cached engine is a miserable failure mode: the bridges it calls
+  aren't there and every getter quietly answers "empty" — no save slots, no
+  characters, an empty pause menu. So `load()` checks the module for the bridges
+  it needs and, if any are missing, refetches once with a cache-busting query and
+  says so in the console. A healthy build loads the engine exactly once.
 
 > Audio autoplay-unlock and the gamepad→keyboard translator are cross-cutting host
 > concerns (the app's shared input script); the SDK only exposes the `input`
@@ -73,14 +134,19 @@ Engine-specific options are described in [src/rsdkv4.options.ts](src/rsdkv4.opti
 
 Built with **`-sWASMFS`** — Emscripten's modern filesystem, replacing MEMFS. The
 game working dir `/data` is mounted on **OPFS** (persistent) via the `WebFS.cpp`
-`web_mount_opfs` helper when the page is **cross-origin isolated**; otherwise it
-falls back to the WASMFS in-memory backend so the engine still boots. `Data.rsdk`
+`web_mount_opfs` helper when the page is **cross-origin isolated** *and* the wasm
+build can create the OPFS backend from the main thread (see the caveat below —
+today's build can't); otherwise it falls back to the WASMFS in-memory backend so
+the engine still boots. `Data.rsdk`
 and the generated `settings.ini` are written there and read via CWD (the engine
 is booted with the `UsingCWD` arg).
 
 ### Backend selection — `config.persist`
-- `undefined` (default) — **auto**: OPFS when cross-origin isolated, else in-memory.
-- `'opfs'` — **force** OPFS; warn + fall back to in-memory if unavailable.
+- `undefined` (default) — **auto**: OPFS when cross-origin isolated *and* the build
+  supports the mount, else in-memory.
+- `'opfs'` — **ask for** OPFS; warn + fall back to in-memory if unavailable. (It
+  can't be *forced*: a build that can't mount OPFS would abort the module, so the
+  SDK checks first and falls back rather than trying.)
 - `null` — **force the in-memory** WASMFS backend (the MEMFS-equivalent fallback;
   non-persistent).
 
@@ -95,6 +161,32 @@ is booted with the `UsingCWD` arg).
 This prevents cross-game reuse collisions and allows purging one game's files
 without touching the others.
 
+### `/data` *is* the OPFS root
+`web_mount_opfs` mounts the backend returned by `wasmfs_create_opfs_backend()`,
+whose root is `navigator.storage.getDirectory()`. So the WASM path `/data/<ns>/…`
+and the OPFS path `<ns>/…` a host reaches from JS are **the same file**:
+
+| host, from JS (OPFS API)     | engine, inside WASMFS         |
+| ---------------------------- | ----------------------------- |
+| `rsdkv4/Sonic1/Data.rsdk`    | `/data/rsdkv4/Sonic1/Data.rsdk` |
+
+A launcher can therefore write a player's `Data.rsdk` straight into the folder the
+engine will use as its working dir and then load with
+`storageNamespace: 'rsdkv4/Sonic1'` and **no `assets.data` at all** — the SDK finds
+the file already persisted and skips the copy. That is what this repo's demo does
+(see [Try it locally](#try-it-locally)); it keeps one copy of a ~40 MB pack instead
+of two, and the game's save data lands next to it in the same folder.
+
+### Save data survives even without the mount
+The engine writes its save file (`SData.bin`) into the working dir, which is
+in-memory on every build that can't mount OPFS — so game saves would die with the
+page and every slot would read "NEW GAME" forever. The *host* side of OPFS has no
+such limitation (the plain async API works on any main thread), so the SDK
+mirrors that one file itself: it copies any stored `SData.bin` into the working
+dir before the engine boots, and copies it back out on pause, on `destroy()`, and
+every 10s in between. Saves therefore persist per `storageNamespace` even while
+the working dir does not. `persist: null` turns the mirror off with everything else.
+
 ### Skip re-fetch when already persisted
 When the working dir is OPFS-backed, the SDK checks whether `/data/Data.rsdk`
 (and `settings.ini`) already exist and **reuses them instead of re-downloading**.
@@ -126,15 +218,20 @@ const purged = sonic2.purgeStorage();
 console.log(purged); // { data: true|false, settings: true|false }
 ```
 
-> Persistence only actually engages under cross-origin isolation (see the OPFS
-> caveat below), so the skip-fetch benefit needs COOP/COEP + `-pthread` to be real.
-
-> ⚠️ **OPFS caveat (unverified):** OPFS sync-access handles only exist in Workers,
-> so Emscripten proxies them to a thread — reliable OPFS needs **`-pthread`** in
-> the build plus **COOP/COEP** headers on the host. This build is single-threaded,
-> so today OPFS persistence is best-effort and gated on `crossOriginIsolated`.
-> Adding `-pthread` interacts with SDL2 + `emscripten_set_main_loop` and must be
-> validated with a real build.
+> Persistence doesn't engage with the current build (see the OPFS caveat below),
+> so the skip-fetch benefit isn't real yet — every load fetches.
+
+> ⚠️ **OPFS caveat:** OPFS sync-access handles only exist in Workers, so WASMFS's
+> OPFS backend spawns a proxy worker — and it **refuses to do that from the main
+> browser thread** unless the build has **`-sASYNCIFY`** or **`-sJSPI`**. It
+> doesn't fail softly either: `wasmfs_create_opfs_backend()` asserts, and the
+> failed assert `abort()`s the module, so there is nothing left to fall back with.
+> The SDK mounts by calling into the module from the page (main thread) and this
+> build has neither flag, so `web_opfs_supported()` (WebFS.cpp) reports 0 and the
+> SDK never attempts the mount — COOP/COEP alone changes nothing. Making it real
+> means either building with Asyncify/JSPI, or `-pthread` + performing the mount
+> from the engine thread; both interact with SDL2 + `emscripten_set_main_loop` and
+> must be validated with a real build.
 
 ## Build
 
@@ -149,7 +246,9 @@ make build-wasm   # local: runs scripts/build.sh inside emscripten/emsdk (Docker
 
 - `build-lib` compiles the SDK/options/manifest (`.js` + `.d.ts`) → `dist/rsdkv4/`.
 - `build-manifest` serializes the typed manifest to `dist/manifest.json`.
-- `build-demo` compiles `src/demo/demo.ts` → `dist/demo.js`, copies
+- `build-demo` compiles `src/demo/{demo,library}.ts` → `dist/`, copies the shared
+  demo template from `@wasm-gaming/engine-specs` → `dist/demo/`, overwrites its
+  launcher with `src/demo/components/launcher.html` (the two-game one), copies
   `src/demo/index.html` → `dist/index.html`, seeds `dist/settings.ini`.
 - **`scripts/build.sh`** does not call Docker — it runs the WASM build steps
   directly and expects an Emscripten SDK on PATH. In CI it runs inside an
@@ -176,40 +275,94 @@ dist/
 │   └── rsdkv4.manifest.js(+ .d.ts)
 ├── manifest.json         # declarative manifest (artifacts → rsdkv4/rsdkv4.*)
 ├── index.html            # demo shell (import map → ./rsdkv4/rsdkv4.sdk.js)
-├── demo.js
+├── demo.js               # window.SDK + window.rsdkv4Library
+├── library.js            # the two-game OPFS library (src/demo/library.ts)
+├── start-screens.js      # save-select screen (src/demo/start-screens.ts)
+├── assets/               # demo artwork (game logos), from src/demo/assets/
+├── demo/                 # shared template (engine-specs); launcher.html and
+│                         #   esc-menu.html replaced by our own copies
 ├── settings.ini          # seeded from src/settings.default.ini if absent
-└── Data.rsdk             # dev-provided (git-ignored)
+└── Data.rsdk             # unused by the demo; kept for manual experiments
 ```
 
 ## Try it locally
 
 ```bash
-make build                           # produce dist/ (TypeScript + WASM)
-cp /path/to/Data.rsdk dist/          # git-ignored dev file the demo auto-loads
-cp /path/to/settings.ini dist/       # OPTIONAL — else seeded/generated
-make preview                         # serves dist/ on :8080
-# open http://localhost:8080/
+make build      # produce dist/ (TypeScript + WASM)
+make preview    # serves dist/ on :8024 with COOP/COEP
+# open http://localhost:8024/
+```
+
+### The launcher is a two-game library
+
+One WASM, two games — so the demo launcher is not a ROM picker but a shelf with
+one slot per game. Drop **Sonic 1's** `Data.rsdk` on one slot and **Sonic 2's** on
+the other (drag-and-drop or the file picker), pick a slot, press **Play**. Each
+pack is stored once, in the browser, and never uploaded:
+
+```
+OPFS root
+└── rsdkv4/
+    ├── Sonic1/
+    │   ├── Data.rsdk      ← what you dropped
+    │   ├── settings.ini   ← written by the SDK on first launch
+    │   └── …              ← that game's save data
+    └── Sonic2/…
 ```
 
-The demo fetches `./Data.rsdk` (required) and, if present, `./settings.ini`
-(optional) from `dist/`, mounting both into WASMFS. Without a `Data.rsdk` file the
-demo shows a pick / drag-and-drop prompt; without a `settings.ini` file the SDK
-synthesizes one from `config.options`.
+Because [`/data` is the OPFS root](#data-is-the-opfs-root), that folder *is* the
+engine's working dir: launching loads with `storageNamespace: 'rsdkv4/Sonic1'` and
+no assets, so nothing is copied or re-read. **Replace** swaps the pack; **Remove**
+deletes only `Data.rsdk`, leaving settings and saves for when it comes back.
+
+A page that isn't cross-origin isolated can't reach OPFS from WASM (see the caveat
+above), so the SDK falls back to an in-memory working dir and pulls the bytes
+through `dataProvider()` — the library serves them from the same stored copy, so
+the games still launch. Saves still survive, through the
+[save-data mirror](#save-data-survives-even-without-the-mount).
+
+### The game's own menus, in HTML
+
+Launching goes straight to a **save-select screen** — the demo's, not the engine's
+(it boots with `skipStartMenu: true`). It is laid out like Sonic Mania's: a row of
+portrait cards, status on top, character in the middle, chaos emeralds along the
+bottom, `NO SAVE` first. File and character are the *same* choice: **←/→ picks the
+file, ↑/↓ picks the player** (Sonic, Tails, Knuckles, Sonic & Tails) on any unused
+file, Enter starts. A used file starts as the character it was saved with. Everything but the game logo
+(`src/demo/assets/`) is drawn in CSS, and it drives the engine through
+`instance.game`, so the resulting game is the same one the native text menus
+would have started.
+
+**Escape** opens the pause overlay, which pauses the engine *and its music* and
+shows only what RSDKv4 can actually do live:
+
+- **Jump to** — buttons for the title screen, the game's stage menu, level select
+  and special stages 1-8. Each closes the overlay and warps straight away, so
+  there is no "now press resume" step
+- **Game options** — the engine's own GAME OPTIONS (spindash, speed caps, S1
+  spikes, item box set, super forms), read and written through the same globals
+  and save file the native screen uses
+
+The pieces: [src/demo/library.ts](src/demo/library.ts) (storage),
+[src/demo/start-screens.ts](src/demo/start-screens.ts) (save select),
+[src/demo/components/launcher.html](src/demo/components/launcher.html) (the slots),
+[src/demo/components/esc-menu.html](src/demo/components/esc-menu.html) (pause overlay),
+[src/demo/index.html](src/demo/index.html) (wiring to `SDK.load`).
 
 ## Live demo (GitHub Pages)
 
 The `pages` job in [.github/workflows/build.yml](.github/workflows/build.yml)
-publishes `dist/` to GitHub Pages on pushes to `main` (and manual runs). Since
-`Data.rsdk` is git-ignored, the live demo opens on the pick / drag-and-drop
-prompt — drop a `Data.rsdk` to boot.
+publishes `dist/` to GitHub Pages on pushes to `main` (and manual runs). No game
+data ships with it, so the live demo opens on two empty slots — drop each game's
+`Data.rsdk` once and they stay in that browser.
 
 - **One-time setup:** repo *Settings → Pages → Build and deployment → Source =
   GitHub Actions*. The workflow also calls `actions/configure-pages` with
   `enablement: true`, so first deploy can bootstrap Pages automatically when the
   repo-level Pages site does not exist yet.
-- **OPFS note:** GitHub Pages can't set COOP/COEP headers, so the page isn't
-  cross-origin isolated — OPFS stays off and the SDK uses the in-memory WASMFS
-  backend (see the filesystem caveat above).
+- **OPFS note:** OPFS stays off and the SDK uses the in-memory WASMFS backend —
+  GitHub Pages can't set COOP/COEP headers, and this build couldn't mount OPFS
+  even isolated (see the filesystem caveat above).
 
 ## Status
 
@@ -219,9 +372,9 @@ prompt — drop a `Data.rsdk` to boot.
   the `web_devmenu_*` embind bridge, `callMain`/`FS`/`ccall`, no `--preload-file`).
 - ⏳ **End-to-end runtime in a browser** (boot from a real `Data.rsdk`) — not yet
   verified.
-- ⏳ **OPFS persistence** — gated on `crossOriginIsolated`; almost certainly needs
-  a `-pthread` build + COOP/COEP to actually engage (see the caveat above). Until
-  then the SDK falls back to the in-memory WASMFS backend.
+- ⏳ **OPFS persistence** — not engaged: WASMFS's OPFS backend can't be created on
+  the main browser thread without an Asyncify/JSPI build (see the caveat above),
+  so the SDK detects that and falls back to the in-memory WASMFS backend.
 
 ## License
 

package/dist/manifest.json

@@ -1,7 +1,8 @@
 {
   "id": "rsdkv4",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "name": "Retro Software Development Kit v4",
+  "description": "RSDKv4 compiled to WebAssembly via Emscripten. One game-agnostic WASM binary runs both Sonic 1 and Sonic 2 — the difference is only which Data.rsdk the host supplies at runtime. Ships none of the game: the player provides their own Data.rsdk, and it never leaves their browser.",
   "artifacts": {
     "wasm": "rsdkv4/rsdkv4.wasm",
     "js": "rsdkv4/rsdkv4.js"
@@ -26,7 +27,17 @@
       "description": "Engine settings. Omitted → the SDK generates one from config.options."
     }
   ],
-  "input": "rsdkv4",
+  "input": {
+    "up": "ArrowUp",
+    "down": "ArrowDown",
+    "left": "ArrowLeft",
+    "right": "ArrowRight",
+    "a": "KeyZ",
+    "b": "KeyX",
+    "c": "KeyC",
+    "start": "Enter",
+    "select": "ShiftLeft"
+  },
   "video": {
     "baseWidth": 424,
     "baseHeight": 240,
@@ -50,20 +61,28 @@
         "type": "boolean",
         "default": true
       },
+      "skipStartMenu": {
+        "type": "boolean",
+        "default": false,
+        "description": "Skip the engine's own save/character/options screens — set it when the host renders them from instance.game."
+      },
       "startingCategory": {
         "type": "integer",
         "minimum": 0,
-        "default": 0
+        "default": 255,
+        "description": "0-based stage-list category; 255 = unset (normal boot flow)."
       },
       "startingScene": {
         "type": "integer",
         "minimum": 0,
-        "default": 0
+        "default": 255,
+        "description": "0-based scene in the category; 255 = unset (normal boot flow)."
       },
       "startingPlayer": {
         "type": "integer",
         "minimum": 0,
-        "default": 0
+        "default": 255,
+        "description": "Player/character index; 255 = unset (normal boot flow)."
       }
     }
   },

package/dist/rsdkv4/rsdkv4.manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsdkv4.manifest.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,eAAO,MAAM,QAAQ,EAAE,cAkCtB,CAAC;AAEF,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"rsdkv4.manifest.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,eAAO,MAAM,QAAQ,EAAE,cA+CtB,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/rsdkv4/rsdkv4.manifest.js

@@ -4,8 +4,9 @@
 import { RSDKV4_OPTIONS_SCHEMA } from './rsdkv4.options.js';
 export const manifest = {
     id: 'rsdkv4',
-    version: '0.1.0',
+    version: '0.1.5',
     name: 'Retro Software Development Kit v4',
+    description: 'RSDKv4 compiled to WebAssembly via Emscripten. One game-agnostic WASM binary runs both Sonic 1 and Sonic 2 — the difference is only which Data.rsdk the host supplies at runtime. Ships none of the game: the player provides their own Data.rsdk, and it never leaves their browser.',
     artifacts: {
         // Relative to the manifest (dist/manifest.json); the engine files live in
         // the dist/rsdkv4/ subfolder.
@@ -30,7 +31,18 @@ export const manifest = {
             description: 'Engine settings. Omitted → the SDK generates one from config.options.',
         },
     ],
-    input: 'rsdkv4',
+    // RSDKv4 keyboard defaults. The key names are KeyboardEvent.code values.
+    input: {
+        up: 'ArrowUp',
+        down: 'ArrowDown',
+        left: 'ArrowLeft',
+        right: 'ArrowRight',
+        a: 'KeyZ',
+        b: 'KeyX',
+        c: 'KeyC',
+        start: 'Enter',
+        select: 'ShiftLeft',
+    },
     video: { baseWidth: 424, baseHeight: 240, aspect: '16:9' },
     options: RSDKV4_OPTIONS_SCHEMA,
     capabilities: { saveStates: false, sram: false, coreSelectable: false },

package/dist/rsdkv4/rsdkv4.manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"rsdkv4.manifest.js","sourceRoot":"","sources":["../../src/rsdkv4.manifest.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,iFAAiF;AAGjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACtC,EAAE,EAAE,QAAQ;IACZ,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,mCAAmC;IACzC,SAAS,EAAE;QACT,0EAA0E;QAC1E,8BAA8B;QAC9B,IAAI,EAAE,oBAAoB;QAC1B,EAAE,EAAE,kBAAkB;KACvB;IACD,MAAM,EAAE;QACN;YACE,GAAG,EAAE,MAAM;YACX,4EAA4E;YAC5E,0CAA0C;YAC1C,SAAS,EAAE,iBAAiB;YAC5B,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,CAAC,OAAO,CAAC;YACjB,WAAW,EACT,iFAAiF;SACpF;QACD;YACE,GAAG,EAAE,UAAU;YACf,SAAS,EAAE,oBAAoB;YAC/B,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,CAAC,MAAM,CAAC;YAChB,WAAW,EACT,uEAAuE;SAC1E;KACF;IACD,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE;IAC1D,OAAO,EAAE,qBAAqB;IAC9B,YAAY,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE;CACxE,CAAC;AAEF,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"rsdkv4.manifest.js","sourceRoot":"","sources":["../../src/rsdkv4.manifest.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,iFAAiF;AAGjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACtC,EAAE,EAAE,QAAQ;IACZ,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,mCAAmC;IACzC,WAAW,EACT,uRAAuR;IACzR,SAAS,EAAE;QACT,0EAA0E;QAC1E,8BAA8B;QAC9B,IAAI,EAAE,oBAAoB;QAC1B,EAAE,EAAE,kBAAkB;KACvB;IACD,MAAM,EAAE;QACN;YACE,GAAG,EAAE,MAAM;YACX,4EAA4E;YAC5E,0CAA0C;YAC1C,SAAS,EAAE,iBAAiB;YAC5B,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,CAAC,OAAO,CAAC;YACjB,WAAW,EACT,iFAAiF;SACpF;QACD;YACE,GAAG,EAAE,UAAU;YACf,SAAS,EAAE,oBAAoB;YAC/B,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,CAAC,MAAM,CAAC;YAChB,WAAW,EACT,uEAAuE;SAC1E;KACF;IACD,yEAAyE;IACzE,KAAK,EAAE;QACL,EAAE,EAAE,SAAS;QACb,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,YAAY;QACnB,CAAC,EAAE,MAAM;QACT,CAAC,EAAE,MAAM;QACT,CAAC,EAAE,MAAM;QACT,KAAK,EAAE,OAAO;QACd,MAAM,EAAE,WAAW;KACpB;IACD,KAAK,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE;IAC1D,OAAO,EAAE,qBAAqB;IAC9B,YAAY,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE;CACxE,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/rsdkv4/rsdkv4.options.d.ts

@@ -10,6 +10,12 @@ export interface Rsdkv4Options {
     engineDebugMode?: boolean;
     /** VSync the engine's SDL window. */
     vsync?: boolean;
+    /**
+     * Skip RSDKv4's in-canvas Start Menu (save select / character select / game
+     * options). Set this when the host draws those screens itself from
+     * `instance.game` — otherwise the engine's own menu runs underneath.
+     */
+    skipStartMenu?: boolean;
     /** Boot directly into a stage: 0-based stage-list category. */
     startingCategory?: number;
     /** Boot directly into a stage: 0-based scene within the category. */
@@ -17,6 +23,12 @@ export interface Rsdkv4Options {
     /** Starting player/character index. */
     startingPlayer?: number;
 }
+/**
+ * RSDKv4 reads 255 as "not set" for the starting stage/player (see Userdata.cpp:
+ * anything else — **including 0** — makes Engine::Init skip the start-menu flow
+ * and force InitStartingStage). So "boot normally" has to be 255, not 0.
+ */
+export declare const RSDKV4_UNSET = 255;
 export declare const DEFAULT_RSDKV4_OPTIONS: Required<Rsdkv4Options>;
 export declare const RSDKV4_OPTIONS_SCHEMA: JSONSchema;
 //# sourceMappingURL=rsdkv4.options.d.ts.map

package/dist/rsdkv4/rsdkv4.options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsdkv4.options.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAO1D,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,UAoBnC,CAAC"}
+{"version":3,"file":"rsdkv4.options.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAQ1D,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,UAyCnC,CAAC"}

package/dist/rsdkv4/rsdkv4.options.js

@@ -10,13 +10,20 @@
 // At runtime these options are serialized into RSDKv4's `settings.ini` (see the
 // SDK's settings serializer) when the host does not pass an explicit `settings`
 // asset.
+/**
+ * RSDKv4 reads 255 as "not set" for the starting stage/player (see Userdata.cpp:
+ * anything else — **including 0** — makes Engine::Init skip the start-menu flow
+ * and force InitStartingStage). So "boot normally" has to be 255, not 0.
+ */
+export const RSDKV4_UNSET = 255;
 export const DEFAULT_RSDKV4_OPTIONS = {
     devMenu: false,
     engineDebugMode: true,
     vsync: true,
-    startingCategory: 0,
-    startingScene: 0,
-    startingPlayer: 0,
+    skipStartMenu: false,
+    startingCategory: RSDKV4_UNSET,
+    startingScene: RSDKV4_UNSET,
+    startingPlayer: RSDKV4_UNSET,
 };
 export const RSDKV4_OPTIONS_SCHEMA = {
     type: 'object',
@@ -33,9 +40,29 @@ export const RSDKV4_OPTIONS_SCHEMA = {
             description: 'Enables the web devmenu embind bridge (stage list / warp / pause).',
         },
         vsync: { type: 'boolean', default: true },
-        startingCategory: { type: 'integer', minimum: 0, default: 0 },
-        startingScene: { type: 'integer', minimum: 0, default: 0 },
-        startingPlayer: { type: 'integer', minimum: 0, default: 0 },
+        skipStartMenu: {
+            type: 'boolean',
+            default: false,
+            description: "Skip the engine's own save/character/options screens — set it when the host renders them from instance.game.",
+        },
+        startingCategory: {
+            type: 'integer',
+            minimum: 0,
+            default: RSDKV4_UNSET,
+            description: '0-based stage-list category; 255 = unset (normal boot flow).',
+        },
+        startingScene: {
+            type: 'integer',
+            minimum: 0,
+            default: RSDKV4_UNSET,
+            description: '0-based scene in the category; 255 = unset (normal boot flow).',
+        },
+        startingPlayer: {
+            type: 'integer',
+            minimum: 0,
+            default: RSDKV4_UNSET,
+            description: 'Player/character index; 255 = unset (normal boot flow).',
+        },
     },
 };
 //# sourceMappingURL=rsdkv4.options.js.map

package/dist/rsdkv4/rsdkv4.options.js.map

@@ -1 +1 @@
-{"version":3,"file":"rsdkv4.options.js","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,+EAA+E;AAC/E,qCAAqC;AACrC,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,iEAAiE;AACjE,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,SAAS;AAuBT,MAAM,CAAC,MAAM,sBAAsB,GAA4B;IAC7D,OAAO,EAAE,KAAK;IACd,eAAe,EAAE,IAAI;IACrB,KAAK,EAAE,IAAI;IACX,gBAAgB,EAAE,CAAC;IACnB,aAAa,EAAE,CAAC;IAChB,cAAc,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAe;IAC/C,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,OAAO,EAAE;YACP,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,WAAW,EACT,mHAAmH;SACtH;QACD,eAAe,EAAE;YACf,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,oEAAoE;SAClF;QACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;QACzC,gBAAgB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QAC7D,aAAa,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QAC1D,cAAc,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;KAC5D;CACF,CAAC"}
+{"version":3,"file":"rsdkv4.options.js","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,+EAA+E;AAC/E,qCAAqC;AACrC,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,iEAAiE;AACjE,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,SAAS;AA6BT;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC,MAAM,CAAC,MAAM,sBAAsB,GAA4B;IAC7D,OAAO,EAAE,KAAK;IACd,eAAe,EAAE,IAAI;IACrB,KAAK,EAAE,IAAI;IACX,aAAa,EAAE,KAAK;IACpB,gBAAgB,EAAE,YAAY;IAC9B,aAAa,EAAE,YAAY;IAC3B,cAAc,EAAE,YAAY;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAe;IAC/C,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,OAAO,EAAE;YACP,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,WAAW,EACT,mHAAmH;SACtH;QACD,eAAe,EAAE;YACf,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,oEAAoE;SAClF;QACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;QACzC,aAAa,EAAE;YACb,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,WAAW,EACT,8GAA8G;SACjH;QACD,gBAAgB,EAAE;YAChB,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,YAAY;YACrB,WAAW,EAAE,8DAA8D;SAC5E;QACD,aAAa,EAAE;YACb,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,YAAY;YACrB,WAAW,EAAE,gEAAgE;SAC9E;QACD,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,YAAY;YACrB,WAAW,EAAE,yDAAyD;SACvE;KACF;CACF,CAAC"}

package/dist/rsdkv4/rsdkv4.sdk.d.ts

@@ -12,8 +12,65 @@ export interface RsdkDevMenuBridge {
     loadStage(categoryIdx: number, stageIdx: number): void;
     setPaused(paused: boolean): void;
 }
-export type Rsdkv4Instance = EngineInstance & {
+/** One of RSDKv4's four save slots, as the engine's own save-select screen sees it. */
+export interface RsdkSaveSlot {
+    /** 0-3. */
+    slot: number;
+    /** No game stored here — starting it means picking a character first. */
+    empty: boolean;
+    /** Character index into `players()`: 0 Sonic, 1 Tails, 2 Knuckles, 3 Sonic & Tails. */
+    character: number;
+    lives: number;
+    score: number;
+    emeralds: number;
+    /** Stage list the save resumes into (1 regular, 3 special), or -1 when empty. */
+    list: number;
+    /** 0-based scene within `list` — index it against `devMenu.getStageList()`. */
+    zone: number;
+}
+/** A row of the engine's GAME OPTIONS screen (differs between Sonic 1 and 2). */
+export interface RsdkGameOption {
+    key: string;
+    label: string;
+    value: number;
+    type: 'boolean' | 'enum';
+    /** Choice labels, for `type: 'enum'` (item box sets). */
+    values?: string[];
+}
+/**
+ * The engine's Start Menu as data, so a host can render save-slot / character /
+ * game-option screens itself. Everything here mirrors what RSDKv4's own in-canvas
+ * menu does — see WebGame.cpp.
+ */
+export interface RsdkGameBridge {
+    /** 1 = Sonic 1, 2 = Sonic 2, 0 = unrecognised pack. */
+    type(): number;
+    /** Playable characters from the pack's GameConfig, in engine order. */
+    players(): string[];
+    saveSlots(): RsdkSaveSlot[];
+    /**
+     * Start a game the way the native menu would: a slot with data continues it,
+     * an empty slot starts a new game as `player`, and `slot: null` plays without
+     * saving. Resumes the engine if the SDK had it paused.
+     */
+    start(slot: number | null, player?: number): void;
+    /** Wipe a slot back to "NEW GAME". */
+    deleteSave(slot: number): void;
+    options(): RsdkGameOption[];
+    /** Set an option; written through to the engine and its save file, as the engine does. */
+    setOption(key: string, value: number): void;
+}
+export type Rsdkv4Instance = Omit<EngineInstance, 'pause' | 'resume'> & {
+    /**
+     * Pause, on behalf of `owner` (default 'host'). The first caller to pause owns
+     * it and only that owner's `resume()` lifts it, so a pause overlay can't
+     * resume a game a start screen — or the host — had already frozen. Audio stops
+     * with the engine.
+     */
+    pause(owner?: string): void;
+    resume(owner?: string): void;
     devMenu: RsdkDevMenuBridge;
+    game: RsdkGameBridge;
     /** True when the working dir is OPFS-backed (persistent) rather than in-memory. */
     persistent: boolean;
     /** Relative storage namespace used under /data (e.g. "sonic1", "sonic2"). */
@@ -37,6 +94,8 @@ export type Rsdkv4LoadConfig = EngineConfig & {
      * Examples: "sonic1", "sonic2", "my-pack/v1".
      */
     storageNamespace?: string;
+    /** Deprecated alias for `canvasEl`, kept for hosts written against 0.0.x. */
+    canvas?: HTMLCanvasElement;
 };
 /** Boot the RSDKv4 engine. */
 export declare function load(config: Rsdkv4LoadConfig): Promise<Rsdkv4Instance>;

package/dist/rsdkv4/rsdkv4.sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsdkv4.sdk.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.sdk.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD,OAAO,EAAE,QAAQ,EAAE,CAAC;AA+GpB,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,YAAY,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IACzE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,YAAY,IAAI;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;CACtD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IACpD,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,8BAA8B;AAC9B,wBAAsB,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+H5E;;;;;AAED,wBAAkC"}
+{"version":3,"file":"rsdkv4.sdk.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.sdk.ts"],"names":[],"mappings":"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"}