@wasm-gaming/fbneo-wasm 0.1.0 → 0.1.2

package/README.md

@@ -35,7 +35,84 @@ engine.start();
 FBNeo identifies a game by the ROM zip **filename** (without extension). Pass the
 game short name explicitly via `options.driver` (e.g. `"mslug"`, `"sf2"`,
 `"kof98"`), or let it be inferred from `options.romFileName` / the picked file's
-name.
+name. (The bytes are always written to MEMFS as `<driver>.zip`, so the source
+file itself never needs renaming — only its *name* has to resolve to a driver.)
+
+### Identifying a ROM set from its contents
+
+When the filename is unreliable (a browser-mangled `mslug (1).zip`) but the ROM
+files inside must keep their canonical names, recover the driver from the zip's
+**contents** with the opt-in `@wasm-gaming/fbneo-wasm/romset` helper. It matches
+the CRC-32s stored in the zip's central directory against a dataset of every
+FBNeo ROM set — the same identity FBNeo uses internally — so it is unaffected by
+re-compression, entry reordering, or split/merged packaging.
+
+```js
+import { RomsetIndex, resolveDriver } from '@wasm-gaming/fbneo-wasm/romset';
+
+// Load the dataset for the system(s) you support (per-system JSON, loaded on demand).
+const neogeo = await fetch('/romsets/neogeo.json').then((r) => r.json());
+const index = new RomsetIndex([neogeo]);
+
+const match = resolveDriver(romZipBytes, index); // { driver: 'mslug', coverage: 1, ... } | null
+const engine = await load({
+  canvas,
+  assets: { rom: romZipBytes },
+  options: { driver: match?.driver }, // fall back to your own logic when null
+});
+```
+
+The dataset ships as `data/romsets/<system>.json` (also served at `/romsets/…`
+from the built `dist/`); `data/romsets/index.json` lists the systems and game
+counts. Regenerate it from a pinned FBNeo checkout with `make romsets`.
+
+Each ROM entry carries its internal name (`n`) and CRC-32 (`c`). `neogeo.json`
+additionally carries each chip's size (`s`) and hardware region (`r`) — the chip
+*layout* — which is what lets the `neo` helper below rebuild a ROM set from a
+flash-cart image.
+
+Because the match is by CRC-32 — and FBNeo itself looks ROM chips up by CRC
+before falling back to their names — a set is usually accepted as downloaded:
+extra files, subdirectories, and non-canonical chip filenames inside the zip do
+not matter. Only the zip's *name* has to resolve to a driver, which is exactly
+what this helper supplies.
+
+### Neo Geo `.neo` files (NeoSD / Terraonion)
+
+FBNeo reads `.zip` and `.7z` ROM sets only. A `.neo` — the single-file format for
+NeoSD/Terraonion flash carts, and how most Neo Geo homebrew is distributed — is a
+4 KiB header followed by each ROM region as one contiguous blob (with the sprite
+region byte-interleaved as the cartridge wires it), so it cannot be handed to the
+engine as-is. The opt-in `@wasm-gaming/fbneo-wasm/neo` helper rebuilds the chip
+split FBNeo expects, in the browser and with no dependencies:
+
+```js
+import { isNeoFile, neoToRomset } from '@wasm-gaming/fbneo-wasm/neo';
+
+const neogeo = await fetch('/romsets/neogeo.json').then((r) => r.json());
+
+if (isNeoFile(bytes)) {
+  const { driver, zip } = neoToRomset(bytes, neogeo); // throws if it cannot be rebuilt
+  await load({ canvas, assets: { rom: zip }, options: { driver } });
+}
+```
+
+It identifies the driver by matching the `.neo`'s region sizes against the chip
+layouts in `data/romsets/neogeo.json`, rebuilds the individual chip dumps
+(de-interleaving sprites, undoing the `HARDWARE_SNK_SWAPP` program-ROM swap), and
+CRC-32 verifies every chip before returning — so it throws loudly rather than
+handing the engine a broken set. The zip it returns is *stored*, not deflated:
+FBNeo decompresses each chip immediately, so compressing would only be undone.
+
+The same conversion is available offline, which is handy for preparing a set once
+rather than on every page load:
+
+```sh
+node scripts/neo2romset.mjs mygame.neo --out ./roms   # needs `make build-lib`
+```
+
+Sets whose program ROM lives inside the SMA custom chip cannot be reproduced by a
+straight carve; those fail CRC verification and are reported rather than written.
 
 ### Options