Files

Cristian Gora 1ccaa8b398 Full correctness check against the docs: safer writes, reverts and texts

Safety
- Writes are serialized (Workspace.lock): two background jobs rebuilding one
  package (a sound and its subtitle applied side by side) lost an edit.
- A store copies a bank file or package as "original" only if it matches the
  shipped catalog (Workspace.unoriginal_files: in-memory sounds, bank copies of
  voice lines, subtitles); the editor refuses to switch stores while changes
  are applied. A second store could otherwise resurrect a reverted sound.
- Mod import in the editor asks before overwriting files changed outside the
  tool (it forced silently).
- Revert all in the editor reverts texts too; the uninstaller counts text
  edits before offering to delete the store.
- ackit restore-backup: the full-backup restore decisions.md described; it
  keeps the sounds of WADs without a full copy recorded.
- build_catalog also stops when a subtitle differs from the catalog.

Languages and texts
- Game.language() returns languages without voices (JPN, RUS, ...) and
  Game.voice_archive() their INT voices; ackit text --lang JPN works.
- Menu lookups parse one cached file (find & replace: minutes -> ms).
- Subtitles decode cp1252 as Windows does: the UTF-8-in-cp1252 line
  Speech_TAPE_J_Answer_1_00 (KOR/POL/POR/RUS) is written back byte-for-byte;
  SUB_KOR/SUB_RUS rebuilt from the original game (only those rows changed).
- Mods exported while another language is loaded keep name and line.

Other fixes
- Down-mix folds extra channels in at -3 dB (a 5.1 centre voice was dropped).
- e2e_editor no longer overwrites the user's settings.json; kill_game waits
  for the game to exit before reverts.
- Recorder handles Int32/UInt8 input and split frames; package block cache
  locked; conflict messages, CLI help examples, stale docstrings and doc
  references fixed; tests no longer read this PC's game language.

Docs (decisions, user guide, README, subtitles.md, banks.md, catalog README,
REPORT, NOTES, CLAUDE.md) updated; check_docs: 102 claims match. 148 tests;
e2e_features 9/9, e2e_editor and verify PASS; game original afterwards.

2026-10-13 21:34:13 +02:00

2.6 KiB

Raw Blame History

CLAUDE.md

Batman: Arkham City (PC) audio toolkit + editor. Read NOTES.md first (status, next steps, environment).

Layout: ackit/ library + CLI (python -m ackit -h), app/ PySide6 editor, tests/ pytest, data/catalog/ CSVs (+ user's original lists in data/catalog/source/, never edit them), docs/, tools/ build scripts.
Dev env: .venv (Python 3.14, pip install -e .[app,dev,verify]). Run tests with .venv/Scripts/python -m pytest -q.
Writing game files goes through ackit.workspace.Workspace only (originals store, atomic writes, conflict checks, one write at a time: Workspace.lock, held by every apply/revert/rebuild incl. Texts). Speech/ambience: in place, never larger than the original WEM; music packs: any size (docs/formats/wad.md). In-memory sounds (archive BANK, loose .bnk + .upk packages): in place into every copy; a bank file is always rebuilt from the store's original copy + the applied replacements (docs/formats/banks.md, upk.md). Texts go through Workspace.texts (subtitles in packages, in place and NUL-padded; menu .int files).
Never use Steam "verify integrity". Keep game files original after tests (ackit status, ackit revert --all).
Real-game checks: ackit verify (offline), ackit verify --catalog [--quick] (catalog vs game files), ackit verify --ingame [--banks | --texts] (Windows; needs Steam running and logged in, WinDbg; ~1.5 min; reverts and checks byte-identity itself).
Rebuild catalogs only from original game files: python tools/build_catalog.py (~5 min, scans all packages; stops if a sound or subtitle differs from the current catalog). Voice lines are identified by the game's Wwise Sound objects (ackit/lines.py, column line; one recording per language), never by WAD position or name: positions differ per language (docs/decisions.md 5, docs/formats/banks.md Lines).
Figures in the docs are checked, not copied: after changing data, code or docs run python tools/check_docs.py (--scan: also the bank survey and the catalog check's facts, ~10 min; --wems: every WEM rebuilt, ~10 min); add a claim there for every new figure.
Real-game write round trips: python tools/e2e_features.py, python tools/e2e_editor.py (they revert in a finally block; still check ackit status after any interrupted run).
Shell: git at C:\Program Files\Git\cmd (prepend to PATH). Write Python with the Write/Edit tools; avoid PowerShell here-strings and heredoc string surgery with backslash escapes (they produced NUL bytes before).
The speaker loopback can contain other apps' audio (voice chat): never save raw captures.

2.6 KiB Raw Blame History

CLAUDE.md

2.6 KiB

Raw Blame History