@wasm-gaming/rsdkv3-wasm 0.1.4 → 0.2.0

package/dist/rsdkv3/rsdkv3.sdk.d.ts

@@ -1,7 +1,30 @@
-import type { EngineConfig, EngineInstance, AssetData } from '@wasm-gaming/engine-specs';
-import { manifest } from './rsdkv3.manifest.js';
-export { manifest };
-/** RSDKv3-specific bridge for the launcher's debug/stage-select UI. */
+/**
+ * The engine package's entry point: an `EngineSDK` for RSDKv3 (Sonic CD).
+ *
+ * ```js
+ * import Rsdkv3SDK from '@wasm-gaming/rsdkv3-wasm';
+ *
+ * const play = await new Rsdkv3SDK({ config: { soundtrack: 1 } })
+ *   .assets({ data: () => readDataRsdk() })    // bytes, or a thunk
+ *   .storage({ namespace: 'sonic-cd' })        // → OPFS rsdkv3/sonic-cd/
+ *   .mount(document.querySelector('#stage'))
+ *   .start();
+ *
+ * play.pause('menu'); play.resume('menu');
+ * play.devMenu.getStageList();               // the host draws its own stage select
+ * await play.destroy();                      // save flushed, loop stopped, audio closed
+ * ```
+ *
+ * One game-agnostic `rsdkv3.wasm`: `Data.rsdk` is written into the filesystem at
+ * runtime, never baked in. The working dir `/data/rsdkv3/<namespace>` is 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, on page hide and on destroy).
+ */
+import { EnginePlayBase, EngineSDKBase, EventEmitter, type EngineInit, type EngineSDKConstructor, type EventsOf, type PayloadKind } from '@wasm-gaming/engine-specs';
+import { type Rsdkv3Config, type Rsdkv3Options, type Rsdkv3Payloads } from './rsdkv3.options.js';
+export type { Rsdkv3Asset, Rsdkv3Assets, Rsdkv3Config, Rsdkv3Events, Rsdkv3Options, Rsdkv3Payloads, Rsdkv3Storage, } from './rsdkv3.options.js';
+export { RSDKV3_SPEC, RSDKV3_VIDEO } from './rsdkv3.options.js';
+/** The launcher's handle on RSDKv3's stage list, for drawing its own dev menu. */
 export interface RsdkDevMenuBridge {
     getStageList(): Array<{
         name: string;
@@ -9,37 +32,55 @@ export interface RsdkDevMenuBridge {
             name: string;
         }>;
     }>;
-    loadStage(categoryIdx: number, stageIdx: number): void;
-    setPaused(paused: boolean): void;
+    loadStage(category: number, stage: number): void;
 }
-export type Rsdkv3Instance = EngineInstance & {
-    devMenu: RsdkDevMenuBridge;
-    /** Always false in the current rsdkv3 build (in-memory FS backend). */
-    persistent: boolean;
-    /** Relative storage namespace used under /data (e.g. "sonic-cd"). */
-    storageNamespace: string;
-    /** Remove 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.
+ * Where an engine keeps one namespace: `<engineId>/<namespace>`, relative to the OPFS
+ * root. Identical in every wasm-gaming engine, written to move verbatim into
+ * engine-specs: segments cleaned, `.` and `..` dropped, anything outside
+ * `[A-Za-z0-9._-]` → `_`, nothing usable → `default`; a leading `<engineId>/` is
+ * stripped once.
  */
-export type Rsdkv3LoadConfig = EngineConfig & {
-    dataProvider?: () => Promise<AssetData> | AssetData;
-    settingsProvider?: () => Promise<AssetData> | AssetData;
-    /** Per-game storage folder under /data used for the in-memory filesystem. */
-    storageNamespace?: string;
+export declare function storagePath(engineId: string, namespace: unknown): {
+    namespace: string;
+    path: string;
+    prefixed: boolean;
 };
-/** Boot the RSDKv3 engine. */
-export declare function load(config: Rsdkv3LoadConfig): Promise<Rsdkv3Instance>;
-declare const _default: {
-    manifest: import("@wasm-gaming/engine-specs").EngineManifest;
-    load: typeof load;
-};
-export default _default;
+/** Serialise the engine config into RSDKv3's settings.ini. */
+export declare function buildSettingsIni(config: Rsdkv3Config): string;
+/** The live engine: one booted RSDKv3 and its session. */
+export declare class Rsdkv3Play extends EnginePlayBase<Rsdkv3Payloads> {
+    #private;
+    constructor(init?: EngineInit<Rsdkv3Payloads>, events?: EventEmitter<EventsOf<Rsdkv3Payloads>>);
+    get namespace(): string;
+    /** Where this session's files live, relative to the OPFS root: `rsdkv3/<namespace>`. */
+    get storagePath(): string;
+    get pausedBy(): string | null;
+    /** RSDKv3's stage list, for a host that draws its own stage select. */
+    get devMenu(): RsdkDevMenuBridge;
+    /**
+     * Freeze the game and its sound. The first caller owns the pause; only that
+     * owner's {@link resume} lifts it. The save is flushed.
+     */
+    pause(owner?: string): void;
+    resume(owner?: string): void;
+    /** Copy `SData.bin` to OPFS `rsdkv3/<namespace>/` if it changed; emits `saves`. */
+    flushSaves(): Promise<void>;
+    protected mounted(target: HTMLElement): void;
+    protected open(_options: Rsdkv3Options): Promise<void>;
+    protected patched(_kind: PayloadKind, _patch: object): void;
+    protected close(): Promise<void>;
+}
+/** The factory a host constructs: static identity, the configuration chain, `start()`. */
+export declare class Rsdkv3SDK extends EngineSDKBase<Rsdkv3Payloads> {
+    static readonly id = "rsdkv3";
+    /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
+    static readonly version = "0.2.0";
+    static readonly name = "Retro Software Development Kit v3";
+    static readonly description = "RSDKv3 (Sonic CD 2011 decompilation) compiled to WebAssembly. Ships none of the game: the player provides Data.rsdk, and it never leaves their browser.";
+    protected createPlay(init: EngineInit<Rsdkv3Payloads>, events: EventEmitter<EventsOf<Rsdkv3Payloads>>): Rsdkv3Play;
+}
+/** CI's conformance line: if this class stops satisfying the contract, `make test` fails. */
+export declare const RSDKV3_ENGINE: EngineSDKConstructor<Rsdkv3Payloads>;
+export default Rsdkv3SDK;
 //# sourceMappingURL=rsdkv3.sdk.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rsdkv3.sdk.d.ts","sourceRoot":"","sources":["../../src/rsdkv3.sdk.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAuB,MAAM,2BAA2B,CAAC;AAC9G,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD,OAAO,EAAE,QAAQ,EAAE,CAAC;AA0FpB,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,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,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,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,8BAA8B;AAC9B,wBAAsB,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2H5E;;;;;AAED,wBAAkC"}
+{"version":3,"file":"rsdkv3.sdk.d.ts","sourceRoot":"","sources":["../../src/rsdkv3.sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EACb,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA0BhE,kFAAkF;AAClF,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,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,GACjB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAaxD;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA0B7D;AAyCD,0DAA0D;AAC1D,qBAAa,UAAW,SAAQ,cAAc,CAAC,cAAc,CAAC;;gBAqBhD,IAAI,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAI9F,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wFAAwF;IACxF,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,uEAAuE;IACvE,IAAI,OAAO,IAAI,iBAAiB,CAc/B;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,SAAS,GAAG,IAAI;IAU3B,MAAM,CAAC,KAAK,SAAS,GAAG,IAAI;IAS5B,mFAAmF;IACnF,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;cASR,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;cAwB5B,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;cAQlD,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;cAI3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA+IhD;AAED,0FAA0F;AAC1F,qBAAa,SAAU,SAAQ,aAAa,CAAC,cAAc,CAAC;IAC1D,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAa;IAC/B,yEAAyE;IACzE,MAAM,CAAC,QAAQ,CAAC,OAAO,WAAW;IAClC,MAAM,CAAC,QAAQ,CAAC,IAAI,uCAAuC;IAC3D,MAAM,CAAC,QAAQ,CAAC,WAAW,6JACiI;cAEzI,UAAU,CAC3B,IAAI,EAAE,UAAU,CAAC,cAAc,CAAC,EAChC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,GAC7C,UAAU;CAGd;AAED,6FAA6F;AAC7F,eAAO,MAAM,aAAa,EAAE,oBAAoB,CAAC,cAAc,CAAa,CAAC;AAE7E,eAAe,SAAS,CAAC"}