docs: fix doc/code inconsistencies across formats, CLI, and specs #282

Merged

jqueuniet merged 0 commits from docs/fix-high-consistency into main

2026-07-22 07:48:12 +02:00

jqueuniet commented

2026-07-22 07:23:21 +02:00

(Migrated from codeberg.org)

Fixes a batch of documentation/spec facts that had drifted from the code, found by a global doc↔source consistency audit across the CLI, save format, binary formats, audio, and .ksy specs. Documentation-only except one Rust doc-comment; no behavior changes. Every edit was verified against the cited code, and all six edited .ksy files compile with kaitai-struct-compiler.

HIGH (would mislead into a broken command / corrupt data / wrong output)

cli-save-editing.md — inventory --clear/--move/--copy examples now pass --gdat (the CLI hard-errors without it for edits); prose + context-file table mark --gdat required for inventory mutations.
save-record-stream.md — the v1d64d3 dynamic mask swap is type‑14 Missiles inside a creature sub-chain, not type‑15 Clouds (clouds are read unconditionally); matches records.rs/checkcode.rs. Phase 6 retitled "timer-actuator links" to match its own body.
music.md — OPL master gain corrected from "+2 dB" to 1.72× (≈ +4.7 dB), matching RenderOpts::default.

MED (stale / internally-contradicted format facts)

saves.md — unknown_36 is per-save (not constant 0xf858); DOS detection keys only on w_timer_flag == 1. SaveEffects mask table1d6456 → table1d645d.
save-object-editability.md — Misc charge documented as editable under the moneybox mask (was listed "not modeled").
save-record-stream.md — creature alt-mask gate is a GDAT descriptor bit0 lookup (b_04&1 only as no-GDAT fallback); chest contents routing is class parity (class&1); phases decode 4→5→6→3→7; raw arrays carry no mask.
.ksy specs — graphics ENT1 count → width; inst [5] flags / transpose i16 / smod params; song real field names; sksave body-decoded note + header w_timer_flag/w36/w38 fixes. Byte layouts unchanged.
dungeon-dat.md — DOS-EN Columns array is 725 entries / 1450 bytes (357/714 was a synthetic test value); real Creature field names; container destMap bits live in Chest::unused, now decoded as the MAP-container teleport destination; chest.rs doc-comment synced with its accessors.
tooling/README.md, development.md — list the palette-oracle harness. README.md — add the [SCUMMVM] external-reference tag.

LOW (citations / cosmetic)

cli-save-editing.md — document champion --name2. music.md — drop the phantom --by-category flag.
mac-resources.md — resource reference-list ID is signed i16.
save-drop-representation.md — fix stale checkcode.rs line citations and the packed [u8;16] alt-species mask bit-indexing.
save-unmodeled-fields-audit.md — Champion now has getters + 13 setters; drop stale "zero setters" claims, refresh citations.
dm2_dungeon_dat.ksy — n_records' 16 slots are fully decoded via DB_SIZES.

Fixes a batch of documentation/spec facts that had drifted from the code, found by a global doc↔source consistency audit across the CLI, save format, binary formats, audio, and `.ksy` specs. Documentation-only except one Rust doc-comment; no behavior changes. Every edit was verified against the cited code, and all six edited `.ksy` files compile with `kaitai-struct-compiler`. ### HIGH (would mislead into a broken command / corrupt data / wrong output) - **cli-save-editing.md** — inventory `--clear/--move/--copy` examples now pass `--gdat` (the CLI hard-errors without it for edits); prose + context-file table mark `--gdat` required for inventory mutations. - **save-record-stream.md** — the `v1d64d3` dynamic mask swap is type‑14 Missiles inside a creature sub-chain, **not** type‑15 Clouds (clouds are read unconditionally); matches `records.rs`/`checkcode.rs`. Phase 6 retitled "timer-actuator links" to match its own body. - **music.md** — OPL master gain corrected from "+2 dB" to `1.72×` (≈ +4.7 dB), matching `RenderOpts::default`. ### MED (stale / internally-contradicted format facts) - **saves.md** — `unknown_36` is per-save (not constant `0xf858`); DOS detection keys only on `w_timer_flag == 1`. SaveEffects mask `table1d6456` → `table1d645d`. - **save-object-editability.md** — Misc `charge` documented as editable under the moneybox mask (was listed "not modeled"). - **save-record-stream.md** — creature alt-mask gate is a GDAT descriptor bit0 lookup (`b_04&1` only as no-GDAT fallback); chest contents routing is class parity (`class&1`); phases decode 4→5→6→3→7; raw arrays carry no mask. - **.ksy specs** — graphics ENT1 `count` → `width`; inst `[5]` flags / `transpose` i16 / smod params; song real field names; sksave body-decoded note + header `w_timer_flag`/`w36`/`w38` fixes. Byte layouts unchanged. - **dungeon-dat.md** — DOS-EN Columns array is 725 entries / 1450 bytes (357/714 was a synthetic test value); real Creature field names; container destMap bits live in `Chest::unused`, now decoded as the MAP-container teleport destination; `chest.rs` doc-comment synced with its accessors. - **tooling/README.md**, **development.md** — list the palette-oracle harness. **README.md** — add the `[SCUMMVM]` external-reference tag. ### LOW (citations / cosmetic) - **cli-save-editing.md** — document champion `--name2`. **music.md** — drop the phantom `--by-category` flag. - **mac-resources.md** — resource reference-list ID is signed `i16`. - **save-drop-representation.md** — fix stale `checkcode.rs` line citations and the packed `[u8;16]` alt-species mask bit-indexing. - **save-unmodeled-fields-audit.md** — Champion now has getters + 13 setters; drop stale "zero setters" claims, refresh citations. - **dm2_dungeon_dat.ksy** — `n_records`' 16 slots are fully decoded via `DB_SIZES`.

No reviewers

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!282

No description provided.

Rows
Columns