dungeon.dat: magic-map images from dm2 extract #402
Labels
No labels
area/ci-release
area/cli
area/docs
area/dungeon
area/ftl
area/graphics
area/gui
area/music
area/saves
area/tooling
port/amiga
port/dos
port/fm-towns
port/mac
port/pc98
port/sega-cd
priority/high
priority/low
priority/medium
type/bug
type/chore
type/docs
type/feature
type/research
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
jqueuniet/dm2-tools#402
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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.datalso writes onemap_NN.pngper map, next to the existingmap_NN.json(same numbering).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.
graphics.datmap chips (cls4 = 0xf9), as the engine picksthem.
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.Non-goals (follow-ups)
shift_x/shift_y.dm2-graphics.Anti-goals
pits, closed teleporters, actuators as such).
My calls (check these)
are left to the builder.
graphics.dat, extract writes the JSON and says mapimages are not supported yet.
graphics.datof another release.Decided
dm2 extract; without--gdat, extract behaves as today.map_NN.png, besidemap_NN.json.imaginarybit, passable whileclosed) 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.(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_yoffset. They check layout and contents,not artwork.
Constraints and known facts
strips of 7-px frames,
frames = width / 7; the frame index selects theappearance. Each chip carries its own 16-colour palette; map chips use
alpha-A transparency (
dm2-graphicstransparency.rsalready handlesthis).
cls3 = dtImage,cls4 = 0xf9): base terrain stripcls1 0x08keyed by the map'smap_graphics_style; wall ornaments0x09;floor ornaments
0x0a; teleporter swirl0x18; creatures0x0f.dm2-dungeon'sTileAttr, as settled in #392,not from the older spec.
dm2-graphicsicon.rsalready writes APNG.(
DRAW_MAP_CHIP), the cell summary (SUMMARIZE_STONE_ROOM) and the chipquery. Only code ported from the original binary (
//^seg:off, or v5) isauthoritative; SPX additions are leads.
dm2-graphics, cell-to-chip rules in a library crate, not in the CLI.Left to the builder
magic-map-rendering-spec.md, whichcites the retired SKULLWIN tree) against SKWINSPX, and correcting it where
#392 found the tile bits read differently.
facing; pick the frame and mirror flags of a party facing north.
chips), and the game-tick phase to start from.
(
GET_RANDOM_ORNAMENT_ORDINAL); reproduce it or document the gap.dungeon.datandgraphics.datisdetected and reported.
dm2-dungeon,dm2-graphics, ora new crate), and the CLI flag name for creatures.
graphics.dat: say map images are notsupported yet, still write the JSON.
Magic-Map Export Implementation Plan
Goal:
dm2 extract dungeon.dat -o out/ --gdat graphics.datwrites one magic-mapmap_NN.png(APNG when animated) per map, drawn with the game's own map chips.Architecture: A new library crate
dm2-magicmapturns a dungeon cell into an ordered list of chips (class tuple, frame, mirror) for a given game tick, following SKWINSPX v5'sDM2_DRAW_MAP_CHIP, composites them on an 8-px grid and encodes PNG/APNG. The CLI and the bindings (throughdm2-convert) call it.dm2-graphicsgains the creature AI lookup now private todm2-saves.Tech Stack: Rust 2024,
png(APNG, asdm2-graphics/src/icon.rs), existingdm2-dungeon/dm2-graphicsAPIs.Spec: issue #402 (draft:
scratch/magic-map-export-design.md).Global Constraints
map_NN.pngbesidemap_NN.json; extract unchanged without--gdat.--creaturesto enable);--scale N, integer, default 1, minimum 1.graphics.dat, extract still writes the JSON and prints that map images are not supported yet.argl3 & 2) set, so hidden passages, hidden pits and secret ornaments blink or show as in the magic map's reveal mode.src/v5/skguidrw.cppDM2_DRAW_MAP_CHIP2413-3200,DM2_DRAW_CHIP_OF_MAGIC_MAP312, iterator around 3760-3925) and v4 code carrying//^seg:offmarkers. The June spec (scratch/magic-map-rendering-spec.md) cites retired SKULLWIN: use it as a map, not as truth. Tile meanings come fromdm2_dungeon::TileAttr(#392).dm2-convertcalldm2-magicmap;dm2-magicmapcallsdm2-dungeon/dm2-graphics; no reach-through.Engine facts the tasks rely on (verified in v5)
dm2data.cpp:1411-1414); blit key colourALPHA_A(0x0a); mirror flags bit0 = X, bit1 = Y;table1d6980 = {0,0,3,3},table1d6984[20](dm2data.cpp:882-889).(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.attributesbits 2:1 = 0) on map 0's party start tile; DOS-EN reads011111122200(sksvgame.cpp:140-225).has_buttonorswitch_enabled, +4 when state is 0 or 5; stairs6 + ((dir - facing) & 3), rotated +2 (mod 4) whenup,dirfromDM2_query_0cee_06dc.imaginary: drawn as wall except whentick & 2(reveal mode), where it falls through to floor.(0x18, 0, 0x01, 0xf9)frametick % frames.(0x09, ordinal); without reveal, skipped when(0x09, ordinal, 0x0b, 0xf9)exists. Floor ornament(0x0a, ordinal), same rule; frame from the summary's anim byte.(0x0f, type, 0x01, 0xf9); mobile: frame2 * (tick % (frames / 2)) + (rel & 1), mirrortable1d6980[rel],rel = (facing - creature.direction) & 3; static (AI flag bit 0): framerel & 1. No chip: skipped when static or AI flag 0x2000, else image(0x0f, type, 0x01, 0x40)frametick & 1.Review Focus
(0x08, tileset)strip (beta, demos): skip that map with a warning naming it, keep the others.graphics.datwith a DOS dungeon): refuse with one clear error before writing images.map_graphics_stylefor map exits and bit-3 floors, warn once.--scale 0or a huge scale: reject 0 in clap; cap the canvas (32 * 8 * scale) at 4096 px per side with an error.Task 1: Creature AI lookup in
dm2-graphicsFiles:
crates/dm2-graphics/src/lib.rs(newcreature_aimodule export)crates/dm2-graphics/src/creature_ai.rscrates/dm2-saves/src/sksave.rs:44-77,crates/dm2-saves/src/records.rs:115Interfaces:
Produces:
Archive::creature_ai_index(&self, creature_type: u8) -> u8(inline word(0x0f, type, 0x0b, 0x05), else0x04, elsetype, ascompute_creature_alt_species_mask);dm2_graphics::creature_ai_is_static(ai_index: u8) -> bool(bit 0 of the AI flags, from the table now atdm2_saves::records::CREATURE_GIDX_ALT_TABLE, moved here).Step 1: Confirm against SKWINSPX that the table's bit is
AIDefinition::w0AIFlags & 1(v0/dme.hIsStaticObject,dAITable); note the source in the doc comment.Step 2: Failing test
creature_ai_static_matches_saves_tableincreature_ai.rs: for everyai_index < 64,creature_ai_is_static(i)equals bitiof[0xff, 0x1f, 0x10, 0x00, 0xe0, 0x20, 0x08, 0x99];>= 64isfalse. Fixture test: DOS-ENcreature_ai_index(20) == 20.Step 3: Implement; make
compute_creature_alt_species_maskcall the two functions; remove the table fromdm2-saves.Step 4:
cargo test -p dm2-graphics -p dm2-savespasses (save round-trip tests unchanged).Step 5: Commit
refactor(graphics): share the creature AI static flag with dm2-saves.Task 2:
dm2-magicmapcrate and terrain chipsFiles:
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 }(cls40xf9 except the 0x40 creature fallback)pub struct MapView<'a> { dungeon: &'a Dungeon<'a>, map: usize, tileset: u8, border: u8 }withMapView::new(d: &'a Dungeon<'a>, map: usize, borders: &[u8]) -> Option<Self>(Nonewhenmapis 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.rson 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) inframe - 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 givesNone, andMapView::new(.., &[])usesmap_graphics_styleas the border tileset.Step 3: Implement from v5
DM2_DRAW_MAP_CHIP2503-2860 and the v4 summary (skdungn.cppSUMMARIZE_STONE_ROOM), facing 0, reveal on. PortDM2_query_0cee_06dcfor the stair direction and the door-axis test of the summary. The swirl frame count comes from the chip, soterrain_chipsreturns the swirl withframe = tickand the compositor reduces it modulo the strip's frame count.Step 4:
cargo test -p dm2-magicmappasses.Step 5: Commit
feat(magicmap): select terrain map chips per cell.Task 3: Ornaments
Files: Modify
crates/dm2-magicmap/src/cell.rs; createsrc/ornament.rs.Interfaces:
Produces:
terrain_chipsalso 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
0x7eon side 1 of (0,5)) yields a0x09chip with mirrortable1d6980[1]; a floor actuator0x2cat (2,1) yields a0x0achip; random wall ornaments: a cell from a map withwall_graphics_random_decorations > 0matches the ordinal fromGET_RANDOM_ORNAMENT_ORDINAL(portGET_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 & 1at every tick; a type with no0xf9chip 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*8RGBA, background opaque black, gap pixels black; scale 3 triples both sides; map 0 has no animated chip, so the result has noacTLchunk; DOS-EN map 1 (outdoor, teleporter) hasacTLwithnum_framesequal to the loop length; a Macgraphics.datwith the DOS dungeon givesByteOrderMismatch; a console archive givesConsoleFamily; a map whosemap_graphics_stylehas no(0x08, style)strip givesNoTileset; scale making a side over 4096 givesTooLarge.Step 2: Implement: decode each chip once (
Archive::decode_image, slice withImage::frames(7)), keyALPHA_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 atTICK_MS. Find the engine tick length in SKWINSPX (timer setup) and pinTICK_MSwith 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 --gdatFiles: Modify
crates/dm2-cli/src/main.rs(Extract args),crates/dm2-cli/src/commands/extract.rs:437-480; testcrates/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
--gdatwritesmap_00.png..map_NN.pngnext to the JSON; without--gdatno PNG appears;--scale 2doubles map 0's size;--creatureschanges at least one map's bytes; a consolegraphics.datwrites the JSON and printsmap 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>; wasmdungeonMapPng, FFIdm2_dungeon_map_png, Pythondungeon_map_png(dungeon, gdat, map, scale=1, creatures=False) -> bytes.Step 1: Failing tests: FFI
abi.rsand 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.--scale 2; for levels 1-3, compare each map against the DMDC2 atlas region at itsshift_x/shift_y(walls, doors, pits, stairs, teleporters). List any difference and trace it to the engine before fixing.TICK_MSwith citations; CHANGELOG entries (Added: crate, CLI flags, bindings).scratch/ingame-checks/402-..., listed inscratch/pending-ingame-checks.md).docs(magicmap): document the magic-map rendering.PR split (about 1000 lines each): Tasks 1-2; 3-4; 5-6; 7-8.
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 --gdatrender. Terrain, both doors, the white wall ornaments and the fire ornament all agree.The remaining differences come from the played world, not from rendering:
--creatures.Open: the game animates faster than the render's 166 ms per tick. The timing is being traced in the engine.