Chaos Strikes Back — Reverse Engineering Notes

This page consolidates the reverse-engineering findings behind Firestaff’s CSB implementation: source module inventory, the Amiga IMG1 graphics container, the CSBWin DSA (Dynamic Scripting Architecture) system, the CSB save format, the viewport rendering path, and the reference boundary between ReDMCSB and CSBWin. For narrative status/progress see CSB-Technical-Reference and for the authenticated DSA/save contract see CSB-DSA-and-Save-Internals.

1. CSB-Specific Modules

Firestaff’s CSB implementation lives in src/csb/ (357 .c files) and include/csb_v1_* / related headers (245+ files), plus redmcsb_* modules that port ReDMCSB functions unmodified for CSB reuse.

ls src/csb/*.c | sort      # 357 files
ls include/csb_v1_* | sort # 245 files

Module families (by prefix)

2. IMG1 Graphics Format (Amiga)

The original Amiga v3.1 graphic stream uses IMG1 nibble-RLE, wrapped in a big-endian DMCSB2 container. It is deliberately kept distinct from the optional CSBWin custom-graphics override format used only as a source-study fixture.

Container header

Known hash-identified variants (include/csb_v1_amiga_graphics_dat.h):

Nibble-RLE encoding

Each IMG1 graphic is decoded via a 4-bit (nibble) run-length scheme, distinct from DM1’s byte-oriented IMG3 compressed-line format. Firestaff replaced its ExpandGraphic byte-format decoder with a dedicated IMG1 nibble-RLE decoder (csb_v1_amiga_graphics_dat.c, csb_v1_graphics_lzw_pc34_compat.c family) because reusing the PC IMG3 path silently mis-decoded CSB Amiga-sourced art.

Two title/entrance graphics anchor correctness:

Both decode 100% correctly through the IMG1 path per CSB-Technical-Reference.md.

IMG1 vs IMG3 — key differences

CSBWin’s own CSBgraphics.dat companion format (produced by CSBGraffer / CSBWin Viewport Compiler) is a third, separate container — classified by csb_v1_csbgraphics_dat_classify.c and bound at runtime via csb_v1_csbgraphics_runtime_binding.c / csb_v1_csbgraphics_runtime_plan.c. It must not be confused with Amiga CSBGRAPHICS.DAT or treated as evidence of an original PC/DOS CSB release.

3. DSA (Dynamic Scripting Architecture)

CSBWin’s DSA system is a stack-based scripting VM used by custom dungeons (and embedded in the original CSB dungeon for some triggers). It is unique to the CSBWin PC port — ReDMCSB does not define it. Firestaff treats a loaded DSA action as authenticated source data, never a general-purpose scripting API: unsupported opcodes and malformed records fail closed rather than falling back to a generic interpreter.

Record identity

Every DSA record is identified by the source tuple:

(absolute_dsa_id, state, ordinal, source_action_pointer)

The pointer identity is retained at runtime — a host-constructed or copied action with matching words cannot be substituted into an authenticated runner.

Actuator binding (type-47 DSAselector)

A type-47 DB3 actuator does not name a DSA directly; its selector bits resolve through the imported source level table:

selector = (DB3.word2 >> 7) & 0x1f
dsa_id   = DSALevelIndex[current_level][selector]

Binding rejects on wrong actuator type, missing index, undefined ID, or an action absent from the staged extension — never a synthesized default.

Opcode families implemented

NOOP, EQUAL, QUESTION, plus STKOP families: Loc2AbsCoord, FetchExCellFlg, BitCount, ParamFetch/ParamStore, GlobalFetch, PartyDistance, TimeFetch, ThisDSAId, WhoHasTalent, CountInjury, TalentsFetch, DisableSaves, ChPoss/MonPoss, ExamineCell, Copy, CharFetch/CharStore, SwapCharacter, CausePoison, Mastery, MissileInfoFetch/Store, MonsterFetch, PartyFetch, Override, Message, Overlay, Palette, ExperiencePlus, JumpGear/GosubGear.

CausePoison and CountInjury double as combat integration points (Q-CSB-08 damage-character filter), not pure stack primitives.

LOAD/STORE, banks, and control transfer

• LOAD/STORE: source-shaped, operating on local DSAVARS and owned global banks. Out-of-bank variables/globals reject.
• JUMP/GOSUB: follow CSBWin Execute selection rules —
  • state/column lookup picks the first exact file-order (state, column) action match;
  • JUMP transfers only within the bounded execution frame;
  • GOSUB records a one-frame nested transfer and preserves outer continuation;
  • a missing target ends selection without inventing a synthetic action;
  • depth and transfer ceilings reject the action before publication.
• World-mutating AMPERSAND forms, unsupported loads, malformed words, and unowned pointers all reject — a rejection leaves parameters, globals, filter receipt, and dungeon state unchanged (transactional publish).

Module map

Full opcode-by-opcode detail, admitted/restored timer bridge semantics, and the real-package DSA receipt contract (firestaff_csb_v1_csbwin_extended_dsa_handoff_probe) are documented in CSB-DSA-and-Save-Internals.

4. CSB Save Format

CSB save handling spans two layers: the original ReDMCSB save/dungeon-tail contract (shared with DM1) and CSBWin’s extended-save format for DSA/custom dungeons.

Original save (ReDMCSB-derived)

GAMEBLOCK1/body import and extended tails

CSBWin extends the original save with GAMEBLOCK2, CHARDESC, ITEM16, timers, game-info, DSA action records, level-index data, and an optional trace bitmap. The extension loader stages all of these before a live profile is changed — failure in a later record invalidates the whole candidate rather than keeping an earlier partial import (csb_v1_csbwin_save_loader_boundary_pc34_compat.c).

• The CSBWin save loader boundary rejects malformed non-empty DB11/EXPOOL tails before atomic runtime staging.
• csb_v1_csbwin_dungeon_tail.c handles the CSBWin-specific dungeon tail layout distinct from the ReDMCSB F0434 tail.

F0435 native provenance

F0435 provenance is recorded only after a committed import, never on a rejected candidate — this is the “did this save actually come from a real CSB/CSBWin file” marker used elsewhere in the runtime to gate CSBWin-only behavior (DSA execution, extended timers).

Export/import and Utility Disk

Test coverage: 32 save/Utility Disk files (Q-CSB-09), 15 of which are executable test binaries; all pass.

For a legacy CSBWin source artifact, csb_v1_runtime_export_csbwin_source_save_to_path() is intentionally a provenance-checked byte copy with source-slot backup rotation. csb_v1_runtime_export_csbwin_core_save_to_path() writes the complete legacy body only while every live event still has its original source receipt. The verified legacy path retains the exact TIMER-record width, raw CSBWin queue order, and complete saved-dungeon tail separately from DB11/EXPOOL state, after the tail prefix, DB0–DB15 spans, and terminal checksum pass. A stock CSBGAME2.DAT round-trips through independent runtime ownership and re-authenticates. ITEM16 ownership is restored without injecting new C37 entries because CSBWin SaveGame.cpp restores ITEM16 and TIMER data without calling ProcessMonstersOnLevel() in the resume branch.

This is not yet a user-facing F0433 writer after play: a changed timer, heap position, dungeon record, or EXPOOL/DSA continuation needs a source-owned writer receipt. M11 therefore still rejects Save and Play for a mutated resumed CSBWin GAMEBLOCK instead of emitting an incomplete CSBGAME*.DAT.

Timer queue restart boundary

For a resumed CSBWin save, TIMER/TimerQueue state remains source-owned: core export retains original array indexes, heap topology, sequence words, and GAMEBLOCK2 timer counters only when every live timeline entry still has an exact saved queue-slot receipt (time, function, priority, coordinates, cell, effect). A fired, replaced, duplicated, or unmapped event breaks the receipt and CSBWin export rejects rather than emit a reconstructed queue.

5. Viewport and Rendering

CSB path

csb_v1_viewport_render_frame()          [src/csb/csb_v1_viewport_pc34_compat.c]
        │  builds DM1_Viewport3DState from CSB_V1_ViewportConfig
        ▼
dm1_viewport_3d_draw_frame()            [shared DM1 V1 viewport engine]

csb_v1_viewport_render_frame(CSB_V1_ViewportConfig *cfg, int party_dir, int party_x, int party_y) is the integration entry point (called from csb_v1_boot.c). It is a documented passthrough to the shared DM1 V1 viewport engine (source: CSBWin Viewport.cpp F0128; ReDMCSB DUNVIEW.C F0128), reusing the same 320×200 indexed pixel format and 224×136 viewport sub-region at screen row 33 so DM1 draw primitives work unmodified. It is a no-op when viewport_pixels is NULL (staged-integration guard).

CSB config supplies:

• viewport_pixels + stride — target pixel buffer
• dungeon_grid/width/height — square-type data for element routing
• wall_set_index — selects which GRAPHICS.DAT/CSBGRAPHICS.DAT wall set

Callback-based wall ornament resolution

Wall ornament ordinals are resolved through csb_v1_viewport_wall_ornament_ordinal_resolver_pc34_compat.c, which feeds the shared DM1_ViewportWallOrnamentOrdinalCallback used by dm1_viewport_3d_draw_frame — the same callback contract DM1’s CSB-style path (as opposed to the M11 monolithic path) uses.

For the Amiga runtime, the F0107 callback applies the source MEDIA720 scale selection and resolves placement from authentic Amiga Graphics.DAT item 696 (C696). It fails closed when the item or selected zone is invalid and uses the full M615 source bitmap without PC34 source cropping. The real-media utility check covers parsing and selected anchors only; matched-frame placement, palette/light, alcove/inscription appearance and the floor-trapdoor path still need independent verification. See the CSB evidence ledger.

Per-depth/per-element decomposition

Unlike DM1’s M11 path (a single large m11_draw_viewport with inline dungeon-data access), CSB’s viewport is decomposed into dozens of focused modules, one per depth (D0-D3) × side (center/left/right) × element type:

F0115 first-object native graphics use the G0209 weapon[46]/armour[58]/ junk[52]/potion[21] tables with C10 blit (conditional horizontal flip). Creature groups use per-creature transparency (G0219 coordinateSet_transparentColor) and D2/D3 palette remap tables (G0221/G0222).

Test coverage: 47 viewport tests (Q-CSB-06) covering walls D0-D3 all sides, doors, partly-open doors, ornaments, floor/ceiling, backgrounds, center fields, footprints, and projectile routing.

CSB vs DM1 M11 path

6. ReDMCSB vs CSBWin Reference Boundary

ReDMCSB and CSBWin answer different questions and are not interchangeable evidence.

ReDMCSB is the primary source for original CSB engine behavior, original EVENT/timeline structure, media branches, and original save-header contracts — it is explicitly not evidence for CSBWin extensions. CSBWin is the primary (and only) source for DSA, extended saves, and CSBWin-specific champion/input behavior.

The ReDMCSB archive itself contains platform dispatch and assembly segments rather than a universal host spec: USIOSTUB.C forwards mouse/queued-input through library vectors, MUSCSTUB.C forwards music calls, VBLANK.C installs interrupt handlers, GRAPH21.C carries media-specific CPSE/fuzzy- sector logic. These establish that a code path exists on the original platform, not that Firestaff’s SDL3 port reproduces equivalent ordering, sampling, mixing, or copy-protection results.

Required evidence tuples

For any claimed original save format:

(media/version hash, original save bytes, parser receipt, runtime capture)

For any CSBWin DSA/save claim:

(CSBWin save hash, timer queue slot, source timer index,
 DSA/EXPOOL record identity, selected source action)

Absent these tuples, Firestaff fails closed or states the route is not yet verified. The detailed gap-tracking queue is REDMCSB-CSB-GAP-001 through REDMCSB-CSB-GAP-013 in TODO.md.

7. Parity Evidence

parity-evidence/ contains the cross-game pass corpus. The exact current count is repository-derived rather than maintained as a narrative number. 28 are CSB-specific (pass*csb* or explicit CSB-scope filenames), covering DSA opcode receipts, save loader boundaries, viewport element routing, IMG1 graphics decode, and the CSBWin extended-save handoff contract.

ls parity-evidence | grep -ci csb   # 28
ls parity-evidence | wc -l          # 1071

For the full pass index and evidence-document conventions, see Parity-Evidence.

See also

• CSB-Technical-Reference — Q-CSB-01 through Q-CSB-10 status and verification commands
• CSB-DSA-and-Save-Internals — authenticated DSA/save/raster contract detail
• Architecture-Overview — project-wide module map