shmupX · packages/shmup-engine/src/sfc · reverse-engineering status
What @shmupx/shmup-engine/sfc decodes of a 1994 Super Famicom Dezaemon battery-SRAM save, and what stands between it and the parity the Saturn map reports. This cart was ported to the PlayStation as Dezaemon+, whose save keeps these region names in a new order — the PSX map. The series then went 3D on the Nintendo 64, whose 64DD data disk has a map of its own. Target is the original cart (Athena, SHVC-66): a little-endian 65C816, 512 KB of LoROM and 128 KB of battery SRAM dumped raw — no header, no interleave, no compression, nothing like the Saturn's BUP image. The ROM documents its own SRAM map, a 26-row ADDRESS NAME debug table at ROM 0x66A5, so every byte is labelled and the parser reads all 26 regions; but the only fixture is the factory sample with its graphics bank all zero, nothing has been traced through an emulator, and as of 2026-09-07 the parser is a read-only structural pass: nothing is played, mapped into game.json or written back. Canonical notes: packages/shmup-engine/FORMAT-SFC.md.
The SFC parser landed in one pass (2026-09-07) with the factory sample as its only fixture; on 2026-10-14 the ROM was traced statically — the chip banking, the map rows, the entry fields, the appearance tables, the scroll sequencer and the boot path — against that sample and ALDI Adventure, and a writer landed on it. SOLVED means the layout is traced, documented in FORMAT-SFC.md and consumed by code; MEANING OPEN means the bytes are located but a field's semantics are untraced; NO TRACE means nothing exists yet. Each item ends with what would close it.
32 bytes at 0x0000, repeated byte for byte at 0x7E5A, sixteen little-endian words. Traced statically — $00:847B computes, $00:8482 verifies, sharing a body at $00:848A. Each word is 0xFFFF minus the mod-216 sum of the words over a scatter/gather segment list; $80:8665 holds seventeen descriptors. Word 0 covers GRAPIC DATA and PALETTE DATA, 1–6 and 7–C the six stages twice over, D the ship/title/config group, E sound, F the block's own first fifteen words, so the block totals 0xFFFF by construction. SFC_CHECKSUM_DESCRIPTORS is the table transcribed; sealSfcChecksums() writes a save, verifySfcChecksums() checks one, and the probe report says "all 17 words verify" for both dumps. checksum.js · FORMAT-SFC.md
Also traced: the boot path. Word F (or the copy's word, with the block restored from the copy) gates the load, T.TABATA with four of eight bytes matching keeps the save, and words 0–E only raise a "CHECK SUM" message. RESERVED is never read.
A group word is not a VRAM tile number: the chip assembler $80:AC5D reads bits 8–10 as a sheet (0/1 the save's own 32 KB halves, 2/3 the ROM's factory art at 0x40000, 4 the editor's icons), bits 3–7 a chip row and 0–2 a column — offset = base + row × 0x400 + col × 0x40, the 2×2 chip's tiles at +0, +0x20, +0x200, +0x220 — and copies the chip into the SLOT the word occupies; the slot decides the VRAM tile ((i >> 3) × 32 + (i & 7) × 2). Bits 14–15 are the flips, 0xFFFF the empty word drawn as the ROM's blank chip 0x03FF. That is why the sample names only 0x200–0x3FF (its art is the ROM's, read at play time — the data-source flag $19CE) and ALDI only 0x000–0x1FF. Both saves render end to end under it: the stage maps, the ship sheet, the enemy sheets, the bosses. chips.js · groups.js · cover.js
What closed it: static disassembly of the assembler and the stage assembly's four passes (MAP GROUP → BG tiles 0x200+, MY SHIP → OBJ names 0x000–0xFF, BOSS → BG tiles 0x20–0x9F, ENEMY → OBJ names 0x100–0x1FF), then rendering both dumps. The shelf cover now draws through it, with the ROM when given.
0x5058-0x7E58: 16 songs of 0x2E0 bytes (the editor's clear copies one ROM block, $80:8E46, to all sixteen). BGM PATCH is one song number per slot — 0–5 a stage's song, 6–11 its boss song, 12 the title, 13–15 ending / clear / game over — and values from 0x10 pick the ROM's built-in songs, which is all the sample's patch does: its stream is never played. The bit-packed note format is still unread. The writer carries the sample's 16 songs and the sample's patch, so an exported game sounds like the factory game. tables.js · factory-data.js
What closes it: the APU upload path ($8F:FC78), or one note added in the composer, saved and diffed; and whether an all-zero song is tolerated.
ENEMY DATA is 6 stages × 0x200, not 24 × 128: five classes of eight-byte entries — 0, 1, 2 sixteen each (16×16, 32×16, 16×32 sprites), 3 eight (32×32), 4 four (64×64) — then a 32-byte boss block. The object builder $00:A713 reads byte 0 as the movement family (bits 3–7: 0 stationary, 1 straight down, 2–16 authored paths, 17–19 homing and dashes) and variant (speed), byte 1 the shot aim and rate, byte 2 the shot type and the item-drop bit, byte 3 the hit points ({1, 50 … 2000}) and two flags, byte 4 the score ({50 … 10000}) and the animation interval, byte 5 a shot parameter. ENEMY ODR is 320 bytes a stage of slot references into the stage's 64-slot enemy sheet, laid out by class: four 16×16 frames, two frames of two chips, two of four, one of sixteen. APPEAR DATA is 256 records of 14 spawn bytes (one per playfield column 1..14: valid, class, entry) and a 1,024-byte line table — one line per 16 px, one map row — naming the record that fires there; class 5 spawns the boss. enemy.js · groups.js · sfc-write.js
Still open inside it: byte 1's aim value (the writer copies the sample's), the shot types' shapes, the boss block's pair bytes and score table. What closes them: the shot routine $02:82AD and the phase logic $02:A337, or one enemy under Mesen.
MAP DATA is 128 rows of 18 bytes: two halves of eight cells and a flag byte — cell bit 7 the horizontal flip, bits 0–6 the MAP GROUP slot, the flag byte's bits the cells' vertical flips. The playfield is 16 chips (256 px) wide; the "18 columns" counted the flag bytes as cells, and the empty columns were those bytes. SCROLL EFECT's first 256 bytes are the map-row-block sequencer ($00:D851): entry i names the 4-row block of the map shown while the scroll runs through its 64 px, so the 128-row map plays in order and repeats across the stage's 1,024 lines by default, or is re-sequenced. The second 256 bytes (0x42) have no reader in the play engine: the scroll advances 1 px a frame, and loops inside the current window while a boss lives. map.js
What closed it: the stage loader $00:9B9C and the tilemap streamer, then rendering both dumps upright at 16 columns through real chips.
The read direction still has no SFC map-to-game.js: nothing decoded here reaches the editor's game.json. The pieces now exist — chips decode to pixels, entries to named fields, appearance lines to (column, class, entry) — so a mapper is a matter of assembling them the way the writer disassembles a level. index.js
What closes it: an SFC map-to-game over the decoded sheets, entries and lines; the writer's report is the inverse's checklist.
The launcher's SNES shelf boots the cart with a save as its .srm (EmulatorJS snes9x), and /api/sfc-save installs a save as Mednafen's SRAM for the ROM on this machine and starts it. What is still untested is a written save under the game: the first built image parses, verifies and renders, and the round trip in Mednafen is the next step.
What closes it: one run — deno task build:sfc, the editor's → MEDNAFEN (SRAM) row, the cart booting into the game.
exportLevelToSfcSram(level, art) builds the 128 KB image from a level record: the art quantised into the rows the game copies (scenery row n, enemies 6+n, boss 12+n, title 19) and cut into chips of the save's two sheets with mirrors shared; scenery into map rows and group slots; enemies into entries of the class their art fits, their frames into the stage sheet and ENEMY ODR, their waves into appearance records and lines; the boss into the 8×4 sheet with the sample's block and a class-5 spawn; the ship's three poses from the level's own frames (Duke when it has none) over the factory ship sheet, whose shots, bullets and items stay the ROM's; the title picture composed from the title editor's backdrop, logo and subtitle as the browser lays them out; the factory sound; the checksums sealed last; the image read back before it leaves. A row is written with a sprite's first colour in word 0, since the console lands rows one colour up. deno task build:sfc runs it from a shell, the editor's CONSOLE › SFC pick has DOWNLOAD .SRM and → MEDNAFEN (SRAM). sfc-write.js · sfc-format.js · build-sfc.ts
Templates inside it: the shot aim, the boss block, the ship sheet past the three pose slots (shots, bullets, items, explosions are the factory's), and hits × 25 against the hit-point table.
ALDI Adventure sits beside the ROM in dev-fixtures/SNES Dezaemon - Kaite Tsukutte Asoberu/, pulled from the SFC library, and the fixture-gated tests read both it and the sample: every claim above was checked against the two, and the checksum table reproduces all seventeen words of each. test/sfc-checksum.test.js · test/sfc-index.test.js
What would add to it: a save written by a real session, to catch whatever a one-stage test level does not.
Confirmed The bytes decode as the ROM's label says and a test locks it — never that a runtime consumes them. Rows regions.js calls likely or open say so: the stride is what the code applies, the semantics belong to section 03 — or, for the graphics bank, to item 2.
| Area | Coverage |
|---|---|
| Container | A raw 131,072-byte dump — no header, no interleave, no compression — of the 128 KB battery SRAM that LoROM maps as four 32 KB segments in banks $70-$73. Recognised by size plus the ASCII magic T.TABATA at 0x7FF8, the programmer's initials (ROM credits TSUTOMU TABATA 94/01/27); a 65,536-byte file is accepted too, everything but GRAPIC DATA lying below 0x10000. The boot code insists on exactly 128 KB — it writes $707E7B, the MOUSE SPEED word, and reads it back through the mirror — which is why copiers with more SRAM fail its S-RAM CHECK!. isSfcSav(); splitSegments(), four views tagged with their bank, present / blank; readChecksumBlocks(). sram.js |
| The ROM's own map | At ROM 0x66A5 the game keeps a debug table ADDRESS NAME, 26 rows of XXXXX-XXXXX NAME; regions.js is that table verbatim, spelling included (SCROLL EFECT, GRAPIC DATA), with a confidence and a note per row, and coverage() proves the 26 regions tile 0x00000-0x20000 with no gap or overlap. parseRomRegionTable() reads the table back and regionTableMatches() holds the two equal; readRomHeader() reads the internal header at 0x7FC0 — title DEZAEMON, map mode 0x30 (LoROM, FastROM), cart type 0x02 (ROM + SRAM + battery), size codes 0x09 / 0x07 for 512 KB / 128 KB, checksum valid — skipping a 512-byte copier header; romDefaultImage() / compareWithRomDefault() pull the 64 KB factory image at 0x50000, the one the game copies into fresh SRAM, and score a save against it. rom.js · regions.js |
| Palettes | PALETTE DATA 0x40-0x340: 24 rows × 16 BGR555 little-endian words, R bits 0–4, G 5–9, B 10–14 — the Saturn's own layout, so rgb555ToRgb() from decode-cg.js converts unchanged and rowsToPalettes() feeds indexedToRgba() laid out as the console draws a row: the game copies words 0–14 into colours 1–15 of the palette its layer owns, so a pixel of index k shows word k − 1 and word 15 is never seen. Rows 0–21 are colour (bit 15 clear): five identical default rows at 0x100, 0x120, 0x140, 0x160 and 0x180, a blue-grey ramp from 0x2A0, a red-to-yellow-to-white one from 0x2C0. Rows 22–23 (0x300-0x340) carry R/G/B ramps and primaries and each ends in a bit-15 word (0x87F7, 0xB76E) — the editor's own colour picker, by the look of it — so decodePaletteData() reports colorRowCount (22 in the sample) rather than assuming. cgram.js |
| Stage maps | MAP DATA 0x340-0x3940: 6 stages × 0x900, 128 rows of 18 bytes — two halves of eight cells and a flag byte, cell bit 7 the horizontal flip, bits 0–6 the MAP GROUP slot, flag bits the vertical flips — decoded as 16 × 128 cells of {slot, hflip, vflip}, row 0 the stage start. Traced in the stage loader $00:9B9C and rendered through real chips in both dumps. encodeMapRow() is the inverse. map.js |
| Scroll tables | SCROLL EFECT 0x3940-0x4540 as 6 × two 256-byte tables: the map-row-block sequencer (traced, $00:D851) and the 0x42 table no play-time reader was found for. writeDefaultScroll() writes the editor's clear image. map.js |
| Chip words and sheets | Every GROUP region is a list of chip words — sheet (bits 8–10), row (3–7), column (0–2), flips (14–15) — one per slot of the sheet the stage assembly builds: MAP GROUP 6 × 128, ENEMY GROUP 6 × 64, BOSS GROUP 6 × 32, TITLE GROUP 32, ENDING GROUP 12, MY SHIP GROUP 64. decodeChipWord, chipSource, decodeChipPixels (from the save or the ROM), encodeChipPixels; the ODR regions decode to slot references with flips. chips.js · groups.js |
| High scores and configuration | HIGH SCORE 0x7E8E-0x7FCE: 20 × 16 bytes — u32 score, four bytes not yet understood, char[8] name — two tables of ten; the sample holds the factory ladder 1000, 900 … 100 twice with ........ names. TITLE TYPE u16 (0x020A), MOUSE SPEED (0 — the cart supports the SNES Mouse; ROM string MODIFIED FROM SHVC MOUSE BIOS), EDIT BGM (0), BGM PATCH 16 bytes (11 12 13 14 15 16 16 17 18 16 19 1a 10 1c 1d 1b, one instrument per BGM slot), KEY CONFIG 20 08 10 20, RESERVED 0x7FD2-0x7FF8 about half 0xFF (20 of 38), RESERVED 0x20-0x40 zero but for 0x3160 at 0x3E. The scores and the five configuration words are fixture-locked; the two RESERVED ranges are counted confirmed by regions.js on the label alone — no test reads them, and their two observations are probe readings. tables.js |
| Enemy and appearance tables | ENEMY DATA as 6 stages of five entry classes (16/16/16/8/4 entries of 8 bytes) with every field named — family, variant, aim, rate, shot type, item drop, hit points, flags, score, animation — and the boss block's; APPEAR DATA as 256 records of 14 spawn bytes and the 1,024-line table. encodeEnemyEntry and encodeAppearByte are the inverses; the value tables (SFC_ENEMY_HP, SFC_ENEMY_SCORE, SFC_ANIM_INTERVALS, SFC_SHOT_RATES, SFC_STRAIGHT_SPEEDS, SFC_BOSS_HP) are the ROM's. enemy.js |
| Tile codec and sheets | SNES 4bpp planar 8×8 tiles both ways, flipTile, assemble2x2, tilesToIndexed, withPaletteRow; GRAPIC DATA as the save's two 128 × 512 px chip sheets (userSheetIndexed). Locked by synthetic round trips and by ALDI's 1,947 tiles rendering as its enemies and scenery. tiles.js · chips.js · graphics.js |
| Probe tool | deno task sfc:probe: report (per-region statistics, the checksum verification, entries and spawn lines per stage, the ROM cross-check, report.json), png palettes|graphics|map|scroll|groups (the map through its chips and the stage's own row, the two user sheets, the assembled ship / title / boss / enemy sheets through their rows — --rom for a cart that draws the factory art), hex --range, diff and all. tools/sfc-sav/main.ts |
| Tests | Eleven files: tiles, cgram, chips, sram, regions, tables, checksum, format, tile-bank, write, index, cover. The synthetic ones always run; the fixture-gated ones read the sample in fixtures/, the ROM and ALDI Adventure in dev-fixtures/ (all gitignored) and hold the checksum table to both dumps and the reader to the sample's decoded tables. test/sfc-*.test.js |
Likely What is still read off ranges and samples rather than the engine: a handful of fields inside regions whose layout is now traced.
0x3A40-… — cleared to 0x42; no reader in the play engine was found, and the scroll advances 1 px a frame regardless$02:82AD consumes; the shapes of shot types 0–2$02:A337; the phases cycle on a timerAbsent What has no code behind it yet.
./sfc subpath and nothing in the editor reads a cart back into a level (item 6)