@wasm-gaming/rsdkv4-wasm 0.1.2

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

@@ -0,0 +1,4 @@
+import type { EngineManifest } from '@wasm-gaming/engine-specs';
+export declare const manifest: EngineManifest;
+export default manifest;
+//# sourceMappingURL=rsdkv4.manifest.d.ts.map

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

@@ -0,0 +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"}

package/dist/rsdkv4/rsdkv4.manifest.js

@@ -0,0 +1,39 @@
+// The rsdkv4 EngineManifest — typed against the contract, so a drift from
+// @wasm-gaming/engine-specs is a compile error here. `npm run build:manifest`
+// serializes this to dist/manifest.json (the artifact CI attaches to a Release).
+import { RSDKV4_OPTIONS_SCHEMA } from './rsdkv4.options.js';
+export const manifest = {
+    id: 'rsdkv4',
+    version: '0.1.0',
+    name: 'Retro Software Development Kit v4',
+    artifacts: {
+        // Relative to the manifest (dist/manifest.json); the engine files live in
+        // the dist/rsdkv4/ subfolder.
+        wasm: 'rsdkv4/rsdkv4.wasm',
+        js: 'rsdkv4/rsdkv4.js',
+    },
+    assets: [
+        {
+            key: 'data',
+            // Lives under the OPFS-backed (persistent) working dir; the engine reads it
+            // via CWD (booted with the UsingCWD arg).
+            mountPath: '/data/Data.rsdk',
+            required: true,
+            accept: ['.rsdk'],
+            description: 'RSDKv4 game data pack. Differs per game (Sonic 1 vs Sonic 2); selects the game.',
+        },
+        {
+            key: 'settings',
+            mountPath: '/data/settings.ini',
+            required: false,
+            accept: ['.ini'],
+            description: 'Engine settings. Omitted → the SDK generates one from config.options.',
+        },
+    ],
+    input: 'rsdkv4',
+    video: { baseWidth: 424, baseHeight: 240, aspect: '16:9' },
+    options: RSDKV4_OPTIONS_SCHEMA,
+    capabilities: { saveStates: false, sram: false, coreSelectable: false },
+};
+export default manifest;
+//# sourceMappingURL=rsdkv4.manifest.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,22 @@
+import type { JSONSchema } from '@wasm-gaming/engine-specs';
+export interface Rsdkv4Options {
+    /**
+     * RSDKv4'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.
+     */
+    devMenu?: boolean;
+    /** RSDKv4 EngineDebugMode — enables the web devmenu embind bridge hooks. */
+    engineDebugMode?: boolean;
+    /** VSync the engine's SDL window. */
+    vsync?: boolean;
+    /** Boot directly into a stage: 0-based stage-list category. */
+    startingCategory?: number;
+    /** Boot directly into a stage: 0-based scene within the category. */
+    startingScene?: number;
+    /** Starting player/character index. */
+    startingPlayer?: number;
+}
+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

@@ -0,0 +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"}

package/dist/rsdkv4/rsdkv4.options.js

@@ -0,0 +1,41 @@
+// Engine-specific options for RSDKv4.
+//
+// This is the authoritative description of what `EngineConfig.options` accepts
+// for this engine. It provides both:
+//   - `Rsdkv4Options`         — the compile-time type (for TS hosts/launchers)
+//   - `RSDKV4_OPTIONS_SCHEMA` — the JSON Schema mirrored into manifest.json's
+//                               `options` (for runtime host UI + validation)
+//   - `DEFAULT_RSDKV4_OPTIONS` — defaults the SDK falls back to.
+//
+// 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.
+export const DEFAULT_RSDKV4_OPTIONS = {
+    devMenu: false,
+    engineDebugMode: true,
+    vsync: true,
+    startingCategory: 0,
+    startingScene: 0,
+    startingPlayer: 0,
+};
+export const RSDKV4_OPTIONS_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        devMenu: {
+            type: 'boolean',
+            default: false,
+            description: "RSDKv4's native in-canvas Dev Menu. The launcher provides its own overlay via instance.devMenu, so keep this off.",
+        },
+        engineDebugMode: {
+            type: 'boolean',
+            default: true,
+            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 },
+    },
+};
+//# sourceMappingURL=rsdkv4.options.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,48 @@
+import type { EngineConfig, EngineInstance, AssetData } from '@wasm-gaming/engine-specs';
+import { manifest } from './rsdkv4.manifest.js';
+export { manifest };
+/** RSDKv4-specific bridge for the launcher's debug/stage-select UI. */
+export interface RsdkDevMenuBridge {
+    getStageList(): Array<{
+        name: string;
+        stages: Array<{
+            name: string;
+        }>;
+    }>;
+    loadStage(categoryIdx: number, stageIdx: number): void;
+    setPaused(paused: boolean): void;
+}
+export type Rsdkv4Instance = EngineInstance & {
+    devMenu: RsdkDevMenuBridge;
+    /** 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"). */
+    storageNamespace: string;
+    /** Remove persisted game files for this namespace only. */
+    purgeStorage(): {
+        data: boolean;
+        settings: boolean;
+    };
+};
+/**
+ * Extra (engine-specific) config on top of the contract's EngineConfig: lazy asset
+ * providers, invoked only on a cache miss — e.g. to skip a large Data.rsdk fetch
+ * when it's already persisted in OPFS.
+ */
+export type Rsdkv4LoadConfig = EngineConfig & {
+    dataProvider?: () => Promise<AssetData> | AssetData;
+    settingsProvider?: () => Promise<AssetData> | AssetData;
+    /**
+     * Per-game storage folder under /data used for OPFS/WASMFS files.
+     * Examples: "sonic1", "sonic2", "my-pack/v1".
+     */
+    storageNamespace?: string;
+};
+/** Boot the RSDKv4 engine. */
+export declare function load(config: Rsdkv4LoadConfig): Promise<Rsdkv4Instance>;
+declare const _default: {
+    manifest: import("@wasm-gaming/engine-specs").EngineManifest;
+    load: typeof load;
+};
+export default _default;
+//# sourceMappingURL=rsdkv4.sdk.d.ts.map

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

@@ -0,0 +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"}

package/dist/rsdkv4/rsdkv4.sdk.js

@@ -0,0 +1,257 @@
+// @wasm-gaming/rsdkv4-wasm — SDK entry point.
+//
+// Conforms to the wasm-gaming engine contract (github.com/wasm-gaming/engine-specs):
+// exports `manifest` (declarative) and `load(config)` (imperative).
+//
+// One game-agnostic rsdkv4.wasm runs both Sonic 1 and Sonic 2 — the difference is
+// only which Data.rsdk the host hands us in `config.assets.data`, written into the
+// filesystem at runtime (not baked with --preload-file).
+//
+// Filesystem: built with -sWASMFS (the modern Emscripten filesystem, not MEMFS).
+// The game working dir `/data` is mounted on **OPFS** for persistence when the
+// page is cross-origin isolated; otherwise it falls back to the WASMFS in-memory
+// backend (transient, but the engine still boots). The backend is selectable via
+// `config.persist` (see mountWorkingDir), and when the dir is OPFS-backed the SDK
+// reuses an already-persisted Data.rsdk/settings.ini instead of re-fetching.
+import { manifest } from './rsdkv4.manifest.js';
+import { DEFAULT_RSDKV4_OPTIONS } from './rsdkv4.options.js';
+export { manifest };
+const WORK_ROOT = '/data';
+const DEFAULT_STORAGE_NAMESPACE = 'default';
+/** Serialize engine options into RSDKv4's settings.ini format. */
+function buildSettingsIni(options = {}) {
+    const o = { ...DEFAULT_RSDKV4_OPTIONS, ...options };
+    return [
+        '[Dev]',
+        `EngineDebugMode=${o.engineDebugMode ? 'true' : 'false'}`,
+        `DevMenu=${o.devMenu ? 'true' : 'false'}`,
+        `StartingCategory=${o.startingCategory | 0}`,
+        `StartingScene=${o.startingScene | 0}`,
+        `StartingPlayer=${o.startingPlayer | 0}`,
+        '',
+        '[Window]',
+        `VSync=${o.vsync ? 'true' : 'false'}`,
+        '',
+    ].join('\n');
+}
+function toUint8(x) {
+    if (x == null)
+        return null;
+    if (typeof x === 'string')
+        return new TextEncoder().encode(x);
+    if (x instanceof Uint8Array)
+        return x;
+    if (x instanceof ArrayBuffer)
+        return new Uint8Array(x);
+    if (ArrayBuffer.isView(x))
+        return new Uint8Array(x.buffer, x.byteOffset, x.byteLength);
+    throw new TypeError('asset must be Uint8Array | ArrayBuffer | string');
+}
+/** Normalize a user-provided storage namespace into a safe relative path. */
+function normalizeStorageNamespace(namespace) {
+    if (typeof namespace !== 'string' || !namespace.trim())
+        return DEFAULT_STORAGE_NAMESPACE;
+    const cleaned = namespace
+        .split('/')
+        .map((segment) => segment.trim())
+        .filter(Boolean)
+        .map((segment) => segment.replace(/[^A-Za-z0-9._-]/g, '_'))
+        .filter(Boolean)
+        .join('/');
+    return cleaned || DEFAULT_STORAGE_NAMESPACE;
+}
+/** Best-effort mkdir -p for the Emscripten FS layer. */
+function ensureDir(Module, path) {
+    const parts = path.split('/').filter(Boolean);
+    let current = '';
+    for (const part of parts) {
+        current += `/${part}`;
+        try {
+            Module.FS.mkdir(current);
+        }
+        catch {
+            /* already exists */
+        }
+    }
+}
+/**
+ * Mount the game working dir, honoring `persist`:
+ *   'opfs'     → force an OPFS (persistent) mount; warn + fall back if unavailable.
+ *   null       → force the in-memory WASMFS backend (the MEMFS-equivalent fallback).
+ *   undefined  → auto: OPFS when the page is cross-origin isolated, else in-memory.
+ * ('idbfs' isn't supported under WASMFS and is treated as in-memory.)
+ *
+ * OPFS sync access needs a worker/pthread + cross-origin isolation, so 'auto' only
+ * attempts it when isolated (the single-threaded build would otherwise trap).
+ * Returns whether the resulting mount is persistent.
+ */
+function mountWorkingDir(Module, persist) {
+    const isolated = typeof crossOriginIsolated !== 'undefined' && crossOriginIsolated;
+    const attemptOpfs = persist === 'opfs' || (persist === undefined && isolated);
+    if (attemptOpfs && typeof Module.ccall === 'function') {
+        try {
+            const rc = Module.ccall('web_mount_opfs', 'number', ['string'], [WORK_ROOT]);
+            if (rc === 0)
+                return { persistent: true };
+        }
+        catch {
+            /* fall through to in-memory */
+        }
+        if (persist === 'opfs') {
+            console.warn('[rsdkv4] OPFS requested but unavailable — using in-memory WASMFS');
+        }
+    }
+    ensureDir(Module, WORK_ROOT);
+    return { persistent: false };
+}
+/** True if `path` exists in the (mounted) filesystem. */
+function fileExists(Module, path) {
+    try {
+        Module.FS.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Delete a file if present; returns true when something was removed. */
+function deleteFileIfExists(Module, path) {
+    if (!fileExists(Module, path))
+        return false;
+    try {
+        Module.FS.unlink(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Boot the RSDKv4 engine. */
+export async function load(config) {
+    const { canvas, assets, onEvent } = config;
+    const options = config.options;
+    if (!canvas)
+        throw new Error('rsdkv4: config.canvas is required');
+    // Emscripten's SDL2 port locates the canvas via document.querySelector('#canvas').
+    if (canvas.id !== 'canvas')
+        canvas.id = 'canvas';
+    const emit = (e) => {
+        try {
+            onEvent?.(e);
+        }
+        catch { /* host handler must not break us */ }
+    };
+    const jsUrl = config.jsUrl ?? new URL('./rsdkv4.js', import.meta.url).href;
+    const wasmUrl = config.wasmUrl ?? new URL('./rsdkv4.wasm', import.meta.url).href;
+    // RSDKv4 keyboard bindings are the shared input script's default preset.
+    if (typeof window !== 'undefined')
+        window.__gamepadKeyMap = manifest.input;
+    const mod = await import(/* @vite-ignore */ jsUrl);
+    const createRSDKv4 = mod.default;
+    const Module = await createRSDKv4({
+        canvas,
+        noInitialRun: true, // built with -sINVOKE_RUN=0; we mount data before main()
+        locateFile: (path) => (path.endsWith('.wasm') ? wasmUrl : path),
+        print: (...a) => console.log('[rsdkv4]', ...a),
+        printErr: (...a) => console.error('[rsdkv4]', ...a),
+        onAbort: (reason) => emit({ type: 'error', error: new Error(`rsdkv4 aborted: ${reason}`) }),
+    });
+    // Mount the working dir first, so we can see what's already persisted (OPFS)
+    // before deciding whether to pull assets.
+    const { persistent } = mountWorkingDir(Module, config.persist);
+    const storageNamespace = normalizeStorageNamespace(config.storageNamespace);
+    const workDir = `${WORK_ROOT}/${storageNamespace}`;
+    ensureDir(Module, workDir);
+    const dataPath = `${workDir}/Data.rsdk`;
+    const settingsPath = `${workDir}/settings.ini`;
+    // Data.rsdk — precedence: explicit asset > already persisted (skip fetch) > lazy provider.
+    let dataBytes = toUint8(assets?.data);
+    if (!dataBytes) {
+        if (fileExists(Module, dataPath)) {
+            console.log(`[rsdkv4] Data.rsdk already in persistent storage (${storageNamespace}) — skipping fetch`);
+        }
+        else if (config.dataProvider) {
+            dataBytes = toUint8(await config.dataProvider());
+        }
+    }
+    if (dataBytes) {
+        Module.FS.writeFile(dataPath, dataBytes);
+    }
+    else if (!fileExists(Module, dataPath)) {
+        throw new Error('rsdkv4: no Data.rsdk — provide assets.data, a dataProvider, or a persisted copy (OPFS)');
+    }
+    // settings.ini — explicit asset > persisted > lazy provider > generated from options.
+    let settingsBytes = toUint8(assets?.settings);
+    if (!settingsBytes && !fileExists(Module, settingsPath) && config.settingsProvider) {
+        settingsBytes = toUint8(await config.settingsProvider());
+    }
+    if (settingsBytes) {
+        Module.FS.writeFile(settingsPath, settingsBytes);
+    }
+    else if (!fileExists(Module, settingsPath)) {
+        Module.FS.writeFile(settingsPath, new TextEncoder().encode(buildSettingsIni(options)));
+    }
+    // else: keep the persisted settings.ini
+    Module.FS.chdir(workDir);
+    const setPaused = (paused) => {
+        if (typeof Module.web_devmenu_set_paused === 'function')
+            Module.web_devmenu_set_paused(paused);
+    };
+    const devMenu = {
+        getStageList() {
+            if (typeof Module.web_devmenu_get_stage_list !== 'function')
+                return [];
+            try {
+                return JSON.parse(Module.web_devmenu_get_stage_list());
+            }
+            catch (e) {
+                console.error('[rsdkv4] getStageList failed', e);
+                return [];
+            }
+        },
+        loadStage(categoryIdx, stageIdx) {
+            if (typeof Module.web_devmenu_load_stage === 'function') {
+                Module.web_devmenu_load_stage(categoryIdx | 0, stageIdx | 0);
+            }
+        },
+        setPaused,
+    };
+    // Run main() from the OPFS/WASMFS working dir. simulate_infinite_loop schedules
+    // the rAF loop and returns via a benign unwind Emscripten swallows.
+    Module.callMain(['UsingCWD']);
+    emit({ type: 'ready' });
+    return {
+        start() { },
+        pause() { setPaused(true); },
+        resume() { setPaused(false); },
+        reset() {
+            throw new Error('rsdkv4: reset() is not supported — destroy() and load() again');
+        },
+        setInput(preset) {
+            if (typeof window !== 'undefined') {
+                window.__gamepadKeyMap = preset ?? manifest.input;
+            }
+        },
+        destroy() {
+            try {
+                Module.pauseMainLoop?.();
+            }
+            catch { /* noop */ }
+            try {
+                setPaused(true);
+            }
+            catch { /* noop */ }
+        },
+        devMenu,
+        persistent,
+        storageNamespace,
+        purgeStorage() {
+            return {
+                data: deleteFileIfExists(Module, dataPath),
+                settings: deleteFileIfExists(Module, settingsPath),
+            };
+        },
+    };
+}
+export default { manifest, load };
+//# sourceMappingURL=rsdkv4.sdk.js.map

package/dist/rsdkv4/rsdkv4.sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsdkv4.sdk.js","sourceRoot":"","sources":["../../src/rsdkv4.sdk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@wasm-gaming/rsdkv4-wasm",
+  "version": "0.1.2",
+  "description": "RSDKv4 (Retro Software Development Kit v4) compiled to WebAssembly, with a JS SDK conforming to the wasm-gaming engine contract. Runs Sonic 1 & Sonic 2 from a single WASM by loading Data.rsdk at runtime.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wasm-gaming/rsdkv4-wasm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wasm-gaming/rsdkv4-wasm/issues"
+  },
+  "homepage": "https://github.com/wasm-gaming/rsdkv4-wasm#readme",
+  "type": "module",
+  "main": "./dist/rsdkv4/rsdkv4.sdk.js",
+  "types": "./dist/rsdkv4/rsdkv4.sdk.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/rsdkv4/rsdkv4.sdk.d.ts",
+      "import": "./dist/rsdkv4/rsdkv4.sdk.js"
+    },
+    "./options": {
+      "types": "./dist/rsdkv4/rsdkv4.options.d.ts",
+      "import": "./dist/rsdkv4/rsdkv4.options.js"
+    },
+    "./manifest": "./dist/manifest.json"
+  },
+  "files": [
+    "dist/rsdkv4/",
+    "dist/manifest.json",
+    "src/rsdkv4.manifest.ts",
+    "src/rsdkv4.options.ts",
+    "src/rsdkv4.sdk.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
+    }
+  },
+  "devDependencies": {
+    "@wasm-gaming/engine-specs": "^0.1.0",
+    "typescript": "^5.5.0"
+  },
+  "engineContract": "https://github.com/wasm-gaming/engine-specs",
+  "license": "MIT"
+}

package/src/rsdkv4.manifest.ts

@@ -0,0 +1,44 @@
+// The rsdkv4 EngineManifest — typed against the contract, so a drift from
+// @wasm-gaming/engine-specs is a compile error here. `npm run build:manifest`
+// serializes this to dist/manifest.json (the artifact CI attaches to a Release).
+
+import type { EngineManifest } from '@wasm-gaming/engine-specs';
+import { RSDKV4_OPTIONS_SCHEMA } from './rsdkv4.options.js';
+
+export const manifest: EngineManifest = {
+  id: 'rsdkv4',
+  version: '0.1.0',
+  name: 'Retro Software Development Kit v4',
+  artifacts: {
+    // Relative to the manifest (dist/manifest.json); the engine files live in
+    // the dist/rsdkv4/ subfolder.
+    wasm: 'rsdkv4/rsdkv4.wasm',
+    js: 'rsdkv4/rsdkv4.js',
+  },
+  assets: [
+    {
+      key: 'data',
+      // Lives under the OPFS-backed (persistent) working dir; the engine reads it
+      // via CWD (booted with the UsingCWD arg).
+      mountPath: '/data/Data.rsdk',
+      required: true,
+      accept: ['.rsdk'],
+      description:
+        'RSDKv4 game data pack. Differs per game (Sonic 1 vs Sonic 2); selects the game.',
+    },
+    {
+      key: 'settings',
+      mountPath: '/data/settings.ini',
+      required: false,
+      accept: ['.ini'],
+      description:
+        'Engine settings. Omitted → the SDK generates one from config.options.',
+    },
+  ],
+  input: 'rsdkv4',
+  video: { baseWidth: 424, baseHeight: 240, aspect: '16:9' },
+  options: RSDKV4_OPTIONS_SCHEMA,
+  capabilities: { saveStates: false, sram: false, coreSelectable: false },
+};
+
+export default manifest;

package/src/rsdkv4.options.ts

@@ -0,0 +1,64 @@
+// Engine-specific options for RSDKv4.
+//
+// This is the authoritative description of what `EngineConfig.options` accepts
+// for this engine. It provides both:
+//   - `Rsdkv4Options`         — the compile-time type (for TS hosts/launchers)
+//   - `RSDKV4_OPTIONS_SCHEMA` — the JSON Schema mirrored into manifest.json's
+//                               `options` (for runtime host UI + validation)
+//   - `DEFAULT_RSDKV4_OPTIONS` — defaults the SDK falls back to.
+//
+// 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.
+
+import type { JSONSchema } from '@wasm-gaming/engine-specs';
+
+export interface Rsdkv4Options {
+  /**
+   * RSDKv4'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.
+   */
+  devMenu?: boolean;
+  /** RSDKv4 EngineDebugMode — enables the web devmenu embind bridge hooks. */
+  engineDebugMode?: boolean;
+  /** VSync the engine's SDL window. */
+  vsync?: boolean;
+  /** Boot directly into a stage: 0-based stage-list category. */
+  startingCategory?: number;
+  /** Boot directly into a stage: 0-based scene within the category. */
+  startingScene?: number;
+  /** Starting player/character index. */
+  startingPlayer?: number;
+}
+
+export const DEFAULT_RSDKV4_OPTIONS: Required<Rsdkv4Options> = {
+  devMenu: false,
+  engineDebugMode: true,
+  vsync: true,
+  startingCategory: 0,
+  startingScene: 0,
+  startingPlayer: 0,
+};
+
+export const RSDKV4_OPTIONS_SCHEMA: JSONSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    devMenu: {
+      type: 'boolean',
+      default: false,
+      description:
+        "RSDKv4's native in-canvas Dev Menu. The launcher provides its own overlay via instance.devMenu, so keep this off.",
+    },
+    engineDebugMode: {
+      type: 'boolean',
+      default: true,
+      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 },
+  },
+};