@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.
- package/LICENSE +674 -0
- package/README.md +103 -27
- package/THIRD_PARTY_NOTICES.md +122 -0
- package/dist/blastem/LICENSE +674 -0
- package/dist/blastem/THIRD_PARTY_NOTICES.md +122 -0
- package/dist/blastem/app/app.css +128 -0
- package/dist/blastem/app/app.js +580 -0
- package/dist/blastem/blastem.js +14 -1
- package/dist/blastem/blastem.options.d.ts +65 -7
- package/dist/blastem/blastem.options.d.ts.map +1 -1
- package/dist/blastem/blastem.options.js +35 -16
- package/dist/blastem/blastem.options.js.map +1 -1
- package/dist/blastem/blastem.sdk.d.ts +132 -12
- package/dist/blastem/blastem.sdk.d.ts.map +1 -1
- package/dist/blastem/blastem.sdk.js +587 -131
- package/dist/blastem/blastem.sdk.js.map +1 -1
- package/dist/blastem/blastem.wasm +0 -0
- package/dist/blastem/engine-specs.js +382 -0
- package/package.json +17 -15
- package/src/app/app.css +128 -0
- package/src/app/app.js +580 -0
- package/src/blastem.options.ts +101 -21
- package/src/blastem.sdk.ts +662 -160
- package/dist/blastem/blastem.manifest.d.ts +0 -4
- package/dist/blastem/blastem.manifest.d.ts.map +0 -1
- package/dist/blastem/blastem.manifest.js +0 -25
- package/dist/blastem/blastem.manifest.js.map +0 -1
- package/dist/manifest.json +0 -56
- package/src/blastem.manifest.ts +0 -27
package/README.md
CHANGED
|
@@ -1,41 +1,117 @@
|
|
|
1
1
|
# @wasm-gaming/blastem-wasm
|
|
2
2
|
|
|
3
|
-
BlastEm
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
})
|
|
21
|
-
|
|
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
|
-
```
|
|
27
|
-
make build
|
|
28
|
-
make
|
|
29
|
-
make build-wasm
|
|
30
|
-
make
|
|
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
|
-
|
|
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
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
|
|
41
|
-
|
|
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.
|