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] (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).
• 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.