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; 8,098 shared by all languages + ~1,460 localized speech lines per voice language) 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) and in 41 scripted RSubtitle objects (radio, encryption cards, Riddler; linked through RSubtitleLookup), parsed, cataloged (SUB_<LANG>.csv) and linked to their speech sound through the soundbanks (~99 % of the strings). Edited in place in every copy.
• Names true to the game: the position of a variation inside a WAD entry differs between languages (75 % of the lines), so speech sounds are named after the game's line (its speech event) - the same in every language and the same as the subtitle. The curated ITA speaker lists are mapped through these names; checked against the speaker field of the game's own dialogue objects: 955 / 955 agree. In-memory speech is per language too (one bank copy per language): the sound list shows only the selected language.
• 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: one Language setting (default: the game's language) for voices, subtitles and menu text (languages without voices use the INT ones, like the game); tabs Sounds / Subtitles / Menu text. The sound editor shows Listen / Replace / Subtitle side by side (resizable columns, no scrolling at usual window sizes); 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: ~1 % of the subtitle strings have no event path to a sound (unused or placeholder lines); they are listed and editable but not linked.
• Subtitle coverage is uneven in the game itself: no subtitles exist for efforts/grunts, few for combat barks (11 %) and cutscene lines (10 %; most cutscene lines are not played through speech events and have no dialogue object). No other subtitle storage was found in the packages (all classes with subtitle data checked).
• ~200 speech sounds per language are played by no event and keep a position name (NAME_i); their speaker labels apply to ITA only.
• 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.