dungeon.dat: assemble magic-map images per level #409
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#409
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?
Follow-up to #402.
dm2 extract --gdatwrites one magic-map image per map stored indungeon.dat. In-game, a level is several maps placed side by side.Goal
Assemble each level's maps into one image. Each map goes at its
shift_x/shift_yin level coordinates, the same layout as the DMDC2 "World Atlas".Known facts
--creatures) and--scaleshould behave as for per-map images.Design
dungeon.dat: magic-map images per level
Follow-up to #402 (per-map magic-map images,
dm2-magicmap).Intent
In-game, a level is made of several maps placed side by side. The per-map images from #402 show each piece alone, with border chips where the map ends. A level image puts the pieces together the way the game does, so a whole level can be looked over at a glance.
Goals
dm2 extract dungeon.dat -o out/ --gdat graphics.datalso writes onelevel_NN.pngper level, alongside the existingmap_NN.png/map_NN.json. It is written on every--gdatrun, with no extra flag.NNis the maps'levelfield (DOS-EN uses 0-10).Only magic-map chips are drawn: no coordinate rulers or labels.
Each map sits at its
shift_x/shift_yin level coordinates. The canvas is the smallest rectangle holding all the level's maps. Cells no map covers are opaque black, like the gaps between cells.Seam rule, the decided priority for a cell several maps claim:
Teleporter::blocks_passage, which neighbouring maps treat as a map exit, #392), gives way to another map's real tile.dungeon.datorder wins. No warning: overlap on seams is normal.In DOS-EN, 2275 cells overlap:
The winning cell is drawn with everything the per-map renderer draws for it on its own map: tileset, ornaments, creatures and animation.
Creatures are on by default, for per-map and level images and in the bindings. This reverses #402's default. The CLI flag becomes
--no-creatures.--scaleapplies to level images as to map images.Animation loops over the whole level image (the least common multiple of the cells' periods, capped at 64 ticks) at
dm2_graphics::GAME_TICK_MS. A level with nothing animated is a plain PNG. The 4096 px per side limit applies.A level with a map that cannot render (missing tileset) is skipped with a warning. The per-map images that do render are still written.
Bindings parity:
dungeon_level_png(dungeon, gdat, level, scale, creatures)throughdm2-convert, wasmdungeonLevelPng, FFIdm2_dungeon_level_png, Pythondungeon_level_png(dungeon, gdat, level, scale=1, creatures=True). The per-mapdungeon_map_pngPython default becomescreatures=True.Non-goals
Anti-goals
Constraints
dm2-convertcalldm2-magicmap;dm2-magicmapcallsdm2-dungeon/dm2-graphics.terrain_chips/creature_chipsper owning map and its local coordinates. Don't duplicate rules.dm2-magicmapand thecreaturesoption are unreleased, so their API may change without a deprecation path.docs/formats/dungeon-dat.md).Left to the builder
render_level_png(d, gdat, level, opts)besiderender_map_png, sharing the compositor; and howRenderOptionsexpresses the creatures default (aDefaultimpl withcreatures: trueis fine).dungeon_level_pngeverywhere; Changed: creatures on by default,--no-creatures).Level Magic-Map Images Implementation Plan
Goal:
dm2 extract --gdatalso writes onelevel_NN.pngper level, assembling the level's maps as the game places them; creatures become on by default.Architecture:
dm2-magicmapgains a level layout (which map and local cell owns each level cell, by the seam rule) and renders any layout through the existing compositor; a per-map image is the one-map layout. The CLI and the bindings callrender_level_pngbesiderender_map_png.Tech Stack: Rust 2024; existing
dm2-magicmap/dm2-dungeon/dm2-graphics.Spec: issue #409 (draft:
scratch/level-assembly-design.md).Global Constraints
level_NN.pngbesidemap_NN.png, written on every--gdatrun;NN= the maps'levelfield (two digits).Teleporter::blocks_passage) gives way to another map's real tile; (2) between remaining real tiles, one inside its map beats one on another map's outer edge; (3) otherwise the map first indungeon.datorder wins. No warning.--no-creaturesreplaces--creatures; Python defaultscreatures=Truefordungeon_map_pnganddungeon_level_png.dm2_graphics::GAME_TICK_MS; 4096 px per side limit.dm2-convert->dm2-magicmap->dm2-dungeon/dm2-graphics. Reuseterrain_chips/creature_chips; no duplicated rules.dm2-magicmapand the creatures option are unreleased: API may change freely.Review Focus
levelvalue with no maps: a typed error, not a panic or empty PNG (Task 3 test).TooLargebefore allocating (Task 3 test).Task 1: Creatures on by default
Files:
crates/dm2-magicmap/src/render.rs(RenderOptions),crates/dm2-cli/src/main.rs(Extract args),crates/dm2-cli/src/commands/extract.rs,crates/dm2-cli/tests/extract_magic_map.rs,bindings/python/dm2_tools/__init__.py,bindings/python/README.md,crates/dm2-wasm/README.md,docs/formats/dungeon-dat.md(Creatures paragraph),CHANGELOG.md.Interfaces:
Produces:
impl Default for RenderOptions={ scale: 1, creatures: true }; CLI flag--no-creatures(requires--gdat); Pythondungeon_map_png(dungeon, gdat, map, scale=1, creatures=True).Step 1: Failing tests:
RenderOptions::default() == RenderOptions { scale: 1, creatures: true }; CLI: DOS-EN map 4 PNG differs between a plain--gdatrun and--gdat --no-creatures;--creaturesis rejected as an unknown flag; Python:dungeon_map_png(...)withoutcreaturesequalscreatures=True.Step 2: Implement; wasm/FFI keep an explicit
creaturesbool (no defaults in those ABIs).Step 3: Docs + CHANGELOG (Changed: creatures on by default,
--no-creatures). Gates; commitfeat(magicmap): draw creatures by default.Task 2: Level layout and the seam rule
Files: Create
crates/dm2-magicmap/src/level.rs; modifycrates/dm2-magicmap/src/lib.rs(module + exports).Interfaces:
Produces:
pub struct LevelLayout { pub origin: (u16, u16), pub width: u16, pub height: u16, cells: Vec<Option<(usize, u8, u8)>> }— level-coordinate bounding box of the level's maps; each cell's owner(map index, local x, local y)orNonewhen no map covers it.impl LevelLayout { pub fn owner(&self, x: u16, y: u16) -> Option<(usize, u8, u8)> }(canvas-relative coordinates).pub fn level_layout(d: &Dungeon, level: u8) -> Option<LevelLayout>(Nonewhen no map has that level).pub fn levels(d: &Dungeon) -> Vec<u8>(distinctlevelvalues, ascending).Step 1: Failing tests (synthetic two-map dungeons via
test_util::Fixtureextended to several maps if needed): rule 1 — map exit on A over floor on B → B owns; connector teleporter (blocks_passage) on A over floor on B → B owns; rule 2 — wall on A's outer edge vs floor inside B → B owns; rule 3 — floor inside A vs wall inside B, A first → A owns; all map exits → the first map owns; uncovered cell →None; bounding box = min shift .. max(shift + size).Step 2: DOS-EN fixture test: for every level, every cell of every map has an owner, and the number of cells with more than one claimant across all levels is 2275 (the count measured for the design).
Step 3: Implement. A connector is a teleporter tile whose record (first teleporter on the tile's chain) has
blocks_passage().Step 4: Tests pass; gates; commit
feat(magicmap): resolve level layouts with the seam rule.Task 3: Render any layout;
render_level_pngFiles:
crates/dm2-magicmap/src/render.rs,crates/dm2-magicmap/src/lib.rs.Interfaces:
Consumes:
level_layout,LevelLayout::owner.Produces:
pub fn render_level_png(d: &Dungeon, gdat: &Archive, level: u8, opts: &RenderOptions) -> Result<Vec<u8>, MagicMapError>MagicMapError::LevelOutOfRange(u8)(no map has that level).NoTileset { map, tileset }for the first such map.render_map_pngunchanged in signature and output bytes.Step 1: Failing tests: a one-map level (synthetic) renders byte-identical to
render_map_pngof that map; DOS-EN: each level's PNG is8 * width * scaleby8 * height * scaleof its layout; a seam cell owned by map B in level L has the same pixels as that cell in B's own map image (compare the 8x8 block, tick 0); two maps with differentmap_graphics_stylekeep their own base strips;render_level_png(.., 99, ..)->LevelOutOfRange(99); scale making a side over 4096 ->TooLarge; uncovered cells are opaque black.Step 2: Implement: the renderer iterates placed cells
(canvas x, y, map, local x, local y)with oneMapViewper map (built once, all sharing oneStripscache); per-map rendering builds the identity placement of one map. Canvas coordinates becomeu16. Loop detection and APNG writing stay shared.Step 3: Tests pass (existing render tests unchanged); gates; commit
feat(magicmap): render level images.Task 4:
extractwrites level imagesFiles:
crates/dm2-cli/src/commands/extract.rs,crates/dm2-cli/tests/extract_magic_map.rs.Interfaces:
Consumes:
levels,render_level_png.Step 1: Failing tests: DOS-EN
--gdatrun writeslevel_00.png..level_10.pngfor exactly the levelslevels()returns, beside the map images;--no-creaturesapplies to level images too (DOS-EN level holding map 4 differs with and without); with one map patched to tileset 15 (as the existing NoTileset test), the level holding it is skipped with one warningwarning: level NN: ...and every other level and map image is written; console-family still writes JSON only.Step 2: Implement inside the existing render-everything-before-writing step; whole-file errors still abort before anything is written.
Step 3: Tests pass; gates; commit
feat(cli): write level magic-map images.Task 5: 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 incrates/dm2-convert/tests/reads.rs,crates/dm2-ffi/tests/abi.rs,bindings/python/tests/test_reads.py.Interfaces:
Produces:
dm2_convert::dungeon_level_png(dungeon: &[u8], gdat: &[u8], level: u8, scale: u8, creatures: bool) -> Result<Vec<u8>, ConvertError>; wasmdungeonLevelPng; FFIdm2_dungeon_level_png; Pythondungeon_level_png(dungeon, gdat, level, scale=1, creatures=True) -> bytes.Step 1: Failing tests: DOS-EN level 1 returns PNG bytes in convert, FFI and Python; level 99 errors; scale 0 errors (
ZeroScale).Step 2: Implement following
dungeon_map_pngthrough each layer; keep the C header in sync.Step 3: Tests pass (Python as in the #402 work:
cargo build --release -p dm2-ffi, thenPYTHONPATH=bindings/python UV_CACHE_DIR=scratch/uv-cache uv run --no-project --with pytest -- python -m pytest bindings/python/tests -q);cargo check -p dm2-wasm --target wasm32-unknown-unknown; commitfeat(bindings): expose level magic-map rendering.Task 6: Validation and docs
Files:
docs/formats/dungeon-dat.md("Magic map" section),CHANGELOG.md,crates/dm2-magicmap/README.md.--scale 2and compare each with the DMDC2 atlas level image (http://dmweb.free.fr/files/Game,Dungeon_Master_II,DMDC2,Dungeon,Level_0N,Map.png; the atlas adds a coordinate border). Check seams especially: walls, floors, pits, doors and stairs should match; trace any other difference to the engine or to the atlas's documented conventions before changing code. Fix real defects with a test each, in their own commit.render_level_png,dungeon_level_pngin every binding); commitdocs(magicmap): document level images.PR split: Tasks 1-3 (library); Tasks 4-6 (CLI, bindings, docs).