@wasm-gaming/rsdkv4-wasm 0.1.5 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -0
- package/dist/rsdkv4/rsdkv4.options.d.ts +355 -23
- package/dist/rsdkv4/rsdkv4.options.d.ts.map +1 -1
- package/dist/rsdkv4/rsdkv4.options.js +169 -52
- package/dist/rsdkv4/rsdkv4.options.js.map +1 -1
- package/dist/rsdkv4/rsdkv4.sdk.d.ts +259 -64
- package/dist/rsdkv4/rsdkv4.sdk.d.ts.map +1 -1
- package/dist/rsdkv4/rsdkv4.sdk.js +1063 -434
- package/dist/rsdkv4/rsdkv4.sdk.js.map +1 -1
- package/package.json +7 -12
- package/src/rsdkv4.options.ts +481 -73
- package/src/rsdkv4.sdk.ts +1338 -506
- package/dist/manifest.json +0 -94
- package/dist/rsdkv4/rsdkv4.manifest.d.ts +0 -4
- package/dist/rsdkv4/rsdkv4.manifest.d.ts.map +0 -1
- package/dist/rsdkv4/rsdkv4.manifest.js +0 -51
- package/dist/rsdkv4/rsdkv4.manifest.js.map +0 -1
- package/src/rsdkv4.manifest.ts +0 -57
package/README.md
CHANGED
|
@@ -364,6 +364,60 @@ data ships with it, so the live demo opens on two empty slots — drop each game
|
|
|
364
364
|
GitHub Pages can't set COOP/COEP headers, and this build couldn't mount OPFS
|
|
365
365
|
even isolated (see the filesystem caveat above).
|
|
366
366
|
|
|
367
|
+
## Project Specs
|
|
368
|
+
|
|
369
|
+
What this project is, and the constraints that shape it.
|
|
370
|
+
|
|
371
|
+
- **A contract implementation, not a game.** The deliverable is one game-agnostic
|
|
372
|
+
`rsdkv4.wasm` plus an SDK conforming to
|
|
373
|
+
[@wasm-gaming/engine-specs](https://github.com/wasm-gaming/engine-specs) — `manifest`
|
|
374
|
+
(Layer A) and `load()` (Layer B). A host drives this engine exactly as it drives the
|
|
375
|
+
other eleven.
|
|
376
|
+
- **Ships none of the game.** The player provides `Data.rsdk`; it never leaves the
|
|
377
|
+
browser and is never committed. Which pack the host hands over is what selects Sonic 1
|
|
378
|
+
or Sonic 2.
|
|
379
|
+
- **The engine's own values are the SDK's only private vocabulary.** They live in
|
|
380
|
+
[src/rsdkv4.options.ts](src/rsdkv4.options.ts) — seven keys, mirrored as JSON Schema in
|
|
381
|
+
`manifest.options` — and in the extra fields of `Rsdkv4LoadConfig`. Everything else is
|
|
382
|
+
contract, documented once at the [contract
|
|
383
|
+
reference](https://wasm-gaming.github.io/engine-specs/api-docs/).
|
|
384
|
+
- **The host owns the files; the SDK owns its folder.** The SDK reads the pack and never
|
|
385
|
+
writes it. What it does write — save data, `settings.ini` — lives under the host-chosen
|
|
386
|
+
`storageNamespace`.
|
|
387
|
+
- **Persistence needs cross-origin isolation.** OPFS sync access exists only in workers,
|
|
388
|
+
so the working dir falls back to in-memory WASMFS when the page isn't isolated (or when
|
|
389
|
+
the build can't create the backend from the main thread — see the filesystem caveat).
|
|
390
|
+
- **Everything builds from the Makefile**, `package.json` has no scripts. `dist/` is both
|
|
391
|
+
the npm artifact and the Pages site: demo at the root, `/craft`, `/vanilla`, and the API
|
|
392
|
+
reference at `/api-docs`.
|
|
393
|
+
- **Sessions are the record.** Specs and decisions live in [SESSIONS/](SESSIONS/), append-only.
|
|
394
|
+
- **Where it is going:** contract 1.0 replaces `{ manifest, load }` with `EngineSDK` /
|
|
395
|
+
`EnginePlay` classes. The six `docs/{SDK,PLAY}-*.md` documents describe that API for this
|
|
396
|
+
engine, and the migration plan is
|
|
397
|
+
[SESSIONS/2026-08-14_12h35.sdk-migration-to-contract-1.0.session.md](SESSIONS/2026-08-14_12h35.sdk-migration-to-contract-1.0.session.md).
|
|
398
|
+
|
|
399
|
+
## Todos
|
|
400
|
+
|
|
401
|
+
Contract 1.0 migration — blocked on `engine-specs` unless noted:
|
|
402
|
+
|
|
403
|
+
- [ ] **Worker smoke test** (not blocked, do first): `-pthread` + `-sPROXY_TO_PTHREAD` +
|
|
404
|
+
`OffscreenCanvas`, then measure audio (SDL's callback decodes Ogg straight from the
|
|
405
|
+
pack) and input latency. The async 1.0 API rests on this.
|
|
406
|
+
- [ ] Split `Rsdkv4Options` into `Rsdkv4Config` (engine) and `Rsdkv4Options` (session).
|
|
407
|
+
- [ ] Manifest to 1.0: `contractVersion`, `config`, no `mountPath`, `capabilities.saves`.
|
|
408
|
+
- [ ] Parse `SData.bin` from JS, so `sdk.saves()` reads slots without booting the wasm.
|
|
409
|
+
- [ ] `Rsdkv4Play` / `Rsdkv4SDK` classes; `create()` as the only engine-specific method.
|
|
410
|
+
- [ ] Migrate the three hosts: `src/vanilla`, `src/craft`, `src/demo` (~65 call sites).
|
|
411
|
+
|
|
412
|
+
Independent of the migration:
|
|
413
|
+
|
|
414
|
+
- [ ] `export default { manifest, load } satisfies EngineSDK` — nothing declares conformance today.
|
|
415
|
+
- [ ] Emit `{ type: 'exit' }` at the end of `destroy()`.
|
|
416
|
+
- [ ] Don't emit `ready` when the engine never came up: today `waitForEngine()` times out
|
|
417
|
+
after 4 s, warns, and reports success anyway.
|
|
418
|
+
- [ ] `assertManifest(manifest)` in [scripts/emit-manifest.mjs](scripts/emit-manifest.mjs).
|
|
419
|
+
- [ ] End-to-end browser run from a real `Data.rsdk`.
|
|
420
|
+
|
|
367
421
|
## Status
|
|
368
422
|
|
|
369
423
|
- ✅ **TS build** — compiles clean; manifest validates against the contract.
|
|
@@ -1,34 +1,366 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* What this engine's four payloads accept, and the {@link RSDKV4_SPEC} that describes
|
|
3
|
+
* them to a host.
|
|
4
|
+
*
|
|
5
|
+
* ```ts
|
|
6
|
+
* import type { Rsdkv4Config, Rsdkv4Options } from '@wasm-gaming/rsdkv4-wasm/options';
|
|
7
|
+
* ```
|
|
8
|
+
*
|
|
9
|
+
* The contract's own module documents *how* the four payloads behave — they read as
|
|
10
|
+
* descriptors and write as patches, and `live` says whether a key reaches a running
|
|
11
|
+
* engine. This module is only the part that is RSDKv4's: which keys exist, what they
|
|
12
|
+
* mean here, and what the engine does with them.
|
|
13
|
+
*
|
|
14
|
+
* The split between the first two is the whole design:
|
|
15
|
+
*
|
|
16
|
+
* - {@link Rsdkv4Config} is **the engine**. It is serialized into RSDKv4's
|
|
17
|
+
* `settings.ini` and read once, at boot — so none of it is `live`.
|
|
18
|
+
* - {@link Rsdkv4Options} is **the session**: which character, which save slot, which
|
|
19
|
+
* stage. That is what a `restart()` reopens. It also carries the engine's own GAME
|
|
20
|
+
* OPTIONS rows, which *are* `live` — and which are not declared here at all, because
|
|
21
|
+
* they differ between Sonic 1 and Sonic 2 and are only knowable once the pack is
|
|
22
|
+
* loaded.
|
|
23
|
+
*
|
|
24
|
+
* @module
|
|
25
|
+
*/
|
|
26
|
+
import type { EnginePayloads, EngineSpec } from '@wasm-gaming/engine-specs';
|
|
27
|
+
/** Bytes a host can hand over for an asset. */
|
|
28
|
+
export type Rsdkv4AssetData = Uint8Array | ArrayBuffer | ArrayBufferView | string;
|
|
29
|
+
/**
|
|
30
|
+
* An asset, eagerly or on demand.
|
|
31
|
+
*
|
|
32
|
+
* The thunk form is what the old `dataProvider` / `settingsProvider` config fields
|
|
33
|
+
* were: `assets({ data: () => fetch(url).then((r) => r.arrayBuffer()) })`. See
|
|
34
|
+
* {@link Rsdkv4Assets} for when each one is actually called — they differ, and the
|
|
35
|
+
* difference is tens of megabytes.
|
|
36
|
+
*/
|
|
37
|
+
export type Rsdkv4Asset = Rsdkv4AssetData | (() => Rsdkv4AssetData | Promise<Rsdkv4AssetData>);
|
|
38
|
+
/**
|
|
39
|
+
* The engine, as `settings.ini` — read once at boot, which is why nothing here is
|
|
40
|
+
* `live`. Change any of it and the engine has to come back up: `destroy()` and a new
|
|
41
|
+
* factory, not `restart()`.
|
|
42
|
+
*
|
|
43
|
+
* Regenerated on every boot, and that is safe: RSDKv4's `writeSettings()` is inside
|
|
44
|
+
* `#ifndef __EMSCRIPTEN__`, so this build never writes the file back and there is
|
|
45
|
+
* nothing of the player's in it to overwrite. A host that wants its own file hands one
|
|
46
|
+
* over as `assets.settings` instead, and then this payload is ignored.
|
|
47
|
+
*/
|
|
48
|
+
export interface Rsdkv4Config {
|
|
49
|
+
/**
|
|
50
|
+
* VSync the engine's SDL window.
|
|
51
|
+
*
|
|
52
|
+
* @defaultValue `true`
|
|
53
|
+
*/
|
|
54
|
+
vsync?: boolean;
|
|
3
55
|
/**
|
|
4
|
-
* RSDKv4's native in-canvas Dev Menu.
|
|
5
|
-
*
|
|
56
|
+
* RSDKv4's native in-canvas Dev Menu. Off by default: a host that wants a
|
|
57
|
+
* debug/stage-select UI draws it from `play.devMenu`, and leaving this on has
|
|
6
58
|
* historically produced a native menu-like screen at boot.
|
|
59
|
+
*
|
|
60
|
+
* @defaultValue `false`
|
|
7
61
|
*/
|
|
8
62
|
devMenu?: boolean;
|
|
9
|
-
/**
|
|
63
|
+
/**
|
|
64
|
+
* RSDKv4 `EngineDebugMode`. In this build it gates the engine's log output and
|
|
65
|
+
* nothing else — `play.devMenu` and `play.game` are embind bridges the wasm installs
|
|
66
|
+
* unconditionally, so they work either way.
|
|
67
|
+
*
|
|
68
|
+
* @defaultValue `true`
|
|
69
|
+
*/
|
|
10
70
|
engineDebugMode?: boolean;
|
|
11
|
-
/** VSync the engine's SDL window. */
|
|
12
|
-
vsync?: boolean;
|
|
13
71
|
/**
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* `
|
|
72
|
+
* Who draws the save-select / character-select / game-options screens.
|
|
73
|
+
*
|
|
74
|
+
* `'native'` leaves RSDKv4's own in-canvas Start Menu on. `'host'` skips it, for a
|
|
75
|
+
* host that renders those screens itself from `play.game` — otherwise the engine's
|
|
76
|
+
* menu runs underneath the host's.
|
|
77
|
+
*
|
|
78
|
+
* This is the old `skipStartMenu` boolean, the right way up: the inverted name meant
|
|
79
|
+
* `false` had to be read twice to mean "yes, show it".
|
|
80
|
+
*
|
|
81
|
+
* @defaultValue `'native'`
|
|
82
|
+
*/
|
|
83
|
+
startMenu?: 'native' | 'host';
|
|
84
|
+
/**
|
|
85
|
+
* Where to load the Emscripten glue from. Defaults to `./rsdkv4.js` next to the
|
|
86
|
+
* built SDK, which is where `make build` puts it.
|
|
87
|
+
*/
|
|
88
|
+
jsUrl?: string;
|
|
89
|
+
/** Where to load the wasm from. Defaults to `./rsdkv4.wasm` next to the built SDK. */
|
|
90
|
+
wasmUrl?: string;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* A stage, as the engine's two-level stage list indexes it.
|
|
94
|
+
*
|
|
95
|
+
* `name` is **read-only**: the descriptors {@link Rsdkv4Options.stage} reports back
|
|
96
|
+
* carry one so a host can paint a stage picker straight from `options()`, but writing
|
|
97
|
+
* it is ignored — `category` and `scene` are what reach the engine.
|
|
98
|
+
*/
|
|
99
|
+
export interface Rsdkv4Stage {
|
|
100
|
+
/** 0-based category, as ordered by `play.devMenu.getStageList()`. */
|
|
101
|
+
category: number;
|
|
102
|
+
/** 0-based scene within the category. */
|
|
103
|
+
scene: number;
|
|
104
|
+
/** `"<Category> · <Scene>"`, filled in by the SDK. Ignored on write. */
|
|
105
|
+
name?: string;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* RSDKv4's fourteen buttons, in the engine's own `InputButtons` order.
|
|
109
|
+
*
|
|
110
|
+
* The order is not cosmetic: it is the bit order of the mask the SDK hands the
|
|
111
|
+
* engine once per tick, so this array is the wire format and not merely a list.
|
|
112
|
+
*
|
|
113
|
+
* Sonic 1 and Sonic 2 read only the four directions, A, B, C and start. The other
|
|
114
|
+
* six exist in the engine and are free for a host to do as it likes with.
|
|
115
|
+
*/
|
|
116
|
+
export declare const RSDKV4_BUTTONS: readonly ["up", "down", "left", "right", "a", "b", "c", "x", "y", "z", "l", "r", "start", "select"];
|
|
117
|
+
/**
|
|
118
|
+
* One button, spelled as {@link RSDKV4_BUTTONS} spells it.
|
|
119
|
+
*
|
|
120
|
+
* Derived from the array rather than declared beside it, so there is one list and
|
|
121
|
+
* not two to drift apart — and so a typo in a `buttons` literal is a compile error
|
|
122
|
+
* rather than a button that silently never fires.
|
|
123
|
+
*/
|
|
124
|
+
export type Rsdkv4Button = (typeof RSDKV4_BUTTONS)[number];
|
|
125
|
+
/**
|
|
126
|
+
* Every button as a boolean — what a host hands over to {@link Rsdkv4Options.buttons}
|
|
127
|
+
* and keeps writing to for as long as it holds the claim.
|
|
128
|
+
*
|
|
129
|
+
* All fourteen are required. A key that is merely absent reads as `false` on every
|
|
130
|
+
* tick, which is a dead button and no error anywhere; requiring the whole set is what
|
|
131
|
+
* turns that into something the compiler catches.
|
|
132
|
+
*/
|
|
133
|
+
export type Rsdkv4Buttons = Record<Rsdkv4Button, boolean>;
|
|
134
|
+
/**
|
|
135
|
+
* What the engine binds each button to by default, for a host that has taken input
|
|
136
|
+
* over and now has to bind them itself.
|
|
137
|
+
*
|
|
138
|
+
* Not engine configuration — nothing here is read by the engine, and writing to it
|
|
139
|
+
* changes nothing. It is a starting table, so a host that claims input can offer the
|
|
140
|
+
* bindings a player already knows instead of inventing its own.
|
|
141
|
+
*/
|
|
142
|
+
export interface Rsdkv4InputDefaults {
|
|
143
|
+
/** `KeyboardEvent.code` values, as `settings.ini`'s `[Keyboard 1]` binds them. */
|
|
144
|
+
keyboard: Record<Rsdkv4Button, string>;
|
|
145
|
+
/**
|
|
146
|
+
* Indices into `Gamepad.buttons` under the browser's **standard mapping**.
|
|
147
|
+
*
|
|
148
|
+
* These are translated, not copied: `settings.ini`'s `[Controller 1]` holds
|
|
149
|
+
* SDL's `SDL_CONTROLLER_BUTTON_*` values, and those are different numbers — SDL's
|
|
150
|
+
* left shoulder is 9, where the browser's is 4. A host polling the Gamepad API
|
|
151
|
+
* wants the browser's, so that is what this carries.
|
|
152
|
+
*
|
|
153
|
+
* `null` where the engine's default has no standard-mapping button: `select` is
|
|
154
|
+
* bound to SDL's GUIDE, which this build's own web-gamepad mapping never wires
|
|
155
|
+
* up, so it is dead on a pad in the engine too. `y` and `z` are the analog
|
|
156
|
+
* triggers (the engine reads them past a deadzone, as ZL/ZR).
|
|
157
|
+
*/
|
|
158
|
+
gamepad: Record<Rsdkv4Button, number | null>;
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* The engine's own default bindings. See {@link Rsdkv4InputDefaults}.
|
|
162
|
+
*
|
|
163
|
+
* Directions are the arrow keys. This build's `ProcessInput()` also reads `KeyW`,
|
|
164
|
+
* `KeyA`, `KeyS` and `KeyD` as a second set of them, and takes those three scancodes
|
|
165
|
+
* off `x`, `y` and `z` to do it — so the table below is what a *claiming* host should
|
|
166
|
+
* bind, and the engine under SDL polling answers to both.
|
|
167
|
+
*
|
|
168
|
+
* This replaces the old `RSDKV4_KEYMAP`, which nothing read and which was wrong in
|
|
169
|
+
* three ways for want of ever being checked against the engine: it listed 9 of the
|
|
170
|
+
* 14 buttons, and bound `select` to `ShiftLeft` where the engine's default is `Tab`.
|
|
171
|
+
*/
|
|
172
|
+
export declare const RSDKV4_INPUT: Rsdkv4InputDefaults;
|
|
173
|
+
/**
|
|
174
|
+
* The session — what a `restart()` reopens.
|
|
175
|
+
*
|
|
176
|
+
* **Absence is the neutral value.** The old `RSDKV4_UNSET = 255` sentinel is gone:
|
|
177
|
+
* leaving a key out means "boot the way the engine normally would", and there is no
|
|
178
|
+
* longer a number that quietly means something else. (In particular `player: 0` used
|
|
179
|
+
* to be indistinguishable from "unset" in the ini, which is why it was a footgun.)
|
|
180
|
+
*
|
|
181
|
+
* The index signature is not laziness. The engine's GAME OPTIONS rows — spin dash,
|
|
182
|
+
* item-box set, and whatever else the loaded pack declares — are keys neither this
|
|
183
|
+
* package nor the host can know ahead of time. They come back from `options()` as
|
|
184
|
+
* descriptors with their own labels and choices, `live: true`, and are written back
|
|
185
|
+
* the same way. That is what lets a host paint a settings screen without knowing a
|
|
186
|
+
* single key name.
|
|
187
|
+
*/
|
|
188
|
+
export interface Rsdkv4Options {
|
|
189
|
+
/**
|
|
190
|
+
* The character to start a *new* game as, by the name the pack reports — the
|
|
191
|
+
* `enum` of this key's descriptor is exactly `play.game.players()`, so a host paints
|
|
192
|
+
* a character picker from it and writes one of the values straight back. Matched
|
|
193
|
+
* case-insensitively; an unknown name is an error rather than a silent Sonic.
|
|
194
|
+
*
|
|
195
|
+
* Continuing a slot that already has a save ignores this: the save carries its own
|
|
196
|
+
* character.
|
|
197
|
+
*/
|
|
198
|
+
player?: string;
|
|
199
|
+
/**
|
|
200
|
+
* Which of RSDKv4's four save slots (0-3) the session runs on. `null` plays without
|
|
201
|
+
* saving, as the native menu's NO SAVE does.
|
|
202
|
+
*
|
|
203
|
+
* A slot with data continues it; an empty slot starts a new game as {@link player}.
|
|
204
|
+
*/
|
|
205
|
+
slot?: number | null;
|
|
206
|
+
/**
|
|
207
|
+
* Jump straight to a stage, skipping wherever the session would otherwise open.
|
|
208
|
+
*
|
|
209
|
+
* Applied through the engine's own stage loader after boot, not through
|
|
210
|
+
* `settings.ini`'s `Starting*` trio — which is why it works on a `restart()` of a
|
|
211
|
+
* running engine and not only on the first one.
|
|
212
|
+
*/
|
|
213
|
+
stage?: Rsdkv4Stage;
|
|
214
|
+
/**
|
|
215
|
+
* Take input over: hand the engine a live object of fourteen booleans and it stops
|
|
216
|
+
* polling SDL, reading yours instead — touch buttons, rebinding, netplay, a test
|
|
217
|
+
* that drives a stage from a script.
|
|
218
|
+
*
|
|
219
|
+
* ```ts
|
|
220
|
+
* const buttons = { up: false, down: false, ...rest, select: false }; // all 14
|
|
221
|
+
* play.options({ buttons }); // claim
|
|
222
|
+
* play.options({ buttons: null }); // release — the engine polls SDL again
|
|
223
|
+
* ```
|
|
224
|
+
*
|
|
225
|
+
* **Read once per tick, from wherever it lives.** The engine calls in at the top of
|
|
226
|
+
* its input pass and the SDK reads the object at that moment, so a plain object and
|
|
227
|
+
* a reactive store both work and neither one needs the SDK to know which it is.
|
|
228
|
+
* Whatever is `true` when the engine asks is what the engine sees.
|
|
229
|
+
*
|
|
230
|
+
* Three things become the host's the moment it claims:
|
|
231
|
+
*
|
|
232
|
+
* - **Keyup on focus loss.** SDL resets its keyboard when the window loses focus; a
|
|
233
|
+
* host that owns input inherits that job (`blur`, `visibilitychange`) or a held
|
|
234
|
+
* arrow strands the player mid-run.
|
|
235
|
+
* - **The gamepad, entirely.** The engine stops polling it, so a host that wants one
|
|
236
|
+
* polls the Gamepad API itself — deadzones and the D-pad-from-axes fallback
|
|
237
|
+
* included. {@link RSDKV4_INPUT} is the table to start from.
|
|
238
|
+
* - **Releasing.** Absence means "leave the claim as it is"; only `null` releases.
|
|
239
|
+
* A component that claims and then unmounts without releasing leaves the engine
|
|
240
|
+
* pulling at an object nobody writes to any more.
|
|
241
|
+
*
|
|
242
|
+
* Not persistable, and not a settings row: it reads back from `options()` as `null`
|
|
243
|
+
* whether or not a claim is held, so that `JSON.stringify(await play.options())`
|
|
244
|
+
* cannot sweep fourteen transient booleans into a host's saved settings. Ask
|
|
245
|
+
* `play.input.claimed` for the claim state.
|
|
246
|
+
*
|
|
247
|
+
* `play.input.claim(buttons)` and `play.input.release()` are the same thing, named.
|
|
248
|
+
*/
|
|
249
|
+
buttons?: Rsdkv4Buttons | null;
|
|
250
|
+
/**
|
|
251
|
+
* The engine's GAME OPTIONS rows. See the note on the interface: these are declared
|
|
252
|
+
* by the loaded pack, not here.
|
|
253
|
+
*
|
|
254
|
+
* A `boolean` row reads and writes as a boolean, an enum row as one of its choice
|
|
255
|
+
* labels; the raw engine-side number is accepted on write too.
|
|
256
|
+
*/
|
|
257
|
+
[key: string]: unknown;
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* The two files the engine reads out of its working directory.
|
|
261
|
+
*
|
|
262
|
+
* Neither is `live`: they are read while the engine comes up, so a patch after that
|
|
263
|
+
* lands in the state a *future* engine would boot from.
|
|
264
|
+
*/
|
|
265
|
+
export interface Rsdkv4Assets {
|
|
266
|
+
/**
|
|
267
|
+
* The `Data.rsdk` pack — the whole game, and what decides *which* game: one
|
|
268
|
+
* game-agnostic wasm runs both Sonic 1 and Sonic 2, the pack is the difference.
|
|
269
|
+
*
|
|
270
|
+
* Precedence, and the reason the thunk form exists: bytes handed over here win;
|
|
271
|
+
* otherwise a copy already persisted in this storage namespace is reused; only if
|
|
272
|
+
* there is neither is a thunk called. That is what keeps a host from re-fetching
|
|
273
|
+
* tens of megabytes it already has. With none of the three, `start()` fails.
|
|
274
|
+
*/
|
|
275
|
+
data?: Rsdkv4Asset;
|
|
276
|
+
/**
|
|
277
|
+
* A ready-made `settings.ini`, for a host that would rather write the file itself
|
|
278
|
+
* than describe it through {@link Rsdkv4Config}. Given one, the config payload is
|
|
279
|
+
* not serialized at all.
|
|
280
|
+
*
|
|
281
|
+
* Unlike `data`, a thunk here is called on **every** boot rather than only on a
|
|
282
|
+
* cache miss — the file is a few hundred bytes, and re-reading it is what makes the
|
|
283
|
+
* host's copy authoritative instead of whatever an earlier session left behind.
|
|
284
|
+
*/
|
|
285
|
+
settings?: Rsdkv4Asset;
|
|
286
|
+
}
|
|
287
|
+
/** Where this engine's files live, and whether they outlive the page. */
|
|
288
|
+
export interface Rsdkv4Storage {
|
|
289
|
+
/**
|
|
290
|
+
* Per-game folder for the pack, the settings and the save file, so two games do not
|
|
291
|
+
* overwrite each other. Examples: `"sonic1"`, `"rsdkv4/Sonic2"`.
|
|
292
|
+
*
|
|
293
|
+
* It is a path under the engine's working root *and* the OPFS directory the SDK
|
|
294
|
+
* mirrors save data into, which is what lets a host read `<namespace>/SData.bin`
|
|
295
|
+
* itself. Anything that is not a usable relative path normalises to `"default"` —
|
|
296
|
+
* including the object you get from interpolating a game record by mistake.
|
|
297
|
+
*
|
|
298
|
+
* @defaultValue `"default"`
|
|
299
|
+
*/
|
|
300
|
+
namespace?: string;
|
|
301
|
+
/**
|
|
302
|
+
* What the engine's working directory is backed by.
|
|
303
|
+
*
|
|
304
|
+
* `'opfs'` forces a persistent mount and warns if it cannot have one; `null` means
|
|
305
|
+
* the host wants nothing kept, which switches off the save mirror as well; leaving
|
|
306
|
+
* it out picks OPFS when the page is cross-origin isolated.
|
|
307
|
+
*
|
|
308
|
+
* Worth knowing: on every build without Asyncify/JSPI — today's included — the mount
|
|
309
|
+
* itself cannot be OPFS, so the working dir is in-memory whatever this says. Saves
|
|
310
|
+
* survive anyway, because the SDK mirrors `SData.bin` into
|
|
311
|
+
* `<namespace>/` through the host-side OPFS API. `null` is what turns that off.
|
|
312
|
+
*/
|
|
313
|
+
persist?: 'opfs' | null;
|
|
314
|
+
}
|
|
315
|
+
/** One of RSDKv4's four save slots, as the engine's own save-select screen sees it. */
|
|
316
|
+
export interface RsdkSaveSlot {
|
|
317
|
+
/** 0-3. */
|
|
318
|
+
slot: number;
|
|
319
|
+
/** No game stored here — starting it means picking a character first. */
|
|
320
|
+
empty: boolean;
|
|
321
|
+
/** Character index into `play.game.players()`: 0 Sonic, 1 Tails, 2 Knuckles, 3 both. */
|
|
322
|
+
character: number;
|
|
323
|
+
lives: number;
|
|
324
|
+
score: number;
|
|
325
|
+
emeralds: number;
|
|
326
|
+
/** Stage list the save resumes into (1 regular, 3 special), or -1 when empty. */
|
|
327
|
+
list: number;
|
|
328
|
+
/** 0-based scene within `list` — index it against `play.devMenu.getStageList()`. */
|
|
329
|
+
zone: number;
|
|
330
|
+
}
|
|
331
|
+
/**
|
|
332
|
+
* What this engine announces on top of the contract's core set (`start`, `error`,
|
|
333
|
+
* `exit`, `pause`, `resume`).
|
|
334
|
+
*/
|
|
335
|
+
export interface Rsdkv4Events {
|
|
336
|
+
/**
|
|
337
|
+
* The save file changed, with every slot as it now stands.
|
|
338
|
+
*
|
|
339
|
+
* Emitted when the SDK has just written `<namespace>/SData.bin` out of the wasm and
|
|
340
|
+
* the bytes are not what they were — on its slow timer, on a pause, and on the way
|
|
341
|
+
* down. A host painting save slots subscribes to this instead of polling.
|
|
17
342
|
*/
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
343
|
+
saves: RsdkSaveSlot[];
|
|
344
|
+
}
|
|
345
|
+
/** The four payloads, closed — the single type parameter everything else takes. */
|
|
346
|
+
export interface Rsdkv4Payloads extends EnginePayloads {
|
|
347
|
+
config: Rsdkv4Config;
|
|
348
|
+
options: Rsdkv4Options;
|
|
349
|
+
assets: Rsdkv4Assets;
|
|
350
|
+
storage: Rsdkv4Storage;
|
|
351
|
+
events: Rsdkv4Events;
|
|
25
352
|
}
|
|
26
353
|
/**
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
354
|
+
* Everything the engine declares about its own properties, as data.
|
|
355
|
+
*
|
|
356
|
+
* `default` appears here and nowhere else: the contract's base class seeds the
|
|
357
|
+
* starting state from it, so there is no second table of defaults to drift out of
|
|
358
|
+
* agreement with this one — which is exactly what the old
|
|
359
|
+
* `DEFAULT_RSDKV4_OPTIONS`-alongside-a-JSON-Schema pair did.
|
|
360
|
+
*
|
|
361
|
+
* What is missing from `options` is deliberate: `player` and `stage` get their `enum`
|
|
362
|
+
* filled in from the loaded pack, and the GAME OPTIONS rows are added outright, when a
|
|
363
|
+
* running engine is asked to describe itself.
|
|
30
364
|
*/
|
|
31
|
-
export declare const
|
|
32
|
-
export declare const DEFAULT_RSDKV4_OPTIONS: Required<Rsdkv4Options>;
|
|
33
|
-
export declare const RSDKV4_OPTIONS_SCHEMA: JSONSchema;
|
|
365
|
+
export declare const RSDKV4_SPEC: EngineSpec<Rsdkv4Payloads>;
|
|
34
366
|
//# sourceMappingURL=rsdkv4.options.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rsdkv4.options.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"rsdkv4.options.d.ts","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"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"}
|