dungeon.dat: decode the remaining residual bits #392

Closed
opened 2026-10-28 08:04:56 +01:00 by jqueuniet · 7 comments
Owner

Prerequisite of #390 (schema v3): decode as many residual bits as possible first, so v3 carries named fields rather than residuals.

Counts are over the 16 fixture dungeons.

Identified in SKWINSPX: add accessors

Field Bits Set in Meaning
Map flags_word 2 1 map w2_2_2: map uses the invisible lower-pitfall graphics
Map flags_word 6 22 maps w2_6_6: map uses the message-board graphics
Scroll attributes 10–15 127/127 w2_a_f: graphics.dat text number; values above 1 replace the dungeon.dat text reference (sktext.cpp:646)
Actuator behaviour 11 423/13578 ActuatorToggler / IsDisabled
Creature b15 2 3841/3841 important flag (skgame.cpp:3182)
Creature b14 7 0 b14_7_7: when set, the creature doesn't drop its possessions on spawn

Named, meaning partial

  • Teleporter dest_map_word bit 0 (w4_0_0, set on 896): when set, skdungn.cpp:61 returns early for teleporter tiles.
  • Teleporter bits 1–2 (b4_1_2, values 3 and 6 seen): when not 3, actions open and close the teleporter through tile bit 3.

Unknown

  • Map w12 bits 8–11 (unknown1, values 1–5 in 389 maps): no reader found, and no correlation with the other map fields.
  • Always 0 in the fixtures; keep as residuals: num_graphs_word bits 12–15 (rFloors), w14 bits 0–3, unused_4/unused_5, door bits 14–15.

Tile attribute nibbles

  • Floor: the whole nibble is raw. Bit 3 is set on 2145 tiles.
  • Door bit 3: set on 380/698.
  • Trick wall bit 0: set on 130.
  • DM1 leads, unverified for DM2: floor bit 3 and trick-wall bit 0 mean "random ornament allowed"; door bit 3 is the orientation.

Actuators

  • Uncatalogued types: 10 types, 182 records (0x00, 0x02, 0x09, 0x1c, 0x28 ×111, 0x29, 0x33, 0x37, 0x3e, 0x7d).
  • Data where the catalog expects none: 492 records have non-zero data under types listed without a word-1 parameter.
  • No word-3 layout: 71 records use the "Strength" class, which has no layout.
  • Local targets: the word-3 layout for local targets is not decoded.

v3 decisions

  • Text database: emit strings only if the 5-bit encoder rebuilds it byte-exact.
  • Derived sections: map_offset, map_data_size, n_records, obj_list_size, the columns array and the object list follow from the rest. Keep them explicit or derive them.

Order

  1. Accessors for the identified bits.
  2. Engine reading for the teleporter w4 bits and the tile nibbles.
  3. Actuator catalog gaps.
  4. Map w12 bits 8–11.
Prerequisite of #390 (schema v3): decode as many residual bits as possible first, so v3 carries named fields rather than residuals. Counts are over the 16 fixture dungeons. ## Identified in SKWINSPX: add accessors | Field | Bits | Set in | Meaning | |---|---|---|---| | Map `flags_word` | 2 | 1 map | `w2_2_2`: map uses the invisible lower-pitfall graphics | | Map `flags_word` | 6 | 22 maps | `w2_6_6`: map uses the message-board graphics | | Scroll attributes | 10–15 | 127/127 | `w2_a_f`: `graphics.dat` text number; values above 1 replace the `dungeon.dat` text reference (`sktext.cpp:646`) | | Actuator `behaviour` | 11 | 423/13578 | `ActuatorToggler` / `IsDisabled` | | Creature `b15` | 2 | 3841/3841 | important flag (`skgame.cpp:3182`) | | Creature `b14` | 7 | 0 | `b14_7_7`: when set, the creature doesn't drop its possessions on spawn | ## Named, meaning partial - **Teleporter `dest_map_word` bit 0** (`w4_0_0`, set on 896): when set, `skdungn.cpp:61` returns early for teleporter tiles. - **Teleporter bits 1–2** (`b4_1_2`, values 3 and 6 seen): when not 3, actions open and close the teleporter through tile bit 3. ## Unknown - **Map `w12` bits 8–11** (`unknown1`, values 1–5 in 389 maps): no reader found, and no correlation with the other map fields. - **Always 0 in the fixtures; keep as residuals:** `num_graphs_word` bits 12–15 (`rFloors`), `w14` bits 0–3, `unused_4`/`unused_5`, door bits 14–15. ## Tile attribute nibbles - **Floor:** the whole nibble is raw. Bit 3 is set on 2145 tiles. - **Door bit 3:** set on 380/698. - **Trick wall bit 0:** set on 130. - DM1 leads, unverified for DM2: floor bit 3 and trick-wall bit 0 mean "random ornament allowed"; door bit 3 is the orientation. ## Actuators - **Uncatalogued types:** 10 types, 182 records (0x00, 0x02, 0x09, 0x1c, 0x28 ×111, 0x29, 0x33, 0x37, 0x3e, 0x7d). - **Data where the catalog expects none:** 492 records have non-zero data under types listed without a word-1 parameter. - **No word-3 layout:** 71 records use the "Strength" class, which has no layout. - **Local targets:** the word-3 layout for local targets is not decoded. ## v3 decisions - **Text database:** emit strings only if the 5-bit encoder rebuilds it byte-exact. - **Derived sections:** `map_offset`, `map_data_size`, `n_records`, `obj_list_size`, the columns array and the object list follow from the rest. Keep them explicit or derive them. ## Order 1. Accessors for the identified bits. 2. Engine reading for the teleporter `w4` bits and the tile nibbles. 3. Actuator catalog gaps. 4. Map `w12` bits 8–11.
Author
Owner

Progress (branch feat/392-residual-accessors):

Decoded:

  • Map flags: bit 2 is use_invisible_lower_pitfall, bit 6 is use_message_board.
  • Scroll: gdat_text (bits 15:10).
  • Creature: important (bit 10) and keeps_possession_positions (bit 7; when set, possessions keep their stored positions on actuator spawn).
  • Shooter word 3 (the "Strength" class): shot_energy (bits 11:4) and shot_energy_decay (bits 15:12), as read by ACTIVATE_SHOOTER and missile stepping.
  • Teleporter w4: blocks_passage (bit 0: IS_TILE_PASSAGE returns blocked, and neighbouring maps see a map exit); activation (bits 2:1; at 3, actions leave the open bit alone).
  • Tiles: door bit 3 is north_south; trick-wall bit 0 is map_blink (the magic map blinks the tile as floor).

Corrections to the inventory:

  • Actuator behaviour bit 11: only set on shooters (0x08, 0x0a, 0x0e). ActuatorToggler is SPX's DM1 compatibility, and ACTIVATE_SHOOTER doesn't read the bit. Still unknown.
  • Floor bit 3: the only reader found is the on/off state of type-0x11 text ornaments. That doesn't obviously explain 2145 tiles, so it is documented but not decoded.

Conflicts with the current decoding (SKWINSPX SUMMARIZE_STONE_ROOM against SKULLWIN c_gui_vp.cpp):

  • Walls: SKWINSPX reads four per-side ornament flags, rotated by facing; TileAttr::Wall decodes a 2-bit face selector in bits 1:0. Retail walls never set bits 3:2, which fits the selector, but this needs settling.
  • Stairs: bit 3 is compared with facing parity, like door orientation. That is an orientation, not the "down flag" TileAttr::Stairs claims. Bit 2 is the separate flag.
Progress (branch `feat/392-residual-accessors`): **Decoded:** - **Map flags:** bit 2 is `use_invisible_lower_pitfall`, bit 6 is `use_message_board`. - **Scroll:** `gdat_text` (bits 15:10). - **Creature:** `important` (bit 10) and `keeps_possession_positions` (bit 7; when set, possessions keep their stored positions on actuator spawn). - **Shooter word 3** (the "Strength" class): `shot_energy` (bits 11:4) and `shot_energy_decay` (bits 15:12), as read by `ACTIVATE_SHOOTER` and missile stepping. - **Teleporter `w4`:** `blocks_passage` (bit 0: `IS_TILE_PASSAGE` returns blocked, and neighbouring maps see a map exit); `activation` (bits 2:1; at 3, actions leave the open bit alone). - **Tiles:** door bit 3 is `north_south`; trick-wall bit 0 is `map_blink` (the magic map blinks the tile as floor). **Corrections to the inventory:** - **Actuator `behaviour` bit 11:** only set on shooters (0x08, 0x0a, 0x0e). `ActuatorToggler` is SPX's DM1 compatibility, and `ACTIVATE_SHOOTER` doesn't read the bit. Still unknown. - **Floor bit 3:** the only reader found is the on/off state of type-0x11 text ornaments. That doesn't obviously explain 2145 tiles, so it is documented but not decoded. **Conflicts with the current decoding** (SKWINSPX `SUMMARIZE_STONE_ROOM` against SKULLWIN `c_gui_vp.cpp`): - **Walls:** SKWINSPX reads four per-side ornament flags, rotated by facing; `TileAttr::Wall` decodes a 2-bit face selector in bits 1:0. Retail walls never set bits 3:2, which fits the selector, but this needs settling. - **Stairs:** bit 3 is compared with facing parity, like door orientation. That is an orientation, not the "down flag" `TileAttr::Stairs` claims. Bit 2 is the separate flag.
Author
Owner

Tile conflicts resolved in favour of SKWINSPX, the maintained tree (SKULLWIN is retired). Its editor (v4/skeditdn.cpp) documents each bit:

  • Pit: bit 3 open, bit 2 hidden (not a grate), bit 0 imaginary.
  • Stairs: bit 3 north-south orientation, bit 2 leads up.
  • Teleporter: bit 3 open, bit 2 haze.
  • Door: bit 3 north-south orientation.
  • Walls: per-side random-ornament flags (CSBwin TAG00a4a2).
  • Trick wall: bit 3 gives random ornaments on all sides while closed.

TileAttr was rewritten to match. Still unknown: pit bit 1 (the editor marks it ?).

Tile conflicts resolved in favour of SKWINSPX, the maintained tree (SKULLWIN is retired). Its editor (`v4/skeditdn.cpp`) documents each bit: - **Pit:** bit 3 open, bit 2 hidden (not a grate), bit 0 imaginary. - **Stairs:** bit 3 north-south orientation, bit 2 leads up. - **Teleporter:** bit 3 open, bit 2 haze. - **Door:** bit 3 north-south orientation. - **Walls:** per-side random-ornament flags (CSBwin `TAG00a4a2`). - **Trick wall:** bit 3 gives random ornaments on all sides while closed. `TileAttr` was rewritten to match. Still unknown: pit bit 1 (the editor marks it `?`).
Author
Owner

Confidence. SKWINSPX is a reimplementation; the retail engines are the truth.

Anchored to the original binary (//^seg:off markers in the cited code):

  • Shooters: energy and decay (ACTIVATE_SHOOTER, missile step).
  • Teleporter w4: blocks_passage (IS_TILE_PASSAGE) and activation (ACTUATE_TELEPORTER).
  • Creature important: SET_ITEM_IMPORTANCE.
  • Trick-wall map_blink: DRAW_MAP_CHIP.
  • Viewport summary (SUMMARIZE_STONE_ROOM):
    • per-side wall ornament flags;
    • door and stair bit 3 tested against facing parity;
    • pit bit 3 open;
    • teleporter drawn only when bits 3 and 2 are both set;
    • trick-wall bits 2 and 3.
  • Map flag bits 2 and 6: level graphics loading.

SKWINSPX-only, to confirm in-game:

  • Names from SPX's own editor (skeditdn.cpp): pit bit 2 "hidden", stair bit 2 "leads up", teleporter bit 2 "haze". The summary only passes bit 2 along.
  • Pit bit 0 "imaginary": the editor's name, used by creature AI code without anchors nearby.
  • Creature keeps_possession_positions: spawn code without anchors nearby.
  • Scroll: the original reads gdat_text != 0; SPX changed it to > 1. The doc now says non-zero.
Confidence. SKWINSPX is a reimplementation; the retail engines are the truth. **Anchored to the original binary** (`//^seg:off` markers in the cited code): - **Shooters:** energy and decay (`ACTIVATE_SHOOTER`, missile step). - **Teleporter `w4`:** `blocks_passage` (`IS_TILE_PASSAGE`) and `activation` (`ACTUATE_TELEPORTER`). - **Creature `important`:** `SET_ITEM_IMPORTANCE`. - **Trick-wall `map_blink`:** `DRAW_MAP_CHIP`. - **Viewport summary (`SUMMARIZE_STONE_ROOM`):** - per-side wall ornament flags; - door and stair bit 3 tested against facing parity; - pit bit 3 open; - teleporter drawn only when bits 3 and 2 are both set; - trick-wall bits 2 and 3. - **Map flag bits 2 and 6:** level graphics loading. **SKWINSPX-only, to confirm in-game:** - **Names from SPX's own editor (`skeditdn.cpp`):** pit bit 2 "hidden", stair bit 2 "leads up", teleporter bit 2 "haze". The summary only passes bit 2 along. - **Pit bit 0 "imaginary":** the editor's name, used by creature AI code without anchors nearby. - **Creature `keeps_possession_positions`:** spawn code without anchors nearby. - **Scroll:** the original reads `gdat_text != 0`; SPX changed it to `> 1`. The doc now says non-zero.
Author
Owner

In-game (DOS EN): pit bit 2 is hidden. Of two open pits, only the one without bit 2 is drawn. With no map below, falling deals ~4.5k damage instead of changing level; the second fall killed the party. The stair bit 2 check is pending.

In-game (DOS EN): pit bit 2 is **hidden**. Of two open pits, only the one without bit 2 is drawn. With no map below, falling deals ~4.5k damage instead of changing level; the second fall killed the party. The stair bit 2 check is pending.
Author
Owner

In-game (DOS EN): stair bit 2 is leads up. The up stair (bit 2 set) took the party to the map above. The down stair did nothing, since there is no map below, but it turned the party to the starting direction. Both were drawn with the debug placeholder graphic, likely because the start map's graphics set has no stair images.

In-game (DOS EN): stair bit 2 is **leads up**. The up stair (bit 2 set) took the party to the map above. The down stair did nothing, since there is no map below, but it turned the party to the starting direction. Both were drawn with the debug placeholder graphic, likely because the start map's graphics set has no stair images.
Author
Owner

Actuator catalog completed from SKWINSPX's handlers (branch feat/392-actuator-catalog).

New types:

  • 0x00 none;
  • floor 0x02 creature trap floor (creatures only);
  • 0x09 weapon shooter (creates the item data names);
  • 0x1c ladder (beta; data 5:0 is the destination map);
  • floor 0x28 creature attacker (killer handler; attacks creatures whose anim_seq matches data 8:4, with argument 3:0);
  • floor 0x2e party teleporter;
  • 0x33-0x37 tick generators with the period multiplied by 8 to 128.

Word-1 classes corrected:

  • floor 0x03: party facing + 1, 0 for any;
  • 0x0b: the same creature filter as 0x28;
  • 0x18 / 0x46: button delay in ticks;
  • 0x20: relay delay in ticks;
  • 0x2c: animation phase;
  • 0x42: 0..3 in retail data; SKWINSPX leaves the handler unimplemented, so the meaning is unconfirmed.

Still uncatalogued: 0x29 and 0x3e (beta, one record each) and 0x7d (DOS and Mac demos, 4 records); neither source documents them.

Confidence: all cited dispatch sites carry original-binary anchors, except the ladder (SPX reworked its trigger condition) and 0x42 (unimplemented).

Actuator catalog completed from SKWINSPX's handlers (branch `feat/392-actuator-catalog`). **New types:** - `0x00` none; - floor `0x02` creature trap floor (creatures only); - `0x09` weapon shooter (creates the item `data` names); - `0x1c` ladder (beta; data 5:0 is the destination map); - floor `0x28` creature attacker (killer handler; attacks creatures whose `anim_seq` matches data 8:4, with argument 3:0); - floor `0x2e` party teleporter; - `0x33`-`0x37` tick generators with the period multiplied by 8 to 128. **Word-1 classes corrected:** - floor `0x03`: party facing + 1, 0 for any; - `0x0b`: the same creature filter as `0x28`; - `0x18` / `0x46`: button delay in ticks; - `0x20`: relay delay in ticks; - `0x2c`: animation phase; - `0x42`: 0..3 in retail data; SKWINSPX leaves the handler unimplemented, so the meaning is unconfirmed. **Still uncatalogued:** `0x29` and `0x3e` (beta, one record each) and `0x7d` (DOS and Mac demos, 4 records); neither source documents them. **Confidence:** all cited dispatch sites carry original-binary anchors, except the ladder (SPX reworked its trigger condition) and `0x42` (unimplemented).
Author
Owner

Remaining unknowns resolved in #395 and #396, checked against SKWINSPX's v5 code (derived from the DOS binary).

Map w12 bits 11:8 (#395)

  • Exposed as Map::num_leading_creature_types().
  • Neither SKWINSPX's own code nor its DOS-derived code reads these bits. IS_CREATURE_ALLOWED_ON_LEVEL scans the whole allowed_creature_types list, not a leading part of it.
  • Observed: across all 614 fixture maps, the value (0–5) never exceeds the list length. On 510 maps, it counts the leading entries that have no creature placed at load. The meaning is still open.

Corrections to earlier decoding (#396)

  • Trick wall bit 0: besides the magic-map blink, it makes the wall passable while closed (IS_TILE_BLOCKED), so it is DM1's "imaginary" wall. map_blink is renamed imaginary.
  • keeps_possession_positions (creature b14 bit 7): read in ARRANGE_DUNGEON at new-game setup, for static creatures only. When clear, their possessions get random positions. It has nothing to do with actuator spawns. No retail record sets it.
  • Actuator 0x42: SKWINSPX's own code leaves it as a stub, but v5 implements it (3A15:0D5C). It turns the creature on the target tile to face data & 3. The trigger depends on the revert bit and the action. Each full game has exactly four 0x42 records, with data 0, 1, 2 and 3. Decoded as ParamClass::Direction.

Now backed by DOS-derived code, no longer SKWINSPX-only

  • Pit bit 0: in CREATURE_GO_THERE, creatures never use an open pit with bit 0 set to go down a level. Not checked: whether the party falls through one.
  • Teleporter bit 2: the viewport draws the teleporter only when bits 3 and 2 are both set, and as floor otherwise.

Newly catalogued

  • Wall 0x29 (beta): handled in PLACE_OR_REMOVE_OBJECT_IN_ROOM. It fires when the side holds no other item, the any-item counterpart of 0x2a. Its data is unread. Its one record sits on a wall side holding a chest.

Nothing in the retail engine reads these

  • Actuator behaviour bit 11: set only on shooters and 0x7d. INVOKE_ACTUATOR takes the delay from bits 10:7, the shooter code reads only words 2 and 6, and no other read of word 4 reaches bit 11.
  • Floor bit 3: its only reader is the type-0x11 text ornament. It is set only on 165 tiles of map 1 in every full game, all without objects. So it has no effect in retail; it may be leftover editor data.
  • Wall 0x3e (beta): falls in the wall dispatcher's no-op group.
  • 0x7d (demos): beyond the dispatcher's range.
  • 0x3e and 0x7d stay uncatalogued. How the beta and demo engines handle them is unchecked.
Remaining unknowns resolved in #395 and #396, checked against SKWINSPX's v5 code (derived from the DOS binary). **Map `w12` bits 11:8** (#395) - Exposed as `Map::num_leading_creature_types()`. - Neither SKWINSPX's own code nor its DOS-derived code reads these bits. `IS_CREATURE_ALLOWED_ON_LEVEL` scans the whole `allowed_creature_types` list, not a leading part of it. - Observed: across all 614 fixture maps, the value (0–5) never exceeds the list length. On 510 maps, it counts the leading entries that have no creature placed at load. The meaning is still open. **Corrections to earlier decoding** (#396) - **Trick wall bit 0:** besides the magic-map blink, it makes the wall passable while closed (`IS_TILE_BLOCKED`), so it is DM1's "imaginary" wall. `map_blink` is renamed `imaginary`. - **`keeps_possession_positions` (creature `b14` bit 7):** read in `ARRANGE_DUNGEON` at new-game setup, for static creatures only. When clear, their possessions get random positions. It has nothing to do with actuator spawns. No retail record sets it. - **Actuator 0x42:** SKWINSPX's own code leaves it as a stub, but v5 implements it (`3A15:0D5C`). It turns the creature on the target tile to face `data & 3`. The trigger depends on the revert bit and the action. Each full game has exactly four 0x42 records, with data 0, 1, 2 and 3. Decoded as `ParamClass::Direction`. **Now backed by DOS-derived code, no longer SKWINSPX-only** - **Pit bit 0:** in `CREATURE_GO_THERE`, creatures never use an open pit with bit 0 set to go down a level. Not checked: whether the party falls through one. - **Teleporter bit 2:** the viewport draws the teleporter only when bits 3 and 2 are both set, and as floor otherwise. **Newly catalogued** - **Wall 0x29 (beta):** handled in `PLACE_OR_REMOVE_OBJECT_IN_ROOM`. It fires when the side holds no other item, the any-item counterpart of 0x2a. Its data is unread. Its one record sits on a wall side holding a chest. **Nothing in the retail engine reads these** - **Actuator `behaviour` bit 11:** set only on shooters and 0x7d. `INVOKE_ACTUATOR` takes the delay from bits 10:7, the shooter code reads only words 2 and 6, and no other read of word 4 reaches bit 11. - **Floor bit 3:** its only reader is the type-0x11 text ornament. It is set only on 165 tiles of map 1 in every full game, all without objects. So it has no effect in retail; it may be leftover editor data. - **Wall 0x3e (beta):** falls in the wall dispatcher's no-op group. - **0x7d (demos):** beyond the dispatcher's range. - 0x3e and 0x7d stay uncatalogued. How the beta and demo engines handle them is unchecked.
Sign in to join this conversation.
No milestone
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.

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