Asset loading#

Purpose#

Read binary game assets from disk into memory buffers, with CD-path fallback logic for missing files and packed-asset fallback for some PL8 payloads.

Key entry points#

Symbol	Address	Role
`lotr2_asset_read_file`	0x4ca01c	`lotr2_io_open` + `__read`; used across game for sprites and data
`lotr2_asset_probe_readable`	0x4c9f84	Open-only probe with CD fallback; returns 0/1/2 (missing/direct/CD)
`lotr2_asset_write_file`	0x4ca199	Create/truncate write via `crt_write`
`lotr2_asset_write_file_at`	0x4cac46	Seek + write at offset
`lotr2_asset_read_ini_key_byte`	0x4caccf	Reads config blob; scans for marker; returns byte field
`lotr2_asset_resolve_cd_path`	0x4c9ab0	First fallback path rewrite when direct open/read fails
`lotr2_asset_resolve_pk_path`	0x4c98b4	Second fallback path rewrite for packed/decompressed assets
`lotr2_asset_restore_working_path`	0x4c9ca0	Restores path state after fallback attempts
`lotr2_asset_decompress_sierra_pack`	0x4cad5e	Expands packed assets into palette + pixel buffers
`lotr2_asset_get_extension`	0x4c9ce8	Saves the three-character extension from a dotted path
`lotr2_asset_set_extension`	0x4c9d58	Restores a saved extension into an existing dotted path
`lotr2_asset_strip_extension`	0x4c9dca	Temporarily removes an extension during fallback path construction
`lotr2_asset_append_extension`	0x4c9e13	Appends the saved extension to a path without one
`lotr2_asset_verify_pl8`	0x4c9eaa	Existence check with same CD/pk fallback as read

Fallback chain#

lotr2_asset_read_file first attempts the requested path directly. If that fails, it calls lotr2_asset_resolve_cd_path, retries, restores the path state, then calls lotr2_asset_resolve_pk_path and retries again before restoring state a second time. lotr2_asset_verify_pl8 uses the same CD/pk fallback sequence for existence checks.

Dependencies#

io/MODULE.md
gfx/MODULE.md — consumes .pl8 / .256 payloads
ui/MODULE.md — status.txt progress logging during loads

Data files#

Extension	Examples	Notes
`.pl8`	`grtnoble.pl8`, `panels2.pl8`	8-bit planar sprites
`.256`	`base01.256`, `gateway.256`	256-color palettes
`.dat`	`castles.dat`, `l2_maps.dat`	Game data tables
`.ini`	`l2.ini`, `sierra.ini`	Configuration

Format notes#

lotr2_gfx_load_pl8_rect reads a 16-byte PL8 frame header at frame_index * 0x10 + 8, then reads width * height bytes from the header payload offset.
lotr2_asset_decompress_sierra_pack searches packed data for marker blocks, copies a 0x300-byte RGB palette, and expands the following RLE-like pixel stream into the destination framebuffer buffer.

Open questions#

Confirm the packed asset marker names referenced by lotr2_asset_decompress_sierra_pack.