gora/UnheardCity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add mission 3 brief and plan

Browse Source
This commit is contained in:
Cristian Gora
2026-10-09 19:30:28 +02:00
parent 67bc541b1e
commit b3c9b84dc7
3 changed files with 49 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
NOTES.md
View File

@@ -14,10 +14,19 @@
Packaging: `python tools/build_app.py` -> dist/UnheardCity (self-contained, licenses); packaged exe passes
`--smoke-test` with PATH = C:\Windows only. Real e2e through the editor code path (tools/e2e_editor.py): PASS
(music heard in game ncc 1.0, reverts byte-identical, speech line apply/revert byte-identical).
- NEXT: editing of the ~15,800 in-memory sounds in soundbanks (loose `SFX\*.bnk` footsteps first, then banks
embedded in `.upk` packages); not listed or editable yet, survey in `docs/formats/banks.md`.
- NEXT (optional): verify >2-channel channel order in game; speech heard in-game (needs gameplay).
- OPEN: channel order for >2 channels unverified.
- Mission 3 (2026-10-09, brief: `docs/history/mission3_audio_text_prompt.md`): full-game audio, then subtitle
and menu text editing. Plan (one commit per stage; a stage = code + tests + docs + this status):
1. [ ] `ackit/lzo.py`, `ackit/upk.py` (UE3 package summary, compressed chunks, block-level read/patch),
`ackit/bnk.py` (bank parsing: DIDX/DATA/HIRC sources, prefetch). Unit + real-game read-only tests.
2. [ ] Catalog of in-memory sounds (archive `BANK`): build from loose banks + packages, location index,
names/categories, prefetch handling; `ackit verify --catalog` cross-check (missing/extra/duplicate/
character/category/language) + test.
3. [ ] Writing in-memory sounds through `Workspace` (in place, <= original size; every copy in every
package; byte-identical revert), CLI + editor; real-game e2e.
4. [ ] Subtitles + menu text: find/document formats, `ackit` parse/write with backup/revert.
5. [ ] Editor: Subtitles section linked to audio, separate Menu text section, revert, mod export/import.
6. [ ] Final e2e (audio + text), packaged build, REPORT.md.
- OPEN: channel order for >2 channels unverified; speech heard in-game (needs gameplay).
## Environment facts
- Game: Steam AppID 200260 "Batman: Arkham City GOTY", `C:\Program Files (x86)\Steam\steamapps\common\Batman Arkham

2
docs/README.md
View File

@@ -12,4 +12,4 @@
| [reverse-engineering/decoder.md](reverse-engineering/decoder.md) | BatmanAC.exe decoder functions and addresses |
| [reverse-engineering/findings.md](reverse-engineering/findings.md) | root cause, findings, in-game experiment log (incl. failed hypotheses) |
| [../data/catalog/README.md](../data/catalog/README.md) | catalog CSV schema, adding languages |
| [history/](history/) | the two mission briefs this project was built from |
| [history/](history/) | the mission briefs this project was built from |

35
docs/history/mission3_audio_text_prompt.md Normal file
View File

@@ -0,0 +1,35 @@
# CONTINUE: Finish full-game audio editing, then add subtitle and menu-text editing
Same autonomous rules as before: I won't answer questions, so decide, log assumptions in `NOTES.md`, and continue. Start by reading `NOTES.md`, `CLAUDE.md`, `docs/` and `docs/decisions.md` to restore context, and apply the new findings from the last session. Keep the Steam, backup and byte-identical-originals rules.
## 1. Complete audio editing for every sound in the game
- Make editing work for every audio file in the game (all WADs and languages), using the new findings. Handle edge cases explicitly (different codecs/variants, streamed vs. in-memory, sizes, alignment) in `ackit`, not in app-side workarounds.
- Make sure every single audio file is cataloged and the catalog is correct: add a verification command and test that cross-checks the catalog CSVs against the real WADs (missing, extra, duplicate, wrong character, wrong category, wrong language). Fix the data, and report remaining unknowns in `docs/`.
## 2. Subtitles and menu text editing
- Reverse engineer where and how the game stores subtitles and menu/UI text (they are text files in the game folders). Document the formats and encodings in `docs/`, and implement parsing and writing in `ackit` (with safe backup/revert, as for audio).
- In the editor:
- **Subtitles section**, linked to audio. Each sound shows its subtitle, and each subtitle links back to its sound. Editing both together should be convenient: search by text, character and category, show both side by side in the single-file editor, and bulk edit/find-and-replace.
- **Separate "Menu text" section**, kept apart from audio and subtitles, with its own search, filters and per-string editing.
- Support revert (per entry and all), mod export/import for text, and detect when game files changed underneath.
## Quality rules
- Do it properly: no hacks. If the editor UI or `ackit` need major restructuring to fit this cleanly, do it, and keep the repository organised as it is now (clear modules, no duplicated code, no leftover scripts).
- Add the necessary tests: unit, headless app-logic, GUI smoke tests, and a real end-to-end test against the game for audio and for text (apply, check the game starts and shows the change, revert, byte-identical).
- Document everything and update the existing documents (`README`, `docs/`, `decisions.md`, user guide, `NOTES.md`, `CLAUDE.md`), including the new catalog schema and the text file formats.
- Update the relevant docs and README in the same commit as each change, not at the end. A stage is not finished until its docs, tests and `NOTES.md` status are updated.
- Rebuild the packaged distribution (with bundled tools and licenses) and re-verify it.
## Saving quota (I'm on a limited Claude Pro quota; this is a hard requirement)
- Plan before acting: write a short ordered plan in `NOTES.md`, work in small stages, and commit after each. Finish and verify one stage before starting the next, so a usage pause never leaves broken work.
- Keep context small: never print whole files, big logs, WAD listings or catalogs. Use grep, head/tail, counts and summaries, and read only the line ranges you need. Write long outputs to files and inspect them selectively.
- Don't re-read what you already know: rely on `NOTES.md` and `docs/` instead of re-deriving or re-reading large sources. Update them as you go so a context reset is cheap.
- Use cheaper subagents (Sonnet or Haiku) for mechanical and bulk work: catalog cross-checks, CSV fixes, log triage, repetitive edits, test runs, and doc updates. Keep the main Opus context for reverse engineering, design decisions and tricky debugging.
- Run the cheapest check that proves the point: run the specific failing test first, not the whole suite after every edit. Run the full suite only at stage boundaries.
- Run the expensive real-game end-to-end tests (launching the game) sparingly: once per stage after the headless tests pass, plus the full pass at the end. Batch many changes into one game run where possible.
- Avoid GUI screenshots and image reads unless a layout problem needs them. Prefer headless assertions.
- Don't rebuild the distribution until the end, except for a single early build to check the pipeline.
- Avoid repeated failed attempts: after two failures on the same problem, write down the hypotheses tried, then change approach instead of retrying.
- Order of priority if the quota runs short: (1) correct, complete audio editing and catalog, (2) subtitle editing linked to audio, (3) menu text section, (4) tests and docs for each as you go, (5) packaging. Always leave `NOTES.md` with a clear "Current status / Next steps" so work can resume cleanly after a pause.
Finish with a short summary and a `REPORT.md` of anything unresolved.