Before modding a format: a writer that gives every file back byte for byte

What to know

A reader that decodes every file is not yet a writer. Readers built for a viewer convert as they go (palette colours to RGB, fixed point to floats, sections sorted) and skip what they do not need (string pools, "unused" tails, the bytes after a name's terminator). A writer from that view gives files the game may still load but that cannot be checked. The check that catches every loss is: decode each file of the player's copy, write it back, compare all bytes. Only then change one value and load it in the game.

What POD's writers needed (measured on every file of the disc, 2026-10-23):

• Keep the stored form beside the friendly view: raw palettes, each fixed name field whole, the unused tail of the last block.
• Keep pools and tables as stored and append to them. POD's text pool is not in key order: rebuilt from the keys it gives other bytes. A pool may also end without a terminator; add one before appending.
• Some leftovers follow a rule and can be made again: POD's font files end in a buffer where each byte is the byte one block earlier XORed with the key.
• Write from the reader's own walk, not from a signature scan. A scan that guesses a block's page size found a "block" in one track that runs past the end.
• A container whose entry offsets count raw bytes (checksum words included) needs its entry table recomputed when a part grows. Test it by growing a part (one more texture page) and reading every entry to its end.
• Checksummed containers must be encoded again after any change; a wrong sum stops the game.

Evidence

crates/pod-formats/tests/writers.rs in the POD project: images (146), text (12), stills (6), texture blocks (371 pages), fonts (4), effects (3) and tracks (36) write back identical, and a changed copy reads back changed. Four changed files then loaded in the original game.

What to do

For each format: add the round-trip test over every file first (validate.py DECODER.py GLOB --write, with an encode(result) beside decode), then fix the reader until it keeps every byte, then add the one edit the mod needs and a test that reads it back. Run the tests in release builds: a nearest-colour search over every picture is slow in debug.