wasm: a save's live dungeon as layout and chips #482

Closed
opened 2026-11-02 21:45:18 +01:00 by jqueuniet · 1 comment
Owner

A save holds the live dungeon: its own map_data and object chains, with doors opened, creatures moved or killed, items dropped. DungeonFile.levelLayout and levelChips only read dungeon.dat, so a browser cannot show the save's state.

Wanted on SaveGame (with context): levelLayout(level) and levelChips(level, options), same JSON as DungeonFile's, read from the save's state and its graphics.dat. dm2-magicmap draws from a Dungeon, so this likely needs one built over the save's map_data and objects.

The web editor shows this in its Dungeon tab when a save is open, beside dungeon.dat as shipped, and later edits on it: party, doors, floor items, creatures.

A save holds the live dungeon: its own `map_data` and object chains, with doors opened, creatures moved or killed, items dropped. `DungeonFile.levelLayout` and `levelChips` only read dungeon.dat, so a browser cannot show the save's state. Wanted on `SaveGame` (with context): `levelLayout(level)` and `levelChips(level, options)`, same JSON as `DungeonFile`'s, read from the save's state and its graphics.dat. dm2-magicmap draws from a `Dungeon`, so this likely needs one built over the save's `map_data` and objects. The web editor shows this in its Dungeon tab when a save is open, beside dungeon.dat as shipped, and later edits on it: party, doors, floor items, creatures.
Author
Owner

#482 — a save's live dungeon as layout and chips

Intent

A save holds the live dungeon: doors opened, creatures moved or killed, items
dropped. DungeonFile.levelLayout / levelChips only read dungeon.dat. The
web editor's Dungeon tab wants the same views of an open save, beside the
shipped dungeon, and later of its edits (party, doors, floor items, creatures).

Goals

  • SaveGame.levelLayout(level, options) and SaveGame.levelChips(level, options) (wasm), same JSON as DungeonFile's, drawn from the save's state
    and the GraphicsArchive the save keeps.
  • Same pair in the FFI (dm2_save_game_level_layout, _level_chips): bindings
    features land on both.
  • Engine-faithful state: what the engine holds after loading the save, record
    stream overlay included (user's call). Stale creatures, wrong door states and
    missing dropped items are all failures.
  • Edits made through SaveGame show in the next call.

Non-goals

  • mapLayout / mapChips / mapPng / levelPng on SaveGame (trivial to
    add later on the same base).
  • Party marker or any JSON beyond DungeonFile's.
  • Limited saves (no context): refused with NoContext.
  • Items held by champions or the cursor: not on the map.

Anti-goals

  • Changing dm2-magicmap to know about saves. It draws a Dungeon; we give it
    one.
  • Reaching into dm2-saves internals from dm2-convert or the bindings:
    convert calls one dm2-saves API.

How: a dungeon.dat image of the live state

The save's raw sections are dungeon.dat's sections in the same order
(docs/formats/dungeon-dat.md § File body layout):

save                         live dungeon.dat image
dungeon_state (FileHeader) ─▶ header
map_table                  ─▶ per-map metadata
obj_link_arrays            ─▶ columns
obj_list                   ─▶ object list
text_data                  ─▶ text data
raw_record_arrays[16]      ─▶ records      ◀── overlay (2), (3)
map_data                   ─▶ tile data    ◀── overlay (1)
                              checksum (recomputed: byte sum mod 0x10000)

dungeon_state is the play-time header (SgWords maps all 44 bytes), so the
section sizes match. The image parses with the existing Dungeon::parse, and
dm2-convert wraps it in a DungeonFile to reuse level_layout /
level_chips unchanged.

The overlay replays the engine's load (DM2_READ_SKSAVE_DUNGEON, SKWINSPX
sksvgame.cpp; per-tile loop ~L1180–1320, READ_RECORD_CHECKCODE ~L830–960)
from the decoded RecordStream, per TileChain:

  1. Floor bits (floor_bits, mask 0x08 pit / 0x07 door / 0x04 trick wall /
    0x08 detail-less teleporter): SUPPRESS_READER(tile, mask, …, argflag=false)
    merges, so tile = (tile & !mask) | (bits & mask) at
    map_offset + x * height + y. Mask selection is the decoder's
    (decode_tile_chains); reuse it, don't restate it.
  2. Static overlays (existing_chain_reads): zip with the same step list
    the decoder walked (static_overlay_steps, Beta pair-fold included) to get
    each read's (rec_type, rec_index). Body merges byte-wise with the mask the
    decoder used (select_object_mask(tile_chain_body_mask(…))):
    rec = (rec & !mask) | body. actuator_extra replaces w_02 bits 7..15
    (w_02 = (w_02 & 0x7f) | (v << 7)), in the save's byte order, before the
    body merge (engine order).
  3. Dynamic records (appended_records): the engine frees the raw dynamic
    tail and allocates fresh records from the stream. We instead use R≡C
    (docs/formats/save-placement-linkage.md): the raw chain's dynamic tail,
    in order, is the stream's appended_records. Walk it with
    TileChainWalker and write each CheckcodeRecord's body into its raw slot,
    keeping the raw link words (next_oid; possession head of types 4/9/14).
    Recurse sub_records onto the raw possession chain the same way. Side
    fields the stream carries apart from data (creature ai_spec_flags,
    chest class) go back into their bytes as read_chain takes them out; use
    CheckcodeRecord::decode_object's view of the record where it already
    does so. A count or type mismatch between the raw chain and the stream is
    an error, never a silent partial image.

Back-link teleporter tiles (should_read_chain == false) are left as raw, like
the engine.

Where it lives

  • dm2-saves: SaveDump::live_dungeon(&self, map_info: &DungeonMapInfo) -> Result<Vec<u8>, JsonError> (name is the builder's call), full dumps only
    (WrongVariant otherwise). Built from raw + record_stream, no bitstream
    re-encode. Walker map info from the save's map_data
    (SaveFile::save_map_info logic).
  • dm2-convert: SaveGame::level_layout(level, &LayoutOptions) and
    level_chips(level, &ChipsOptions), reusing DungeonFile's option types.
    Each call builds the image and a DungeonFile from it: no cache, so edits
    show at once. A cache invalidated on edit is the builder's call if a call
    proves slow on the 4 MB DOS dump; measure first.
  • dm2-wasm / dm2-ffi: thin wrappers, doc comments as on DungeonFile.
    TS option types are LayoutOptions / ChipsOptions.
  • crates/dm2-wasm/README.md, CHANGELOG.md: document the two methods.

Tests

Fixtures: dos-en/saves/sksave*.dat, mac-us/saves/*, dos-en-beta saves.

  • Image parses; levelLayout / levelChips succeed for every level of every
    fixture save.
  • Overlay is load-bearing: on a fixture, a door tile whose floor bits differ
    from raw map_data, and a tile whose creature/item set differs from
    dungeon.dat, show the save's state (pick concrete tiles while building).
  • An edit shows in the image. No SaveGame edit touches the map yet (all
    are held-item edits), so test at the dm2-saves level: add_object on a
    SaveFileFull → SaveDump::full → image shows the item.
  • Limited save: NoContext.
  • FFI ABI test entries as for the other dm2_save_game_* calls.

Left to the builder

Function names, error variant names, internal module split, test tile picks,
whether a no-overlay helper is exposed for tests.

# #482 — a save's live dungeon as layout and chips ## Intent A save holds the live dungeon: doors opened, creatures moved or killed, items dropped. `DungeonFile.levelLayout` / `levelChips` only read `dungeon.dat`. The web editor's Dungeon tab wants the same views of an open save, beside the shipped dungeon, and later of its edits (party, doors, floor items, creatures). ## Goals - `SaveGame.levelLayout(level, options)` and `SaveGame.levelChips(level, options)` (wasm), same JSON as `DungeonFile`'s, drawn from the save's state and the `GraphicsArchive` the save keeps. - Same pair in the FFI (`dm2_save_game_level_layout`, `_level_chips`): bindings features land on both. - Engine-faithful state: what the engine holds after loading the save, record stream overlay included (user's call). Stale creatures, wrong door states and missing dropped items are all failures. - Edits made through `SaveGame` show in the next call. ## Non-goals - `mapLayout` / `mapChips` / `mapPng` / `levelPng` on `SaveGame` (trivial to add later on the same base). - Party marker or any JSON beyond `DungeonFile`'s. - Limited saves (no context): refused with `NoContext`. - Items held by champions or the cursor: not on the map. ## Anti-goals - Changing `dm2-magicmap` to know about saves. It draws a `Dungeon`; we give it one. - Reaching into `dm2-saves` internals from `dm2-convert` or the bindings: convert calls one `dm2-saves` API. ## How: a dungeon.dat image of the live state The save's raw sections are dungeon.dat's sections in the same order (`docs/formats/dungeon-dat.md` § File body layout): ```text save live dungeon.dat image dungeon_state (FileHeader) ─▶ header map_table ─▶ per-map metadata obj_link_arrays ─▶ columns obj_list ─▶ object list text_data ─▶ text data raw_record_arrays[16] ─▶ records ◀── overlay (2), (3) map_data ─▶ tile data ◀── overlay (1) checksum (recomputed: byte sum mod 0x10000) ``` `dungeon_state` is the play-time header (`SgWords` maps all 44 bytes), so the section sizes match. The image parses with the existing `Dungeon::parse`, and `dm2-convert` wraps it in a `DungeonFile` to reuse `level_layout` / `level_chips` unchanged. The overlay replays the engine's load (`DM2_READ_SKSAVE_DUNGEON`, SKWINSPX `sksvgame.cpp`; per-tile loop ~L1180–1320, `READ_RECORD_CHECKCODE` ~L830–960) from the decoded `RecordStream`, per `TileChain`: 1. **Floor bits** (`floor_bits`, mask 0x08 pit / 0x07 door / 0x04 trick wall / 0x08 detail-less teleporter): `SUPPRESS_READER(tile, mask, …, argflag=false)` merges, so `tile = (tile & !mask) | (bits & mask)` at `map_offset + x * height + y`. Mask selection is the decoder's (`decode_tile_chains`); reuse it, don't restate it. 2. **Static overlays** (`existing_chain_reads`): zip with the same step list the decoder walked (`static_overlay_steps`, Beta pair-fold included) to get each read's `(rec_type, rec_index)`. Body merges byte-wise with the mask the decoder used (`select_object_mask(tile_chain_body_mask(…))`): `rec = (rec & !mask) | body`. `actuator_extra` replaces `w_02` bits 7..15 (`w_02 = (w_02 & 0x7f) | (v << 7)`), in the save's byte order, before the body merge (engine order). 3. **Dynamic records** (`appended_records`): the engine frees the raw dynamic tail and allocates fresh records from the stream. We instead use R≡C (`docs/formats/save-placement-linkage.md`): the raw chain's dynamic tail, in order, is the stream's `appended_records`. Walk it with `TileChainWalker` and write each `CheckcodeRecord`'s body into its raw slot, keeping the raw link words (`next_oid`; possession head of types 4/9/14). Recurse `sub_records` onto the raw possession chain the same way. Side fields the stream carries apart from `data` (creature `ai_spec_flags`, chest class) go back into their bytes as `read_chain` takes them out; use `CheckcodeRecord::decode_object`'s view of the record where it already does so. A count or type mismatch between the raw chain and the stream is an error, never a silent partial image. Back-link teleporter tiles (`should_read_chain == false`) are left as raw, like the engine. ## Where it lives - `dm2-saves`: `SaveDump::live_dungeon(&self, map_info: &DungeonMapInfo) -> Result<Vec<u8>, JsonError>` (name is the builder's call), full dumps only (`WrongVariant` otherwise). Built from `raw` + `record_stream`, no bitstream re-encode. Walker map info from the save's `map_data` (`SaveFile::save_map_info` logic). - `dm2-convert`: `SaveGame::level_layout(level, &LayoutOptions)` and `level_chips(level, &ChipsOptions)`, reusing `DungeonFile`'s option types. Each call builds the image and a `DungeonFile` from it: no cache, so edits show at once. A cache invalidated on edit is the builder's call if a call proves slow on the 4 MB DOS dump; measure first. - `dm2-wasm` / `dm2-ffi`: thin wrappers, doc comments as on `DungeonFile`. TS option types are `LayoutOptions` / `ChipsOptions`. - `crates/dm2-wasm/README.md`, `CHANGELOG.md`: document the two methods. ## Tests Fixtures: `dos-en/saves/sksave*.dat`, `mac-us/saves/*`, `dos-en-beta` saves. - Image parses; `levelLayout` / `levelChips` succeed for every level of every fixture save. - Overlay is load-bearing: on a fixture, a door tile whose floor bits differ from raw `map_data`, and a tile whose creature/item set differs from `dungeon.dat`, show the save's state (pick concrete tiles while building). - An edit shows in the image. No `SaveGame` edit touches the map yet (all are held-item edits), so test at the `dm2-saves` level: `add_object` on a `SaveFileFull` → `SaveDump::full` → image shows the item. - Limited save: `NoContext`. - FFI ABI test entries as for the other `dm2_save_game_*` calls. ## Left to the builder Function names, error variant names, internal module split, test tile picks, whether a no-overlay helper is exposed for tests.
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jqueuniet/dm2-tools#482
No description provided.