Document soundbank findings

ackit/allocsize.py

@@ -1,6 +1,6 @@
 """Model of the game's codec-setup bump-allocator usage (dwDecodeAllocSize).
 
-Reversed from the dumped BatmanAC.exe (see docs/decoder_re.md):
+Reversed from the dumped BatmanAC.exe (see docs/reverse-engineering/decoder.md):
 WwiseVorbisParseSetupHeader (runtime 0x010B4D10) and its callees are a Tremor-lowmem
 derivative; every pool allocation is rounded up to 4 bytes.
 """

ackit/builder.py

@@ -1,7 +1,7 @@
 """Build an Arkham City compatible WEM from a standard Ogg Vorbis stream.
 
-Field rules were derived from all 2467 WEMs of the ITA WAD and are validated by
-rebuilding original files byte-for-byte (scripts/validate_builder.py).
+Field rules were derived from the WEMs of the ITA WAD and are validated by
+rebuilding original files byte-for-byte (`ackit verify`, tests/test_realgame.py).
 """
 import struct
 

ackit/catalog.py

@@ -1,4 +1,5 @@
-"""Index of every sound in the game, with names, categories and characters.
+"""Index of every sound in the game's WAD archives, with names, categories and characters
+(sounds stored inside soundbanks are not indexed yet: docs/formats/banks.md).
 
 Sources, in order:
   1. data/catalog/<ARCHIVE>.csv  -- shipped catalog (instant) when the WAD fingerprint matches;

ackit/codebooks.py

@@ -1,7 +1,7 @@
 """Wwise packed codebook library (ww2ogg 'packed_codebooks.bin' format).
 
 The game's built-in table (runtime 0x0158E748, 598 entries) is byte-identical to
-ww2ogg's standard packed_codebooks.bin; see docs/wem_format.md.
+ww2ogg's standard packed_codebooks.bin; see docs/formats/wem.md.
 """
 import os
 import struct

ackit/pack.py

@@ -9,7 +9,7 @@ BKPK header (u32 LE):
   0x2C end of table (0x48 + 12N)   0x38 embedded bank size   0x3C embedded bank offset
   table: N x {u32 media id, u32 size, u32 offset-in-WAD-entry}, sorted by id; each media
   starts at the next 0x800-aligned offset after the previous one.
-See docs/wad_format.md.
+See docs/formats/wad.md.
 """
 import struct
 

ackit/verify/debugger.py

@@ -31,7 +31,7 @@ def find_cdb():
             return p
     raise FileNotFoundError("x86 cdb.exe not found (install WinDbg or set ACKIT_CDB)")
 
-# Runtime addresses (image base 0x400000; ASLR off for this exe). See docs/decoder_re.md.
+# Runtime addresses (image base 0x400000; ASLR off for this exe). See docs/reverse-engineering/decoder.md.
 ADDR = dict(
     get_or_create_setup=0x010B3400,   # __thiscall(cache, AkSrcInfo*, ...) ; info+0x9c hash
     parse_setup=0x010B4D10,           # WwiseVorbisParseSetupHeader(info, channels, reader, pool) -> 0 ok

ackit/wad.py

@@ -11,7 +11,7 @@ Layout (little endian):
   0x1C  N x {u32 hash, u32 size, u32 offset}   sorted by hash as *signed* int32
 Entries are stored in table order, each at a 0x1000-aligned offset; 'size' is the
 entry payload size padded to 0x800. Padding bytes are zero; the file ends 0x1000-aligned.
-See docs/wad_format.md.
+See docs/formats/wad.md.
 """
 import struct
 from dataclasses import dataclass

ackit/wwvorbis.py

@@ -2,7 +2,7 @@
 
 Wwise stores a stripped setup header (codebooks referenced by 10-bit IDs into the
 built-in library, narrowed fields) and "modified" audio packets (no packet-type bit,
-no prev/next window flags). See docs/wem_format.md.
+no prev/next window flags). See docs/formats/wem.md.
 """
 from .bits import BitReader, BitWriter, ilog
 from .codebooks import CodebookLibrary, wwise_book_to_vorbis, skip_vorbis_book, book_bits_key