@wasm-gaming/rsdkv4-wasm 0.1.4 → 0.2.0

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

@@ -1,22 +1,361 @@
-import type { JSONSchema } from '@wasm-gaming/engine-specs';
-export interface Rsdkv4Options {
+/**
+ * What this engine's four payloads accept, and the {@link RSDKV4_SPEC} that describes
+ * them to a host.
+ *
+ * ```ts
+ * import type { Rsdkv4Config, Rsdkv4Options } from '@wasm-gaming/rsdkv4-wasm/options';
+ * ```
+ *
+ * The contract's own module documents *how* the four payloads behave — they read as
+ * descriptors and write as patches, and `live` says whether a key reaches a running
+ * engine. This module is only the part that is RSDKv4's: which keys exist, what they
+ * mean here, and what the engine does with them.
+ *
+ * The split between the first two is the whole design:
+ *
+ * - {@link Rsdkv4Config} is **the engine**. It is serialized into RSDKv4's
+ *   `settings.ini` and read once, at boot — so none of it is `live`.
+ * - {@link Rsdkv4Options} is **the session**: which character, which save slot, which
+ *   stage. That is what a `restart()` reopens. It also carries the engine's own GAME
+ *   OPTIONS rows, which *are* `live` — and which are not declared here at all, because
+ *   they differ between Sonic 1 and Sonic 2 and are only knowable once the pack is
+ *   loaded.
+ *
+ * @module
+ */
+import type { EnginePayloads, EngineSpec } from '@wasm-gaming/engine-specs';
+/** Bytes a host can hand over for an asset. */
+export type Rsdkv4AssetData = Uint8Array | ArrayBuffer | ArrayBufferView | string;
+/**
+ * An asset, eagerly or on demand.
+ *
+ * The thunk form is what the old `dataProvider` / `settingsProvider` config fields
+ * were: `assets({ data: () => fetch(url).then((r) => r.arrayBuffer()) })`. See
+ * {@link Rsdkv4Assets} for when each one is actually called — they differ, and the
+ * difference is tens of megabytes.
+ */
+export type Rsdkv4Asset = Rsdkv4AssetData | (() => Rsdkv4AssetData | Promise<Rsdkv4AssetData>);
+/**
+ * The engine, as `settings.ini` — read once at boot, which is why nothing here is
+ * `live`. Change any of it and the engine has to come back up: `destroy()` and a new
+ * factory, not `restart()`.
+ *
+ * Regenerated on every boot, and that is safe: RSDKv4's `writeSettings()` is inside
+ * `#ifndef __EMSCRIPTEN__`, so this build never writes the file back and there is
+ * nothing of the player's in it to overwrite. A host that wants its own file hands one
+ * over as `assets.settings` instead, and then this payload is ignored.
+ */
+export interface Rsdkv4Config {
+    /**
+     * VSync the engine's SDL window.
+     *
+     * @defaultValue `true`
+     */
+    vsync?: boolean;
     /**
-     * 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
+     * RSDKv4's native in-canvas Dev Menu. Off by default: a host that wants a
+     * debug/stage-select UI draws it from `play.devMenu`, and leaving this on has
      * historically produced a native menu-like screen at boot.
+     *
+     * @defaultValue `false`
      */
     devMenu?: boolean;
-    /** RSDKv4 EngineDebugMode — enables the web devmenu embind bridge hooks. */
+    /**
+     * RSDKv4 `EngineDebugMode`. In this build it gates the engine's log output and
+     * nothing else — `play.devMenu` and `play.game` are embind bridges the wasm installs
+     * unconditionally, so they work either way.
+     *
+     * @defaultValue `true`
+     */
     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;
+    /**
+     * Who draws the save-select / character-select / game-options screens.
+     *
+     * `'native'` leaves RSDKv4's own in-canvas Start Menu on. `'host'` skips it, for a
+     * host that renders those screens itself from `play.game` — otherwise the engine's
+     * menu runs underneath the host's.
+     *
+     * This is the old `skipStartMenu` boolean, the right way up: the inverted name meant
+     * `false` had to be read twice to mean "yes, show it".
+     *
+     * @defaultValue `'native'`
+     */
+    startMenu?: 'native' | 'host';
+    /**
+     * Where to load the Emscripten glue from. Defaults to `./rsdkv4.js` next to the
+     * built SDK, which is where `make build` puts it.
+     */
+    jsUrl?: string;
+    /** Where to load the wasm from. Defaults to `./rsdkv4.wasm` next to the built SDK. */
+    wasmUrl?: string;
+}
+/**
+ * A stage, as the engine's two-level stage list indexes it.
+ *
+ * `name` is **read-only**: the descriptors {@link Rsdkv4Options.stage} reports back
+ * carry one so a host can paint a stage picker straight from `options()`, but writing
+ * it is ignored — `category` and `scene` are what reach the engine.
+ */
+export interface Rsdkv4Stage {
+    /** 0-based category, as ordered by `play.devMenu.getStageList()`. */
+    category: number;
+    /** 0-based scene within the category. */
+    scene: number;
+    /** `"<Category> · <Scene>"`, filled in by the SDK. Ignored on write. */
+    name?: string;
+}
+/**
+ * RSDKv4's fourteen buttons, in the engine's own `InputButtons` order.
+ *
+ * The order is not cosmetic: it is the bit order of the mask the SDK hands the
+ * engine once per tick, so this array is the wire format and not merely a list.
+ *
+ * Sonic 1 and Sonic 2 read only the four directions, A, B, C and start. The other
+ * six exist in the engine and are free for a host to do as it likes with.
+ */
+export declare const RSDKV4_BUTTONS: readonly ["up", "down", "left", "right", "a", "b", "c", "x", "y", "z", "l", "r", "start", "select"];
+/**
+ * One button, spelled as {@link RSDKV4_BUTTONS} spells it.
+ *
+ * Derived from the array rather than declared beside it, so there is one list and
+ * not two to drift apart — and so a typo in a `buttons` literal is a compile error
+ * rather than a button that silently never fires.
+ */
+export type Rsdkv4Button = (typeof RSDKV4_BUTTONS)[number];
+/**
+ * Every button as a boolean — what a host hands over to {@link Rsdkv4Options.buttons}
+ * and keeps writing to for as long as it holds the claim.
+ *
+ * All fourteen are required. A key that is merely absent reads as `false` on every
+ * tick, which is a dead button and no error anywhere; requiring the whole set is what
+ * turns that into something the compiler catches.
+ */
+export type Rsdkv4Buttons = Record<Rsdkv4Button, boolean>;
+/**
+ * What the engine binds each button to by default, for a host that has taken input
+ * over and now has to bind them itself.
+ *
+ * Not engine configuration — nothing here is read by the engine, and writing to it
+ * changes nothing. It is a starting table, so a host that claims input can offer the
+ * bindings a player already knows instead of inventing its own.
+ */
+export interface Rsdkv4InputDefaults {
+    /** `KeyboardEvent.code` values, as `settings.ini`'s `[Keyboard 1]` binds them. */
+    keyboard: Record<Rsdkv4Button, string>;
+    /**
+     * Indices into `Gamepad.buttons` under the browser's **standard mapping**.
+     *
+     * These are translated, not copied: `settings.ini`'s `[Controller 1]` holds
+     * SDL's `SDL_CONTROLLER_BUTTON_*` values, and those are different numbers — SDL's
+     * left shoulder is 9, where the browser's is 4. A host polling the Gamepad API
+     * wants the browser's, so that is what this carries.
+     *
+     * `null` where the engine's default has no standard-mapping button: `select` is
+     * bound to SDL's GUIDE, which this build's own web-gamepad mapping never wires
+     * up, so it is dead on a pad in the engine too. `y` and `z` are the analog
+     * triggers (the engine reads them past a deadzone, as ZL/ZR).
+     */
+    gamepad: Record<Rsdkv4Button, number | null>;
+}
+/**
+ * The engine's own default bindings. See {@link Rsdkv4InputDefaults}.
+ *
+ * This replaces the old `RSDKV4_KEYMAP`, which nothing read and which was wrong in
+ * three ways for want of ever being checked against the engine: it listed 9 of the
+ * 14 buttons, and bound `select` to `ShiftLeft` where the engine's default is `Tab`.
+ */
+export declare const RSDKV4_INPUT: Rsdkv4InputDefaults;
+/**
+ * The session — what a `restart()` reopens.
+ *
+ * **Absence is the neutral value.** The old `RSDKV4_UNSET = 255` sentinel is gone:
+ * leaving a key out means "boot the way the engine normally would", and there is no
+ * longer a number that quietly means something else. (In particular `player: 0` used
+ * to be indistinguishable from "unset" in the ini, which is why it was a footgun.)
+ *
+ * The index signature is not laziness. The engine's GAME OPTIONS rows — spin dash,
+ * item-box set, and whatever else the loaded pack declares — are keys neither this
+ * package nor the host can know ahead of time. They come back from `options()` as
+ * descriptors with their own labels and choices, `live: true`, and are written back
+ * the same way. That is what lets a host paint a settings screen without knowing a
+ * single key name.
+ */
+export interface Rsdkv4Options {
+    /**
+     * The character to start a *new* game as, by the name the pack reports — the
+     * `enum` of this key's descriptor is exactly `play.game.players()`, so a host paints
+     * a character picker from it and writes one of the values straight back. Matched
+     * case-insensitively; an unknown name is an error rather than a silent Sonic.
+     *
+     * Continuing a slot that already has a save ignores this: the save carries its own
+     * character.
+     */
+    player?: string;
+    /**
+     * Which of RSDKv4's four save slots (0-3) the session runs on. `null` plays without
+     * saving, as the native menu's NO SAVE does.
+     *
+     * A slot with data continues it; an empty slot starts a new game as {@link player}.
+     */
+    slot?: number | null;
+    /**
+     * Jump straight to a stage, skipping wherever the session would otherwise open.
+     *
+     * Applied through the engine's own stage loader after boot, not through
+     * `settings.ini`'s `Starting*` trio — which is why it works on a `restart()` of a
+     * running engine and not only on the first one.
+     */
+    stage?: Rsdkv4Stage;
+    /**
+     * Take input over: hand the engine a live object of fourteen booleans and it stops
+     * polling SDL, reading yours instead — touch buttons, rebinding, netplay, a test
+     * that drives a stage from a script.
+     *
+     * ```ts
+     * const buttons = { up: false, down: false, ...rest, select: false }; // all 14
+     * play.options({ buttons });       // claim
+     * play.options({ buttons: null }); // release — the engine polls SDL again
+     * ```
+     *
+     * **Read once per tick, from wherever it lives.** The engine calls in at the top of
+     * its input pass and the SDK reads the object at that moment, so a plain object and
+     * a reactive store both work and neither one needs the SDK to know which it is.
+     * Whatever is `true` when the engine asks is what the engine sees.
+     *
+     * Three things become the host's the moment it claims:
+     *
+     * - **Keyup on focus loss.** SDL resets its keyboard when the window loses focus; a
+     *   host that owns input inherits that job (`blur`, `visibilitychange`) or a held
+     *   arrow strands the player mid-run.
+     * - **The gamepad, entirely.** The engine stops polling it, so a host that wants one
+     *   polls the Gamepad API itself — deadzones and the D-pad-from-axes fallback
+     *   included. {@link RSDKV4_INPUT} is the table to start from.
+     * - **Releasing.** Absence means "leave the claim as it is"; only `null` releases.
+     *   A component that claims and then unmounts without releasing leaves the engine
+     *   pulling at an object nobody writes to any more.
+     *
+     * Not persistable, and not a settings row: it reads back from `options()` as `null`
+     * whether or not a claim is held, so that `JSON.stringify(await play.options())`
+     * cannot sweep fourteen transient booleans into a host's saved settings. Ask
+     * `play.input.claimed` for the claim state.
+     *
+     * `play.input.claim(buttons)` and `play.input.release()` are the same thing, named.
+     */
+    buttons?: Rsdkv4Buttons | null;
+    /**
+     * The engine's GAME OPTIONS rows. See the note on the interface: these are declared
+     * by the loaded pack, not here.
+     *
+     * A `boolean` row reads and writes as a boolean, an enum row as one of its choice
+     * labels; the raw engine-side number is accepted on write too.
+     */
+    [key: string]: unknown;
+}
+/**
+ * The two files the engine reads out of its working directory.
+ *
+ * Neither is `live`: they are read while the engine comes up, so a patch after that
+ * lands in the state a *future* engine would boot from.
+ */
+export interface Rsdkv4Assets {
+    /**
+     * The `Data.rsdk` pack — the whole game, and what decides *which* game: one
+     * game-agnostic wasm runs both Sonic 1 and Sonic 2, the pack is the difference.
+     *
+     * Precedence, and the reason the thunk form exists: bytes handed over here win;
+     * otherwise a copy already persisted in this storage namespace is reused; only if
+     * there is neither is a thunk called. That is what keeps a host from re-fetching
+     * tens of megabytes it already has. With none of the three, `start()` fails.
+     */
+    data?: Rsdkv4Asset;
+    /**
+     * A ready-made `settings.ini`, for a host that would rather write the file itself
+     * than describe it through {@link Rsdkv4Config}. Given one, the config payload is
+     * not serialized at all.
+     *
+     * Unlike `data`, a thunk here is called on **every** boot rather than only on a
+     * cache miss — the file is a few hundred bytes, and re-reading it is what makes the
+     * host's copy authoritative instead of whatever an earlier session left behind.
+     */
+    settings?: Rsdkv4Asset;
+}
+/** Where this engine's files live, and whether they outlive the page. */
+export interface Rsdkv4Storage {
+    /**
+     * Per-game folder for the pack, the settings and the save file, so two games do not
+     * overwrite each other. Examples: `"sonic1"`, `"rsdkv4/Sonic2"`.
+     *
+     * It is a path under the engine's working root *and* the OPFS directory the SDK
+     * mirrors save data into, which is what lets a host read `<namespace>/SData.bin`
+     * itself. Anything that is not a usable relative path normalises to `"default"` —
+     * including the object you get from interpolating a game record by mistake.
+     *
+     * @defaultValue `"default"`
+     */
+    namespace?: string;
+    /**
+     * What the engine's working directory is backed by.
+     *
+     * `'opfs'` forces a persistent mount and warns if it cannot have one; `null` means
+     * the host wants nothing kept, which switches off the save mirror as well; leaving
+     * it out picks OPFS when the page is cross-origin isolated.
+     *
+     * Worth knowing: on every build without Asyncify/JSPI — today's included — the mount
+     * itself cannot be OPFS, so the working dir is in-memory whatever this says. Saves
+     * survive anyway, because the SDK mirrors `SData.bin` into
+     * `<namespace>/` through the host-side OPFS API. `null` is what turns that off.
+     */
+    persist?: 'opfs' | null;
+}
+/** One of RSDKv4's four save slots, as the engine's own save-select screen sees it. */
+export interface RsdkSaveSlot {
+    /** 0-3. */
+    slot: number;
+    /** No game stored here — starting it means picking a character first. */
+    empty: boolean;
+    /** Character index into `play.game.players()`: 0 Sonic, 1 Tails, 2 Knuckles, 3 both. */
+    character: number;
+    lives: number;
+    score: number;
+    emeralds: number;
+    /** Stage list the save resumes into (1 regular, 3 special), or -1 when empty. */
+    list: number;
+    /** 0-based scene within `list` — index it against `play.devMenu.getStageList()`. */
+    zone: number;
+}
+/**
+ * What this engine announces on top of the contract's core set (`start`, `error`,
+ * `exit`, `pause`, `resume`).
+ */
+export interface Rsdkv4Events {
+    /**
+     * The save file changed, with every slot as it now stands.
+     *
+     * Emitted when the SDK has just written `<namespace>/SData.bin` out of the wasm and
+     * the bytes are not what they were — on its slow timer, on a pause, and on the way
+     * down. A host painting save slots subscribes to this instead of polling.
+     */
+    saves: RsdkSaveSlot[];
+}
+/** The four payloads, closed — the single type parameter everything else takes. */
+export interface Rsdkv4Payloads extends EnginePayloads {
+    config: Rsdkv4Config;
+    options: Rsdkv4Options;
+    assets: Rsdkv4Assets;
+    storage: Rsdkv4Storage;
+    events: Rsdkv4Events;
+}
+/**
+ * Everything the engine declares about its own properties, as data.
+ *
+ * `default` appears here and nowhere else: the contract's base class seeds the
+ * starting state from it, so there is no second table of defaults to drift out of
+ * agreement with this one — which is exactly what the old
+ * `DEFAULT_RSDKV4_OPTIONS`-alongside-a-JSON-Schema pair did.
+ *
+ * What is missing from `options` is deliberate: `player` and `stage` get their `enum`
+ * filled in from the loaded pack, and the GAME OPTIONS rows are added outright, when a
+ * running engine is asked to describe itself.
+ */
+export declare const RSDKV4_SPEC: EngineSpec<Rsdkv4Payloads>;
 //# sourceMappingURL=rsdkv4.options.d.ts.map

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

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

package/dist/rsdkv4/rsdkv4.options.js

@@ -1,41 +1,180 @@
-// 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,
+/**
+ * What this engine's four payloads accept, and the {@link RSDKV4_SPEC} that describes
+ * them to a host.
+ *
+ * ```ts
+ * import type { Rsdkv4Config, Rsdkv4Options } from '@wasm-gaming/rsdkv4-wasm/options';
+ * ```
+ *
+ * The contract's own module documents *how* the four payloads behave — they read as
+ * descriptors and write as patches, and `live` says whether a key reaches a running
+ * engine. This module is only the part that is RSDKv4's: which keys exist, what they
+ * mean here, and what the engine does with them.
+ *
+ * The split between the first two is the whole design:
+ *
+ * - {@link Rsdkv4Config} is **the engine**. It is serialized into RSDKv4's
+ *   `settings.ini` and read once, at boot — so none of it is `live`.
+ * - {@link Rsdkv4Options} is **the session**: which character, which save slot, which
+ *   stage. That is what a `restart()` reopens. It also carries the engine's own GAME
+ *   OPTIONS rows, which *are* `live` — and which are not declared here at all, because
+ *   they differ between Sonic 1 and Sonic 2 and are only knowable once the pack is
+ *   loaded.
+ *
+ * @module
+ */
+/**
+ * RSDKv4's fourteen buttons, in the engine's own `InputButtons` order.
+ *
+ * The order is not cosmetic: it is the bit order of the mask the SDK hands the
+ * engine once per tick, so this array is the wire format and not merely a list.
+ *
+ * Sonic 1 and Sonic 2 read only the four directions, A, B, C and start. The other
+ * six exist in the engine and are free for a host to do as it likes with.
+ */
+export const RSDKV4_BUTTONS = [
+    'up',
+    'down',
+    'left',
+    'right',
+    'a',
+    'b',
+    'c',
+    'x',
+    'y',
+    'z',
+    'l',
+    'r',
+    'start',
+    'select',
+];
+/**
+ * The engine's own default bindings. See {@link Rsdkv4InputDefaults}.
+ *
+ * This replaces the old `RSDKV4_KEYMAP`, which nothing read and which was wrong in
+ * three ways for want of ever being checked against the engine: it listed 9 of the
+ * 14 buttons, and bound `select` to `ShiftLeft` where the engine's default is `Tab`.
+ */
+export const RSDKV4_INPUT = {
+    keyboard: {
+        up: 'ArrowUp',
+        down: 'ArrowDown',
+        left: 'ArrowLeft',
+        right: 'ArrowRight',
+        a: 'KeyZ',
+        b: 'KeyX',
+        c: 'KeyC',
+        x: 'KeyA',
+        y: 'KeyS',
+        z: 'KeyD',
+        l: 'KeyQ',
+        r: 'KeyE',
+        start: 'Enter',
+        select: 'Tab',
+    },
+    gamepad: {
+        up: 12,
+        down: 13,
+        left: 14,
+        right: 15,
+        a: 0,
+        b: 1,
+        c: 2,
+        x: 3,
+        y: 6,
+        z: 7,
+        l: 4,
+        r: 5,
+        start: 9,
+        select: null,
+    },
 };
-export const RSDKV4_OPTIONS_SCHEMA = {
-    type: 'object',
-    additionalProperties: false,
-    properties: {
+/**
+ * Everything the engine declares about its own properties, as data.
+ *
+ * `default` appears here and nowhere else: the contract's base class seeds the
+ * starting state from it, so there is no second table of defaults to drift out of
+ * agreement with this one — which is exactly what the old
+ * `DEFAULT_RSDKV4_OPTIONS`-alongside-a-JSON-Schema pair did.
+ *
+ * What is missing from `options` is deliberate: `player` and `stage` get their `enum`
+ * filled in from the loaded pack, and the GAME OPTIONS rows are added outright, when a
+ * running engine is asked to describe itself.
+ */
+export const RSDKV4_SPEC = {
+    config: {
+        vsync: { default: true, live: false, description: 'VSync the engine window.' },
         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.",
+            live: false,
+            description: "RSDKv4's native in-canvas Dev Menu. Hosts draw their own from play.devMenu.",
         },
         engineDebugMode: {
-            type: 'boolean',
             default: true,
-            description: 'Enables the web devmenu embind bridge (stage list / warp / pause).',
+            live: false,
+            description: "Gates the engine's log output. The embind bridges are installed either way.",
+        },
+        startMenu: {
+            default: 'native',
+            enum: ['native', 'host'],
+            live: false,
+            description: "Who draws save/character/options: the engine's own menu, or the host from play.game.",
+        },
+        jsUrl: { live: false, description: 'Emscripten glue URL. Defaults to ./rsdkv4.js.' },
+        wasmUrl: { live: false, description: 'WASM URL. Defaults to ./rsdkv4.wasm.' },
+    },
+    options: {
+        // No `default` on any of the three: absence is what "boot normally" means here,
+        // and a default would take that away.
+        player: {
+            live: false,
+            description: 'Character for a new game, by name. Choices arrive once the pack is loaded.',
+        },
+        slot: {
+            enum: [null, 0, 1, 2, 3],
+            live: false,
+            description: 'Save slot 0-3, or null to play without saving.',
+        },
+        stage: {
+            live: false,
+            description: 'Jump straight to a stage. Choices arrive once the pack is loaded.',
+        },
+        // No `default`, for the same reason as the three above: absence is what "the
+        // engine polls SDL as usual" means, and only `null` is a release.
+        //
+        // `live` because it is the one option that reaches a running engine directly
+        // rather than through a restart — and the description says the rest out loud,
+        // because the contract has no flag for "transient, do not paint, do not
+        // persist" and a host reading descriptors to build a settings screen would
+        // otherwise put fourteen booleans on it.
+        buttons: {
+            live: true,
+            description: 'Host-driven input: a live object of 14 booleans the engine reads once per tick, or null to hand input back. Transient — not a settings row, not persistable, and it always reads back as null.',
+        },
+    },
+    assets: {
+        data: {
+            allowedTypes: ['.rsdk'],
+            live: false,
+            description: 'The RSDKv4 game data pack. Selects the game; 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 pack, settings and save file.",
+        },
+        persist: {
+            enum: ['opfs', null],
+            live: false,
+            description: "'opfs' forces persistence, null keeps nothing, absent auto-detects.",
         },
-        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

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