shmupX · dev-fixtures/dezaemon298.ddd · reverse-engineering status

Dezaemon N64 Parity Map

The odd one out among these four maps. The other three describe parsers that exist — the Saturn map, the Super Famicom one, the PlayStation one. This one arrived last and caught up fastest. @shmupx/shmup-engine/n64 reads dev-fixtures/dezaemon298.ddd and deno task n64:probe looks inside it: all 60 files extract, and 58 of them decompress to exactly the byte size third-party documentation predicts, using this repo's own LZSS decoder unmodified. What it is not is a consumer: nothing is played or mapped into game.json. It is no longer read-only, though — since 2026-10-14 disk-write.js writes a disk back, and deno task build:ddd presses a level's art into one (item 11). Target is the unreleased 64DD expansion for Dezaemon 3D (Athena, 1997): a prototype data disk written 1998-02-23 19:24:25 from a Partner-N64 unit, disk ID DEZA, carrying a filesystem that is Athena's own (ATNFS0) and not Nintendo's MFS. Surveyed 2026-09-19, the writer added 2026-10-14. The canonical notes are packages/shmup-engine/FORMAT-N64.md.

.ddd = .ndd minus the 24-LBA system area → libleo LBA → byte 85 sectors × 232…112 → ATNFS structure-of-arrays · names · startLBA · blockCount · u32 stored size → Okumura LZSS (decompress.js, unmodified) → per project GAM · CGR · CMD · CBL · ULB · MUS + 8 stages × {BL · MD · GR} ‖ parser · probe · FORMAT-N64.md · write path → .ddd / .ndd · no game.json · launcher row (untested)
Format knowledge Confirmed the container, the read-only directory, the codec, and the two graphics types — 8,683,520 of the 12,596,477 bytes a project decompresses to, 69%, and it is that high for the same reason as on the PlayStation page: the graphics are two thirds of the payload Likely CMD · CBL · ULB · #BL · #MD · GAM and the writable directory — 3,638,925 bytes, 29%: documented field by field by a third party whose arithmetic closes exactly, and not yet checked struct by struct against these bytes Open the MUS sequence body — 274,032 bytes, 2%: 24 songs of 0x2C9A of which only the 0x1A-byte header is described
Shipped in this repo Decoded 100% of the disk's bytes now extract and decompress through committed code, and 69% of them — CGR and the per-stage GR — are decoded the whole way to pixels you can look at Extracted only 29% · CMD · CBL · ULB · #BL · #MD · GAM come out as correct decompressed bytes with no typed reader over them yet Undocumented 2% · the MUS sequence body, which extracts like everything else and which nothing can read

01What remains

Unusually for these maps, almost none of what remains is reverse engineering. The format was closed in a single pass (2026-09-19) once the prior art was found — a canonical dump of the same disk on 64dd.org and a field-by-field format document shipped with a 2024 fan translation. What remains is mostly writing the code. MEANING OPEN means bytes located at a stride something gives but whose semantics are untraced; NO TRACE means nothing exists yet.

  1. 1

    The parser itselfDONE 2026-09-19

    Landed. packages/shmup-engine/src/n64/ is the parser — geometry.js for the LBA map, directory.js for ATNFS, graphics.js for RGBA5551, index.js as the front door — behind the "./n64" subpath export, with tools/n64-ddd/main.ts over it as deno task n64:probe and 19 tests in tests/dezaemon_n64_test.ts. Eighteen run anywhere against a synthetic disk built in the test file; the nineteenth is ignore:-gated on the fixture and is the one that asserts 58 of 60. What is not done is downstream: no typed readers for the record formats (section 03), no game.json. FORMAT-N64.md and the write path followed on 2026-10-14 (item 11).

  2. 2

    The zone table above LBA 368DONE 2026-10-14

    Landed. geometry.js holds the full table — two heads, sixteen physical zones, the per-disk-type vzone → pzone permutation for types 0–6 — and lbaToOffset() over every user LBA, 0 to 4291, with the ROM area ending at LBA 1417 and the RAM area running 1418–4291 on the Dezaemon disk's type 0. All 60 sample files still live below LBA 368, where the map degenerates to lba × 19720 under LBA 268 and 268 × 19720 + (lba − 268) × 18360 after it, and three measurements of the fixture pin the rest: those 268 blocks of 19,720 bytes and then 18,360 (the directory's own blockCount arithmetic, item 1); the three directory copies landing at exactly in-block offset 834 of LBA 1417, 1419 and 1422 under this ordering of the sector sizes and under no other; and the sixteen zones summing to 64,458,560, the length of every .ddd. It is cross-checked against jkbenaim/leotools's leogeo.c and mupen64plus-core's src/device/dd/disk.h, which agree with it and with each other. The warning stands for anyone re-deriving it: the ordering is not a monotone 232→112 descent.

  3. 3

    How big the directories actually areMEANING OPEN

    The read-only directory has 60 populated entries and the writable one 21 used slots — 11 live including DEZA3D.SYS, DEZA3D.HSC and nine files of a user project DST, plus 10 tombstoned. Those counts are measured. The capacities — 834 and 480 slots, the latter reading as 16 projects × 30 files — are inferred from the strides between the parallel arrays, and those strides run through zero fill, which cannot distinguish a large array from a small one followed by padding. One disk cannot settle it. Take the slot count as a parameter; do not hard-code 480.

  4. 4

    The MUS sequence bodyMEANING OPEN

    24 songs of 0x2C9A each, 0x42E70 total, and the documentation describes the 0x1A-byte header and stops. That leaves roughly 11.4 KB per song of sequence data with no reading at all — the single largest undocumented run on the disk and the whole of the open band in the meter above. It is also the one item with no cheap route: the playback code is on a cartridge nobody has, so it would have to come out of the bytes alone. Budget a week and expect it to resist.

  5. 5

    The fields the documentation marks ???MEANING OPEN

    Its author says so plainly — "please note these are not complete!" — and leaves named gaps: #MD +0xC11..0xC1F, #BL 0x47, 0x5B and 0x8B2F, and GAM 0x1, 0x225, 0x557, 0x558. Separately, one of its counts is demonstrably wrong: it claims 520 images for #GR, and 0x104000 ÷ 2 bytes ÷ (64 × 32) is 260. Take its dimensions, not its totals, and re-derive every count from the size.

  6. 6

    Why the two GAM files are nine bytes shortMEANING OPEN

    SAMPLEZ1.GAM and SAMP.GAM decompress to 1,360 bytes where the documented structure is 1,369 — the only two misses in sixty, and the deficit is identical. This is not a defect in the read path: the same documentation warns by name that "in the recovered prototype disks, SAMPLEZ1 & SAMP's GAM file data has slightly different, incompatible formatting", and these are exactly and only those two files. So the miss is a fourth independent confirmation that the chain is right. What the nine bytes are is still unknown, and a retail disk would presumably settle it — except no retail disk exists.

  7. 7

    The DezaDiskTool bytecodeNO TRACE

    The fan-translation release ships DezaDiskTool.exe, a PyInstaller bundle whose three Python bytecode bodies were extracted during this survey but not decompiled: the tool proper (46,491 B — a Filetable class, a known_sizes table, an 8.3 name helper, an LBA-usage checksum), its LZSS module (10,359 B), and an N64 helper (40,813 B). Running pycdc or decompyle3 over them would hand over the size table and the exact list of which extensions are compressed as someone else's tested code rather than as inference. Half a day, and it retires most of items 3 and 5. This is the highest-value unspent hour on the page.

  8. 8

    This fixture is the wrong dump for the save areaMEANING OPEN

    64dd.org labels our file the "Old Dump" and hosts DEZA_1_19980223.zip as current. They differ in 175,897 bytes, every one of them inside the save area (0x18CF180–0x1922C3F); the ROM area holding all 60 sample files is byte-identical, so nothing else on this page is affected. But the DST user project lives in exactly the region that differs, and a 2021 64dd.org note describes correcting a dump that "may have been tampered by accident". If anyone parses DST, use deza1.NDD, not this fixture.

  9. 9

    No controlled delta is possible hereNO TRACE

    The method that promotes a claim to confirmed on the other three maps — change one thing in the editor under an emulator, save, diff — still cannot be run. It needs a 64DD emulator, a disk writer and the DEZA64 cartridge: the writer exists now (item 11); the other two are still missing here — no emulator or disk fixture is in CI, and the cartridge was never released. So for this platform confidence tops out at likely for anything not provable by arithmetic, and a disk the writer builds is untested on hardware or in an emulator. That is precisely why the exact-size test in section 02 carries so much weight: it is the only arithmetic proof available, and it happens to cover the entire chain at once — and the writer's own check is the same proof run backwards, the prototype rebuilt from its two projects coming out the same bytes.

  10. 10

    A viewer, and then the ceilingNO TRACE

    Worth stating plainly so nobody plans past it. Neither psx-sav nor sfc-sav output ever reaches this repo's game.json; the only pipeline into a playable level is the Saturn .sav path. And Dezaemon 3D is a 3D shooter whose data model — s16 vertex meshes, baked per-face lighting, texture tile descriptors — does not obviously map onto a chip-grid 2D level. So the credible deliverable is a viewer, in the shape sfc:probe and psx:probe already have: report, hex, png, then a shelf cover. A launcher row exists since 2026-10-14 — the n64dd core in static/emulators.json, static/n64dd/play.html on EmulatorJS's mupen64plus-next, and the editor's → PLAY 64DD row, which boots the disk beside the operator's own Dezaemon 3D cartridge (translated to English by the 2024 patch under static/n64dd/) and 64DD IPL — but it is untested in a browser here, and the disk it boots carries the level's enemies as the document's records say they are laid out, which no one here has seen the game read (item 11).

  11. 11

    The write pathDONE 2026-10-14

    Landed, and honest about how far it reaches. disk-write.js builds a disk — buildDisk(), putProject(), removeProject(), convertDisk() — on a donor .ddd/.ndd or from nothing: the files laid end to end from LBA 9 in directory order with their block counts walked through the zone table (item 2), the read-only directory encoded as its five parallel arrays (directory.js) and written in its three copies, the 0xFF run up to the directory's block, the donor's RAM area carried byte for byte, and for an .ndd a system area (system-area.js) that passes the checks mupen64plus-core makes before it mounts a disk. project-write.js makes a project out of a level: each frame one 64×32 RGBA5551 texture (shrunk to fit when bigger) laid into the blank slots of CGR and the stage GR sheets, never over a painted one; then, through the typed codecs of records.js (section 03), a billboard model per frame in #MD, an enemy entry per letter and drop digit in #BL with its frames' model numbers, score, HP, speed, shot and item, the boss with the stage-clear flag, the layout of every cell on the map layer at the frame its row scrolls in, the ship and item icons as common models 10 and 12..18 in CMD with CBL's item entries pointing at them, and GAM with the final stage set — a template project's CMD, CBL, MUS, ULB and map tables carried when there is one. export-ddd.js is the one call, behind deno task build:ddd and the editor's CONSOLE › N64 row with its donor-disk input, and n64:probe grew put, rm, convert and sys over the same code. Verified: every disk is read back through the reader before it is returned — directory, invariants, every new stream decompressed and compared — and the fixture-gated test rebuilds the prototype from its own two projects and gets the same 64,458,560 bytes; 22 tests in tests/dezaemon_n64_write_test.ts. What remains: the writable area — its directory, the allocation map, DEZA3D.SYS, DEZA3D.HSC — is never written, no layout effect is, and the MUS bodies are blank; every unit the records carry that is not a measurement (that a stage's model k is model number 20 + k, that x ±400 spans the screen, the UV units of a billboard) is a reading of the document and of the cartridge's sample stages, marked likely; a disk built from nothing is not expected to put the cartridge into disk mode. A project this writes is a pressed one beside the two samples, not a saved one. Untested on hardware or in an emulator (item 9).

02Already decoded

Confirmed Measured against the bytes of dev-fixtures/dezaemon298.ddd and reproduced independently. As everywhere on these pages, "confirmed" never means a runtime consumes the result — nothing does. Everything in this section is now committed, and the claims marked with offsets are the ones the tests assert.

FeatureWhat is decoded, and what pins it
The whole read pathThe load-bearing result. Using only the directory arrays, a two-zone LBA→byte function and this repo's existing packages/shmup-engine/src/decompress.js, all 60 files extract and 58 decompress to exactly their documented size — CGR 163,840, ULB 57,600, CMD 62,120, MUS 274,032, 0GR 1,064,960. The two misses are the two GAM files, both short by the same 9 bytes, and the documentation names those two files as malformed on the prototype disks (item 6). Landing five distinct types on exact sizes up to a megabyte is not reachable by chance, and this one test confirms the LBA mapping, the directory layout, the codec and the third-party documentation simultaneously.
What the file isThe user data area of a 64DD disk — not a ROM, and there is no N64 ROM magic anywhere in the 64 MB, nor should there be (the 64DD IPL jumps straight to LBA 24 with no header). Settled by byte comparison against 64dd.org's canonical deza1.NDD: the sizes differ by 473,280 = 24 × 85 × 232, exactly the system area, and deza1.NDD[473280:] is byte-identical to this file except in the save area. So .ddd is .ndd with the 24-LBA system area sliced off — an ad-hoc 2018 dumper's extension, not a format any spec, tool or emulator names.
The disk's own wordsAt 0x28E80, in romaji: KONO DISK WA DEZA64 DATA DISK DESU / ICHIDO DENGEN WO KIRI DEZA64 NO / ROMCARTRIDGE WO SOUNYUUSHITE / DENGEN WO IRENAOSHITE KUDASAI — "this is a DEZA64 data disk; power off, insert the DEZA64 ROM cartridge, power on again". DEZA64 is Dezaemon 3D's internal codename, and the sentence is the disk stating its own dependency on the cartridge that was never released.
The system areaAbsent from our file, recovered from the canonical dump: region E8 48 D3 16 (JP), format type 0x10, disk type 0, Disk ID DEZA with BCD timestamp 1998-02-23 19:24:25, PTN64 (written from a Partner-N64 development unit) and ATNFS0 in the free area. One trap worth recording: the ROM-end / RAM-start / RAM-end LBA fields at 0xE0 read 1016 / 1C22 / 282E, which is an arithmetic sequence stepping by 6 and past the maximum LBA — filler, not data. The disk does not record where its own ROM area ends. What the cartridge DOES read is the disk ID, and only two fields of it (LuigiBlood's 64dd wiki, Dezaemon 3D page): the company code E7 (Athena) and the free area ATNFS? with ? the disk type in ASCII — no game code, no initial code — on a Japanese retail or a development drive. system-area.js writes both from the disk type (isDezaemonDiskId() is the check); that it is what the cartridge wants is the wiki's word, marked likely.
The ROM/RAM splitRecovered from the data instead, and unambiguous: exactly one large 0xFF run, 0x6C7188–0x18CA9C8, 18,888,768 bytes of unwritten media. The last sample file's stored extent ends at 0x6C7187, flush against it. That run is blank media, not corruption, and region 2's 6.2–7.7 bits/byte is LZSS output, not encryption.
Container geometryA linear concatenation of variable-size blocks in libleo LBA order from user LBA 0 (physical LBA 24). A block is 85 sectors of user data (90 on the media: four more of C2 error correction and one gap, which no image carries); sector size is one of 232/216/208/192/176/160/144/128/112 by zone; the disk has two sides of 1,175 cylinder tracks over eight zones each (158, 158, 149 ×5, 114 tracks; side 1 starts one zone in), two blocks a track, twelve tracks a zone kept spare for defects on a retail disk and ten on a development one, the two blocks of odd tracks interleaved and side 1 read from each zone's end — all of which is the driver's business and not an image's; 4,292 blocks summing to exactly 64,458,560. The ROM area is zones 0, 1 and 2 of both sides always and one zone more per disk type, the RAM area the rest. Nothing here needs reverse engineering — the tables are published on LuigiBlood's 64dd wiki and implemented in leo64dd_python, leotools, Project64 and mupen64plus-core. The first hint came from the file itself: the gaps between the directory's backup copies are exact sums of block sizes, 34,680 = 85×192 + 85×216 and 48,960 = 3 × 85×192.
The directory (read-only)Athena's own ATNFS, and a structure of arrays, not packed records — which is why earlier passes found names and no sizes. Base 0x18CA9C8, 60 entries: names char[11] = NAME(8, space-padded) + EXT(3) with no separator at 0x18CAD0A; u16 big-endian start LBA at 0x18CD0E0; u16 block count at 0x18CD764; an all-zero u16 array at 0x18CDDE8; and u32 big-endian stored size at 0x18CE46C — that last array is the one that makes extraction possible. Allocation is contiguous: startLBA[i] + blockCount[i] == startLBA[i+1] for all 59 pairs, LBA 9 → 368. Replicated byte-identically at 0x18D3482 and 0x18DF3C2, all three at in-block offset 834 — redundant backups.
CompressionOkumura LZSS, and packages/shmup-engine/src/decompress.js decompresses these files unmodified — the same parameters as the PlayStation Dezaemon 2 work already shipped here: 4096-byte ring zero-filled, write pointer at 0xFEE, flag byte LSB-first, 1 = literal, 0 = 2-byte match with off = b1 | ((b2 & 0xF0) << 4) and len = (b2 & 0x0F) + 3. Corroborated independently: the LZSS module inside DezaDiskTool.exe self-describes as a port of Okumura's codec. The trap: this decoder cannot fail — it will happily "decompress" noise, and one pass of this very survey was misled that way. It is evidence only when the caller supplies the stored length from the directory and the output length matches a predicted value. There is no length prefix on these streams.
Graphics formatN64 RGBA5551, 2 bytes per pixel, no palette, on flat 64-pixel-wide scanline sheets — not the rgb555ToRgb unpack the PSX and SFC parsers use, since the alpha bit is bit 0. Pinned by measurement: of the 432,506 nonzero big-endian 16-bit words in SAMPLEZ1.0GR, every one has bit 0 set, fraction 1.000000, and the same holds for all 29,180 in CGR. Nothing but an alpha bit produces that. It also corrects the documentation's image count — 0x104000 ÷ 2 ÷ (64 × 32) is 260, not 520. Rendered as a contact sheet the tiles are unmistakably real art: the sample game's two SOLID GEAR title logos (in stage 0's sheet), WARNING and DANGER plates, a CODE NAME DUAL-LANCER briefing screen, sys check 01/02, and Japanese cut-in portraits.
The model record0xC20 bytes, and the pleasant surprise of the survey: plain data, not F3DEX display lists. +0x0 u8 vertex count (≤100), +0x1 u8 face count (≤100), +0x2 100 vertices of s16 x,y,z, +0x25A 100 faces of 0x14 bytes (three vertex indices, three s16 UV pairs, three bytes of baked RGB light, one flags byte), +0xA2C 16 tile descriptors, +0xBAC per-vertex groups. Corroborated by a scan of the whole 64 MB, which found only 4 G_ENDDL and 1 G_RDPPIPESYNC, all inside the boot stub. The engine builds display lists at run time; the disk stores geometry as structs, so a viewer is direct.
The project model30 files per project: 6 globals — GAM CGR CMD CBL ULB MUS — and 3 per stage, BL MD GR, for stages 0,1,2,3,4,5,6,8. Stage 7 is simply absent from the numbering. The disk carries two pressed sample projects, SAMPLEZ1 and SAMP, plus the global DEZA3D.SYS and DEZA3D.HSC and a user project DST in the writable area.
The boot program DEAD ENDRecorded here so nobody spends a day on it. File 0x0–0x29420 (168,992 bytes) is a complete libultra executable, load address 0x80000400, entry 0x80000560; the entry stub's bzero loop gives the BSS bounds (t0 = 0x80029820, length 0x48180 — note the addiu sign-extends, so it is not 0x8003xxxx) and 0xFF filler begins on exactly the byte BSS starts, which pins both the load address and the image end. It holds ~3.9 KB of genuine 64DD block-mode driver (ASIC registers 0x05000508/0x05000510, sector buffer 0x05000000) and no filesystem code at all — not one filename constant, no DEZA3D, no extension table. All 274 jr ra instructions in the 64 MB fall inside this image; there is no code anywhere else on the disk. Its entire job is the "insert the cartridge" screen. Do not disassemble it hoping to find the filesystem — that lives on the cartridge, and it is no longer needed.

03Located but not yet understood

Likely Every one of these has a documented layout whose arithmetic closes exactly against the measured file sizes — CBL = 27 × 0x5C, CMD = 20 × 0xC20 + 40, #MD = 130 × 0xC20 + 260, ULB = 8 × 0xC20 + 8 × 0x1000, CGR = 40 × 0x1000. That is a strong prior and it is not the same thing as having been checked field by field against these bytes. Since 2026-10-14 the field-by-field layouts are code — packages/shmup-engine/src/n64/records.js, a typed encode and decode for every record below, 23 tests in packages/shmup-engine/test/n64-records.test.js — and they were checked against the one real sample the translation ships: the cartridge's own initial save (Scripts/sram, 0x18000 bytes), whose GAM, CBL, ten CMD models, three cartridge-variant stage BLs and eight songs all parse and re-encode byte for byte (encodeGam({}) is that GAM). What the check does not reach is meaning: the units of a face's UV pairs and a tile's offset, the tile index base, the three words at the end of a disk-mode #BL, and the fields the source marks ??? are carried, not understood. The source says of itself "please note these are not complete!", and one of its counts is already known wrong (item 5), so everything here still ships marked likely.

04No trace at all

Absent What is left after the parser and then the writer landed. Shorter than it was on 2026-09-19 morning, shorter again since 2026-10-14, and still longer than the other three maps' equivalents.