From b3c9b84dc732c24d5de461277b22694fd897d0a7 Mon Sep 17 00:00:00 2001 From: Cristian Gora Date: Fri, 9 Oct 2026 19:30:28 +0200 Subject: [PATCH] Add mission 3 brief and plan --- NOTES.md | 17 ++++++++--- docs/README.md | 2 +- docs/history/mission3_audio_text_prompt.md | 35 ++++++++++++++++++++++ 3 files changed, 49 insertions(+), 5 deletions(-) create mode 100644 docs/history/mission3_audio_text_prompt.md diff --git a/NOTES.md b/NOTES.md index 683f38d..b6287a6 100644 --- a/NOTES.md +++ b/NOTES.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 1289c71..c8415eb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 | diff --git a/docs/history/mission3_audio_text_prompt.md b/docs/history/mission3_audio_text_prompt.md new file mode 100644 index 0000000..acc808c --- /dev/null +++ b/docs/history/mission3_audio_text_prompt.md @@ -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.