dm2-dungeon: actuator and creature type catalogs (names + per-type parameter decoding) #263

New issue

Closed

opened 2026-07-17 15:04:35 +02:00 by jqueuniet · 0 comments

jqueuniet commented

2026-07-17 15:04:35 +02:00

(Migrated from codeberg.org)

dm2-dungeon decodes every Actuator and Creature record and round-trips them byte-for-byte, but the type numbers stay numbers: nothing maps Actuator::type() to a name or to its per-type parameter meanings, and nothing maps a Creature type to a creature/decoration name. This is the asterisk on Phase 2's "done" in ROADMAP.md, deferred to follow-up PRs by the bullets in § Phase 2 (Actuator records, Creature records) and § "Per-type object records" in docs/formats/dungeon-dat.md.

Scope

Actuator type catalog — ~125 DM2 sensor/actuator types, floor and wall variants tracked separately.
Per-type Actuator parameter decoding — what behaviour / target mean per type; today they are a raw + bit-accessor surface only.
Creature type catalog — creature names plus the DM2 decorations (trees, tables, pillars) that reuse the Creature category.

Not in scope: the text escape-code 29 / 30 per-version expansion tables. The roadmap groups them with the catalogs, but they are reverse-engineering (per-port table extraction, tables likely in graphics.dat dtText records or hardcoded in the engine), not cataloguing. Worth a separate issue.

Sources

[KKDF2] is the stated authority for DM2-specific types 19–125; [DMWEB] covers sensor types 0–18 and 127. Both are already in docs/external-references.md.
[SKPROJECT]'s DMDC2 dungeon editor ships partial catalogs as data, which is a significant head start and appears not to have been noticed when these bullets were written:
- DMDC2/DM2/_Actuf.Dic.csv and DMDC2/DM2/_Actuw.Dic.csv — 128 rows each (one per type), floor and wall. Each row is name, param1_type, param2_type, param3_type, param3_locator_type, e.g. "Activator, item watcher","Item","No","Locator","Trap". This covers deliverable 2 as well as 1 — the param-type descriptors are exactly the per-type parameter decoding.
- DMDC2/DM2/_Creatures.Dic.csv — 256 rows, creature and decoration names (THORN DEMON, CAVERN TABLE, BUSH, PILLAR…).
- DMDC2/Hint_Actu/*.htm — 50 per-type pages (named <hex><F|W>.htm) carrying a display name plus prose semantics, including honest "still unknown" notes.
- Sibling dictionaries exist for the item categories (_Chests, _Clothes, _Misc, _Missiles, _Potions, _Scrolls, _Weapons, _Heroes, _Messages, _Wall_Ornates, _Floor_Ornates) and for DM1 / DM2 Beta under DMDC2/DM1/ and DMDC2/DM2Beta/.

Coverage is partial, so this does not reduce to a transcription job: 28 of 128 floor rows and 35 of 128 wall rows are named (the rest are "-"), and 76 of 256 creature rows. The named subset is the well-understood core; the tail still needs [KKDF2] plus fixture evidence, and the two sources should be cross-checked against each other rather than either trusted alone.

Open question — licensing

skproject ships no LICENSE file. Type names are facts about the game, but the curation and the prose in Hint_Actu are someone's work, and dm2-tools is MIT / Apache-2.0. Decide before writing code whether we (a) use the dictionaries as leads and verify each entry independently against fixtures + [KKDF2], (b) ask upstream (gbsphenx/skproject) for explicit terms, or (c) treat them as reference-only and cite rather than copy. This choice sets the shape of the work, not just its paperwork.

Notes on shape

The catalogs are data, not logic — the natural form is a table in dm2-dungeon with name lookups over the existing Actuator / Creature accessors, keyed by type and floor/wall variant, with unknown types remaining representable (no panics, no lossy round-trip). Round-trip must stay byte-exact: naming a type must never gate parsing it.

Fixture evidence is available from all 16 staged ports, and DMDC2 additionally ships its own sample dumps (D2.PCAT.DAT, D2.SEGACD.BE.DAT, D2.PCATBeta.DAT, …) that can serve as cross-checks.

Worth splitting per deliverable once the licensing question is settled — the creature catalog is independent of the actuator work.

`dm2-dungeon` decodes every Actuator and Creature record and round-trips them byte-for-byte, but the type numbers stay numbers: nothing maps `Actuator::type()` to a name or to its per-type parameter meanings, and nothing maps a Creature type to a creature/decoration name. This is the asterisk on Phase 2's "done" in ROADMAP.md, deferred to follow-up PRs by the bullets in § Phase 2 (Actuator records, Creature records) and § "Per-type object records" in `docs/formats/dungeon-dat.md`. ## Scope 1. **Actuator type catalog** — ~125 DM2 sensor/actuator types, floor and wall variants tracked separately. 2. **Per-type Actuator parameter decoding** — what `behaviour` / `target` mean per type; today they are a raw + bit-accessor surface only. 3. **Creature type catalog** — creature names plus the DM2 decorations (trees, tables, pillars) that reuse the Creature category. Not in scope: the text escape-code 29 / 30 per-version expansion tables. The roadmap groups them with the catalogs, but they are reverse-engineering (per-port table extraction, tables likely in `graphics.dat` `dtText` records or hardcoded in the engine), not cataloguing. Worth a separate issue. ## Sources - **[KKDF2]** is the stated authority for DM2-specific types 19–125; **[DMWEB]** covers sensor types 0–18 and 127. Both are already in `docs/external-references.md`. - **[SKPROJECT]'s DMDC2 dungeon editor ships partial catalogs as data**, which is a significant head start and appears not to have been noticed when these bullets were written: - `DMDC2/DM2/_Actuf.Dic.csv` and `DMDC2/DM2/_Actuw.Dic.csv` — 128 rows each (one per type), floor and wall. Each row is `name, param1_type, param2_type, param3_type, param3_locator_type`, e.g. `"Activator, item watcher","Item","No","Locator","Trap"`. **This covers deliverable 2 as well as 1** — the param-type descriptors are exactly the per-type parameter decoding. - `DMDC2/DM2/_Creatures.Dic.csv` — 256 rows, creature and decoration names (`THORN DEMON`, `CAVERN TABLE`, `BUSH`, `PILLAR`…). - `DMDC2/Hint_Actu/*.htm` — 50 per-type pages (named `<hex><F|W>.htm`) carrying a display name plus prose semantics, including honest "still unknown" notes. - Sibling dictionaries exist for the item categories (`_Chests`, `_Clothes`, `_Misc`, `_Missiles`, `_Potions`, `_Scrolls`, `_Weapons`, `_Heroes`, `_Messages`, `_Wall_Ornates`, `_Floor_Ornates`) and for DM1 / DM2 Beta under `DMDC2/DM1/` and `DMDC2/DM2Beta/`. **Coverage is partial, so this does not reduce to a transcription job:** 28 of 128 floor rows and 35 of 128 wall rows are named (the rest are `"-"`), and 76 of 256 creature rows. The named subset is the well-understood core; the tail still needs [KKDF2] plus fixture evidence, and the two sources should be cross-checked against each other rather than either trusted alone. ## Open question — licensing `skproject` ships no LICENSE file. Type names are facts about the game, but the curation and the prose in `Hint_Actu` are someone's work, and `dm2-tools` is MIT / Apache-2.0. Decide before writing code whether we (a) use the dictionaries as leads and verify each entry independently against fixtures + [KKDF2], (b) ask upstream (`gbsphenx/skproject`) for explicit terms, or (c) treat them as reference-only and cite rather than copy. This choice sets the shape of the work, not just its paperwork. ## Notes on shape The catalogs are data, not logic — the natural form is a table in `dm2-dungeon` with name lookups over the existing `Actuator` / `Creature` accessors, keyed by type and floor/wall variant, with unknown types remaining representable (no panics, no lossy round-trip). Round-trip must stay byte-exact: naming a type must never gate parsing it. Fixture evidence is available from all 16 staged ports, and DMDC2 additionally ships its own sample dumps (`D2.PCAT.DAT`, `D2.SEGACD.BE.DAT`, `D2.PCATBeta.DAT`, …) that can serve as cross-checks. Worth splitting per deliverable once the licensing question is settled — the creature catalog is independent of the actuator work.

No labels

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#263

No description provided.

Rows
Columns