@wasm-gaming/rsdkv3-wasm 0.1.2 → 0.1.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wasm-gaming/rsdkv3-wasm",
-  "version": "0.1.2",
-  "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.1.5",
+  "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"
@@ -21,30 +21,21 @@
     "./options": {
       "types": "./dist/rsdkv3/rsdkv3.options.d.ts",
       "import": "./dist/rsdkv3/rsdkv3.options.js"
-    },
-    "./manifest": "./dist/manifest.json"
+    }
   },
   "files": [
     "dist/rsdkv3/",
-    "dist/manifest.json",
-    "src/rsdkv3.manifest.ts",
     "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/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 },
   },
 };