@wasm-gaming/rsdkv3-wasm 0.1.4 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wasm-gaming/rsdkv3-wasm",
-  "version": "0.1.4",
-  "description": "RSDKv3 (Retro Software Development Kit v3) compiled to WebAssembly, with a JS SDK conforming to the wasm-gaming engine contract. Runs Sonic CD by loading Data.rsdk at runtime.",
+  "version": "0.2.0",
+  "description": "RSDKv3 (Sonic CD decompilation) compiled to WebAssembly, with a self-contained JS SDK implementing the wasm-gaming engine contract. Data.rsdk is loaded at runtime.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wasm-gaming/rsdkv3-wasm.git"
@@ -22,29 +22,24 @@
       "types": "./dist/rsdkv3/rsdkv3.options.d.ts",
       "import": "./dist/rsdkv3/rsdkv3.options.js"
     },
-    "./manifest": "./dist/manifest.json"
+    "./app": {
+      "import": "./dist/rsdkv3/app/app.js"
+    }
   },
   "files": [
     "dist/rsdkv3/",
-    "dist/manifest.json",
-    "src/rsdkv3.manifest.ts",
+    "src/app/",
     "src/rsdkv3.options.ts",
     "src/rsdkv3.sdk.ts",
-    "src/wasm-specs.ts",
     "README.md"
   ],
   "comment:scripts": "Build logic lives in the Makefile, not here (make build / build-sdk / build-wasm / preview).",
   "scripts": {},
-  "peerDependencies": {
-    "@wasm-gaming/engine-specs": "*"
-  },
-  "peerDependenciesMeta": {
-    "@wasm-gaming/engine-specs": {
-      "optional": true
-    }
+  "comment:dependencies": "engine-specs is the one wasm-gaming package an engine depends on. Its runtime is also copied into dist/rsdkv3/ and imported relatively, so the built SDK loads without a bundler or an import map; the dependency carries the types.",
+  "dependencies": {
+    "@wasm-gaming/engine-specs": "^0.3.2"
   },
   "devDependencies": {
-    "@wasm-gaming/engine-specs": "^0.1.0",
     "typescript": "^5.5.0"
   },
   "engineContract": "https://github.com/wasm-gaming/engine-specs",

package/src/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/src/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;
+}

package/src/rsdkv3.options.ts

@@ -1,68 +1,116 @@
-// Engine-specific options for RSDKv3.
-//
-// This is the authoritative description of what `EngineConfig.options` accepts
-// for this engine. It provides both:
-//   - `Rsdkv3Options`          — compile-time type for TS hosts
-//   - `RSDKV3_OPTIONS_SCHEMA`  — JSON Schema mirrored into manifest.json
-//   - `DEFAULT_RSDKV3_OPTIONS` — defaults used when no settings.ini is supplied
-//
-// At runtime these options are serialized into Sonic CD's `settings.ini` format
-// when the host does not pass an explicit `settings` asset.
+/**
+ * What RSDKv3 accepts, as types and as data.
+ *
+ * The four payloads of the wasm-gaming engine contract, closed for this engine, and
+ * {@link RSDKV3_SPEC} — the same thing as data the contract's base class reads:
+ * every default lives there and nowhere else.
+ */
+import type { EnginePayloads, EngineSpec } from '@wasm-gaming/engine-specs';
 
-import type { JSONSchema } from '@wasm-gaming/engine-specs';
+/** Bytes, or a thunk that produces them only when the engine actually needs them. */
+export type Rsdkv3Asset =
+  | Uint8Array
+  | ArrayBuffer
+  | null
+  | (() => Uint8Array | ArrayBuffer | null | Promise<Uint8Array | ArrayBuffer | null>);
 
-export interface Rsdkv3Options {
-  /**
-   * RSDKv3's native in-canvas Dev Menu. Kept off by default: the launcher owns
-   * the debug/stage-select UI (via `instance.devMenu`), and leaving this on has
-   * historically produced a native menu-like screen at boot.
-   */
+/** The engine, written into the generated `settings.ini`. Fixed for the life of the wasm. */
+export interface Rsdkv3Config {
+  /** RSDKv3's native in-canvas Dev Menu. A host draws its own from `play.devMenu`. */
   devMenu?: boolean;
-  /** RSDKv3 EngineDebugMode — enables the web devmenu embind bridge hooks. */
+  /** RSDKv3 `EngineDebugMode`. */
   engineDebugMode?: boolean;
-  /** VSync setting in the generated settings.ini. */
   vsync?: boolean;
-  /** 0 = JP/EU soundtrack, 1 = US soundtrack. */
-  soundtrack?: number;
-  /** 0 = English. Matches RSDKv3 language numeric value. */
+  /** Sonic CD soundtrack: 0 = JP/EU, 1 = US. */
+  soundtrack?: 0 | 1;
+  /** RSDKv3 language index (0 = English). */
   language?: number;
-  /** Toggle touch controls in the generated settings.ini. */
   disableTouchControls?: boolean;
+  /** Emscripten glue URL. Defaults to `./rsdkv3.js` next to the SDK. */
+  jsUrl?: string;
+  /** WASM URL. Defaults to `./rsdkv3.wasm` next to the SDK. */
+  wasmUrl?: string;
 }
 
-export const DEFAULT_RSDKV3_OPTIONS: Required<Rsdkv3Options> = {
-  devMenu: false,
-  engineDebugMode: false,
-  vsync: false,
-  soundtrack: 0,
-  language: 0,
-  disableTouchControls: true,
-};
+/** The session. Nothing per-session yet. */
+export type Rsdkv3Options = Record<string, never>;
+
+export interface Rsdkv3Assets {
+  /** The game's `Data.rsdk` (Sonic CD). Required to start. */
+  data?: Rsdkv3Asset;
+  /** A ready-made `settings.ini`; omitted, one is generated from `config`. */
+  settings?: Rsdkv3Asset;
+}
 
-export const RSDKV3_OPTIONS_SCHEMA: JSONSchema = {
-  type: 'object',
-  additionalProperties: false,
-  properties: {
+/** Where this engine's files live, and whether they outlive the page. */
+export interface Rsdkv3Storage {
+  /**
+   * Per-game folder, relative to the engine's own: files land in `rsdkv3/<namespace>/`
+   * (WASMFS `/data/rsdkv3/<namespace>`, and the OPFS folder the save is mirrored to).
+   * Segments are cleaned (`.`/`..` dropped, odd characters → `_`); a leading
+   * `rsdkv3/` is stripped once. `play.storagePath` gives the result.
+   *
+   * @defaultValue `"default"`
+   */
+  namespace?: string;
+  /** `null` keeps nothing; otherwise `SData.bin` is mirrored to OPFS. */
+  persist?: 'opfs' | null;
+}
+
+export interface Rsdkv3Events {
+  /** `SData.bin` changed and was written to `rsdkv3/<namespace>/`. */
+  saves: { files: string[] };
+}
+
+export interface Rsdkv3Payloads extends EnginePayloads {
+  config: Rsdkv3Config;
+  options: Rsdkv3Options;
+  assets: Rsdkv3Assets;
+  storage: Rsdkv3Storage;
+  events: Rsdkv3Events;
+}
+
+/** The native picture, which the SDK scales to fit its mount. */
+export const RSDKV3_VIDEO = { width: 426, height: 240, aspect: '16:9' } as const;
+
+export const RSDKV3_SPEC: EngineSpec<Rsdkv3Payloads> = {
+  config: {
     devMenu: {
-      type: 'boolean',
       default: false,
-      description:
-        "RSDKv3's native in-canvas Dev Menu. The launcher provides its own overlay via instance.devMenu, so keep this off.",
+      live: false,
+      description: "RSDKv3's native Dev Menu; keep it off and draw your own from play.devMenu.",
     },
-    engineDebugMode: {
-      type: 'boolean',
-      default: false,
-      description: 'Enables the web devmenu embind bridge (stage list / warp / pause).',
+    engineDebugMode: { default: false, live: false, description: 'RSDKv3 EngineDebugMode.' },
+    vsync: { default: false, live: false, description: 'VSync in the generated settings.ini.' },
+    soundtrack: { default: 0, enum: [0, 1], live: false, description: 'Sonic CD soundtrack: 0 = JP/EU, 1 = US.' },
+    language: { default: 0, live: false, description: 'RSDKv3 language index (0 = English).' },
+    disableTouchControls: { default: true, live: false, description: 'Hide the touch controls.' },
+    jsUrl: { live: false, description: 'Emscripten glue URL. Defaults to ./rsdkv3.js.' },
+    wasmUrl: { live: false, description: 'WASM URL. Defaults to ./rsdkv3.wasm.' },
+  },
+  options: {},
+  assets: {
+    data: {
+      allowedTypes: ['.rsdk'],
+      live: false,
+      description: 'The RSDKv3 game data pack (Sonic CD). Required to start.',
+    },
+    settings: {
+      allowedTypes: ['.ini'],
+      live: false,
+      description: 'A ready-made settings.ini. Omitted, one is generated from config.',
+    },
+  },
+  storage: {
+    namespace: {
+      default: 'default',
+      live: false,
+      description: "Folder for this game's save, inside the engine's own rsdkv3/ folder (OPFS rsdkv3/<namespace>/).",
     },
-    vsync: { type: 'boolean', default: false },
-    soundtrack: {
-      type: 'integer',
-      minimum: 0,
-      maximum: 1,
-      default: 0,
-      description: 'Sonic CD soundtrack selector: 0=JP/EU, 1=US.',
+    persist: {
+      enum: ['opfs', null],
+      live: false,
+      description: 'null keeps nothing; otherwise SData.bin is mirrored to OPFS.',
     },
-    language: { type: 'integer', minimum: 0, default: 0 },
-    disableTouchControls: { type: 'boolean', default: true },
   },
 };