shmupX · packages/shmup-engine · reverse-engineering status
What the importer already decodes of a Sega Saturn Dezaemon 2 save, and what still stands between it and full feature parity. Target is the Saturn release (big-endian SH-2, BackUpRam Format BUP saves, LZSS-compressed 8-section payloads) — not the SNES original, which has its own map, nor the two PlayStation Dezaemons, which have theirs, nor the Nintendo 64 entry, whose unreleased 64DD data disk has a map of its own — a format closed with no parser behind it yet. The canonical RE notes live in packages/shmup-engine/FORMAT.md; the pipeline imports and, since 2026-09-05, exports — exportLevelToSav writes a MiSTer-layout cart that boots and plays in Mednafen; real hardware is still untested.
Two reverse-engineering blitzes (2026-08-28) closed most of the original twelve items, a third (2026-09-01) closed the title screen and the staff roll, and an adversarial pass (2026-09-12) closed four more — the last of them the boss/zako hp ladder, which needed a tuning decision rather than a trace — and turned up two items that were not on the list. TRACED means the layout is read out of the engine and written down in FORMAT.md and only the runtime is missing; MEANING OPEN means the bytes are located but their semantics are untraced; NO TRACE means nothing exists yet.
Landed: an LZSS compressor that mirrors the decoder's ring (src/compress.js, within ~2% of the Saturn's own stream sizes), the section-table/checksum builder and BUP block allocator (src/bup-write.js — header at block 2, 0xFF-interleaved 32 KB + 512 KB image, 1,114,112 bytes), and the game assembler (src/write/game-to-save.js: CG pages under a Saturn or Super Famicom palette target, placement grids, enemy records, boss trailers, sprite banks, settings, songs). Exposed as exportLevelToSav, deno task build:sav and the editor's DOWNLOAD .SAV / → SAVE SHELF rows. Verified by re-import through this very parser and the editor (tests/sav_export_test.ts), and by booting, loading and playing the exported foo cart in Mednafen 1.29 with the real BIOS (2026-09-05); real hardware and MiSTer still untested. The 3D models are written too since 2026-09-12 (src/write/encode-model.js): an import's sec7 rides out on dezaemonModels and is re-encoded instead of the section being zeroed, so a cart keeps its ポリ吉 compositions — all 84 corpus saves that carry models (564 models, 3,165 parts) survive decode→encode→decode unchanged. Still unwritten: real item-icon art.
The weapon system was already exact — burst caps [0,3,3,1,1,6,3,2] and reload intervals [0,6,5,12,1,3,6,28], with the power-scaled drain correctly confined to type 7. The five geometries are now read leaf by leaf out of the handlers at +0xCA7C / +0xDF20 / +0xD06C / +0xE214 / +0xE664 and wired into the runtime: VULCAN B's five muzzle sets, MISSILE's per-shot lateral drift (zero at levels 0 and 1, which the old blanket “±32/±48/±64 by level” got wrong), HOMING's chain table with its per-chain opening aim, SHADOW's fixed ±4 × ±320 px strip, and WAVE's ball with the hit box the engine recomputes from its live scale each frame. Types 5 and 6 also take a different pair of tables when the SUB weapon is OPTION C, which the runtime was applying unconditionally — so its shadow column lived 10/14/19/23/28 frames where the normal path is 10/9/8/8/7. Every shot's damage now takes the ×1.5 the engine pays for flying with the SUB weapon off.
The bigger correction underneath it: the “level” every weapon table is indexed by is the OPTION count, not the power level. Both dispatchers read 0x0608411C, which the item the effect table calls power-up increments and which ship byte +2 caps at 4; the power level is the other array, 0x06084120, which the item called speed-up increments and which indexes the ship's velocity table alone. The corpus settles it: the initial option count is 0–4 across all 262 saves while initial power reaches 7 and the power cap is 5–7 in 175 of them, and every one of these tables has five entries. The runtime read the tables off the power level and clamped to 4, which hid the overrun but fired the wrong level for any ship whose two nibbles differ — Ramsie's, for one, which starts at option 0 and power 2. The two pickups are now wired the way their caps say.
Mostly closed 2026-09-02. The meshes were never in the overlay: the disc's MDLDT_01–56.CMP are the editor's part library, 56 files × 4 SGL meshes, each with three colour tables, and the shape word decodes as family:3 | colourSet:2 | meshIndex:7 (decode-model.js · decode-mdldt.js). A model viewer (/editor/model-viewer.html, Phaser 4 Mesh2D) draws every composition from the shipped mesh-library.json; DAIOH's ship renders as its own ポリ吉-made sprite. All three conventions were then traced through the overlay's SH-2 code (FORMAT.md · sec7 shape word): the family → file order is the resolver's own arithmetic (pages 0–5 = files 01–08 / 09–26 / 27–35 / 36–44 / 45–53 / 54–56), parts compose as T·Rx·Ry·Rz·S (SGL post-multiplies slRotX, slRotY, slRotZ), and the per-model colour word is a whole-model tint the shader folds into every polygon colour. The shader's other inputs were read too: the capture light is −(Rz(45°)·Rx(−50°)·(0,0,1)), fixed to the screen, driving a 32-row table, and the per-channel floors are 0 at capture time — so the viewer's shading is the Saturn's own. The last cosmetic scrap is closed too: POLYHELP.CMP is 43 help messages of 272×16 px 4bpp and POLYBTN.CMP a 256-colour palette plus a 139-sprite atlas, and the six families have no word names — ポリ吉 labels them with the Roman numerals I–VI and calls them ジャンル (genre), reserving “page” for the pages within a genre.
All three are entries of the 128-entry per-object state table at 0x06084590, and each is the plain bullet plus one action fired once, on a fixed distance travelled. None of them homes, which is what this runtime assumed while it flew them straight. State 19 flies 64 px and then snaps its heading to the volley's centre — one kink, not a curve — and reverts to an ordinary bullet. State 17 flies 64 px and then dies, becoming a five-fan along its own heading in the next bullet config. State 18 goes 96 px, half as far again, and re-aims at the player before splitting into a wider fan; with no player left it falls back to 17 exactly. Only two geometries stamp them: 8 on all five of its shots, and 9 on its single one, picking 17 or 18 by the aim bit. All three are now decoded onto the record and run in the runtime, verified in a live scene against the traced distances and spreads.
Two corrections came with it. The boss dispatcher routes nibbles 10/11/12 to its burst handlers, not 9/10/11, so boss fire points do reach geometries 8 and 9 — 84 and 43 of them across 62 saves. And the shooter's spawn flag reads backwards from its name: 1 means a heading-relative volley and 0 means an aimed one, which is what makes geometry 9's aimed shot the one that re-aims when it splits.
Both of this item's predecessors were closed, 2026-09-12 corrected the item itself, and the same day closed it. Record byte 2 bits 0–2 IS hp, and byte 1's [60,30,15,…] is the animation period — the zako initialiser settles it, and an adversarial pass then confirmed all four field readings from the editor's own widgets as well as the engine. The ladder reads 1/3/5/10/20/40/50/100 full-power hits, and the 256× weapon-damage bug it exposed is fixed.
The tuning decision is made: the discount is gone. map-to-game.js now sizes a boss with the same divisor as a zako, shotDamage × 256, so the eight-step ladder lands on its traced 200–1950 hits instead of a 4×-discounted 50–488. The discount was never a divergence anyone chose — it was filed as a trace gap, justified in a comment by a premise (“how player shots scale against boss hp is untraced”) that is now refuted, and calibrated against the stock game's 100–500 on the wrong axis: 2028-AI's own zako stop at 30 hp beside its 200–500 bosses, while an imported zako runs the full ladder to 100, so matching the absolute hit count while leaving zako undiscounted is precisely what broke the ratio. Measured over the corpus, the discount left 31 of 1,455 comparable bosses strictly weaker than the toughest shootable zako of their own stage (36 no tougher; 0 either way at the traced divisor) — shootable because only 40.5% of the 58,249 placed zako records can be hit at all, the rest carrying ARMOUR or NO-COLLISION. It also killed a median boss in 8.6 s — a third of them inside their first movement script, so most of the authored four-patterns-per-band choreography never played. At the traced divisor the median fight is 34.3 s, about one audible BGM loop (median 33.6 s), and there are no inversions. Driven live in the runtime, Ramsie's stage-0 boss now spawns at 900 and dies in 37 s at a measured 19.5 dps.
Two things had to move with it. The .sav write path's BOSS_UNITS_PER_HIT was the divisor's inverse for an authored boss and is now simply SHOT_UNITS (an imported boss round-trips through its raw units and never used it). And 2028-AI's 99-second boss timer — which is a game over, not a stage clear — no longer arms on an import: Dezaemon 2 has no boss time limit, nothing in the traced boss code counts down, and at honest hp a slow loadout measures ~93 s against the hardest boss. Also fixed: a placed boss whose 0x40 trailer is all zeroes (137 records) was silently inheriting the stock starter's 150 hits; the engine does not special-case a zero trailer, it just reads index 0, so it now sizes from BOSS_HP_TABLE[0] like the hardware.
The scaler's second multiplier is implemented too. Every hp the engine hands a spawning object passes +0x15358: ×2/3 EASY, ×1 NORMAL, ×1.5 for both HARD and MANIAC (four difficulties, three factors — and difficulty is a menu choice with no per-save byte, so an import is the NORMAL column by construction), and then a further ×1.5 when both players are in play. It has exactly three callers, all spawn-time initialisers, and nothing re-reads the flag in any damage path — so the runtime now applies it at spawn only: what is already on screen keeps its hp, and a ship joining or going down changes only what spawns next. Every figure here is the one-player normal case; the real envelope runs 200–1950 at 1P/normal, 134–1300 at easy, and 450–4388 at hard with two players.
One sentence this item used to carry is retracted — and so is the retraction it replaced. Boss and zako hp really are separate tables, 0x06085F20 and 0x06085F40, ratio 4000× down to 19.5×. But “the caller that shifts the table >>2 is not a boss path” was wrong: it is where a boss's destructible parts get their hp. The fire-point dispatcher has two arms and the earlier pass conflated them — the type-3 arm reads no hp table and stores the parent's heading (that is the “facing angle” the retracted sentence described), while the type-4 arm indexes 0x06085F40 by the fire point's rate nibble and shifts it, giving a one-shot part 50–488 hits — the very numbers the old core divisor produced, which is the coincidence that made it look plausible. A type-3 part carries ordinary zako hp from its own record, and killing parts never damages the core. One more correction: the corpus ratio is not “exactly 4.0” but exactly 4.0 for 684 of 1,527 records, median 3.9959.
And the parts now carry it. The runtime gave every part a flat 16 hp, or 32 for the large bands; both types are now sized from the save. A part is built by the same initialiser a grid-placed zako goes through, so its score and its armour attribute come off that 18-byte record too — Ramsie's two turrets turn out to be armoured, i.e. indestructible hazards rather than something to shoot off, where the flat 16 had them dying in a second. One divisor does all of it, the same shotDamage × 256 a zako and a core take, so every ratio the author wrote survives the import. The corpus corroborates the split without being asked: a type-4 rate nibble matches its own boss's hp index ×1.87 over chance across 268 games, while type 3 — same byte, same nibble, same editor widget — sits at ×0.98. And the type-3 nibble is now wired up too: it is a respawn period in Saturn frames (0x06085F80, or 0x06085F90 under an F0 core), counted by the per-frame executor rather than by the pattern's fire-tick divider, where the runtime used to invent rate + 2 and then count it on the bullet clock — running anywhere from 0.017× to 540× the traced cadence. The liveness check is gone with it, as the engine has none; the one departure kept is for armoured parts, which this runtime cannot kill, so those still respawn one at a time.
A part's 32-byte step block is a voice column then a pitch column, and decode-song.js decided whether a step sounded by looking at the voice byte — a zero there ended the note. The kernel's note sender does the opposite: it tests the tie bit first, then keys on the pitch byte alone, and the voice byte only selects an instrument. Voice 0 is instrument 0, a real tone-bank voice, not a rest. Over the 258-save corpus that reading dropped 72,282 sounding steps and left 25 songs completely silent — every one of them a song whose composer never moved off instrument 0. The runtime bundle always read the pitch column, so the editor's preview was the half that disagreed with the hardware; the two now match, and 4,311 of the 4,312 non-empty songs in the corpus decode to notes. The one that still does not is a slot whose only pitch bytes are the 231–255 garbage tail, which the decoder clamps away deliberately. Three smaller documentation errors went with it: the per-measure transpose reaches the four pitched accompaniment channels and not the three percussion ones, the sustain byte is only ever 0x80 and never 0x81–0x88, and bit 7 of measure control byte 2 is an undocumented per-measure flag set in most measures.
Opened 2026-09-12, while closing a larger item. The four change channels were re-traced end to end against GAME.bin and four readings turned out to be wrong. Record bytes 6–8 are not a speed channel: they drive 0x06094A40, the third register of the engine's scale triple, which every object initialiser seeds to ×1.0 beside the per-axis pair and which the per-frame pass copies into both hitbox half-extents — a uniform zoom, on 23,552 of the corpus's 75,502 records. The repeat codes 1 and 2 were the wrong way round (1 is ping-pong, 2 is loop; 16,131 records). A ramp is measured by unsigned distance travelled, not by reaching the end value, which is how an angle sweeps the long way round and how a rotation whose start equals its end makes a whole circle (9,664 records). And rotation modes 3 and 4 overwrite the channel's repeat byte with their own number, routing the stepper to a target-tracking arm and killing whatever the record authored (8,490 records).
That pass also retracted a hardware measurement this page and FORMAT.md had carried since 2026-09-12: that all three scale modes zoom both axes. The spawn routine arms the first register for modes 1 and 2 and the second for modes 1 and 3 — exactly the editor's XY / X / Y labels — and the confound is visible in the very enemy the measurement used, Ramsie's falling rock, which runs a ×1.5→0 one-axis ramp and a ×4→0 uniform zoom at the same time. What is left open is small and cosmetic: the two axis registers are plainly distinct in the trace, but nothing there says outright which of them is the horizontal. The decoder follows the editor's list order; confirming it needs one hardware capture.
The ending scene is still stock 2028-AI. Demo/attract recordings live on the retail disc rather than in saves, so this is bounded work — but nothing is decoded for it yet.
Confirmed Checksum-proven or engine-disassembly-traced, and driven end-to-end by the runtime. These need no further RE work.
| Area | Coverage |
|---|---|
| Container | gzip .bcr / interleaved cart dumps / raw .bkr → BUP partitions, directory entries (Shift-JIS names, dates), fragmented block-chain reassembly, full 0x6C section-table + checksum validation, Okumura LZSS. bup-parse.js · payload-table.js · decompress.js |
| Graphics | sec0–3 CG pages (8bpp, 16×16 cells), sec4 RGB555 palettes, background tilemaps with corrected flip bits, per-stage sprite composition bank with boss-core geometry, drawn title screens, and the save's own global art — player ship, item icons, bullet animations, blast frames. decode-cg.js · decode-sprites.js |
| Levels | Placement grid (72 ids), stage count, per-(stage, record) enemy identity, and the authored scroll curve: speed table with easing, wave amplitude and type, per-stage extents. Spawns are scroll-position locked, so pacing survives the round trip. decode-stage.js · map-to-game.js |
| Enemy AI | The 18-byte record plus the engine's own choreography: all 256 appearance behaviour scripts (1,206 rows) interpreted live, the six hardcoded special classes 0x31–0x36, the 16-entry fire-geometry table with the 10/11/12 burst handlers, the four change channels run the engine's way — a signed accumulator against an unsigned sweep, so an angle can turn the long way round — each armed by its own 3-bit field of the per-slot status word, on the traced pixel line shifted by the record's art band and crossed from the air side or the ground side as the flag says, and the hardware terrain-ride model — anchored riders recomputed absolutely from a map anchor, plain riders stepped by the frame's whole pixels, everything else holding station. decode-enemy.js · appearance-table.js · game.bundle.js |
| Death word | Record bytes 2–3 — long mis-read as "fire type / fire params" — are the death word, now implemented in full: item drops by authored slot, child spawn of a successor at the dying enemy's exact position (inheriting an anchored parent's terrain anchor), and chain-kill of every object sharing a formation key in a four-tick ripple where each link runs its own death word. Byte 4 selects silent / small / full blast. decode-enemy.js · game.bundle.js |
| Bosses | 0x40 trailer decoded (size class, HP bands, pattern playlist, 4×14-byte patterns with 3 fire points) and all 32 engine movement scripts embedded with their step interpreter, including the arrive/death selectors that place the authored off-screen start, the death-drift target and the zoom/spin flourishes. Boss parts now carry their own hp and score (2026-09-12) rather than a flat 16/32: a part is built by the same spawn a grid-placed zako is, off the 18-byte record its (group, piece) names, so score and the armour attribute come from that record — and hp splits by type. A type-3 mobile part keeps the record's zako hp; a type-4 turret has it overwritten from the boss table at the fire point's rate nibble, >>2. Ramsie's two turrets turn out to be armoured, i.e. indestructible hazards, not things to shoot off. decode-boss.js · data/boss-move-scripts.json |
| Items & weapons | Eight item slots decoded as movement<<4 | type across nine types with their three launch behaviours, drops dressed in the save's own icons; weapon loadout presets and real per-level damage tables replace the refuted "+3 nibble = main weapon" reading. decode-settings.js · map-to-game.js |
| BGM / SFX | sec6 decoded (24 songs × 32 measures × 4 parts × 16 steps, byte-exact tempo table, loop, echo, transpose) and synthesized live in WebAudio from the save's bytes — not prerecorded. Which column starts a note was corrected on 2026-09-12: the pitch column alone, never the voice column (item 6). Timing is engine-exact. Now with the kernel's auto-accompaniment: a measure's control bytes pick seven pattern channels (three chords, a bass, three percussion) out of the 1,260-row ROM table, transposed and voiced exactly as the driver does it. Instruments are the save's own: each note picks its tone-bank voice, and multisampled banks pick the LAYER covering that note. decode-song.js · data/bgm-accompaniment.json · game.bundle.js |
| Timbres | The 116 tone-bank instruments ship as harmonic profiles derived by spectral analysis of the retail sample bank — analysis output only, never sample audio, which is disc content. Each is rebuilt at runtime as a WebAudio PeriodicWave with the bank's own envelope and level, replacing four fixed square/triangle/noise voices. The instrument map's SNDPAC.BIN offsets and loop points are now read too: hand the runtime the disc's sample bank and it cuts the 85 distinct slices out of it and plays the real Saturn samples, loop points and all — reverse and ping-pong loops baked down to forward loops, every layer of an instrument struck at once so the detune pairs chorus. Since 2026-10-28 the cut bank is published with the game (assets/tone-bank/, deno task deza:tonebank --web), so the web plays the real samples everywhere; a build that leaves it out falls back to the periodic-wave voices. data/bgm-voices.json · data/bgm-instruments.json · src/audio/tone-bank.js |
| Player weapons | The loadout's four presets drive the ship: eight bomb behaviours (flash sphere, rising pillar, tether, expanding ring, lobbed ball, ship aura, ship-as-projectile, rising wave) as piercing per-frame contact objects with their traced growth curves, lifetimes, invincibility and one-in-flight stock rule — and since 2026-09-12 those run on the Saturn's clock: the bomb was the one Dezaemon subsystem that neither gated its state machine to one step per engine frame nor converted its units per tick, so this runtime, which steps twice a frame, grew every bomb twice as fast, ended it half as early, and billed each overlapping enemy double damage. It is now gated the way the weapon and boss state machines are, with the draw and the type-6/7 ship-follow left running every tick; the charge gauge with its levels, busy counters and sub-weapon suppression; and the sub weapon at engine-exact cadence. Option pods are real after all — the 2026-08-28 “no option pods” refutation looked at the MAIN field and generalised. The editor's SUB values 5/6/7 are literally named OPTION A/B/C, and they never reach a shot dispatcher: a per-frame hook (+0x1CEDE) drives three handlers that keep a persistent four-slot object block per player. Now implemented (2026-09-02): A is an orbiting ring of up to four indestructible contact-damage pods that widens and speeds up while held, B a flanking pair that aims away from your stick and fires on its own reload, C a trail that rides your path and re-muzzles the MAIN weapon through every pod. The count is the OPTION stat (ship byte +2), which this codebase had been reading as the shot power level. One adaptation: the engine widens A's ring while the C button is held, and since this runtime autofires it has no held-fire button to inherit, so the ring gets its own input exactly as the charge did: Z on a keyboard, M for player two, or either bottom trigger (L2/R2) on a pad — the two buttons that used to be a sixth and seventh way to fire the bomb. The MAIN and SUB labels were transposed and are now fixed (2026-09-02): the editor's own ARMS panel names byte0 bits4-6 MAIN and bits0-2 SUB, so the weapon this runtime implements is the ship's MAIN gun, and its seven values are the editor's VULCAN A, VULCAN B, MISSILE, HOMING, SHADOW, WAVE and BOUND. A charge above 31 suppresses the MAIN weapon always and the SUB only when the SUB's type is 7 — matched here since 2026-09-02, when this runtime stopped suppressing both unconditionally. decode-settings.js · game.bundle.js |
| Title & staff roll | The save's drawn TITLE 1/2 run the authored entrance program: settings +0x29..+0x2C — the editor's two 5×3 icon grids, the "15 slots" per logo — are ten tri-state fields (vertical entry, horizontal entry, spin, height and width scale per logo), each a straight 128-frame line onto the rest pose, then the 32-frame white flash and the blinking PRESS 1P START BUTTON. FORMAT.md's "one fixed sway-in" was wrong. The ending plays the traced staff roll: the three role labels typed at 4 frames a character over the stages' scenery, each of the six 64×16 credit strips flying in from a corner over 128 ticks (3.0×→1.0×, one turn, afterimage trail, 4× on START), and the title's STAFF ROLL card lists the same labels with their strips. Also found on the way: the BGM table has four special tracks, so every stage's music was one entry off. decode-settings.js · decode-sprites.js · game.bundle.js |
| Two players | Settings bit1 is live: a second ship joins in mid-run on a free pad (or player 2's own keys), flying the save's own P2 art from global bank refs 24–47 and its own weapon preset from ship block +0x10. Each ship carries its own HP, combo, powerups, barrier, charge, sub weapon and bomb — the engine's one-bomb-per-player rule included — and enemies aim at a single global target that alternates between them on a timer, as traced. One player's death does not end the other's game; the run ends only when both are gone. One deliberate divergence from hardware: score is shared, not per player, and the HUD splits the HP and combo troughs vertically (player 1 on top) rather than showing two rows. decode-sprites.js · map-to-game.js · game.bundle.js |
| Orientation | A horizontal save is the SAME simulation drawn transposed, so the world needed no rotation — what it needed were its own numbers, and it has them: scroll rate ×365/256, a scroll window reaching 96 px further past the entry edge, and the horizontal change-channel trigger lines (14/48/116 px instead of 62/112/164). map-to-game.js · game.bundle.js |
| 3D | sec7 decodes: magic, 16 model slots, 9 parts each, 16.16 positions / rotations / scales with mirror-by-negative-scale, and the shape word's family / colour set / mesh index into the disc's 224-mesh ポリ吉 part library, which ships as mesh-library.json and is drawn by the model viewer on Phaser 4's Mesh2D (CPU projection, painter-sorted, flat-shaded). decode-model.js · decode-mdldt.js · model-mesh.js · model-viewer.html |
Partial Bytes extracted and carried through, then nothing reads them — cheap wins once the runtime grows a consumer.
BOSS_HP_TABLE[rate] >> 2 — 50–488 hits — and a type-3 (respawning) part carries ordinary zako hp from its own enemy record; decode-boss.js already puts rate and spawn.record on every fire point, and the runtime still gives every part a flat 32/16.Absent Real Dezaemon 2 features with no code behind them.
Three entries left this list on 2026-09-12. The write path shipped on 2026-09-05 and is item 1 above. What the six ポリ吉 part families are called turned out to be a non-question: the editor numbers them I–VI, and POLYHELP.CMP and POLYBTN.CMP are both decoded (item 3). The dev tooling FORMAT.md used to reference — dev/scan-compression.js, dev/decode-corpus.js, dev/diff-saves.js — was never written, but the work it was meant to do is done by what is in dev-fixtures/debug-tools/ now: sh2dis.mjs for the engine, extract-disc.ts for the whole disc, dump-behavior.mjs and render-chamber.ts for a save.