@wasm-gaming/fbneo-wasm 0.1.1 → 0.2.0

package/src/fbneo.options.ts

@@ -1,83 +1,127 @@
-import type { JSONSchema } from '@wasm-gaming/engine-specs';
+/**
+ * What FBNeo accepts, as types and as data.
+ *
+ * The four payloads of the wasm-gaming engine contract, closed for this engine, and
+ * {@link FBNEO_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';
 
+/** Bytes, or a thunk that produces them only when the engine actually needs them. */
+export type FbneoAsset =
+  | Uint8Array
+  | ArrayBuffer
+  | null
+  | (() => Uint8Array | ArrayBuffer | null | Promise<Uint8Array | ArrayBuffer | null>);
+
+/** The engine: fixed for the life of the wasm instance (`renderFilter` aside). */
+export interface FbneoConfig {
+  /** How the picture is scaled to the mount: crisp pixels or linear filtering. */
+  renderFilter?: 'pixelated' | 'smooth';
+  /** Emscripten glue URL. Defaults to `./fbneo.js` next to the SDK. */
+  jsUrl?: string;
+  /** WASM URL. Defaults to `./fbneo.wasm` next to the SDK. */
+  wasmUrl?: string;
+}
+
+/** The session: which game the ROM set is. */
 export interface FbneoOptions {
   /**
-   * Filename used when writing the ROM zip bytes to Emscripten MEMFS.
-   * FBNeo identifies a game by the zip filename (without extension), so this
-   * should match the driver's expected ROM set name (e.g. "mslug" for Metal Slug).
+   * The FBNeo driver (ROM-set short name, e.g. `mslug`). When empty it is taken from
+   * {@link FbneoOptions.romFileName}; the `romset` helper can recover it from a zip's
+   * contents when the file name is unreliable.
    */
+  driver?: string;
+  /** The ROM zip's file name (`mslug.zip`), used for the driver when `driver` is empty. */
   romFileName?: string;
+}
+
+export interface FbneoAssets {
+  /** The game's ROM set: a `.zip` (or `.7z`) named after its driver. Required to start. */
+  rom?: FbneoAsset;
+  /** A system BIOS set some games need (`neogeo.zip` for Neo Geo). */
+  bios?: FbneoAsset;
+}
+
+/** Where this engine's files live, and whether they outlive the page. */
+export interface FbneoStorage {
   /**
-   * The FBNeo driver/game name to load (e.g. "mslug", "sf2", "kof98").
-   * If omitted, the driver is inferred from `romFileName` (without extension).
+   * Per-game folder for NVRAM/EEPROM, hiscores and save states.
+   *
+   * Relative to the engine's own folder: the SDK always prefixes `fbneo/`, so the files
+   * land in OPFS `fbneo/<namespace>/` and no namespace can reach another engine's
+   * files. Segments are cleaned (`.`/`..` dropped, odd characters → `_`); anything
+   * unusable becomes `"default"`. `play.storagePath` gives the result.
+   *
+   * @defaultValue `"default"`
    */
-  driver?: string;
-  /** Canvas scaling filter: `pixelated` for crisp pixels, `smooth` for linear filtering. */
-  renderFilter?: 'pixelated' | 'smooth';
-  /** Target audio sample rate in Hz. FBNeo defaults to 44100. */
-  audioSampleRate?: number;
-  /** Enable vertical sync. Defaults to true. */
-  vsync?: boolean;
-  /** Use integer scaling (no fractional stretching). Defaults to false. */
-  integerScale?: boolean;
-  /** Window scale multiplier for the internal render resolution. Defaults to 2. */
-  windowScale?: number;
+  namespace?: string;
+  /** `null` keeps nothing; leaving it out (or `'opfs'`) mirrors the save folder to OPFS. */
+  persist?: 'opfs' | null;
 }
 
-export const DEFAULT_FBNEO_OPTIONS: Required<FbneoOptions> = {
-  romFileName: 'game.zip',
-  driver: '',
-  renderFilter: 'pixelated',
-  audioSampleRate: 44100,
-  vsync: true,
-  integerScale: false,
-  windowScale: 2,
-};
+/** Engine events beyond the contract's core set. */
+export interface FbneoEvents {
+  /** Save files were just written to `fbneo/<namespace>/` (names relative to it). */
+  saves: { files: string[] };
+}
 
-export const FBNEO_OPTIONS_SCHEMA: JSONSchema = {
-  type: 'object',
-  additionalProperties: false,
-  properties: {
-    romFileName: {
-      type: 'string',
-      default: 'game.zip',
-      description: 'ROM zip filename written to Emscripten MEMFS when loading a game.',
+export interface FbneoPayloads extends EnginePayloads {
+  config: FbneoConfig;
+  options: FbneoOptions;
+  assets: FbneoAssets;
+  storage: FbneoStorage;
+  events: FbneoEvents;
+}
+
+/** The canvas's backing size; FBNeo scales each game's picture into it. */
+export const FBNEO_VIDEO = { width: 640, height: 480, aspect: '4:3' } as const;
+
+export const FBNEO_SPEC: EngineSpec<FbneoPayloads> = {
+  config: {
+    renderFilter: {
+      default: 'pixelated',
+      enum: ['pixelated', 'smooth'],
+      live: true,
+      description: 'Scaling: crisp pixels or linear filtering.',
     },
+    jsUrl: { live: false, description: 'Emscripten glue URL. Defaults to ./fbneo.js.' },
+    wasmUrl: { live: false, description: 'WASM URL. Defaults to ./fbneo.wasm.' },
+  },
+  options: {
     driver: {
-      type: 'string',
       default: '',
-      description:
-        'FBNeo driver/game name to load (e.g. "mslug"). If empty, inferred from romFileName without extension.',
+      live: false,
+      description: 'FBNeo driver (ROM-set short name, e.g. "mslug"). Empty: taken from romFileName.',
     },
-    renderFilter: {
-      type: 'string',
-      enum: ['pixelated', 'smooth'],
-      default: 'pixelated',
-      description: 'Canvas scaling filter: pixelated for crisp pixels, smooth for linear filtering.',
+    romFileName: {
+      default: '',
+      live: false,
+      description: 'The ROM zip file name; its stem is the driver when driver is empty.',
     },
-    audioSampleRate: {
-      type: 'integer',
-      default: 44100,
-      minimum: 11025,
-      maximum: 96000,
-      description: 'Target audio sample rate in Hz.',
+  },
+  assets: {
+    rom: {
+      allowedTypes: ['.zip', '.7z'],
+      live: false,
+      description: 'The arcade ROM set, named after its driver. Required to start.',
     },
-    vsync: {
-      type: 'boolean',
-      default: true,
-      description: 'Enable vertical sync.',
+    bios: {
+      allowedTypes: ['.zip'],
+      live: false,
+      description: 'Optional system BIOS set (neogeo.zip for Neo Geo).',
     },
-    integerScale: {
-      type: 'boolean',
-      default: false,
-      description: 'Use integer scaling (no fractional stretching).',
+  },
+  storage: {
+    namespace: {
+      default: 'default',
+      live: false,
+      description: "Folder for this game's saves, inside the engine's own fbneo/ folder (OPFS fbneo/<namespace>/).",
     },
-    windowScale: {
-      type: 'integer',
-      default: 2,
-      minimum: 1,
-      maximum: 8,
-      description: 'Window scale multiplier for the internal render resolution.',
+    persist: {
+      enum: ['opfs', null],
+      live: false,
+      description: 'null keeps nothing; otherwise saves are mirrored to OPFS.',
     },
   },
-};
+};