UnheardCity/CLAUDE.md

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). 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 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.