gen1recomp/docs/save-conversion.md

Save conversion

Cartridge .sav files go in and out of the launcher through src/save_convert/. One codec per generation: GenSave (Red/Blue/Yellow), Gen2Save (Gold/Silver/Crystal), Gen3Save (FireRed/LeafGreen/Emerald). SaveConvert.importSav / exportSav are the only entry points; both return nil, message instead of raising.

Supported

• Gen 1: 32768 bytes, English. Gen 2: 32768 bytes plus an optional RTC footer, English. Gen 3: 128 KB flash plus an optional footer.
• Not converted: Japanese and Korean carts, Ruby/Sapphire. Detected ones are refused with a named reason.
• Gen 1 and Gen 2 need the selected game's imported ROM cache; missing data refuses conversion with a named reason.

Round trips

• export(import(cart), cart) reproduces the cart except for a short list of normalizations (box checksums, party level byte, Gen 3 slot rotation and counter).
• Every region is tiered in src/save_convert/regions/gen<N>.lua: T1 modeled, T2 carried verbatim from the cart image, T3 derived.
• The cart image rides inside the slot (rawImport for Gen 1/2, modData.cartImage for Gen 3), so export needs no second file. A .cart sidecar from an older build is read once at export, folded into the slot and deleted.
• Import returns an optional note (backup copy used, stale active box, older Gen 3 slot) that the launcher shows beside the result.
• Gen 2 preserves the current map's object visibility and rebuilds visible NPCs when exporting onto a new map. Fresh and moved exports need the current ROM cache's sprite metadata; re-import the ROM when an older cache is refused.
• Successful exports return named reader warnings to the launcher and CLI. Damaged embedded Gen 3 images refuse export unless a valid matching template can recover them.
• Gen 3 modData.cartImage is PKCI1:<length>:<base64 of LZ> (gen3_port/imagepack.lua, about 5 KB for a typical slot instead of 190 KB); a raw image from an older build is still read.
• Gen 3 regions with no engine state are carried and proven so in regions/gen3.lua (proof per row, checked by tests/save_compat/gen3_carry_contract_test.lua). The FireRed quest log is carried and reset with the map window: the engine's own quest log is a sampled replay, the cart's is an input script.
• Emerald and FireRed engine sections (TV, Frontier, Trainer Hill, Mauville, Lilycove, Apprentices, Hall records, VS Seeker, Trainer Tower, minigame records, Mystery Gift news/card/metadata) live in gen3_port/sections/. The Wonder Card gift payload is script bytecode and stays template-carried; a different engine card clears the cart card instead of writing a card the game would reject.

Reader validator

Compat.check(bytes, version) mirrors the detectors of PKHeX, PKForge and OpenHome and the game's own checks. Errors block the export (Compat.gate), warnings are returned and never block. The tested PKHeX Gold/Silver writer overlaps the last 45 Hall of Fame bytes with a backup copy; exports warn when existing Hall of Fame data would change. Rules are listed in Compat.RULES; tests/save_compat/compat_validator_test.lua crafts a bad image for each one.

Tests and tools

• luajit tests/run_save_compat.lua: fixtures, R1/R2 round trips, fuzz, validator. SAVE_COMPAT_FUZZ_N and SAVE_COMPAT_FUZZ_SEED widen the fuzz runs.
• SAVE_COMPAT_REAL_SAVES="red=/path/a.sav;crystal=/path/b.sav" runs the validator over your own carts.
• scripts/save-compat.sh dumps every fixture export and runs the PKHeX probe (dotnet) and the OpenHome probe (node), then diffs against tests/fixtures/save/expected/. --bless rewrites the expected files; a missing toolchain skips that probe. Needs PKHEX_ROOT and OPENHOME_ROOT checkouts.
• tools/save_convert/convert.lua is the CLI. Set <GAME>_CACHE (for example YELLOW_CACHE or EMERALD_CACHE) to that game's imported cache directory.