Warn users about damaged-dump texture stand-ins where they will see it (Builder UI, game folder note) #2237

Closed

opened 2026-11-11 10:11:02 +00:00 by dazemc · 1 comment

dazemc commented

2026-11-11 10:11:02 +00:00

(Migrated from github.com)

The idea

When a dump has damaged texture files, the builder replaces them with stand-ins and prints a console message (Your game dump is incomplete: ...). That message is easy to miss: Builder window users see progress bars, and the game then builds and plays with wrong textures. The result is real bug reports that cost triage time — #1700 (fairy fountain grotto with no floor) turned out to be exactly this case, fixed by rebuilding from a correct-size dump.

What would help, in increasing order of cost:

Show the damaged-file list in the Builder UI, e.g. a warning on the ready page (and the problem page on failure), not console-only. The data is already there: stand_in_damaged_files() in nx2/make_game.py knows every replaced file.
Write the list into the game folder (e.g. next to hookshot_version.txt), so the launcher, future log readers, and issue triage can point at it. Asking a reporter "does your game folder contain a damaged-files note" is cheaper than a full re-dump cycle.
Document that make_game.py --check only validates exefs, not romfs. A --check ok gives false confidence about texture damage; the romfs damage scan only happens during a full read. Either say so in --check output/docs, or add an opt-in romfs check.
Mind the unpack stamp-skip trap. The builder skips re-reading when the .nup basename and byte size match a previous unpack (unpacked by this builder: <name> <size>). A replacement file with the same name and same byte size but different content would silently reuse the stale extraction. Including mtime (or a content hash) in the stamp would close that.

Related work already in flight (not duplicating): #2005 covers stand-in donor integrity and the unresolved-resource build gate.

Anything else

Evidence from two separate downloads of the same .nup torrent — identical damage in identical files both times, so this was a bad source, not transfer noise. Damaged files and their stand-ins:

Tex/CmnTex_Map_Soil_FairyFountain_Floor_D_Nrm.bntx.zs → replaced with CmnTex_Map_Sand_FairyFountain_Sand_A_Nrm.bntx.zs
Tex/RBake_Scene_GanonStage_G_2_1_d0_t0.bntx.zs → replaced with RBake_Scene_GanonStage_G_2_2_d0_t0.bntx.zs
Tex/Rock_WaterTemple_Gate_M_01_Nrm.bntx.zs → replaced with Rock_WaterTemple_Gate_P_01_Nrm.bntx.zs

Related: #1700 (resolved by correct dump), #2005 (claimed stand-in integrity + build gate), tracking #1002. No game data involved — file names and builder output lines only.

### The idea When a dump has damaged texture files, the builder replaces them with stand-ins and prints a console message (`Your game dump is incomplete: ...`). That message is easy to miss: Builder window users see progress bars, and the game then builds and plays with wrong textures. The result is real bug reports that cost triage time — #1700 (fairy fountain grotto with no floor) turned out to be exactly this case, fixed by rebuilding from a correct-size dump. What would help, in increasing order of cost: 1. **Show the damaged-file list in the Builder UI**, e.g. a warning on the ready page (and the problem page on failure), not console-only. The data is already there: `stand_in_damaged_files()` in `nx2/make_game.py` knows every replaced file. 2. **Write the list into the game folder** (e.g. next to `hookshot_version.txt`), so the launcher, future log readers, and issue triage can point at it. Asking a reporter "does your game folder contain a damaged-files note" is cheaper than a full re-dump cycle. 3. **Document that `make_game.py --check` only validates exefs, not romfs.** A `--check ok` gives false confidence about texture damage; the romfs damage scan only happens during a full read. Either say so in `--check` output/docs, or add an opt-in romfs check. 4. **Mind the unpack stamp-skip trap.** The builder skips re-reading when the `.nup` basename and byte size match a previous unpack (`unpacked by this builder: <name> <size>`). A replacement file with the same name *and* same byte size but different content would silently reuse the stale extraction. Including mtime (or a content hash) in the stamp would close that. Related work already in flight (not duplicating): #2005 covers stand-in donor integrity and the unresolved-resource build gate. ### Anything else Evidence from two separate downloads of the same `.nup` torrent — identical damage in identical files both times, so this was a bad source, not transfer noise. Damaged files and their stand-ins: - `Tex/CmnTex_Map_Soil_FairyFountain_Floor_D_Nrm.bntx.zs` → replaced with `CmnTex_Map_Sand_FairyFountain_Sand_A_Nrm.bntx.zs` - `Tex/RBake_Scene_GanonStage_G_2_1_d0_t0.bntx.zs` → replaced with `RBake_Scene_GanonStage_G_2_2_d0_t0.bntx.zs` - `Tex/Rock_WaterTemple_Gate_M_01_Nrm.bntx.zs` → replaced with `Rock_WaterTemple_Gate_P_01_Nrm.bntx.zs` Related: #1700 (resolved by correct dump), #2005 (claimed stand-in integrity + build gate), tracking #1002. No game data involved — file names and builder output lines only.

NotRexed commented

2026-11-11 21:27:31 +00:00

(Migrated from github.com)

Thanks for the report. Reports of the same problem are now collected in #2505, which lists this one with your details and links back here, so one fix closes them together and the open list stays readable. Follow #2505 for the fix, and add new details there (or here). If this turns out to be a separate problem it will be reopened.