Dungeon Master 1 (DM1) — Reverse Engineering Wiki

This page documents the reverse-engineering knowledge base backing Firestaff’s Dungeon Master 1 (DOS PC 3.4, “I34E”) implementation. The canonical reference source is ReDMCSB, a reconstructed C decompilation of the original Dungeon Master / Chaos Strikes Back engine. Firestaff comments cite ReDMCSB files and F-numbered functions directly (ReDMCSB FILENAME.C:LINE, F0NNN_FUNCTION_NAME), and DM1-specific compatibility modules live under src/dm1/ and include/dm1_v1_*_pc34_compat.h.

All data below was extracted from the current Firestaff source tree with:

grep -rohE 'ReDMCSB [A-Z0-9_]+\.[CH]' include/dm1_v1_* src/dm1/ | sort -u
grep -rohE 'F[0-9]{4}_[A-Za-z0-9_]+' include/dm1_v1_* src/dm1/ | sort -u

1. ReDMCSB Source File Map

96 distinct ReDMCSB source/header filenames are referenced across DM1 compatibility headers and sources. They are grouped below by subsystem. Note that DM1 and CSB (Chaos Strikes Back) share the same PC 3.4 engine codebase in ReDMCSB, so many files serve both games.

Core / Main

Startup / Entrance / Title

PC 3.4 FTL/SWSH media boundary

SWSH.C owns the FTL-logo palette sequence; the logo payload itself is the original SWOOSH member. Firestaff’s PC 3.4 route reads that member directly from the selected ZIP into bounded memory through asset_read_path_alloc(). It does not unpack the archive or create a loose replacement file. The real-media probes ftl_swoosh_palette_regression and ftl_swoosh_ascii_sanity use the same virtual path and verify the source palette mutations plus full 320×200 packed-to-indexed expansion. If the operator-owned archive is absent, those optional visual probes skip; the native archive CLI/start-menu test remains the launch gate.

Dungeon (data model)

Viewport / Rendering

Objects / Items

Champions

Combat

Timeline / Events

Sensors / Doors

Audio

Input / Mouse

Save / Load

Graphics data (GRAPHICS.DAT)

UI / Text / Menu

Hint system (Chaos Strikes Back editor / hint tooling)

Platform / Localization

2. F-Number Function Registry

912 distinct F-numbered identifiers are referenced in DM1 code (functions, constants, and struct/field markers combined). The tables below cover the ~300 function-shaped F-numbers in the ranges most central to DM1 parity work, grouped by subsystem. Names are the canonical Firestaff spelling found in source comments; the originating ReDMCSB file is noted per group above.

Core utilities (F0002-F0030) — MAINLIB.C

Object/icon handling (F0031-F0039) — OBJECT.C

Text/message area (F0040-F0054) — TEXT.C

Sound (F0060-F0065) — SOUND.C

Mouse/pointer (F0066-F0079) — MOUSE.C

Dungeon viewport (F0093-F0135) — DRAWVIEW.C, VIDEODRV.C

This F0093-F0135 range is the material matrix: the D0/D1/D2/D3 naming encodes viewport column distance (D0 = nearest row, D3 = farthest) and L/R/C encode left/right/center screen position — this is the routing table behind m11_draw_viewport and the CSB viewport callback path described in CLAUDE.md.

Dungeon data (F0139-F0174) — DUNGEON.C

Groups/creatures (F0175-F0212) — GROUP.C

Explosions/projectiles (F0213-F0218) — PROJECTILE.C, PROJEXPL.C

Timeline (F0233-F0240) — TIMELINE.C

Sensors (F0267-F0276) — MOVESENS.C

Champions (F0284-F0349) — CHAMPION.C, INVENTORY.C

F0302 owns the transaction at mouse-down. This includes the top-row C020–C027 hand boxes (C211–C218) as well as inventory-page slots. The transient leader hand is therefore the only in-flight owner during a drag: releasing over a different admitted hand box completes one exchange; releasing over the original box is consumed and must not perform a second exchange. This prevents the apparent item disappearance caused by an immediate swap-back.

Doors / movement / sensor dispatch (F0700-F0730) — Firestaff _Compat layer

These are Firestaff-authored bridge functions (not raw ReDMCSB F-numbers) that wrap DUNGEON.C/MOVESENS.C logic into a callback-oriented, testable API. They still carry F-numbers to preserve traceability to the functional area they compat-wrap.

Music (F0740-F0743) — MUSIC.C

Wired into M11_GameViewState via dm1MusicSource / dm1MusicState / dm1MusicDriver fields (see CLAUDE.md). Only the game-won track (C2) is currently proven playable end-to-end; other tracks remain fail-closed.

Startup (F0800-F0910) — STARTUP2.C, GROUP.C (DM1-specific AI mirror), REVIVE.C

3. DUNGEON.DAT File Format

Reference: include/memory_dungeon_dat_pc34_compat.h, ReDMCSB DUNGEON.C.

The on-disk layout (little-endian, Watcom/Borland LSB-first bitfields) is:

Offset 0:   DUNGEON_HEADER            (44 bytes)
Offset 44:  MAP[header.mapCount]      (16 bytes each)
Then:       raw map (square) data, thing arrays, square-first-thing table, text data

Header (44 bytes) — DungeonHeader_Compat

Known dungeon IDs (from DEFS.H): DUNGEON_ID_DM=10, DUNGEON_ID_CSB_PRISON=12, DUNGEON_ID_CSB_GAME=13, DUNGEON_ID_KID=50. A compressed-dungeon (save-game) signature of 0x8104 is explicitly rejected by the DUNGEON.DAT-only loader.

Map descriptors (16 bytes each) — DungeonMapDesc_Compat

Square (tile) encoding

M034_SQUARE_TYPE(square) = square >> 5. Each square byte packs:

Element types (0-6)

Thing types (0-15, 16 slots total)

Per-type byte counts mirror ReDMCSB’s G0235_auc_Graphic559_ThingDataByteCount.

THING encoding (uint16 handle)

bits 15:14  direction   (used at runtime only, not in on-disk thing arrays)
bits 13:10  thing type  (0-15, see table above)
bits  9:0   index       into ThingData[type] array

Special sentinel values: THING_NONE = 0xFFFF (unused slot), THING_ENDOFLIST = 0xFFFE (end of a linked list).

Thing linked lists

Each square flagged with DUNGEON_SQUARE_MASK_THING_LIST has a compact entry in the SquareFirstThings array (one entry per flagged square, not one per tile — looked up via F0160/F0161). Each decoded thing record carries a next field (a THING handle) forming a singly linked list per square; walking stops at THING_ENDOFLIST. F0163/F0164 (DUNGEON_LinkThingToList / DUNGEON_UnlinkThingFromList) mutate these lists; both fail closed if the loaded tables cannot admit the exact requested mutation, including reproducing the original engine’s BUG0_08 full-SFT-overflow corruption case for diagnostic purposes (F0502b_DUNGEON_CheckBug0_08SftOverfill_Compat).

Per-type thing record layouts (decoded structs)

• Door (4B): next, type (1b: set0/set1), ornamentOrdinal (4b), vertical (1b), button (1b), magicDestructible (1b), meleeDestructible (1b)
• TextString (4B): next, visible (1b), textDataWordOffset (13b)
• Teleporter (6B): next, targetMapX/Y (5b each), rotation (2b), absoluteRotation (1b), scope (2b), audible (1b), targetMapIndex (8b)
• Sensor (8B): next, sensorType (7b, M039_TYPE), sensorData (9b, M040_DATA), onceOnly (1b), effect (2b), revertEffect (1b), audible (1b), value (4b), localEffect (1b), ornamentOrdinal (4b), plus a Remote/Local union over the last 2 bytes: Remote = targetCell (2b) + targetMapX/Y (5b each); Local = localMultiple (12b, health multiplier / tick count / kinetic energy depending on sensor type)
• Group (16B): next, slot (possession chain), creatureType (8b, 0-26 for DM), cells (8b, packs up to 4 creature cell positions), health[4], behavior (4b), count (2b, actual count = value + 1), direction (2b), doNotDiscard (1b)
• Weapon (4B): next, type (7b), doNotDiscard (1b), cursed (1b), poisoned (1b), chargeCount (4b), broken (1b), lit (1b, torches)
• Armour (4B): next, type (7b), doNotDiscard (1b), cursed (1b), chargeCount (4b), broken (1b)
• Scroll (4B): next, textStringThingIndex (10b), closed (6b)
• Potion (4B): next, power (8b), type (7b), doNotDiscard (1b)
• Container (8B): next, slot (contents chain), type (2b)
• Junk (4B): next, type (7b), doNotDiscard (1b), cursed (1b), chargeCount (2b)
• Projectile (8B): next, slot, kineticEnergy (8b), attack (8b), eventIndex (16b)
• Explosion (4B): next, type (7b), centered (1b), attack (8b)

Text data encoding

Each 16-bit word packs three 5-bit codes (code[0] = bits 14-10, code[1] = bits 9-5, code[2] = bits 4-0; bit 15 unused):

Strings are exposed by index (not content) since the table is language-dependent. Text types: inscription (0), message (1), scroll (2), with an optional 0x8000 mask to force decode even if the underlying TextString thing is marked invisible.

4. GRAPHICS.DAT Format

DM1 PC 3.4 and the CSB reference/source lineage both use GRAPHICS.DAT, but the on-disk compression differs by platform port in the ReDMCSB source tree:

• PC IMG3 — the PC 3.4 (DOS) graphic entry format. Entries are LZW-compressed (ReDMCSB LZW.C), decoded through the F0687-F0691 chain implemented in Firestaff as redmcsb_f0687_f0688_img3_pc34_compat, redmcsb_f0689_img3_expand_pc34_compat, redmcsb_f0685_img3_line_fill_pc34_compat, and redmcsb_f0691_draw_compressed_img3_pc34_compat. Firestaff’s DM1 path reads GRAPHICS.DAT headers via memory_graphics_dat_header_pc34_compat.h, which stores parallel compressedByteCounts / decompressedByteCounts arrays per entry — confirming each entry can be independently compressed/uncompressed.
• Amiga IMG1 — CSB’s Amiga GRAPHICS.DAT uses a nibble RLE scheme, distinct from PC IMG3 (see csb_v1_amiga_graphics_dat.h, dm1_v1_amiga_graphics_dat.h, csb_v1_csbgraphics_dat_lzw_boundary.h, csb_v1_csbgraphics_dat_classify.h). This is not interchangeable with the PC LZW format even though both are called “GRAPHICS.DAT”.
• FM Towns variants exist for DM2 (dm2_v1_fmtowns_graphics_dat.h, csb_v1_fmtowns_graphics_dat.h). The DM1 FM Towns port ships on a BIN/CUE disc image and drives all in-game presentation through the TownsOS EGB graphics library and its own Phar Lap P3 executable (EDM.EXP / JDM.EXP); see the dedicated DM1 FM Towns guide and the disassembly evidence at parity-evidence/dm1_fmtowns_menu_p3_disassembly.md.

Firestaff’s memory-allocator model for GRAPHICS.DAT (memory_graphics_dat_* modules — allocator entry/boundary/orchestrator, defrag loop/entry, used list, slots, bitmap reuse) mirrors ReDMCSB MEMORY.C’s used-list + defragmentation allocator so that graphic bitmap lifetime and memory pressure match the original engine’s caching behavior (entries can be evicted and re-decoded from the compressed source, matching the original’s memory-constrained DOS environment).

5. Save File Format

Reference: ReDMCSB LOADSAVE.C, SAVEHEAD.C, SAVEUTIL.C, READWRIT.C; Firestaff headers include/memory_savegame_pc34_compat.h, include/redmcsb_f0435_save_tail_pc34_compat.h, include/dm1_v1_original_save_pc34_handoff.h.

Obfuscation (F0417/F0418/F0419/F0420)

F0417_SAVEUTIL_GetChecksumAndObfuscate (SAVEUTIL.C) is the shared XOR-obfuscation-plus-checksum primitive used across the save format. The save header uses a minimal subset: 10 uint16 “Noise” entries are fed through the F0417 XOR+checksum loop (SAVEHEAD.C:44,97,104). The dungeon tail and other sections reuse the same primitive via READWRIT.C F0417/F0419/F0420.

Load order (F0429-F0435)

1. SAVEHEAD.C F0429/F0430 — read and deobfuscate/checksum the save header.
2. READWRIT.C F0433 — dungeon-tail checksum/obfuscation pass.
3. LOADSAVE.C F0435 — continuation after the header’s first three parts: reads EVENTS (with per-part Keys[C3]/Checksums[C3]), then the uint16 TIMELINE, then the dungeon tail proper. Firestaff models this as an indexed part sequence: REDMCSB_F0435_PC34_EVENTS_PART_INDEX = 3, REDMCSB_F0435_PC34_TIMELINE_PART_INDEX = 4, with distinct failure codes (EVENTS_FAILED = -1, TIMELINE_FAILED = -2, DUNGEON_TAIL_FAILED = -3) so a byte-identical original save can be diagnosed at the exact failing part.

Save tail layout (matches F0433/F0435)

DUNGEON_HEADER
MAP[]
column-cumulative SquareFirstThings counts
SquareFirstThings
text data
thing data for all 16 types
raw map (square) data
checksum

Firestaff retains the original tail bytes verbatim (originalSaveTailBytes/originalSaveTailByteCount/ originalSaveTailPristine in DungeonDatState_Compat) until a live world serializer explicitly replaces them, so F0433 can round-trip an original save without lossy decode/re-encode of reserved dungeon fields — this is the mechanism behind the project’s byte-identical DOS savegame compatibility requirement.

6. Key Data Structures

DungeonThings_Compat (include/memory_dungeon_dat_pc34_compat.h)

Aggregates all decoded thing data for a loaded dungeon:

• squareFirstThings[] + squareFirstThingCount
• Per-type decoded arrays + counts: doors, textStrings, teleporters, sensors, groups, weapons, armours, scrolls, potions, containers, junks, projectiles, explosions
• rawThingData[16] + thingCounts[16] — raw byte blobs for all 16 thing-type slots (kept even for types not yet fully decoded)
• textData[] + textDataWordCount
• loaded flag

DungeonMapDesc_Compat

16-byte on-disk map descriptor, decoded into level/width/height, ornament counts, difficulty, allowed creature types, and floor/wall/door graphic set selectors (see §3).

DungeonDatState_Compat

Top-level loader state: header, maps[], per-column cumulative square-first-thing counts (mirrors ReDMCSB G0280), tiles[] (loaded lazily by F0502, separate from header/map load by F0500), file size, loaded/tilesLoaded flags, and the pristine save-tail byte cache described above.

Thing type size/count limits

7. Creature Type Table

DM1 defines DUNGEON_CREATURE_TYPE_MAX = 26, meaning creature type indices run 0-26 inclusive (27 distinct types). Per-type attributes (used for combat resolution, AI behavior gating, and sound selection) are held in DM1_V1_F0144_CreatureInfoPc34 records (include/dm1_v1_creature_attributes_f0144_pc34_compat.h, sourced from ReDMCSB DUNGEON.C F0144), keyed by creatureType (uint8, 0-26). Related lookup tables:

• Map eligibility: dm1_v1_creature_allowed_on_map_f0139_pc34_compat.h (F0139) — cross-references DungeonMapDesc_Compat.allowedCreatureTypes[16] and creatureTypeCount from the map descriptor.
• AI behavior: dm1_v1_creature_ai_behavior_pc34_compat.h, dm1_v1_creature_behavior_bootstrap_pc34_compat.h — behavior dispatch mirrored in the F0810-F0824 range (movement, melee/projectile attack selection, flee/frighten logic, giggler steal-attempt resolution).
• Rendering: dm1_v1_creature_render_pc34_compat.h, dm1_v1_creature_viewport_pc34_compat.h, dm1_v1_f0115_f0219_creature_item_material_pc34_compat.h — viewport creature draw path feeding into F0115 (DUNGEONVIEW_DrawObjectsCreatures).
• Sound: dm1_v1_creature_sound_pc34_compat.h.
• Palette: redmcsb_f8160_creature_palette_c25_pc34_compat.h (F8160, creature replacement-color palette, C25) and redmcsb_f0695_set_creature_replacement_colors_pc34_compat.h (F0695).
• Name scroll UI: redmcsb_f0805_creature_name_scroll_pc34_compat.h (F0805, used by the magic-map / bestiary display).

Groups reference creatureType (8-bit field, 0-26) directly in the on-disk DungeonGroup_Compat record (§3), with up to 4 creatures per group packed via the cells and health[4] fields.

Note: Firestaff exposes these tables by index, not by hardcoded English name — matching the project’s index-first design used for text strings (§3) so that future localization work is not blocked by name-string assumptions baked into the reverse-engineered data layer.

8. Parity Evidence

The parity-evidence/ directory contains the cross-game pass corpus. The exact current count is repository-derived rather than maintained as a narrative number; the DM1-specific subset is identified by pass{NNN}_dm1_v1_* filenames, following the naming convention pass{NNN}_{description}.md described in CLAUDE.md.

Each pass document is a source-lock evidence record: it ties a specific Firestaff implementation change to the exact ReDMCSB source lines it reproduces, and typically records the pc34_compat module(s) touched. Examples visible in the current tree span the full breadth of subsystems covered above — inventory slot placement and drop order (pass1091, pass863), viewport occlusion gating (pass404), initial-hall capture paths (pass466), door/entrance graphics (pass840), palette and cursor bitmap handling (pass850-pass858, pass870-pass871), mandatory graphic indices (pass852), wound defense factor (pass853), champion rename/reincarnate character-string handling (pass854-pass856), square type → event type mapping (pass859, matching F0727 above), champion icon and bar-graph byte offsets (pass860-pass862), and box screen-edge layout constants (pass864-pass866).

This evidence corpus is the practical cross-reference for any future reverse-engineering work: before re-deriving behavior from ReDMCSB source, check whether a parity-evidence/pass*_dm1_v1_* document already records the exact lines and the Firestaff module that encodes them.