File Formats

File Formats

The project implements readers and conversion tools for locally supplied game files. Keep original data, extracted assets, decryption keys, generated game code and game-derived captures outside commits. The descriptions below document container structure and tooling, not a distribution of game content.

HD6 archive indexes

DATA.HD6 and DATA2.HD6 index their corresponding .DAT payloads. tools/hd6/hd6_extract.py reads the index, expands tokenized names and writes files plus an optional manifest.

The index has an HD6 signature, a 52-byte little-endian header, a pool of name fragments, a name table and eight-byte packed file entries. Name records contain LEB128 token indexes terminated by zero.

The implemented file-entry layout is:

Bits	Meaning
0–16	Byte offset into the name table
17–37	Payload offset in units of 1,024 bytes
38–63	Stored size in units of four bytes

Observed sector alignment permits equivalent descriptions of the offset, but the bit boundaries above are the parser's contract. Stored lengths may include padding. The extractor handles a trailing sentinel and dummy entries, sanitizes output paths, and records extracted-file hashes in its manifest.

For a locally extracted disc tree:

python3 tools/hd6/hd6_extract.py --hd6 path/to/DATA.HD6 --list-only
python3 tools/hd6/hd6_extract.py --hd6 path/to/DATA.HD6 \
  --dat path/to/DATA.DAT --out build/assets/data \
  --manifest build/assets/data-manifest.json

Replace the example paths with your own inputs. Validate bounds, file sizes and known container headers across the entire archive when changing the parser; an incorrect bit layout can appear plausible for early entries.

MWo3 overlays

MWo3 files are fixed-address Metrowerks overlays. A 64-byte little-endian header describes the overlay ID, load address, text/data/BSS sizes, constructor range and name. Text and data follow the header; BSS is zero-filled in guest memory.

tools/mwo3/mwo3_to_elf.py wraps these images in ELF files for analysis and recompilation. Constructor thunks can reside in the data section, so conversion must preserve the executable section attributes required by the analysis pipeline.

Use config/<version>/overlays.toml for revision-specific addresses and module information. NTSC-U and PAL use different overlay arenas, and their module sets differ. The runtime must dispatch through the currently resident overlay rather than treating its address range as permanently bound to one module.

MVI movies

MVI is an encrypted movie container. Decrypted output is a PSS/MPEG program stream. The conversion utility is tools/mvi/mvi_decrypt.py; its decryption key must be supplied locally by the user. The project does not provide a key or a key-recovery procedure.

See Building for the asset extraction workflow. Successful decryption or video decoding does not establish complete movie audio support.

Developer capture formats

VU replay uses a prefix with .code, .data and .state files. The state representation depends on the runtime ABI and is not a stable interchange format. It does not serialize every in-flight interpreter detail, so capture replay must be supplemented with authored pipeline/resume tests.

The VU generator accepts versioned VU-BLOCKS text profiles containing a VU unit and exact instruction-pair words. Only authored synthetic profiles belong in the repository; game-derived profiles remain local inputs. Consult the generator for supported profile versions and length bounds.

PCSX2 GS dumps and the project's ordered GS backend traces serve different replay layers. Both may contain game-derived graphics data. Keep them local and record the producing build, scene and capture conditions when using them as regression evidence. See Testing.