docs: correct disproven claims in save-format docs (hero.rs skproject-mask note, saves.md LE claim, mac-post-sgb-reads.md timer count / SGB mask / index-offset width) #176

New issue

Closed

opened 2026-07-04 15:15:18 +02:00 by jqueuniet · 1 comment

jqueuniet commented

2026-07-04 15:15:18 +02:00

(Migrated from codeberg.org)

Documentation claims disproven during a full crate review — worth fixing so they don't mislead future decode work.

hero.rs CHAMPION_MASK note (~131-141): claims skproject's table1d6356 has 8 extra non-zero bytes at 0xAF..=0xB6 vs the retail binary. Verified false against the current skproject checkout: the table is byte-identical to CHAMPION_MASK (positional compare, popcount 1045 both) and unchanged since the original "add v5 code" commit (only an i8→U8 type change since). Good news for SKWINSPX save interchange; the note should be corrected or dated.
docs/formats/saves.md: "Multi-byte fields inside the suppression-encoded bitstream are always little-endian regardless of host CPU" — disproven for Mac (SGB scalars, GlobalWords, timer u16s are big-endian with per-field swapped masks; see #168 for fixture evidence).
docs/formats/mac-post-sgb-reads.md, three stale claims:
- timer_count_raw = 12 (sgb[20] & 0xFF) for skullkeep_void_gate — the fixture-verified formula is (b20 << 1) | (b21 & 1) (= 24 for that save); sgb[20] & 0xFF is the LE misread.
- "SGB mask (60 bytes, DOS mask — identical on Mac and DOS)" — contradicted by the same doc's own "masks are big-endian relative to the DOS masks" note and by the fixture evidence (game_tick bits arrive in BE field order, which requires the per-field-swapped mask).
- Lines ~390/410: "DOS uses 3 bits (mask 0x07)" for the CHECKCODE index offset — contradicted by dos-post-sgb-reads.md, by sksvgame.cpp:847 (vb_34 = 3 → mask 0x03 = 2 bits), and by the crate's skull.exe citation. Both platforms use 2 bits; same resolution for the line-391 open question on the type-9 sub-type (2 bits on DOS too, sksvgame.cpp:886).
savegamebuffer.rs field docs: the "verified empirically against the Mac fixtures" LE claim only ever covered fields whose payload fits a single byte; restate the actual verification scope.

Documentation claims disproven during a full crate review — worth fixing so they don't mislead future decode work. - [ ] **`hero.rs` `CHAMPION_MASK` note (~131-141)**: claims skproject's `table1d6356` has 8 extra non-zero bytes at `0xAF..=0xB6` vs the retail binary. Verified false against the current skproject checkout: the table is byte-identical to `CHAMPION_MASK` (positional compare, popcount 1045 both) and unchanged since the original "add v5 code" commit (only an `i8`→`U8` type change since). Good news for SKWINSPX save interchange; the note should be corrected or dated. - [ ] **`docs/formats/saves.md`**: "Multi-byte fields inside the suppression-encoded bitstream are always little-endian regardless of host CPU" — disproven for Mac (SGB scalars, GlobalWords, timer u16s are big-endian with per-field swapped masks; see #168 for fixture evidence). - [ ] **`docs/formats/mac-post-sgb-reads.md`**, three stale claims: - `timer_count_raw = 12 (sgb[20] & 0xFF)` for `skullkeep_void_gate` — the fixture-verified formula is `(b20 << 1) | (b21 & 1)` (= 24 for that save); `sgb[20] & 0xFF` is the LE misread. - "SGB mask (60 bytes, DOS mask — identical on Mac and DOS)" — contradicted by the same doc's own "masks are big-endian relative to the DOS masks" note and by the fixture evidence (game_tick bits arrive in BE field order, which requires the per-field-swapped mask). - Lines ~390/410: "DOS uses 3 bits (mask 0x07)" for the CHECKCODE index offset — contradicted by `dos-post-sgb-reads.md`, by `sksvgame.cpp:847` (`vb_34 = 3` → mask 0x03 = 2 bits), and by the crate's skull.exe citation. Both platforms use 2 bits; same resolution for the line-391 open question on the type-9 sub-type (2 bits on DOS too, `sksvgame.cpp:886`). - [ ] **`savegamebuffer.rs` field docs**: the "verified empirically against the Mac fixtures" LE claim only ever covered fields whose payload fits a single byte; restate the actual verification scope.

jqueuniet commented

2026-07-06 08:47:22 +02:00

(Migrated from codeberg.org)

Fixed by #209 (merged into main).

Fixed by #209 (merged into `main`).

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

No description provided.

Rows
Columns