@wasm-gaming/blastem-wasm 0.1.0 → 0.1.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 CHANGED
@@ -1,41 +1,117 @@
1
1
  # @wasm-gaming/blastem-wasm
2
2
 
3
- BlastEm (Sega Mega Drive / Genesis emulator by retrodev) compiled to WebAssembly via Emscripten, packaged as a wasm-gaming engine SDK.
3
+ [BlastEm](https://www.retrodev.com/blastem/), the Sega Mega Drive / Genesis emulator by
4
+ Michael Pavone, compiled to WebAssembly and wrapped in a self-contained SDK that implements the
5
+ [wasm-gaming engine contract](https://github.com/wasm-gaming/engine-specs) 1.0.
4
6
 
5
- This subproject follows the same engine-package approach used by jgenesis-wasm, rsdkv3, and rsdkv4:
6
- - typed `manifest`
7
- - typed `options`
8
- - `load(config)` engine SDK surface
9
- - Makefile-driven build (`build-sdk`, `build-wasm`, `preview`)
7
+ ## Install
10
8
 
11
- ## Contract surface
9
+ ```bash
10
+ npm install @wasm-gaming/blastem-wasm
11
+ ```
12
+
13
+ The SDK carries the contract's runtime beside it (`dist/blastem/engine-specs.js`) and imports it
14
+ relatively: it loads from any static server, with no bundler and no import map. The wasm and its
15
+ glue (`blastem.js`, `blastem.wasm`) are built in CI and shipped in the GitHub Release
16
+ (`blastem.tar.gz`, layout `blastem/blastem/…`) and on Pages.
17
+
18
+ ## Use
12
19
 
13
20
  ```js
14
- import { manifest, load } from '@wasm-gaming/blastem-wasm';
15
-
16
- const engine = await load({
17
- canvas,
18
- assets: { rom: romBytes },
19
- onEvent: (e) => console.log(e),
20
- });
21
- engine.start();
21
+ import BlastemSDK from './blastem/blastem.sdk.js';
22
+
23
+ BlastemSDK.id; // 'blastem' — also this engine's folder in OPFS
24
+ BlastemSDK.version; // '0.2.0'
25
+
26
+ const play = await new BlastemSDK()
27
+ .config({ region: 'auto', renderFilter: 'pixelated' })
28
+ .assets({ rom: () => file.arrayBuffer() }) // bytes, or a thunk
29
+ .storage({ namespace: 'old-towers' }) // → OPFS blastem/old-towers/
30
+ .on('saves', ({ detail }) => console.log('saved', detail.files))
31
+ .mount(document.querySelector('#stage')) // a <canvas> is used as is; anything else gets one
32
+ .start();
33
+
34
+ play.pause('menu'); // the first caller owns the pause…
35
+ play.resume('menu'); // …and only it lifts it; sound stops too
36
+ await play.restart(); // soft reset
37
+ await play.destroy(); // saves flushed, loop stopped, audio closed
22
38
  ```
23
39
 
40
+ | payload | keys |
41
+ | --- | --- |
42
+ | `config` | `region` (`auto` \| `us` \| `eu` \| `jp`), `renderFilter` (`pixelated` \| `smooth`, live), `jsUrl`, `wasmUrl` |
43
+ | `options` | — |
44
+ | `assets` | `rom` (`.bin`, `.gen`, `.md`, `.smd`; required) |
45
+ | `storage` | `namespace` (default `default`), `persist` (`'opfs'` \| `null`) |
46
+
47
+ Events: the contract's `start`, `error`, `exit`, `pause`, `resume`, plus `saves`.
48
+
49
+ Controls are BlastEm's defaults: arrows, `A`/`S`/`D` (A/B/C), `Q`/`W`/`E` (X/Y/Z), `Enter` (Start),
50
+ `` ` `` save state, `L` load state, `Tab` soft reset. Gamepads work through SDL2.
51
+
52
+ ## Saves live in the engine's own folder
53
+
54
+ ```
55
+ OPFS root
56
+ └── blastem/ ← BlastemSDK.id, added by the SDK
57
+ └── <namespace>/ ← storage({ namespace }), default "default"
58
+ ├── save.sram ← cartridge SRAM / EEPROM / NOR
59
+ └── *.state ← save states
60
+ ```
61
+
62
+ The wasm writes every save of the running game to MEMFS `/save`. The SDK seeds it from OPFS before
63
+ boot and mirrors back what changed after asking BlastEm to flush: every 10 s, on pause, when the
64
+ page is hidden and on `destroy()`. (Upstream only flushed at exit — a web page never exits — so
65
+ saves used to be lost.) `play.storagePath` gives the folder; `storagePath(engineId, namespace)` is
66
+ exported for hosts that need it before a session exists.
67
+
68
+ One BlastEm per page: after `destroy()`, a new game needs a new page (or iframe).
69
+
24
70
  ## Build
25
71
 
26
- ```sh
27
- make build # Full build: WASM (Docker/Emscripten) + TypeScript SDK
28
- make build-sdk # TypeScript only (SDK + manifest)
29
- make build-wasm # BlastEm WASM only (via Docker)
30
- make preview # Serve dist/ with COOP/COEP headers
72
+ ```bash
73
+ make build-sdk # TypeScript → dist/blastem/ (fast, no Docker)
74
+ make test # type-check + tests against the built package
75
+ make build-wasm # BlastEm → WebAssembly in emscripten/emsdk:4.0.10 (Docker)
76
+ make demo # dist/index.html: a no-build demo (pick or drop a ROM)
77
+ make preview # serve dist/ on :8027
31
78
  ```
32
79
 
33
- ## WASM artifacts
80
+ Everything is pinned: the upstream revision (Mercurial node + archive SHA-256), the UI font and the
81
+ emsdk image, so a commit always builds the same engine. Behind a TLS-intercepting proxy:
82
+ `BUILD_CA_BUNDLE=<ca.pem> make build-wasm`; where GitHub archives are unreachable,
83
+ `BUILD_SDL2_SRC=<libsdl-org/SDL checkout at release-2.32.0>` builds Emscripten's SDL2 port from it.
84
+
85
+ The wasm is ~31 MB, ~2.3 MB gzipped (BlastEm's generated 68000 core is most of it).
86
+
87
+ ## Project Specs
88
+
89
+ - Contract 1.0 class (`BlastemSDK` / `BlastemPlay`), self-contained ESM, engine-specs as the one
90
+ dependency; conformance line `BLASTEM_ENGINE` checked by `make test`.
91
+ - Engine-owned storage `blastem/<namespace>/`, save mirror with an explicit flush bridge.
92
+ - Pinned, reproducible wasm build (see [CORE.md](CORE.md) for what is patched upstream).
93
+ - Records of decisions in [RECORD/](RECORD/).
94
+
95
+ ## Todos
96
+
97
+ - [ ] Optional `stats()` / frame counter for the launcher's core benchmark.
98
+ - [ ] Map more of BlastEm's config (scaling, vsync, sync source) to typed `config`.
99
+ - [ ] Try `-Os` for a smaller wasm and measure the cost.
100
+
101
+ ## License
102
+
103
+ **GPL-3.0-or-later** — the whole repository. See [LICENSE](LICENSE).
104
+
105
+ `blastem.wasm` / `blastem.js` are [BlastEm](https://www.retrodev.com/blastem/) by Michael Pavone
106
+ (GPL-3.0-or-later), compiled to WebAssembly, and `scripts/web_bridge.c` is compiled into it; the SDK
107
+ and the app exist to run that binary, so they are released under the same licence.
34
108
 
35
- | File | Description |
36
- |------|-------------|
37
- | `blastem.js` | Emscripten-generated JS loader |
38
- | `blastem.wasm` | Compiled BlastEm runtime |
109
+ **Corresponding source.** Everything needed to rebuild the binary is public:
110
+ - BlastEm at revision `6d1a7447ee9e`, downloaded from `https://www.retrodev.com/repos/blastem/archive/6d1a7447ee9e.tar.gz`
111
+ and checked against the SHA-256 pinned in [`scripts/build-blastem.sh`](scripts/build-blastem.sh);
112
+ - the patches and the bridge, all in this repository (`scripts/`);
113
+ - the toolchain: the `emscripten/emsdk:4.0.10` image (`make build-wasm`).
39
114
 
40
- BlastEm uses Emscripten SDL2. The JS loader expects a `<canvas id="canvas">` in the DOM.
41
- ROM bytes are written to the in-memory MEMFS at `/rom/game.bin` before the emulator boots.
115
+ The binary also contains SDL2, zlib, Zstandard, Nuklear and the Roboto font, under their own
116
+ permissive licences: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Both files are copied
117
+ into `dist/blastem/`, so every release archive and the npm package carry them.
@@ -0,0 +1,122 @@
1
+ # Third-party notices
2
+
3
+ `blastem.wasm` / `blastem.js` are **BlastEm** compiled to WebAssembly. Besides BlastEm itself
4
+ (GPL-3.0-or-later, see [LICENSE](LICENSE)), the binary contains the components below. Their
5
+ licences are reproduced in full.
6
+
7
+ | Component | Version | Licence | Where it comes from |
8
+ | --- | --- | --- | --- |
9
+ | BlastEm | `6d1a7447ee9e` (v1.0.0+22) | GPL-3.0-or-later | https://www.retrodev.com/repos/blastem — fetched and SHA-256-checked by `scripts/build-blastem.sh` |
10
+ | SDL2 | 2.32.0 | zlib | Emscripten's `sdl2` port |
11
+ | zlib | bundled with BlastEm | zlib | `zlib/` in BlastEm's source |
12
+ | Zstandard | bundled with BlastEm | BSD-3-Clause (dual BSD / GPLv2; used under BSD) | `zstd/` in BlastEm's source |
13
+ | Nuklear | bundled with BlastEm | Public domain, or a perpetual permissive grant | `nuklear_ui/nuklear.h` in BlastEm's source |
14
+ | Roboto Regular | v2.138 | Apache-2.0 | https://github.com/googlefonts/roboto — BlastEm's UI font, SHA-256-checked by the build |
15
+
16
+ ## BlastEm
17
+
18
+ Copyright 2013-2016 Michael Pavone and contributors (as stated in the source headers). BlastEm is free software distributed under the terms of the
19
+ GNU General Public License version 3 or greater. See [LICENSE](LICENSE).
20
+
21
+ ## SDL2 (zlib licence)
22
+
23
+ ```
24
+ Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
25
+
26
+ This software is provided 'as-is', without any express or implied
27
+ warranty. In no event will the authors be held liable for any damages
28
+ arising from the use of this software.
29
+
30
+ Permission is granted to anyone to use this software for any purpose,
31
+ including commercial applications, and to alter it and redistribute it
32
+ freely, subject to the following restrictions:
33
+
34
+ 1. The origin of this software must not be misrepresented; you must not
35
+ claim that you wrote the original software. If you use this software
36
+ in a product, an acknowledgment in the product documentation would be
37
+ appreciated but is not required.
38
+ 2. Altered source versions must be plainly marked as such, and must not be
39
+ misrepresented as being the original software.
40
+ 3. This notice may not be removed or altered from any source distribution.
41
+
42
+ ```
43
+
44
+ ## zlib (zlib licence)
45
+
46
+ ```
47
+ Copyright notice:
48
+
49
+ (C) 1995-2022 Jean-loup Gailly and Mark Adler
50
+
51
+ This software is provided 'as-is', without any express or implied
52
+ warranty. In no event will the authors be held liable for any damages
53
+ arising from the use of this software.
54
+
55
+ Permission is granted to anyone to use this software for any purpose,
56
+ including commercial applications, and to alter it and redistribute it
57
+ freely, subject to the following restrictions:
58
+
59
+ 1. The origin of this software must not be misrepresented; you must not
60
+ claim that you wrote the original software. If you use this software
61
+ in a product, an acknowledgment in the product documentation would be
62
+ appreciated but is not required.
63
+ 2. Altered source versions must be plainly marked as such, and must not be
64
+ misrepresented as being the original software.
65
+ 3. This notice may not be removed or altered from any source distribution.
66
+
67
+ Jean-loup Gailly Mark Adler
68
+ jloup@gzip.org madler@alumni.caltech.edu
69
+ ```
70
+
71
+ ## Zstandard (BSD-3-Clause)
72
+
73
+ ```
74
+ BSD License
75
+
76
+ For Zstandard software
77
+
78
+ Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved.
79
+
80
+ Redistribution and use in source and binary forms, with or without modification,
81
+ are permitted provided that the following conditions are met:
82
+
83
+ * Redistributions of source code must retain the above copyright notice, this
84
+ list of conditions and the following disclaimer.
85
+
86
+ * Redistributions in binary form must reproduce the above copyright notice,
87
+ this list of conditions and the following disclaimer in the documentation
88
+ and/or other materials provided with the distribution.
89
+
90
+ * Neither the name Facebook, nor Meta, nor the names of its contributors may
91
+ be used to endorse or promote products derived from this software without
92
+ specific prior written permission.
93
+
94
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
95
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
96
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
97
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
98
+ ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
99
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
100
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
101
+ ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
102
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
103
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
104
+ ```
105
+
106
+ ## Nuklear
107
+
108
+ ```
109
+ LICENSE:
110
+ This software is dual-licensed to the public domain and under the following
111
+ license: you are granted a perpetual, irrevocable license to copy, modify,
112
+ publish and distribute this file as you see fit.
113
+ ```
114
+
115
+ ## Roboto (Apache License 2.0)
116
+
117
+ Copyright 2011 Google Inc. All Rights Reserved.
118
+
119
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this font except
120
+ in compliance with the License. You may obtain a copy of the License at
121
+ https://www.apache.org/licenses/LICENSE-2.0 — distributed on an "AS IS" BASIS, WITHOUT
122
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.