@wasm-gaming/blastem-wasm 0.1.0 → 0.1.2

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.
@@ -1,31 +1,111 @@
1
- import type { JSONSchema } from '@wasm-gaming/engine-specs';
1
+ /**
2
+ * What BlastEm accepts, as types and as data.
3
+ *
4
+ * The four payloads of the wasm-gaming engine contract, closed for this engine, and
5
+ * {@link BLASTEM_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';
2
9
 
3
- export interface BlastemOptions {
4
- /** ROM filename used when writing bytes to Emscripten MEMFS. */
5
- romFileName?: string;
6
- /** Region hint for the emulator (auto-detected if not set). */
10
+ /** Bytes, or a thunk that produces them only when the engine actually needs them. */
11
+ export type BlastemAsset =
12
+ | Uint8Array
13
+ | ArrayBuffer
14
+ | null
15
+ | (() => Uint8Array | ArrayBuffer | null | Promise<Uint8Array | ArrayBuffer | null>);
16
+
17
+ /** The engine: fixed for the life of the wasm instance. */
18
+ export interface BlastemConfig {
19
+ /** Console region. `auto` lets BlastEm read it from the ROM header. */
7
20
  region?: 'auto' | 'us' | 'eu' | 'jp';
21
+ /** How the picture is scaled to the mount: crisp pixels or linear filtering. */
22
+ renderFilter?: 'pixelated' | 'smooth';
23
+ /** Emscripten glue URL. Defaults to `./blastem.js` next to the SDK. */
24
+ jsUrl?: string;
25
+ /** WASM URL. Defaults to `./blastem.wasm` next to the SDK. */
26
+ wasmUrl?: string;
8
27
  }
9
28
 
10
- export const DEFAULT_BLASTEM_OPTIONS: Required<BlastemOptions> = {
11
- romFileName: 'game.bin',
12
- region: 'auto',
13
- };
29
+ /** The session. BlastEm has no per-session settings worth exposing yet. */
30
+ export type BlastemOptions = Record<string, never>;
14
31
 
15
- export const BLASTEM_OPTIONS_SCHEMA: JSONSchema = {
16
- type: 'object',
17
- additionalProperties: false,
18
- properties: {
19
- romFileName: {
20
- type: 'string',
21
- default: 'game.bin',
22
- description: 'ROM filename written to Emscripten MEMFS when loading a game.',
23
- },
32
+ export interface BlastemAssets {
33
+ /** The cartridge: `.bin`, `.gen`, `.md` or `.smd`. Required to start. */
34
+ rom?: BlastemAsset;
35
+ }
36
+
37
+ /** Where this engine's files live, and whether they outlive the page. */
38
+ export interface BlastemStorage {
39
+ /**
40
+ * Per-game folder for cartridge saves (SRAM/EEPROM) and save states.
41
+ *
42
+ * Relative to the engine's own folder: the SDK always prefixes `blastem/`, so the
43
+ * files land in OPFS `blastem/<namespace>/` and no namespace can reach another
44
+ * engine's files. Segments are cleaned (`.`/`..` dropped, odd characters → `_`);
45
+ * anything unusable becomes `"default"`. `play.storagePath` gives the result.
46
+ *
47
+ * @defaultValue `"default"`
48
+ */
49
+ namespace?: string;
50
+ /**
51
+ * `null` keeps nothing: no saves are read or written. Leaving it out (or `'opfs'`)
52
+ * mirrors the save folder to OPFS.
53
+ */
54
+ persist?: 'opfs' | null;
55
+ }
56
+
57
+ /** Engine events beyond the contract's core set. */
58
+ export interface BlastemEvents {
59
+ /** Save files were just written to `blastem/<namespace>/` (names relative to it). */
60
+ saves: { files: string[] };
61
+ }
62
+
63
+ export interface BlastemPayloads extends EnginePayloads {
64
+ config: BlastemConfig;
65
+ options: BlastemOptions;
66
+ assets: BlastemAssets;
67
+ storage: BlastemStorage;
68
+ events: BlastemEvents;
69
+ }
70
+
71
+ /** The native picture, which the SDK scales to fit its mount. */
72
+ export const BLASTEM_VIDEO = { width: 640, height: 480, aspect: '4:3' } as const;
73
+
74
+ export const BLASTEM_SPEC: EngineSpec<BlastemPayloads> = {
75
+ config: {
24
76
  region: {
25
- type: 'string',
26
- enum: ['auto', 'us', 'eu', 'jp'],
27
77
  default: 'auto',
28
- description: 'Region override for the Mega Drive emulator.',
78
+ enum: ['auto', 'us', 'eu', 'jp'],
79
+ live: false,
80
+ description: 'Console region; auto reads it from the ROM header.',
81
+ },
82
+ renderFilter: {
83
+ default: 'pixelated',
84
+ enum: ['pixelated', 'smooth'],
85
+ live: true,
86
+ description: 'Scaling: crisp pixels or linear filtering.',
87
+ },
88
+ jsUrl: { live: false, description: 'Emscripten glue URL. Defaults to ./blastem.js.' },
89
+ wasmUrl: { live: false, description: 'WASM URL. Defaults to ./blastem.wasm.' },
90
+ },
91
+ options: {},
92
+ assets: {
93
+ rom: {
94
+ allowedTypes: ['.bin', '.gen', '.md', '.smd'],
95
+ live: false,
96
+ description: 'The Mega Drive / Genesis cartridge. Required to start.',
97
+ },
98
+ },
99
+ storage: {
100
+ namespace: {
101
+ default: 'default',
102
+ live: false,
103
+ description: "Folder for this game's saves, inside the engine's own blastem/ folder (OPFS blastem/<namespace>/).",
104
+ },
105
+ persist: {
106
+ enum: ['opfs', null],
107
+ live: false,
108
+ description: 'null keeps nothing; otherwise saves are mirrored to OPFS.',
29
109
  },
30
110
  },
31
111
  };