dungeon.dat: magic-map images from dm2 extract #402

Closed
opened 2026-10-28 23:37:06 +01:00 by jqueuniet · 2 comments
Owner

Intent

Look over a dungeon's content at a glance without loading the game, drawn
with the game's own magic-map artwork. The image shows what the in-game
magic map can show and nothing it cannot.

Goals

  • dm2 extract dungeon.dat -o out/ --gdat graphics.dat also writes one
    map_NN.png per map, next to the existing map_NN.json (same numbering).
  • Content: the terrain the magic map draws (walls, floors, doors in their
    stored state, open pits, stairs and their direction, visible teleporters,
    wall and floor ornaments) and, with an opt-in flag, creatures at their
    new-game positions.
  • Artwork: the graphics.dat map chips (cls4 = 0xf9), as the engine picks
    them.
  • Animated chips (open pits, the teleporter swirl, animated ornaments or
    creatures) make the file an APNG, all animations looping together; a map
    with nothing animated is a plain PNG.
  • --scale N: whole-number upscale, native (1) by default.
  • PC-family releases (DOS, Mac, FM-Towns, PC-98).

Non-goals (follow-ups)

  • Assembling a level's maps into one image, placed by shift_x/shift_y.
  • Console ports (Sega CD, the PSV): their palette scheme is still open in
    dm2-graphics.

Anti-goals

  • Drawing anything the in-game magic map cannot (floor items, text, hidden
    pits, closed teleporters, actuators as such).

My calls (check these)

  • North up, no party marker or start position: the export has no party.
  • The creature flag's name and the crate that owns the cell-to-chip rules
    are left to the builder.
  • On a console-family graphics.dat, extract writes the JSON and says map
    images are not supported yet.
  • A release mismatch between the two files is refused or warned about.
  • Artwork that is not the game's own.
  • Silently wrong output from a graphics.dat of another release.

Decided

  • Folded into dm2 extract; without --gdat, extract behaves as today.
  • One image per map, map_NN.png, beside map_NN.json.
  • Creatures off by default, behind a flag.
  • Hidden passages (trick walls with the imaginary bit, passable while
    closed) are revealed as the magic map's reveal mode does: they blink
    between wall and floor, which makes the map an APNG.
  • --scale: integer only, default 1.
  • Validation: compare against the DMDC2 "World Atlas" maps on DMWeb
    (http://dmweb.free.fr/games/dungeon-master-ii/solutions/maps-dmdc2/,
    DOS). They are per-level, assembled, drawn with editor icons at about
    16 px a cell and labelled in level coordinates: a map's image matches the
    region at its shift_x/shift_y offset. They check layout and contents,
    not artwork.

Constraints and known facts

  • Engine geometry: a 7×7 chip per cell on an 8-px grid. Chips are horizontal
    strips of 7-px frames, frames = width / 7; the frame index selects the
    appearance. Each chip carries its own 16-colour palette; map chips use
    alpha-A transparency (dm2-graphics transparency.rs already handles
    this).
  • Chip families (cls3 = dtImage, cls4 = 0xf9): base terrain strip
    cls1 0x08 keyed by the map's map_graphics_style; wall ornaments 0x09;
    floor ornaments 0x0a; teleporter swirl 0x18; creatures 0x0f.
  • Tile semantics come from dm2-dungeon's TileAttr, as settled in #392,
    not from the older spec.
  • dm2-graphics icon.rs already writes APNG.
  • The engine reference is SKWINSPX: its magic map renderer
    (DRAW_MAP_CHIP), the cell summary (SUMMARIZE_STONE_ROOM) and the chip
    query. Only code ported from the original binary (//^seg:off, or v5) is
    authoritative; SPX additions are leads.
  • Layering: the CLI calls library APIs; chip slicing belongs in
    dm2-graphics, cell-to-chip rules in a library crate, not in the CLI.

Left to the builder

  • Reverifying the earlier investigation (magic-map-rendering-spec.md, which
    cites the retired SKULLWIN tree) against SKWINSPX, and correcting it where
    #392 found the tile bits read differently.
  • Orientation: north up, no party marker. The engine draws relative to party
    facing; pick the frame and mirror flags of a party facing north.
  • Animation frame timing and loop length (the common cycle of the animated
    chips), and the game-tick phase to start from.
  • Wall-ornament randomness: the engine seeds it per cell
    (GET_RANDOM_ORNAMENT_ORDINAL); reproduce it or document the gap.
  • Map exits and map edges (border tileset).
  • The colour of the 1-px gap between cells.
  • How a release mismatch between dungeon.dat and graphics.dat is
    detected and reported.
  • Which crate owns the cell-to-chip rules (dm2-dungeon, dm2-graphics, or
    a new crate), and the CLI flag name for creatures.
  • Behaviour on a console-family graphics.dat: say map images are not
    supported yet, still write the JSON.
## Intent Look over a dungeon's content at a glance without loading the game, drawn with the game's own magic-map artwork. The image shows what the in-game magic map can show and nothing it cannot. ## Goals - `dm2 extract dungeon.dat -o out/ --gdat graphics.dat` also writes one `map_NN.png` per map, next to the existing `map_NN.json` (same numbering). - Content: the terrain the magic map draws (walls, floors, doors in their stored state, open pits, stairs and their direction, visible teleporters, wall and floor ornaments) and, with an opt-in flag, creatures at their new-game positions. - Artwork: the `graphics.dat` map chips (`cls4 = 0xf9`), as the engine picks them. - Animated chips (open pits, the teleporter swirl, animated ornaments or creatures) make the file an APNG, all animations looping together; a map with nothing animated is a plain PNG. - `--scale N`: whole-number upscale, native (1) by default. - PC-family releases (DOS, Mac, FM-Towns, PC-98). ## Non-goals (follow-ups) - Assembling a level's maps into one image, placed by `shift_x`/`shift_y`. - Console ports (Sega CD, the PSV): their palette scheme is still open in `dm2-graphics`. ## Anti-goals - Drawing anything the in-game magic map cannot (floor items, text, hidden pits, closed teleporters, actuators as such). ## My calls (check these) - North up, no party marker or start position: the export has no party. - The creature flag's name and the crate that owns the cell-to-chip rules are left to the builder. - On a console-family `graphics.dat`, extract writes the JSON and says map images are not supported yet. - A release mismatch between the two files is refused or warned about. - Artwork that is not the game's own. - Silently wrong output from a `graphics.dat` of another release. ## Decided - Folded into `dm2 extract`; without `--gdat`, extract behaves as today. - One image per map, `map_NN.png`, beside `map_NN.json`. - Creatures off by default, behind a flag. - Hidden passages (trick walls with the `imaginary` bit, passable while closed) are revealed as the magic map's reveal mode does: they blink between wall and floor, which makes the map an APNG. - `--scale`: integer only, default 1. - Validation: compare against the DMDC2 "World Atlas" maps on DMWeb (<http://dmweb.free.fr/games/dungeon-master-ii/solutions/maps-dmdc2/>, DOS). They are per-level, assembled, drawn with editor icons at about 16 px a cell and labelled in level coordinates: a map's image matches the region at its `shift_x`/`shift_y` offset. They check layout and contents, not artwork. ## Constraints and known facts - Engine geometry: a 7×7 chip per cell on an 8-px grid. Chips are horizontal strips of 7-px frames, `frames = width / 7`; the frame index selects the appearance. Each chip carries its own 16-colour palette; map chips use alpha-A transparency (`dm2-graphics` `transparency.rs` already handles this). - Chip families (`cls3 = dtImage`, `cls4 = 0xf9`): base terrain strip `cls1 0x08` keyed by the map's `map_graphics_style`; wall ornaments `0x09`; floor ornaments `0x0a`; teleporter swirl `0x18`; creatures `0x0f`. - Tile semantics come from `dm2-dungeon`'s `TileAttr`, as settled in #392, not from the older spec. - `dm2-graphics` `icon.rs` already writes APNG. - The engine reference is SKWINSPX: its magic map renderer (`DRAW_MAP_CHIP`), the cell summary (`SUMMARIZE_STONE_ROOM`) and the chip query. Only code ported from the original binary (`//^seg:off`, or v5) is authoritative; SPX additions are leads. - Layering: the CLI calls library APIs; chip slicing belongs in `dm2-graphics`, cell-to-chip rules in a library crate, not in the CLI. ## Left to the builder - Reverifying the earlier investigation (`magic-map-rendering-spec.md`, which cites the retired SKULLWIN tree) against SKWINSPX, and correcting it where #392 found the tile bits read differently. - Orientation: north up, no party marker. The engine draws relative to party facing; pick the frame and mirror flags of a party facing north. - Animation frame timing and loop length (the common cycle of the animated chips), and the game-tick phase to start from. - Wall-ornament randomness: the engine seeds it per cell (`GET_RANDOM_ORNAMENT_ORDINAL`); reproduce it or document the gap. - Map exits and map edges (border tileset). - The colour of the 1-px gap between cells. - How a release mismatch between `dungeon.dat` and `graphics.dat` is detected and reported. - Which crate owns the cell-to-chip rules (`dm2-dungeon`, `dm2-graphics`, or a new crate), and the CLI flag name for creatures. - Behaviour on a console-family `graphics.dat`: say map images are not supported yet, still write the JSON.
Author
Owner

Magic-Map Export Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: dm2 extract dungeon.dat -o out/ --gdat graphics.dat writes one magic-map map_NN.png (APNG when animated) per map, drawn with the game's own map chips.

Architecture: A new library crate dm2-magicmap turns a dungeon cell into an ordered list of chips (class tuple, frame, mirror) for a given game tick, following SKWINSPX v5's DM2_DRAW_MAP_CHIP, composites them on an 8-px grid and encodes PNG/APNG. The CLI and the bindings (through dm2-convert) call it. dm2-graphics gains the creature AI lookup now private to dm2-saves.

Tech Stack: Rust 2024, png (APNG, as dm2-graphics/src/icon.rs), existing dm2-dungeon / dm2-graphics APIs.

Spec: issue #402 (draft: scratch/magic-map-export-design.md).

Global Constraints

  • One image per map, map_NN.png beside map_NN.json; extract unchanged without --gdat.
  • Creatures off by default (--creatures to enable); --scale N, integer, default 1, minimum 1.
  • PC-family archives only; on a console-family graphics.dat, extract still writes the JSON and prints that map images are not supported yet.
  • North up, no party marker; render with the engine's party facing = 0 and the reveal flag (argl3 & 2) set, so hidden passages, hidden pits and secret ornaments blink or show as in the magic map's reveal mode.
  • Engine authority: SKWINSPX v5 (src/v5/skguidrw.cpp DM2_DRAW_MAP_CHIP 2413-3200, DM2_DRAW_CHIP_OF_MAGIC_MAP 312, iterator around 3760-3925) and v4 code carrying //^seg:off markers. The June spec (scratch/magic-map-rendering-spec.md) cites retired SKULLWIN: use it as a map, not as truth. Tile meanings come from dm2_dungeon::TileAttr (#392).
  • Layering: CLI and dm2-convert call dm2-magicmap; dm2-magicmap calls dm2-dungeon / dm2-graphics; no reach-through.
  • Bindings stay at parity (wasm, FFI, Python) with the CLI capability.

Engine facts the tasks rely on (verified in v5)

  • Cell: 7x7 chip, 8-px pitch (dm2data.cpp:1411-1414); blit key colour ALPHA_A (0x0a); mirror flags bit0 = X, bit1 = Y; table1d6980 = {0,0,3,3}, table1d6984[20] (dm2data.cpp:882-889).
  • Base strip (0x08, tileset, 0x01, 0xf9); tileset = map_graphics_style, except map-exit cells and floor tiles with attribute bit 3, which use the level's border tileset, frame 0.
  • Border tileset per level: digits of the first plain text record (attributes bits 2:1 = 0) on map 0's party start tile; DOS-EN reads 011111122200 (sksvgame.cpp:140-225).
  • Frames on the base strip: wall/map exit 0; floor 2; pit 3, 4 when hidden (bit 2), 5 on odd ticks when hidden in reveal mode; door 0xb or 0xa by axis, +2 unless the door record has has_button or switch_enabled, +4 when state is 0 or 5; stairs 6 + ((dir - facing) & 3), rotated +2 (mod 4) when up, dir from DM2_query_0cee_06dc.
  • Trick wall closed with imaginary: drawn as wall except when tick & 2 (reveal mode), where it falls through to floor.
  • Teleporter (open and haze): floor frame 2, then (0x18, 0, 0x01, 0xf9) frame tick % frames.
  • Wall sides: up to 4 ornament ordinals from the cell summary, chip (0x09, ordinal); without reveal, skipped when (0x09, ordinal, 0x0b, 0xf9) exists. Floor ornament (0x0a, ordinal), same rule; frame from the summary's anim byte.
  • Creatures: chip (0x0f, type, 0x01, 0xf9); mobile: frame 2 * (tick % (frames / 2)) + (rel & 1), mirror table1d6980[rel], rel = (facing - creature.direction) & 3; static (AI flag bit 0): frame rel & 1. No chip: skipped when static or AI flag 0x2000, else image (0x0f, type, 0x01, 0x40) frame tick & 1.

Review Focus

  1. A map whose tileset has no (0x08, tileset) strip (beta, demos): skip that map with a warning naming it, keep the others.
  2. Mismatched files (Mac graphics.dat with a DOS dungeon): refuse with one clear error before writing images.
  3. A start tile without the border-tileset text (custom dungeons): fall back to map_graphics_style for map exits and bit-3 floors, warn once.
  4. --scale 0 or a huge scale: reject 0 in clap; cap the canvas (32 * 8 * scale) at 4096 px per side with an error.
  5. Creature types with no chip and unknown 0x2000 flag: draw per the rule above; never panic on a missing image.

Task 1: Creature AI lookup in dm2-graphics

Files:

  • Modify: crates/dm2-graphics/src/lib.rs (new creature_ai module export)
  • Create: crates/dm2-graphics/src/creature_ai.rs
  • Modify: crates/dm2-saves/src/sksave.rs:44-77, crates/dm2-saves/src/records.rs:115

Interfaces:

  • Produces: Archive::creature_ai_index(&self, creature_type: u8) -> u8 (inline word (0x0f, type, 0x0b, 0x05), else 0x04, else type, as compute_creature_alt_species_mask); dm2_graphics::creature_ai_is_static(ai_index: u8) -> bool (bit 0 of the AI flags, from the table now at dm2_saves::records::CREATURE_GIDX_ALT_TABLE, moved here).

  • Step 1: Confirm against SKWINSPX that the table's bit is AIDefinition::w0AIFlags & 1 (v0/dme.h IsStaticObject, dAITable); note the source in the doc comment.

  • Step 2: Failing test creature_ai_static_matches_saves_table in creature_ai.rs: for every ai_index < 64, creature_ai_is_static(i) equals bit i of [0xff, 0x1f, 0x10, 0x00, 0xe0, 0x20, 0x08, 0x99]; >= 64 is false. Fixture test: DOS-EN creature_ai_index(20) == 20.

  • Step 3: Implement; make compute_creature_alt_species_mask call the two functions; remove the table from dm2-saves.

  • Step 4: cargo test -p dm2-graphics -p dm2-saves passes (save round-trip tests unchanged).

  • Step 5: Commit refactor(graphics): share the creature AI static flag with dm2-saves.

Task 2: dm2-magicmap crate and terrain chips

Files:

  • Create: crates/dm2-magicmap/{Cargo.toml,src/lib.rs,src/cell.rs,src/border.rs}; add to workspace members and [workspace.dependencies].

Interfaces:

  • Produces:

    • pub struct Chip { pub cls1: u8, pub cls2: u8, pub cls4: u8, pub frame: u16, pub mirror: u8 } (cls4 0xf9 except the 0x40 creature fallback)
    • pub struct MapView<'a> { dungeon: &'a Dungeon<'a>, map: usize, tileset: u8, border: u8 } with MapView::new(d: &'a Dungeon<'a>, map: usize, borders: &[u8]) -> Option<Self> (None when map is out of range)
    • pub fn border_tilesets(d: &Dungeon) -> Option<Vec<u8>>
    • pub fn terrain_chips(view: &MapView, x: u8, y: u8, tick: u32) -> Vec<Chip> (base chip, teleporter swirl)
  • Step 1: Failing tests in cell.rs on synthetic one-tile maps, facing 0: wall → [(8, ts, 0)]; floor → frame 2; open pit → 3; hidden pit → 4 at tick 0, 5 at tick 1; door (state 4, N-S, no button) → 0xb + 2; open door (state 0) → 0xb + 2 + 4; up stairs and down stairs differ by 2 (mod 4) in frame - 6; imaginary trick wall → wall at ticks 0-1, floor at 2-3; open+haze teleporter → floor chip then (0x18, 0, frame tick % n); map exit → (8, border, 0); floor with bit 3 → (8, border, 0).

  • Step 2: Fixture test dos_en_border_tilesets: border_tilesets(dos-en) == Some(b"011111122200".map(|c| c - b'0')). Synthetic test: no text on the start tile gives None, and MapView::new(.., &[]) uses map_graphics_style as the border tileset.

  • Step 3: Implement from v5 DM2_DRAW_MAP_CHIP 2503-2860 and the v4 summary (skdungn.cpp SUMMARIZE_STONE_ROOM), facing 0, reveal on. Port DM2_query_0cee_06dc for the stair direction and the door-axis test of the summary. The swirl frame count comes from the chip, so terrain_chips returns the swirl with frame = tick and the compositor reduces it modulo the strip's frame count.

  • Step 4: cargo test -p dm2-magicmap passes.

  • Step 5: Commit feat(magicmap): select terrain map chips per cell.

Task 3: Ornaments

Files: Modify crates/dm2-magicmap/src/cell.rs; create src/ornament.rs.

Interfaces:

  • Produces: terrain_chips also returns wall-side ornaments (0x09, ordinal) and floor ornaments (0x0a, ordinal) in engine draw order.

  • Step 1: Failing tests: DOS-EN map 0: a wall cell holding a champion mirror (actuator 0x7e on side 1 of (0,5)) yields a 0x09 chip with mirror table1d6980[1]; a floor actuator 0x2c at (2,1) yields a 0x0a chip; random wall ornaments: a cell from a map with wall_graphics_random_decorations > 0 matches the ordinal from GET_RANDOM_ORNAMENT_ORDINAL (port GET_RANDOM_ORNAMENT_INDEX, skdungn.cpp:306-370).

  • Step 2: Implement the side ordinals (random + wall decorations from actuators/texts on each side) and the floor ornament with its anim frame, from v5 2686-2750 / 2771-2824.

  • Step 3: Tests pass; commit feat(magicmap): draw wall and floor ornaments.

Task 4: Creatures

Files: Create crates/dm2-magicmap/src/creature.rs.

Interfaces:

  • Consumes: Task 1 lookups.

  • Produces: pub fn creature_chips(view: &MapView, gdat: &Archive, x: u8, y: u8, tick: u32) -> Vec<Chip> (one per creature in the tile chain, chain order).

  • Step 1: Failing tests: DOS-EN map with a mobile creature: frame and mirror follow the rule above at ticks 0 and 1; a static creature (AI bit 0, e.g. a table) uses frame rel & 1 at every tick; a type with no 0xf9 chip and AI bit 0 yields nothing.

  • Step 2: Implement from v5 2970-3095.

  • Step 3: Tests pass; commit feat(magicmap): draw creatures at their starting positions.

Task 5: Compositing, animation, PNG/APNG

Files: Create crates/dm2-magicmap/src/render.rs.

Interfaces:

  • Produces:

    • pub struct RenderOptions { pub scale: u8, pub creatures: bool }
    • pub enum MagicMapError { MapOutOfRange(usize), ConsoleFamily, ByteOrderMismatch, NoTileset { map: usize, tileset: u8 }, TooLarge { width: u32, height: u32 } }
    • pub fn render_map_png(d: &Dungeon, gdat: &Archive, map: usize, opts: &RenderOptions) -> Result<Vec<u8>, MagicMapError>
  • Step 1: Failing tests: DOS-EN map 0 at scale 1 is 7*8 x 10*8 RGBA, background opaque black, gap pixels black; scale 3 triples both sides; map 0 has no animated chip, so the result has no acTL chunk; DOS-EN map 1 (outdoor, teleporter) has acTL with num_frames equal to the loop length; a Mac graphics.dat with the DOS dungeon gives ByteOrderMismatch; a console archive gives ConsoleFamily; a map whose map_graphics_style has no (0x08, style) strip gives NoTileset; scale making a side over 4096 gives TooLarge.

  • Step 2: Implement: decode each chip once (Archive::decode_image, slice with Image::frames(7)), key ALPHA_A, apply mirror flags, composite tick by tick. Loop length: the least common multiple of the periods present (4 for blinking trick walls, 2 for hidden pits and creature fallbacks, swirl frame count, 2 * (frames/2) per mobile creature, floor ornament periods), capped at 64; one APNG frame per game tick at TICK_MS. Find the engine tick length in SKWINSPX (timer setup) and pin TICK_MS with its citation; a single-frame result is a plain PNG.

  • Step 3: Tests pass; commit feat(magicmap): render maps to PNG and APNG.

Task 6: dm2 extract --gdat

Files: Modify crates/dm2-cli/src/main.rs (Extract args), crates/dm2-cli/src/commands/extract.rs:437-480; test crates/dm2-cli/tests/extract_magic_map.rs.

Interfaces:

  • Consumes: render_map_png.

  • Produces: Extract flags --gdat <path> (dungeon inputs only; error on other inputs), --creatures, --scale <N> (u8, 1.., default 1; both require --gdat).

  • Step 1: Failing test: extract DOS-EN with --gdat writes map_00.png .. map_NN.png next to the JSON; without --gdat no PNG appears; --scale 2 doubles map 0's size; --creatures changes at least one map's bytes; a console graphics.dat writes the JSON and prints map images are not supported for console-family graphics.dat yet.

  • Step 2: Implement; per-map failures (NoTileset) warn and continue, whole-file failures (ByteOrderMismatch) abort before writing PNGs.

  • Step 3: Tests pass; commit feat(cli): magic-map images from extract --gdat.

Task 7: Bindings

Files: crates/dm2-convert/src/convert.rs, crates/dm2-wasm/src/wasm.rs + README.md, crates/dm2-ffi/src/lib.rs + include/dm2_tools.h, bindings/python/dm2_tools/__init__.py + README.md + tests/test_reads.py.

Interfaces:

  • Produces: dm2_convert::dungeon_map_png(dungeon: &[u8], gdat: &[u8], map: u16, scale: u8, creatures: bool) -> Result<Vec<u8>, ConvertError>; wasm dungeonMapPng, FFI dm2_dungeon_map_png, Python dungeon_map_png(dungeon, gdat, map, scale=1, creatures=False) -> bytes.

  • Step 1: Failing tests: FFI abi.rs and Python: DOS-EN map 0 returns bytes starting with the PNG signature; map 999 raises/returns an error.

  • Step 2: Implement following graphics_decode_icon_png's path through each layer.

  • Step 3: Tests pass; commit feat(bindings): expose magic-map rendering.

Task 8: Validation and docs

Files: docs/formats/dungeon-dat.md (new "Magic map" section), README.md (crate list), CHANGELOG.md, crates/dm2-magicmap/README.md.

  • Step 1: Render DOS-EN with --scale 2; for levels 1-3, compare each map against the DMDC2 atlas region at its shift_x/shift_y (walls, doors, pits, stairs, teleporters). List any difference and trace it to the engine before fixing.
  • Step 2: Document the cell rules, border tilesets, reveal mode and TICK_MS with citations; CHANGELOG entries (Added: crate, CLI flags, bindings).
  • Step 3: Prepare an in-game comparison: one PNG plus the magic map of the same area for the maintainer (scratch/ingame-checks/402-..., listed in scratch/pending-ingame-checks.md).
  • Step 4: Commit docs(magicmap): document the magic-map rendering.

PR split (about 1000 lines each): Tasks 1-2; 3-4; 5-6; 7-8.

# Magic-Map Export Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** `dm2 extract dungeon.dat -o out/ --gdat graphics.dat` writes one magic-map `map_NN.png` (APNG when animated) per map, drawn with the game's own map chips. **Architecture:** A new library crate `dm2-magicmap` turns a dungeon cell into an ordered list of chips (class tuple, frame, mirror) for a given game tick, following SKWINSPX v5's `DM2_DRAW_MAP_CHIP`, composites them on an 8-px grid and encodes PNG/APNG. The CLI and the bindings (through `dm2-convert`) call it. `dm2-graphics` gains the creature AI lookup now private to `dm2-saves`. **Tech Stack:** Rust 2024, `png` (APNG, as `dm2-graphics/src/icon.rs`), existing `dm2-dungeon` / `dm2-graphics` APIs. **Spec:** issue #402 (draft: `scratch/magic-map-export-design.md`). ## Global Constraints - One image per map, `map_NN.png` beside `map_NN.json`; extract unchanged without `--gdat`. - Creatures off by default (`--creatures` to enable); `--scale N`, integer, default 1, minimum 1. - PC-family archives only; on a console-family `graphics.dat`, extract still writes the JSON and prints that map images are not supported yet. - North up, no party marker; render with the engine's party facing = 0 and the reveal flag (`argl3 & 2`) set, so hidden passages, hidden pits and secret ornaments blink or show as in the magic map's reveal mode. - Engine authority: SKWINSPX v5 (`src/v5/skguidrw.cpp` `DM2_DRAW_MAP_CHIP` 2413-3200, `DM2_DRAW_CHIP_OF_MAGIC_MAP` 312, iterator around 3760-3925) and v4 code carrying `//^seg:off` markers. The June spec (`scratch/magic-map-rendering-spec.md`) cites retired SKULLWIN: use it as a map, not as truth. Tile meanings come from `dm2_dungeon::TileAttr` (#392). - Layering: CLI and `dm2-convert` call `dm2-magicmap`; `dm2-magicmap` calls `dm2-dungeon` / `dm2-graphics`; no reach-through. - Bindings stay at parity (wasm, FFI, Python) with the CLI capability. ## Engine facts the tasks rely on (verified in v5) - Cell: 7x7 chip, 8-px pitch (`dm2data.cpp:1411-1414`); blit key colour `ALPHA_A` (0x0a); mirror flags bit0 = X, bit1 = Y; `table1d6980 = {0,0,3,3}`, `table1d6984[20]` (`dm2data.cpp:882-889`). - Base strip `(0x08, tileset, 0x01, 0xf9)`; `tileset = map_graphics_style`, except map-exit cells and floor tiles with attribute bit 3, which use the level's border tileset, frame 0. - Border tileset per level: digits of the first plain text record (`attributes` bits 2:1 = 0) on map 0's party start tile; DOS-EN reads `011111122200` (`sksvgame.cpp:140-225`). - Frames on the base strip: wall/map exit 0; floor 2; pit 3, 4 when hidden (bit 2), 5 on odd ticks when hidden in reveal mode; door 0xb or 0xa by axis, +2 unless the door record has `has_button` or `switch_enabled`, +4 when state is 0 or 5; stairs `6 + ((dir - facing) & 3)`, rotated +2 (mod 4) when `up`, `dir` from `DM2_query_0cee_06dc`. - Trick wall closed with `imaginary`: drawn as wall except when `tick & 2` (reveal mode), where it falls through to floor. - Teleporter (open and haze): floor frame 2, then `(0x18, 0, 0x01, 0xf9)` frame `tick % frames`. - Wall sides: up to 4 ornament ordinals from the cell summary, chip `(0x09, ordinal)`; without reveal, skipped when `(0x09, ordinal, 0x0b, 0xf9)` exists. Floor ornament `(0x0a, ordinal)`, same rule; frame from the summary's anim byte. - Creatures: chip `(0x0f, type, 0x01, 0xf9)`; mobile: frame `2 * (tick % (frames / 2)) + (rel & 1)`, mirror `table1d6980[rel]`, `rel = (facing - creature.direction) & 3`; static (AI flag bit 0): frame `rel & 1`. No chip: skipped when static or AI flag 0x2000, else image `(0x0f, type, 0x01, 0x40)` frame `tick & 1`. ## Review Focus 1. A map whose tileset has no `(0x08, tileset)` strip (beta, demos): skip that map with a warning naming it, keep the others. 2. Mismatched files (Mac `graphics.dat` with a DOS dungeon): refuse with one clear error before writing images. 3. A start tile without the border-tileset text (custom dungeons): fall back to `map_graphics_style` for map exits and bit-3 floors, warn once. 4. `--scale 0` or a huge scale: reject 0 in clap; cap the canvas (32 * 8 * scale) at 4096 px per side with an error. 5. Creature types with no chip and unknown 0x2000 flag: draw per the rule above; never panic on a missing image. --- ### Task 1: Creature AI lookup in `dm2-graphics` **Files:** - Modify: `crates/dm2-graphics/src/lib.rs` (new `creature_ai` module export) - Create: `crates/dm2-graphics/src/creature_ai.rs` - Modify: `crates/dm2-saves/src/sksave.rs:44-77`, `crates/dm2-saves/src/records.rs:115` **Interfaces:** - Produces: `Archive::creature_ai_index(&self, creature_type: u8) -> u8` (inline word `(0x0f, type, 0x0b, 0x05)`, else `0x04`, else `type`, as `compute_creature_alt_species_mask`); `dm2_graphics::creature_ai_is_static(ai_index: u8) -> bool` (bit 0 of the AI flags, from the table now at `dm2_saves::records::CREATURE_GIDX_ALT_TABLE`, moved here). - [ ] **Step 1:** Confirm against SKWINSPX that the table's bit is `AIDefinition::w0AIFlags & 1` (`v0/dme.h` `IsStaticObject`, `dAITable`); note the source in the doc comment. - [ ] **Step 2: Failing test** `creature_ai_static_matches_saves_table` in `creature_ai.rs`: for every `ai_index < 64`, `creature_ai_is_static(i)` equals bit `i` of `[0xff, 0x1f, 0x10, 0x00, 0xe0, 0x20, 0x08, 0x99]`; `>= 64` is `false`. Fixture test: DOS-EN `creature_ai_index(20) == 20`. - [ ] **Step 3:** Implement; make `compute_creature_alt_species_mask` call the two functions; remove the table from `dm2-saves`. - [ ] **Step 4:** `cargo test -p dm2-graphics -p dm2-saves` passes (save round-trip tests unchanged). - [ ] **Step 5:** Commit `refactor(graphics): share the creature AI static flag with dm2-saves`. ### Task 2: `dm2-magicmap` crate and terrain chips **Files:** - Create: `crates/dm2-magicmap/{Cargo.toml,src/lib.rs,src/cell.rs,src/border.rs}`; add to workspace members and `[workspace.dependencies]`. **Interfaces:** - Produces: - `pub struct Chip { pub cls1: u8, pub cls2: u8, pub cls4: u8, pub frame: u16, pub mirror: u8 }` (`cls4` 0xf9 except the 0x40 creature fallback) - `pub struct MapView<'a> { dungeon: &'a Dungeon<'a>, map: usize, tileset: u8, border: u8 }` with `MapView::new(d: &'a Dungeon<'a>, map: usize, borders: &[u8]) -> Option<Self>` (`None` when `map` is out of range) - `pub fn border_tilesets(d: &Dungeon) -> Option<Vec<u8>>` - `pub fn terrain_chips(view: &MapView, x: u8, y: u8, tick: u32) -> Vec<Chip>` (base chip, teleporter swirl) - [ ] **Step 1: Failing tests** in `cell.rs` on synthetic one-tile maps, facing 0: wall → `[(8, ts, 0)]`; floor → frame 2; open pit → 3; hidden pit → 4 at tick 0, 5 at tick 1; door (state 4, N-S, no button) → `0xb + 2`; open door (state 0) → `0xb + 2 + 4`; up stairs and down stairs differ by 2 (mod 4) in `frame - 6`; imaginary trick wall → wall at ticks 0-1, floor at 2-3; open+haze teleporter → floor chip then `(0x18, 0, frame tick % n)`; map exit → `(8, border, 0)`; floor with bit 3 → `(8, border, 0)`. - [ ] **Step 2:** Fixture test `dos_en_border_tilesets`: `border_tilesets(dos-en) == Some(b"011111122200".map(|c| c - b'0'))`. Synthetic test: no text on the start tile gives `None`, and `MapView::new(.., &[])` uses `map_graphics_style` as the border tileset. - [ ] **Step 3:** Implement from v5 `DM2_DRAW_MAP_CHIP` 2503-2860 and the v4 summary (`skdungn.cpp` `SUMMARIZE_STONE_ROOM`), facing 0, reveal on. Port `DM2_query_0cee_06dc` for the stair direction and the door-axis test of the summary. The swirl frame count comes from the chip, so `terrain_chips` returns the swirl with `frame = tick` and the compositor reduces it modulo the strip's frame count. - [ ] **Step 4:** `cargo test -p dm2-magicmap` passes. - [ ] **Step 5:** Commit `feat(magicmap): select terrain map chips per cell`. ### Task 3: Ornaments **Files:** Modify `crates/dm2-magicmap/src/cell.rs`; create `src/ornament.rs`. **Interfaces:** - Produces: `terrain_chips` also returns wall-side ornaments `(0x09, ordinal)` and floor ornaments `(0x0a, ordinal)` in engine draw order. - [ ] **Step 1: Failing tests:** DOS-EN map 0: a wall cell holding a champion mirror (actuator `0x7e` on side 1 of (0,5)) yields a `0x09` chip with mirror `table1d6980[1]`; a floor actuator `0x2c` at (2,1) yields a `0x0a` chip; random wall ornaments: a cell from a map with `wall_graphics_random_decorations > 0` matches the ordinal from `GET_RANDOM_ORNAMENT_ORDINAL` (port `GET_RANDOM_ORNAMENT_INDEX`, `skdungn.cpp:306-370`). - [ ] **Step 2:** Implement the side ordinals (random + wall decorations from actuators/texts on each side) and the floor ornament with its anim frame, from v5 2686-2750 / 2771-2824. - [ ] **Step 3:** Tests pass; commit `feat(magicmap): draw wall and floor ornaments`. ### Task 4: Creatures **Files:** Create `crates/dm2-magicmap/src/creature.rs`. **Interfaces:** - Consumes: Task 1 lookups. - Produces: `pub fn creature_chips(view: &MapView, gdat: &Archive, x: u8, y: u8, tick: u32) -> Vec<Chip>` (one per creature in the tile chain, chain order). - [ ] **Step 1: Failing tests:** DOS-EN map with a mobile creature: frame and mirror follow the rule above at ticks 0 and 1; a static creature (AI bit 0, e.g. a table) uses frame `rel & 1` at every tick; a type with no `0xf9` chip and AI bit 0 yields nothing. - [ ] **Step 2:** Implement from v5 2970-3095. - [ ] **Step 3:** Tests pass; commit `feat(magicmap): draw creatures at their starting positions`. ### Task 5: Compositing, animation, PNG/APNG **Files:** Create `crates/dm2-magicmap/src/render.rs`. **Interfaces:** - Produces: - `pub struct RenderOptions { pub scale: u8, pub creatures: bool }` - `pub enum MagicMapError { MapOutOfRange(usize), ConsoleFamily, ByteOrderMismatch, NoTileset { map: usize, tileset: u8 }, TooLarge { width: u32, height: u32 } }` - `pub fn render_map_png(d: &Dungeon, gdat: &Archive, map: usize, opts: &RenderOptions) -> Result<Vec<u8>, MagicMapError>` - [ ] **Step 1: Failing tests:** DOS-EN map 0 at scale 1 is `7*8 x 10*8` RGBA, background opaque black, gap pixels black; scale 3 triples both sides; map 0 has no animated chip, so the result has no `acTL` chunk; DOS-EN map 1 (outdoor, teleporter) has `acTL` with `num_frames` equal to the loop length; a Mac `graphics.dat` with the DOS dungeon gives `ByteOrderMismatch`; a console archive gives `ConsoleFamily`; a map whose `map_graphics_style` has no `(0x08, style)` strip gives `NoTileset`; scale making a side over 4096 gives `TooLarge`. - [ ] **Step 2:** Implement: decode each chip once (`Archive::decode_image`, slice with `Image::frames(7)`), key `ALPHA_A`, apply mirror flags, composite tick by tick. Loop length: the least common multiple of the periods present (4 for blinking trick walls, 2 for hidden pits and creature fallbacks, swirl frame count, `2 * (frames/2)` per mobile creature, floor ornament periods), capped at 64; one APNG frame per game tick at `TICK_MS`. Find the engine tick length in SKWINSPX (timer setup) and pin `TICK_MS` with its citation; a single-frame result is a plain PNG. - [ ] **Step 3:** Tests pass; commit `feat(magicmap): render maps to PNG and APNG`. ### Task 6: `dm2 extract --gdat` **Files:** Modify `crates/dm2-cli/src/main.rs` (Extract args), `crates/dm2-cli/src/commands/extract.rs:437-480`; test `crates/dm2-cli/tests/extract_magic_map.rs`. **Interfaces:** - Consumes: `render_map_png`. - Produces: Extract flags `--gdat <path>` (dungeon inputs only; error on other inputs), `--creatures`, `--scale <N>` (`u8`, `1..`, default 1; both require `--gdat`). - [ ] **Step 1: Failing test:** extract DOS-EN with `--gdat` writes `map_00.png` .. `map_NN.png` next to the JSON; without `--gdat` no PNG appears; `--scale 2` doubles map 0's size; `--creatures` changes at least one map's bytes; a console `graphics.dat` writes the JSON and prints `map images are not supported for console-family graphics.dat yet`. - [ ] **Step 2:** Implement; per-map failures (`NoTileset`) warn and continue, whole-file failures (`ByteOrderMismatch`) abort before writing PNGs. - [ ] **Step 3:** Tests pass; commit `feat(cli): magic-map images from extract --gdat`. ### Task 7: Bindings **Files:** `crates/dm2-convert/src/convert.rs`, `crates/dm2-wasm/src/wasm.rs` + `README.md`, `crates/dm2-ffi/src/lib.rs` + `include/dm2_tools.h`, `bindings/python/dm2_tools/__init__.py` + `README.md` + `tests/test_reads.py`. **Interfaces:** - Produces: `dm2_convert::dungeon_map_png(dungeon: &[u8], gdat: &[u8], map: u16, scale: u8, creatures: bool) -> Result<Vec<u8>, ConvertError>`; wasm `dungeonMapPng`, FFI `dm2_dungeon_map_png`, Python `dungeon_map_png(dungeon, gdat, map, scale=1, creatures=False) -> bytes`. - [ ] **Step 1: Failing tests:** FFI `abi.rs` and Python: DOS-EN map 0 returns bytes starting with the PNG signature; map 999 raises/returns an error. - [ ] **Step 2:** Implement following `graphics_decode_icon_png`'s path through each layer. - [ ] **Step 3:** Tests pass; commit `feat(bindings): expose magic-map rendering`. ### Task 8: Validation and docs **Files:** `docs/formats/dungeon-dat.md` (new "Magic map" section), `README.md` (crate list), `CHANGELOG.md`, `crates/dm2-magicmap/README.md`. - [ ] **Step 1:** Render DOS-EN with `--scale 2`; for levels 1-3, compare each map against the DMDC2 atlas region at its `shift_x`/`shift_y` (walls, doors, pits, stairs, teleporters). List any difference and trace it to the engine before fixing. - [ ] **Step 2:** Document the cell rules, border tilesets, reveal mode and `TICK_MS` with citations; CHANGELOG entries (Added: crate, CLI flags, bindings). - [ ] **Step 3:** Prepare an in-game comparison: one PNG plus the magic map of the same area for the maintainer (`scratch/ingame-checks/402-...`, listed in `scratch/pending-ingame-checks.md`). - [ ] **Step 4:** Commit `docs(magicmap): document the magic-map rendering`. **PR split (about 1000 lines each):** Tasks 1-2; 3-4; 5-6; 7-8.
Author
Owner

In-game check (DOS EN, map 22, the magic map's 7×7 window around the party at (3,5)): every cell matches the dm2 extract --gdat render. Terrain, both doors, the white wall ornaments and the fire ornament all agree.

The remaining differences come from the played world, not from rendering:

  • (1,5): an opened alcove.
  • (2,5): a lit chimney.
  • (3,4): a door made active by its key.
  • (1,7): a table, drawn only with --creatures.

Open: the game animates faster than the render's 166 ms per tick. The timing is being traced in the engine.

In-game check (DOS EN, map 22, the magic map's 7×7 window around the party at (3,5)): every cell matches the `dm2 extract --gdat` render. Terrain, both doors, the white wall ornaments and the fire ornament all agree. The remaining differences come from the played world, not from rendering: - (1,5): an opened alcove. - (2,5): a lit chimney. - (3,4): a door made active by its key. - (1,7): a table, drawn only with `--creatures`. Open: the game animates faster than the render's 166 ms per tick. The timing is being traced in the engine.
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.

Dependencies

No dependencies set.

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