Crate psx_pack 

Guest-side WORLD.PAK parsing and in-place chunk decompression.

psx-iso::build_world_pack (behind the mkisopsx CLI and the editor’s embedded Play) writes the pack; this crate is the matching reader logic. Before it existed, every streaming game re-derived the parser and the LZ4 decoder from the engine’s editor-playtest example: oot-psx loader.rs, zelda3-psx loader.rs (a copy of oot’s), hl-psx cdstream.rs. Reader and writer now live in one repo so the format cannot drift.

Scope: this root module is PURE logic (parsing + decompression), building and testing on the host. The CD-ROM command/DMA state machine that feeds sectors in lives in cd (cd::SectorReader + cd::load_chunk), cfg(target_arch = "mips")-gated; the reader is psx_io::cd::reader, on the Cd token. Note cd::SectorReader::prepare sets I_MASK to VBlank-only until stop puts it back; read its docs before adopting.

Pack layout (all little-endian, from psx-iso):

header, 28 bytes:  "PSOXWPAK" | u32 version=1 | u32 chunk_count
                   | u32 total_sectors | u32 header_sectors | u32 table_bytes
table:             chunk_count x 24-byte entries:
                   u32 chunk_id | u32 sector_offset | u32 sector_count
                   | u32 byte_size | u32 checksum (FNV-1a) | u32 reserved
payloads:          each chunk starts on a 2048-byte sector boundary

Chunks written with --world-pack-compress-rooms carry an HLZC frame ("HLZC" | u32 raw_len | LZ4 block); decompress_hlzc_in_place undoes it inside the destination buffer, no scratch memory needed.

Modules

cd

The pack-table scan and chunk streaming, on top of the polled sector reader.

visibility

Allocation-free Quake and GoldSrc visibility row codecs. Allocation-free Quake/GoldSrc visibility RLE.

Structs

PackEntry

One chunk-table entry.

PackHeader

Parsed fixed header.

Constants

ENTRY_BYTES

Size of one chunk-table entry in bytes.

HEADER_BYTES

Fixed header size in bytes.

HLZC_MAGIC

Magic framing a compressed chunk payload.

MAGIC

Pack magic, first 8 header bytes.

SECTOR_BYTES

User-data bytes per CD sector (MODE2 form 1).

VERSION

The one pack version this parser understands.

Functions

decompress_hlzc_in_place

Undo the HLZC compression frame in place.

entry_location

Locate table entry index on disc: (header_sector, byte_offset_within_it).

find_chunk

Linear-scan the table for chunk_id. Same slice contract as parse_entry. Packs are written sorted by id unless an explicit order file reorders them, so callers doing many lookups should build their own cache (hl-psx keeps a 512-entry table) rather than rescanning.

fnv1a32

FNV-1a over bytes; the checksum psx-iso stores per entry.

parse_entry

Parse the table entry at index. bytes must start at the beginning of the pack (header included) and cover the entry; read header.header_sectors * SECTOR_BYTES up front and every entry is in range. None when the slice is too short.

parse_entry_at

Parse one ENTRY_BYTES-sized table entry starting at an arbitrary byte offset. This is the sector-local primitive behind parse_entry: a caller holding a single 2048-byte header sector (not the whole pack) can parse the entries it contains directly, and stitch the one entry that straddles into the next sector through a small ENTRY_BYTES buffer (see entry_location). None when the slice is too short.

parse_header

Parse and validate the fixed header from the first pack bytes (any slice covering at least HEADER_BYTES, e.g. the first sector). None on wrong magic or version.