UnheardCity/REPORT.md

Report — full-game audio, subtitles and menu text (mission 3)

Brief: docs/history/mission3_audio_text_prompt.md. Earlier missions: the WAD/WEM toolkit (mission 1) and the editor Unheard City (mission 2).

What works (verified)

• Every sound of the game is cataloged and editable: the speech WADs (5 languages x 10,816), the SFX WAD (651) and, new, the 15,404 in-memory sounds stored inside soundbanks (archive BANK: footsteps, foley, combat, weapons, UI, efforts) in loose .bnk files and in 1,499 .upk packages. ackit reads and patches the LZO-compressed UE3 packages itself (ackit/upk.py, lzo.py; no external tools). A replacement goes into every copy (93,910 copies); 396 speech lines with prefetch heads in banks get their heads rewritten too. Names: 6,456 BANK sounds are named after their Wwise event (Play_...), the rest after their bank.
• Catalog check: ackit verify --catalog compares the catalog with a fresh scan of the game (missing, extra, duplicate, size/checksum, category, character, language, bank copies, subtitle copies/texts): catalog OK on the full game. It found and fixed 2 duplicate names per language (variation shown as NAME#i).
• Subtitles: found in RDialogueEvent objects inside the packages (9,016 speech lines x 11 languages, 168,122 stored copies), parsed, cataloged (SUB_<LANG>.csv) and linked to their speech sound through the soundbanks (92 % of the strings; the rest are unused/placeholder lines). Edited in place in every copy.
• Menu text: the localization files (BmGame\Localization\<LANG>\*.int, ~7,000 strings per language), edited value by value; everything else in the files stays byte-identical.
• Editor: tabs Sounds / Subtitles / Menu text. The sound editor shows and edits the selected speech line's subtitle side by side; the subtitle list links back to the sound. Search, filters (character, category, file, modified), room counter, apply/revert/revert all, find & replace on the filtered rows, mod export/import with texts, changed-outside banner for sounds and texts.
• Safety: every changed file (WAD, bank, package, localization file) is rebuilt from a verified original copy in the store + the edits applied now; reverting the last edit restores it byte-for-byte; files changed by another tool or Steam are detected (whole-file SHA-1) and not overwritten without confirmation.
• Tests: 121 automated tests (unit, synthetic game with packages/banks/dialogues/localization, real-game read-only, offscreen GUI) pass. ackit verify PASS (incl. 300/300 in-memory WEMs rebuilt byte-identically).
• Real game (2026-10-09), all reverting and checking byte-identity themselves: ackit verify --ingame PASS (music heard, ncc 1.0); --banks PASS (77 in-memory sounds of the front-end packages replaced in 54 files: the game loads them, no crash); --texts PASS (12 menu texts found in the game's memory, 12 subtitles patched in packages, no crash); tools/e2e_editor.py PASS. Game files original at the end (ackit status).
• Package: dist/UnheardCity-3.0.0-windows-amd64.zip (86 MB, catalogs included). With PATH reduced to the Windows folders the packaged exe passes its smoke test (26,871 sounds loaded, encode + inject, 9,352 subtitles and 7,020 menu texts loaded, an in-memory sound decoded from a package) and the GUI starts and quits cleanly. The installer is unchanged since mission 2 (install/upgrade/uninstall verified then).

Unresolved / limitations

• Heard in game, not proven automatically: in-memory sounds and subtitles. The game loads the patched packages (probe data and texts found in its memory, no crash), but nothing of this plays/shows on the title screen without input, and keys posted to the game window do not reach the menu (findings 18). Speech lines were already in this situation; the decoder path is the same one proven for music.
• Size limits: in-memory sounds and speech must fit their original size; subtitles must fit the original text's length ("room"); cp1252 subtitles accept cp1252 characters only. Lifting these limits means moving objects inside the packages (new export offsets/sizes, added chunks): designed but not done, because it could not be verified automatically in the game (decisions 4c).
• Unlinked subtitles: ~8 % of the subtitle strings have no event path to a streamed sound (unused or placeholder lines); they are listed and editable but not linked.
• Unnamed sounds: ~9,000 BANK sounds have no event name and are named <Bank>_<n>.
• Two copies of media 1C898731 differ; its checksum is left empty. Channel order for 4-6 channel sounds is unverified. M4A/AAC/WMA input needs an ffmpeg on the system.
• Another game build is scanned at first start (WADs: seconds; banks and subtitles: a few minutes, cached).

Next steps

1. Gameplay check (a person): a replaced footstep/foley sound and an edited subtitle in a mission.
2. Optional: lift the subtitle length limit by relocating dialogue objects (needs that gameplay check).
3. Extend the curated speaker lists (data/catalog/source/<lang>/*.txt) and rebuild the catalog.