@wasm-gaming/fbneo-wasm 0.1.0 → 0.1.1

package/README.md

@@ -35,7 +35,61 @@ 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`.
+
+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. Convert it to a bootable ROM set first:
+
+```sh
+node scripts/neo2romset.mjs mygame.neo --out ./roms
+```
+
+It identifies the driver by matching the `.neo`'s region sizes against FBNeo's own
+chip tables, rebuilds the individual chip dumps (de-interleaving sprites, undoing
+the `HARDWARE_SNK_SWAPP` program-ROM swap), and CRC-verifies every chip before
+writing `<driver>.zip` — so it fails loudly rather than emitting a broken set. It
+reads the chip tables from a FBNeo checkout (`.tmp/fbneo-build/…` by default, as
+left by `make build-wasm-ci`; override with `--src`).
 
 ### Options