@wasm-gaming/rsdkv3-wasm 0.1.4 → 0.2.0

package/README.md

@@ -1,89 +1,98 @@
 # @wasm-gaming/rsdkv3-wasm
 
-RSDKv3 (Retro Software Development Kit v3, Sonic CD 2011 decompilation) compiled
-to WebAssembly, wrapped in a JS SDK conforming to the
-[wasm-gaming engine contract](https://github.com/wasm-gaming/engine-specs).
+RSDKv3 (Retro Software Development Kit v3, the Sonic CD 2011 decompilation) compiled to
+WebAssembly, wrapped in a self-contained SDK that implements the
+[wasm-gaming engine contract](https://github.com/wasm-gaming/engine-specs) 1.0.
 
-The engine does not bake game data with `--preload-file`. Hosts provide
-`Data.rsdk` at runtime, so the same `rsdkv3.wasm` can be reused across installs.
+The engine bakes no game data: the host hands over `Data.rsdk` at runtime, so one `rsdkv3.wasm`
+serves any install.
 
-## Contract surface
+## Install
 
-```js
-import { manifest, load } from '@wasm-gaming/rsdkv3-wasm';
-
-const engine = await load({
-  canvas,
-  assets: { data: dataRsdkBytes /*, settings: iniBytes */ },
-  onEvent: (e) => { /* 'ready' | 'error' */ },
-  // Optional override when artifacts are hosted externally:
-  // jsUrl, wasmUrl,
-});
-
-engine.pause();
-engine.resume();
-engine.setInput('rsdkv4');
-engine.destroy();
+```bash
+npm install @wasm-gaming/rsdkv3-wasm
 ```
 
-- `manifest` defines required `data` (`/data/Data.rsdk`) and optional `settings`
-  (`/data/settings.ini`) assets.
-- `load(config)` returns an `EngineInstance` and exposes `devMenu` bridge helpers:
-  `getStageList()`, `loadStage(category, stage)`, `setPaused(bool)`.
+The SDK carries the contract's runtime beside it (`dist/rsdkv3/engine-specs.js`) and imports it
+relatively: it loads from any static server, with no bundler and no import map. The wasm and its
+glue are built in CI and shipped in the GitHub Release (`rsdkv3.tar.gz`, layout `rsdkv3/rsdkv3/…`).
 
-## Options
+## Use
 
-Engine-specific options are declared in
-[src/rsdkv3.options.ts](src/rsdkv3.options.ts) and mirrored into `manifest.options`:
+```js
+import Rsdkv3SDK from './rsdkv3/rsdkv3.sdk.js';
+
+const play = await new Rsdkv3SDK({ config: { soundtrack: 1 } })   // US soundtrack
+  .assets({ data: () => readDataRsdk() })      // bytes, or a thunk
+  .storage({ namespace: 'sonic-cd' })          // → OPFS rsdkv3/sonic-cd/
+  .on('saves', ({ detail }) => console.log('saved', detail.files))
+  .mount(document.querySelector('#stage'))
+  .start();
+
+play.pause('menu');  play.resume('menu');      // owner-aware; sound stops too
+play.devMenu.getStageList();                   // draw your own stage select…
+play.devMenu.loadStage(0, 2);                  // …and warp
+await play.destroy();                          // save flushed, loop stopped, audio closed
+```
 
-- `devMenu`
-- `engineDebugMode`
-- `vsync`
-- `soundtrack` (`0` JP/EU, `1` US)
-- `language`
-- `disableTouchControls`
+| payload | keys |
+| --- | --- |
+| `config` | `devMenu`, `engineDebugMode`, `vsync`, `soundtrack` (0 JP/EU, 1 US), `language`, `disableTouchControls` (→ generated `settings.ini`), `jsUrl`, `wasmUrl` |
+| `options` | — |
+| `assets` | `data` (`Data.rsdk`, required), `settings` (`settings.ini`, optional) |
+| `storage` | `namespace` (default `default`), `persist` (`'opfs'` \| `null`) |
 
-If `assets.settings` is omitted, the SDK generates `settings.ini` from these
-options.
+Events: the contract's `start`, `error`, `exit`, `pause`, `resume`, plus `saves`.
+RSDKv3 cannot restart in process: after `destroy()`, a new session needs a new page (or iframe).
 
-## Build
+## The engine's own app
 
-All build logic is in [Makefile](Makefile):
+A host that would rather not draw menus mounts the app shipped next to the SDK
+([engine-specs](https://github.com/wasm-gaming/engine-specs) `EngineApp`, `UX.md`):
 
-```bash
-make build        # SDK (TypeScript) + WASM
-make build-sdk    # SDK only
-make build-wasm   # WASM via Docker wrapper
-make preview      # serves dist/ at http://localhost:8080
+```js
+const app = await import('@wasm-gaming/rsdkv3-wasm/app'); // dist/rsdkv3/app/app.js
+const handle = await app.mount(element, { game, storage, assets, input, exit });
+await handle.unmount();
 ```
 
-- `scripts/build.sh` clones `Rubberduckycooly/Sonic-CD-11-Decompilation`, applies
-  known Emscripten patches, vendors `libtheora`, and outputs:
-  - `dist/rsdkv3/rsdkv3.js`
-  - `dist/rsdkv3/rsdkv3.wasm`
-- `scripts/emit-manifest.mjs` writes `dist/manifest.json` from typed manifest.
-- `scripts/seed-settings.mjs` seeds `dist/settings.ini` from
-  `src/settings.default.ini` when absent.
+It shows a boot screen, then Sonic CD with its own title and save select. Select + Start or
+Escape opens the pause menu: *Continuar*, the game's own screens found in the stage list (title
+screen, main menu, level select — only those the data has) and *Volver al lanzador* (asks first).
+There is no load-game screen like rsdkv4's yet: that needs a native bridge (see `RECORD/`).
+
+## Saves live in the engine's own folder
+
+The working dir is `/data/rsdkv3/<namespace>` (in memory). The SDK seeds `SData.bin` from OPFS
+`rsdkv3/<namespace>/` before boot and mirrors it back when it changes — every 10 s, on pause, when
+the page is hidden and on `destroy()` — so saves survive reloads. `play.storagePath` gives the
+folder; `storagePath(engineId, namespace)` is exported.
 
-## Try locally
+## Build
 
 ```bash
-make build
-cp /path/to/Data.rsdk dist/
-make preview
-# open http://localhost:8080/
+make build-sdk      # TypeScript → dist/rsdkv3/ (fast, no Docker)
+make test           # type-check + tests against the built package
+make build-wasm     # RSDKv3 → WebAssembly in emscripten/emsdk:6.0.2 (Docker)
+make demo           # dist/index.html: a no-build demo (pick or drop Data.rsdk)
+make preview        # serve dist/ on :8023
 ```
 
-The demo attempts `./Data.rsdk`; if missing, it shows a file picker and supports
-drag-and-drop.
+The upstream decompilation is pinned (`d1bbec59`, 2026-07-04) together with its submodules, and so
+is the emsdk image, because the build's source patches are written against that exact revision.
+
+## Project Specs
+
+- Contract 1.0 class (`Rsdkv3SDK` / `Rsdkv3Play`), self-contained ESM, engine-specs as the one
+  dependency; conformance line `RSDKV3_ENGINE` checked by `make test`.
+- Engine-owned storage `rsdkv3/<namespace>/` with an `SData.bin` mirror.
+- Records of decisions in [RECORD/](RECORD/).
 
-## Status
+## Todos
 
-- ✅ TypeScript SDK + manifest build
-- ✅ CI workflow scaffold for SDK/WASM/release/pages
-- ⏳ Browser runtime verification with a real `Data.rsdk`
-- ⏳ Full WASM build verification (`make build-wasm`) on this new subproject
+- [ ] Make the build's source patches assert that they applied.
+- [ ] Verify with a real `Data.rsdk` (save written by the game → mirrored → restored).
 
 ## License
 
-MIT for this wrapper. Upstream engine and game data keep their own licenses.
+MIT for this wrapper. The upstream engine and the game data keep their own licenses.

package/dist/rsdkv3/app/app.css

@@ -0,0 +1,77 @@
+/* rsdkv3 app — boot screen and pause menu (same look as rsdkv4's app).
+   Tokens come from engine-specs (UI_TOKENS, `--wg-*`) when the host sets them; the
+   fallbacks are the same values, so the app looks right on a bare page too. */
+
+.rsdk-app {
+  --ring: var(--wg-focus-ring, 0 0 0 3px #fff);
+  --surface: var(--wg-surface, rgb(18 20 28 / 0.78));
+  --line: var(--wg-line, rgb(255 255 255 / 0.12));
+  --text: var(--wg-text, #f4f6fb);
+  --muted: var(--wg-muted, #8e97a9);
+  --danger: var(--wg-danger, #f87171);
+  --ui: var(--wg-font-ui, 'Inter Variable', 'Inter', system-ui, sans-serif);
+  --display: var(--wg-font-display, 'Unbounded Variable', 'Unbounded', system-ui, sans-serif);
+  --ease: var(--wg-ease, cubic-bezier(0.2, 0.8, 0.2, 1));
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  background: #000;
+  color: var(--text);
+  font-family: var(--ui);
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+}
+.rsdk-app * { box-sizing: border-box; }
+.rsdk-stage { position: absolute; inset: 0; display: grid; place-items: center; }
+.rsdk-stage canvas { outline: none; }
+.rsdk-overlay { position: absolute; inset: 0; display: grid; place-items: center; pointer-events: none; }
+.rsdk-overlay > * { pointer-events: auto; }
+.rsdk-app[data-screen='game'] .rsdk-overlay { display: none; }
+
+/* Everything but the game sits on a backdrop that keeps the game visible underneath. */
+.rsdk-app:not([data-screen='game']) .rsdk-overlay {
+  background:
+    radial-gradient(120% 80% at 50% 0%, color-mix(in srgb, var(--accent) 38%, transparent), transparent 70%),
+    rgb(4 6 12 / 0.72);
+  backdrop-filter: blur(14px) saturate(1.2);
+  -webkit-backdrop-filter: blur(14px) saturate(1.2);
+}
+.rsdk-app[data-screen='boot'] .rsdk-overlay { background-color: rgb(4 6 12 / 0.9); }
+
+.kicker { margin: 0; font: 600 0.72rem var(--ui); letter-spacing: 0.22em; text-transform: uppercase; color: var(--muted); }
+.rsdk-app h2 { margin: 0; font: 700 clamp(1.4rem, 3vw, 2.1rem) var(--display); letter-spacing: -0.02em; }
+
+/* ---- boot ---- */
+.rsdk-boot { display: grid; justify-items: center; gap: 22px; }
+.rsdk-boot img { width: min(260px, 50vw); border-radius: 22px; box-shadow: 0 30px 80px -30px #000; animation: rsdk-breathe 2.4s var(--ease) infinite alternate; }
+.rsdk-boot p { margin: 0; color: var(--muted); font-weight: 500; }
+@keyframes rsdk-breathe { from { opacity: 0.55; transform: scale(0.98); } to { opacity: 1; transform: none; } }
+
+/* ---- pause & confirm ---- */
+.rsdk-panel {
+  width: min(440px, 92vw); display: grid; gap: 10px; padding: 26px; border-radius: 28px;
+  background: rgb(20 22 31 / 0.9); border: 1px solid var(--line); box-shadow: 0 40px 100px -30px #000;
+}
+.rsdk-panel h2 { margin-bottom: 8px; }
+.rsdk-panel .text { margin: 0 0 8px; color: var(--muted); line-height: 1.5; }
+.item {
+  all: unset; box-sizing: border-box; display: grid; gap: 2px; padding: 13px 16px; border-radius: 14px;
+  background: rgb(255 255 255 / 0.05); font-weight: 600; cursor: pointer; transition: background 0.15s, box-shadow 0.15s;
+}
+.item small { font-weight: 500; font-size: 0.78rem; color: var(--muted); }
+.item.is-focused { background: #fff; color: #0b0d12; box-shadow: var(--ring); }
+.item.is-focused small { color: #4b5563; }
+.item.is-danger.is-focused { background: var(--danger); color: #1a0505; box-shadow: 0 0 0 3px var(--danger); }
+.rsdk-panel .row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+.rsdk-panel .row .item { text-align: center; }
+.rsdk-confirm { position: absolute; inset: 0; display: grid; place-items: center; background: rgb(0 0 0 / 0.55); }
+
+/* ---- hints ---- */
+.rsdk-hints { display: flex; flex-wrap: wrap; gap: 8px 18px; justify-content: center; color: var(--muted); font-size: 0.78rem; font-weight: 500; }
+.rsdk-hints span { display: inline-flex; align-items: center; gap: 7px; }
+.rsdk-hints kbd { display: inline-grid; place-items: center; min-width: 22px; height: 22px; padding: 0 6px; border-radius: 11px; background: rgb(255 255 255 / 0.12); color: var(--text); font: 700 0.68rem var(--ui); }
+.rsdk-panel .rsdk-hints { justify-content: flex-start; margin-top: 6px; }
+
+@media (prefers-reduced-motion: reduce) {
+  .rsdk-boot img { transition: none; animation: none; }
+}

package/dist/rsdkv3/app/app.js

@@ -0,0 +1,319 @@
+// rsdkv3's own app: what a host gets when it mounts this engine instead of driving
+// the SDK itself — a boot screen, then the game with its OWN title and save select,
+// and a pause menu on the wasm-gaming usability scheme (engine-specs UX.md).
+//
+//   import * as app from '<engines>/rsdkv3/app/app.js'
+//   const handle = await app.mount(target, host)   // EngineApp.mount
+//   await handle.unmount()
+//
+// `host` is engine-specs' EngineAppHost: { game, storage, assets, input, exit }. The
+// input is the host's createInput(): resumed it delivers menu actions; suspended (in
+// game) only Select+Start and Escape come through, as `menu`.
+//
+// Unlike rsdkv4's app there is no load-game screen: Sonic CD's menus are scripts in
+// Data.rsdk, with no native bridge to list or start a save (see RECORD/).
+//
+// Plain JS and DOM on purpose: the app ships inside the engine's package next to the
+// SDK and loads from a static server, so it imports nothing but the SDK.
+
+import Rsdkv3SDK from '../rsdkv3.sdk.js';
+
+const ENGINE = 'rsdkv3';
+const OWNER = 'app';
+
+/**
+ * The game's own screens worth jumping to from the pause menu, looked up by scene
+ * name in the live stage list. Only the ones the loaded Data.rsdk has are offered.
+ */
+export const GAME_SCREENS = [
+  { match: /^TITLE( SCREEN)?$/i, label: 'Pantalla de título' },
+  { match: /^(MAIN MENU|MENU|SAVE SELECT|STAGE MENU)$/i, label: 'Menú del juego' },
+  { match: /^(LEVEL|STAGE) SELECT$/i, label: 'Level select' }, // Sonic CD: STAGE SELECT
+];
+
+/** `[{ label, list, scene }]` for the GAME_SCREENS found in a devMenu stage list. */
+export const findGameScreens = (lists) => {
+  const found = [];
+  for (const screen of GAME_SCREENS) {
+    for (let list = 0; list < (lists?.length ?? 0); list++) {
+      const scene = (lists[list]?.stages ?? []).findIndex(({ name } = {}) => screen.match.test(String(name ?? '').trim()));
+      if (scene >= 0) {
+        found.push({ label: screen.label, list, scene });
+        break;
+      }
+    }
+  }
+  return found;
+};
+
+const esc = (text) => String(text ?? '').replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+let cssLoaded = null;
+const loadCss = () =>
+  (cssLoaded ??= new Promise((resolve) => {
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = new URL('./app.css', import.meta.url).href;
+    link.onload = link.onerror = () => resolve();
+    document.head.append(link);
+  }));
+
+export async function mount(target, host) {
+  await loadCss();
+
+  const root = document.createElement('div');
+  root.className = 'rsdk-app';
+  root.style.setProperty('--accent', host.game?.accent ?? '#1d4ed8');
+  const stage = document.createElement('div');
+  stage.className = 'rsdk-stage';
+  const overlay = document.createElement('div');
+  overlay.className = 'rsdk-overlay';
+  root.append(stage, overlay);
+  target.append(root);
+
+  /** screen: 'boot' | 'game' | 'pause' | 'confirm' | 'error' */
+  const state = {
+    screen: 'boot',
+    status: 'Arrancando el motor…',
+    error: null,
+    pause: { items: [], focus: 0 },
+    confirm: null, // { title, text, yes, no, onYes, onNo, focus, under }
+  };
+
+  let play = null;
+  let leaving = false;
+  let destroyed = false;
+
+  const canvasFocus = () => stage.querySelector('canvas')?.focus({ preventScroll: true });
+  const title = () => host.game?.title ?? 'Sonic CD';
+
+  // ---- screens ------------------------------------------------------------------
+
+  const hints = (pairs) =>
+    `<footer class="rsdk-hints">${pairs.map(([k, t]) => `<span><kbd>${k}</kbd>${t}</span>`).join('')}</footer>`;
+
+  const render = () => {
+    if (destroyed) return;
+    root.dataset.screen = state.screen;
+    const s = state.screen;
+    if (s === 'game') {
+      overlay.innerHTML = '';
+      return;
+    }
+    if (s === 'boot') {
+      overlay.innerHTML = `<section class="rsdk-boot">
+        ${host.game?.art ? `<img src="${esc(host.game.art)}" alt="">` : ''}
+        <p>${esc(state.status)}</p>
+      </section>`;
+      return;
+    }
+    if (s === 'error') {
+      overlay.innerHTML = `<section class="rsdk-panel">
+        <p class="kicker">${esc(title())}</p>
+        <h2>No se pudo arrancar</h2>
+        <p class="text">${esc(state.error)}</p>
+        <button class="item is-focused" data-exit>Volver</button>
+      </section>`;
+      return;
+    }
+    let html = '';
+    const base = s === 'confirm' ? state.confirm.under : s;
+    if (base === 'pause') {
+      html += `<section class="rsdk-panel">
+        <p class="kicker">${esc(title())}</p>
+        <h2>Pausa</h2>
+        ${state.pause.items.map((item, i) => `<button class="item${i === state.pause.focus && s !== 'confirm' ? ' is-focused' : ''}" data-item="${i}">${esc(item.label)}${item.hint ? `<small>${esc(item.hint)}</small>` : ''}</button>`).join('')}
+        ${hints([['A', 'elegir'], ['B', 'continuar']])}
+      </section>`;
+    }
+    if (s === 'confirm') {
+      const c = state.confirm;
+      html += `<div class="rsdk-confirm"><section class="rsdk-panel">
+        <h2>${esc(c.title)}</h2>
+        ${c.text ? `<p class="text">${esc(c.text)}</p>` : ''}
+        <div class="row">
+          <button class="item${c.focus === 0 ? ' is-focused' : ''}" data-confirm="0">${esc(c.no)}</button>
+          <button class="item is-danger${c.focus === 1 ? ' is-focused' : ''}" data-confirm="1">${esc(c.yes)}</button>
+        </div>
+      </section></div>`;
+    }
+    overlay.innerHTML = html;
+  };
+
+  // ---- transitions --------------------------------------------------------------
+
+  const enterGame = () => {
+    state.screen = 'game';
+    render();
+    host.input.suspend();
+    canvasFocus();
+  };
+
+  const gameScreens = () => {
+    try {
+      return findGameScreens(play.devMenu.getStageList());
+    } catch {
+      return [];
+    }
+  };
+
+  const openPause = () => {
+    play?.pause(OWNER);
+    state.pause = {
+      focus: 0,
+      items: [
+        { label: 'Continuar', run: closePause },
+        ...gameScreens().map((screen) => ({
+          label: screen.label,
+          hint: 'pantalla del propio juego',
+          run: () => {
+            closePause();
+            play.devMenu.loadStage(screen.list, screen.scene);
+          },
+        })),
+        { label: 'Volver al lanzador', run: askExit },
+      ],
+    };
+    state.screen = 'pause';
+    host.input.resume();
+    render();
+  };
+
+  const closePause = () => {
+    enterGame();
+    play?.resume(OWNER);
+  };
+
+  // A confirm sits on top of the screen it was asked from and goes back to it.
+  const ask = (options) => {
+    state.confirm = { focus: 0, under: state.screen, ...options };
+    state.screen = 'confirm';
+    render();
+  };
+  const answer = (yes) => {
+    const c = state.confirm;
+    state.screen = c.under;
+    state.confirm = null;
+    render();
+    (yes ? c.onYes : c.onNo)?.();
+  };
+
+  const exit = async () => {
+    if (leaving) return;
+    leaving = true;
+    try {
+      await play?.destroy();
+    } catch (error) {
+      console.warn(`[${ENGINE} app] destroy failed`, error);
+    }
+    play = null;
+    host.exit();
+  };
+
+  const askExit = () =>
+    ask({ title: '¿Volver al lanzador?', text: 'La partida se guarda donde la guarde el juego.', yes: 'Salir', no: 'Seguir', onYes: exit });
+
+  // ---- input ----------------------------------------------------------------------
+
+  const onPause = (action) => {
+    const p = state.pause;
+    if (action === 'up') p.focus = (p.focus + p.items.length - 1) % p.items.length;
+    else if (action === 'down') p.focus = (p.focus + 1) % p.items.length;
+    else if (action === 'accept') return p.items[p.focus].run();
+    else if (action === 'back' || action === 'menu') return closePause();
+    else return;
+    render();
+  };
+
+  const onConfirm = (action) => {
+    const c = state.confirm;
+    if (action === 'left' || action === 'up') c.focus = 0;
+    else if (action === 'right' || action === 'down') c.focus = 1;
+    else if (action === 'accept') return answer(c.focus === 1);
+    else if (action === 'back') return answer(false);
+    else return;
+    render();
+  };
+
+  const off = host.input.on((action) => {
+    if (leaving) return;
+    const s = state.screen;
+    if (s === 'game') {
+      if (action === 'menu') openPause();
+    } else if (s === 'pause') onPause(action);
+    else if (s === 'confirm') onConfirm(action);
+    else if (s === 'error' && (action === 'accept' || action === 'back')) exit();
+    else if (s === 'boot' && action === 'back') exit();
+  });
+
+  // Pointer: hover focuses, click activates — the same paths as the pad. Hover is read
+  // from real movement only: every render replaces the buttons, and the browser fires
+  // a fresh pointerover for whatever lands under a resting cursor.
+  let lastPointer = '';
+  const onPointer = (event) => {
+    if (event.type === 'pointermove') {
+      const at = `${event.clientX},${event.clientY}`;
+      if (at === lastPointer) return;
+      lastPointer = at;
+    }
+    const el = event.target.closest('[data-item],[data-confirm],[data-exit]');
+    if (!el || leaving) return;
+    if (event.type === 'pointermove') {
+      if (el.dataset.item != null && state.screen === 'pause' && state.pause.focus !== +el.dataset.item) {
+        state.pause.focus = +el.dataset.item;
+        render();
+      }
+      return;
+    }
+    if (el.dataset.item != null) state.pause.items[+el.dataset.item].run();
+    else if (el.dataset.confirm != null) answer(el.dataset.confirm === '1');
+    else if (el.dataset.exit != null) exit();
+  };
+  overlay.addEventListener('click', onPointer);
+  overlay.addEventListener('pointermove', onPointer);
+
+  const handle = {
+    async unmount() {
+      destroyed = true;
+      leaving = true;
+      off();
+      overlay.removeEventListener('click', onPointer);
+      overlay.removeEventListener('pointermove', onPointer);
+      try {
+        await play?.destroy();
+      } catch {
+        /* already gone */
+      }
+      play = null;
+      root.remove();
+    },
+  };
+
+  // ---- boot -----------------------------------------------------------------------
+
+  render();
+  host.input.resume();
+  try {
+    play = await new Rsdkv3SDK()
+      .mount(stage)
+      .assets(host.assets)
+      .storage(host.storage)
+      .on('error', ({ detail }) => console.error(`[${ENGINE} app]`, detail))
+      .on('exit', () => exit())
+      .start();
+    if (destroyed) {
+      // Unmounted while booting: nothing to show any more.
+      await play.destroy().catch(() => {});
+      play = null;
+      return handle;
+    }
+    enterGame();
+  } catch (error) {
+    console.error(`[${ENGINE} app]`, error);
+    state.error = error?.message ?? String(error);
+    state.screen = 'error';
+    render();
+  }
+
+  return handle;
+}