@wasm-gaming/sonic3air-wasm 0.0.0 → 0.0.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.
@@ -0,0 +1,68 @@
1
+ /**
2
+ * What Sonic 3 A.I.R. accepts, as types and as data.
3
+ *
4
+ * The four payloads of the wasm-gaming engine contract, closed for this engine, and
5
+ * {@link SONIC3AIR_SPEC} — the same thing as data the contract's base class reads:
6
+ * every default lives there and nowhere else.
7
+ */
8
+ import type { EnginePayloads, EngineSpec } from '@wasm-gaming/engine-specs';
9
+ /** Bytes, or a thunk that produces them only when the engine actually needs them. */
10
+ export type Sonic3AirAsset = Uint8Array | ArrayBuffer | null | (() => Uint8Array | ArrayBuffer | null | Promise<Uint8Array | ArrayBuffer | null>);
11
+ /** Where the engine's files are. Fixed for the life of the page. */
12
+ export interface Sonic3AirConfig {
13
+ /** The engine module (generated by the build). Defaults to `./sonic3air.js` next to the SDK. */
14
+ jsUrl?: string;
15
+ /** The official WebAssembly binary. Defaults to `./sonic3air.wasm` next to the SDK. */
16
+ wasmUrl?: string;
17
+ /** The engine's own data package. Defaults to `./sonic3air.data` next to the SDK. */
18
+ dataUrl?: string;
19
+ }
20
+ /** The session. Nothing per-session: the game has its own menus. */
21
+ export type Sonic3AirOptions = Record<string, never>;
22
+ export interface Sonic3AirAssets {
23
+ /**
24
+ * The Sonic & Knuckles + Sonic 3 ROM (`Sonic_Knuckles_wSonic3.bin`, 4 MB, serial
25
+ * MK-1563): the Steam release's file, or a Mega Drive dump of the lock-on. Required.
26
+ */
27
+ rom?: Sonic3AirAsset;
28
+ /**
29
+ * The remastered soundtrack (`audioremaster.bin`, ~130 MB, from the PC release or the
30
+ * official web zip). Optional: without it the game plays the Mega Drive music.
31
+ */
32
+ audioremaster?: Sonic3AirAsset;
33
+ }
34
+ /** Where this engine's files live, and whether they outlive the page. */
35
+ export interface Sonic3AirStorage {
36
+ /**
37
+ * Per-game folder, relative to the engine's own: the game's save data (saves,
38
+ * settings, mods) is mirrored to OPFS `sonic3air/<namespace>/`. Segments are cleaned
39
+ * (`.`/`..` dropped, odd characters → `_`); a leading `sonic3air/` is stripped once.
40
+ * `play.storagePath` gives the result.
41
+ *
42
+ * @defaultValue `"default"`
43
+ */
44
+ namespace?: string;
45
+ /** `null` keeps nothing; otherwise the game's save data is mirrored to OPFS. */
46
+ persist?: 'opfs' | null;
47
+ }
48
+ export interface Sonic3AirEvents {
49
+ /** Save data changed and was written to (or removed from) `sonic3air/<namespace>/`. */
50
+ saves: {
51
+ files: string[];
52
+ removed: string[];
53
+ };
54
+ }
55
+ export interface Sonic3AirPayloads extends EnginePayloads {
56
+ config: Sonic3AirConfig;
57
+ options: Sonic3AirOptions;
58
+ assets: Sonic3AirAssets;
59
+ storage: Sonic3AirStorage;
60
+ events: Sonic3AirEvents;
61
+ }
62
+ /** The engine always draws 16:9 (its canvas is the window's width by 9/16 of it). */
63
+ export declare const SONIC3AIR_VIDEO: {
64
+ readonly aspect: "16:9";
65
+ readonly ratio: number;
66
+ };
67
+ export declare const SONIC3AIR_SPEC: EngineSpec<Sonic3AirPayloads>;
68
+ //# sourceMappingURL=sonic3air.options.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sonic3air.options.d.ts","sourceRoot":"","sources":["../../src/sonic3air.options.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5E,qFAAqF;AACrF,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,WAAW,GACX,IAAI,GACJ,CAAC,MAAM,UAAU,GAAG,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,WAAW,GAAG,IAAI,CAAC,CAAC,CAAC;AAEvF,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,qFAAqF;AACrF,eAAO,MAAM,eAAe;;;CAA6C,CAAC;AAE1E,eAAO,MAAM,cAAc,EAAE,UAAU,CAAC,iBAAiB,CA+BxD,CAAC"}
@@ -0,0 +1,35 @@
1
+ /** The engine always draws 16:9 (its canvas is the window's width by 9/16 of it). */
2
+ export const SONIC3AIR_VIDEO = { aspect: '16:9', ratio: 16 / 9 };
3
+ export const SONIC3AIR_SPEC = {
4
+ config: {
5
+ jsUrl: { live: false, description: 'Engine module URL. Defaults to ./sonic3air.js next to the SDK.' },
6
+ wasmUrl: { live: false, description: 'WASM URL. Defaults to ./sonic3air.wasm next to the SDK.' },
7
+ dataUrl: { live: false, description: "The engine's data package. Defaults to ./sonic3air.data next to the SDK." },
8
+ },
9
+ options: {},
10
+ assets: {
11
+ rom: {
12
+ allowedTypes: ['.bin', '.md', '.gen'],
13
+ live: false,
14
+ description: 'Sonic & Knuckles + Sonic 3 (Sonic_Knuckles_wSonic3.bin, 4 MB). Required to start.',
15
+ },
16
+ audioremaster: {
17
+ allowedTypes: ['.bin'],
18
+ live: false,
19
+ description: 'The remastered soundtrack (audioremaster.bin). Optional.',
20
+ },
21
+ },
22
+ storage: {
23
+ namespace: {
24
+ default: 'default',
25
+ live: false,
26
+ description: "Folder for this game's save data, inside the engine's own sonic3air/ folder (OPFS sonic3air/<namespace>/).",
27
+ },
28
+ persist: {
29
+ enum: ['opfs', null],
30
+ live: false,
31
+ description: "null keeps nothing; otherwise the game's save data is mirrored to OPFS.",
32
+ },
33
+ },
34
+ };
35
+ //# sourceMappingURL=sonic3air.options.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sonic3air.options.js","sourceRoot":"","sources":["../../src/sonic3air.options.ts"],"names":[],"mappings":"AAsEA,qFAAqF;AACrF,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,EAAW,CAAC;AAE1E,MAAM,CAAC,MAAM,cAAc,GAAkC;IAC3D,MAAM,EAAE;QACN,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,gEAAgE,EAAE;QACrG,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,yDAAyD,EAAE;QAChG,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,0EAA0E,EAAE;KAClH;IACD,OAAO,EAAE,EAAE;IACX,MAAM,EAAE;QACN,GAAG,EAAE;YACH,YAAY,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;YACrC,IAAI,EAAE,KAAK;YACX,WAAW,EAAE,mFAAmF;SACjG;QACD,aAAa,EAAE;YACb,YAAY,EAAE,CAAC,MAAM,CAAC;YACtB,IAAI,EAAE,KAAK;YACX,WAAW,EAAE,0DAA0D;SACxE;KACF;IACD,OAAO,EAAE;QACP,SAAS,EAAE;YACT,OAAO,EAAE,SAAS;YAClB,IAAI,EAAE,KAAK;YACX,WAAW,EAAE,4GAA4G;SAC1H;QACD,OAAO,EAAE;YACP,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC;YACpB,IAAI,EAAE,KAAK;YACX,WAAW,EAAE,yEAAyE;SACvF;KACF;CACF,CAAC"}
@@ -0,0 +1,100 @@
1
+ /**
2
+ * The engine package's entry point: an `EngineSDK` for Sonic 3 A.I.R.
3
+ *
4
+ * ```js
5
+ * import Sonic3AirSDK from '@wasm-gaming/sonic3air-wasm';
6
+ *
7
+ * const play = await new Sonic3AirSDK()
8
+ * .assets({ rom: () => readRom() }) // Sonic_Knuckles_wSonic3.bin: bytes, or a thunk
9
+ * .storage({ namespace: 'sonic3air' }) // → OPFS sonic3air/sonic3air/
10
+ * .mount(document.querySelector('#stage'))
11
+ * .start();
12
+ *
13
+ * play.pause('menu'); play.resume('menu');
14
+ * await play.destroy(); // save data flushed, loop stopped, audio closed
15
+ * ```
16
+ *
17
+ * The engine is Eukaryot's **official** WebAssembly build, unchanged (see
18
+ * scripts/fetch-upstream.mjs): `sonic3air.js` is its Emscripten glue scoped in an ES
19
+ * factory, `sonic3air.data` its own data package, unpacked into `/sonic3air/`. The
20
+ * game's menus — title, save select, options, mods — are its own.
21
+ *
22
+ * What the official page did, this does instead:
23
+ * - the ROM comes from `assets.rom` (validated here) — no file prompt;
24
+ * - the save data folder `/sonic3air/savedata` is in memory, seeded from OPFS
25
+ * `sonic3air/<namespace>/` before the game starts and mirrored back when the game
26
+ * syncs it, every 10 s, on pause, on page hide and on destroy — no IndexedDB;
27
+ * - the remastered soundtrack is `assets.audioremaster`, never downloaded;
28
+ * - the in-game file manager's hooks (import, export, rename) are provided while a
29
+ * session runs.
30
+ */
31
+ import { EnginePlayBase, EngineSDKBase, EventEmitter, type EngineInit, type EngineSDKConstructor, type EventsOf, type PayloadKind } from '@wasm-gaming/engine-specs';
32
+ import { type Sonic3AirOptions, type Sonic3AirPayloads } from './sonic3air.options.js';
33
+ export type { Sonic3AirAsset, Sonic3AirAssets, Sonic3AirConfig, Sonic3AirEvents, Sonic3AirOptions, Sonic3AirPayloads, Sonic3AirStorage, } from './sonic3air.options.js';
34
+ export { SONIC3AIR_SPEC, SONIC3AIR_VIDEO } from './sonic3air.options.js';
35
+ /** The name and place the engine reads the ROM from (its `RomPath`). */
36
+ export declare const ROM_FILE = "Sonic_Knuckles_wSonic3.bin";
37
+ export declare const AUDIO_REMASTER_FILE = "audioremaster.bin";
38
+ /** Sonic & Knuckles with Sonic 3 locked on: 4 MB, serial `MK-1563` in the header. */
39
+ export declare const ROM_SIZE: number;
40
+ /**
41
+ * Where an engine keeps one namespace: `<engineId>/<namespace>`, relative to the OPFS
42
+ * root. Identical in every wasm-gaming engine: segments cleaned, `.` and `..` dropped,
43
+ * anything outside `[A-Za-z0-9._-]` → `_`, nothing usable → `default`; a leading
44
+ * `<engineId>/` is stripped once.
45
+ */
46
+ export declare function storagePath(engineId: string, namespace: unknown): {
47
+ namespace: string;
48
+ path: string;
49
+ prefixed: boolean;
50
+ };
51
+ /**
52
+ * Is this the ROM Sonic 3 A.I.R. needs? The same test as the official page: 4 MB and
53
+ * serial MK-1563 (Sonic & Knuckles, with Sonic 3 locked on) at 0x180. `reason` says
54
+ * what is wrong in words a player can act on.
55
+ */
56
+ export declare function checkRom(bytes: Uint8Array | null | undefined): {
57
+ ok: true;
58
+ } | {
59
+ ok: false;
60
+ reason: string;
61
+ };
62
+ /** Is this save-data path (relative to savedata) one the mirror keeps? */
63
+ export declare const isMirrored: (relative: string) => boolean;
64
+ /** The live engine: one booted Sonic 3 A.I.R. and its session. */
65
+ export declare class Sonic3AirPlay extends EnginePlayBase<Sonic3AirPayloads> {
66
+ #private;
67
+ constructor(init?: EngineInit<Sonic3AirPayloads>, events?: EventEmitter<EventsOf<Sonic3AirPayloads>>);
68
+ get namespace(): string;
69
+ /** Where this session's save data lives, relative to the OPFS root: `sonic3air/<namespace>`. */
70
+ get storagePath(): string;
71
+ get pausedBy(): string | null;
72
+ /**
73
+ * Freeze the game and its sound. The first caller owns the pause; only that owner's
74
+ * {@link resume} lifts it. The save data is flushed.
75
+ */
76
+ pause(owner?: string): void;
77
+ resume(owner?: string): void;
78
+ /** Silence the game without stopping it. Independent of {@link pause}. */
79
+ mute(muted?: boolean): void;
80
+ get muted(): boolean;
81
+ /** Copy the game's changed save data to OPFS `sonic3air/<namespace>/`; emits `saves`. */
82
+ flushSaves(): Promise<void>;
83
+ protected mounted(target: HTMLElement): void;
84
+ protected open(_options: Sonic3AirOptions): Promise<void>;
85
+ protected patched(_kind: PayloadKind, _patch: object): void;
86
+ protected close(): Promise<void>;
87
+ }
88
+ /** The factory a host constructs: static identity, the configuration chain, `start()`. */
89
+ export declare class Sonic3AirSDK extends EngineSDKBase<Sonic3AirPayloads> {
90
+ static readonly id = "sonic3air";
91
+ /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
92
+ static readonly version = "0.0.1";
93
+ static readonly name = "Sonic 3 A.I.R.";
94
+ static readonly description = "Sonic 3 - Angel Island Revisited, Eukaryot's official WebAssembly build. Ships none of the game: the player provides the Sonic & Knuckles + Sonic 3 ROM, and it never leaves their browser.";
95
+ protected createPlay(init: EngineInit<Sonic3AirPayloads>, events: EventEmitter<EventsOf<Sonic3AirPayloads>>): Sonic3AirPlay;
96
+ }
97
+ /** CI's conformance line: if this class stops satisfying the contract, `make test` fails. */
98
+ export declare const SONIC3AIR_ENGINE: EngineSDKConstructor<Sonic3AirPayloads>;
99
+ export default Sonic3AirSDK;
100
+ //# sourceMappingURL=sonic3air.sdk.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sonic3air.sdk.d.ts","sourceRoot":"","sources":["../../src/sonic3air.sdk.ts"],"names":[],"mappings":"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"}