Asset loader

At a glance

Source archive

PROT.DAT, 1233 entries; names resolve through CDNAME.TXT

Loaders

One per scene type - battle, field / town, sound, streams (table below)

Common router

The asset-type dispatcher: an 8-bit type byte picks a handler (TIM, TMD, MES, ANM, …)

Scene change

Field-VM op 0x3F carries a scene name; op 0x3E door-warps reach only the seven minigames

Engine port

engine-core::SceneResources::build_targeted + legaia_asset parsers (scene_asset_table, scene_tmd_stream, battle_data_pack)

Confidence

Confirmed - disassembly + corpus round-trips (how we know)

How it works

"Load this scene" never means "load one file". A battle needs character meshes, monster meshes, palettes (CLUTs - colour tables stored as rows of framebuffer pixels), a sound bank, effect scripts and dialog text, scattered across dozens of PROT entries. Each scene type has a loader that fetches all of it, and every loader shares one shape:

• A small state machine with one numbered case per asset slot.
• Each case hands one entry's bytes to the asset-type dispatcher.
• Some cases kick off async CD reads so data streams in while the scene initialises.

Each format on the way down has its own page: PROT.DAT (the archive), CDNAME (the name map), LZS (the compression), asset-type + asset-descriptor (the router and its 8-byte records). Function names like FUN_8001F05C are RAM addresses from the disassembly - the game shipped without symbols.

Field / town scene loader

The "walk into a room" path: every town, dungeon and field map goes through it. The scene's name becomes a family of consecutive PROT entries, addressed from the block base:

The loader stages the first three sidecars into a per-scene buffer, sizing the read by summing three consecutive entries' sector counts with the standard PROT TOC math.

Name-based scene change

Doors, stairs, town entry from the overworld and the prologue hand-off all carry a destination name: field-VM opcode 0x3F embeds it inline in the bytecode, so nearly every in-game transition has a recoverable destination. The scene-change routine copies the name into the pending-scene buffer, then spawns a transition streaming actor that streams the destination block's .LZS bundle into the shared asset buffer during the fade, and finally flips the game mode to MAIN INIT. Dev and retail branches converge on the same content: raw scene_base + 3 is the bundle entry, verified across the corpus.

Asset descriptor walker

Once the bundle is in RAM, one loop turns it into live assets - and its one surprise is that there is nothing clever in it. The walker reads a count word, then for each slot hands base + data_offset to the dispatcher, which splits the descriptor word into type = word >> 24 and size = word & 0xFF_FFFF and jumps through the handler table.

The walk is also what fills the mesh pool: two dispatcher cases (type 0x02 TMD pack, type 0x09 bare mesh) register meshes into the runtime pointer table in walk order, past the resident 5-mesh head (the party). A magic-byte sweep of a scene block is not equivalent - see scene bundles.

The walker has zero static callers in the main executable; its sole caller lives in the field overlay (code streamed into RAM on demand), at the start of every field session. Engine side: scene_asset_table::resolve handles both the bare bundle and the prescript-prefixed variant, and a disc-gated corpus test verifies the walk against every classified entry.

Door warps into minigames (opcode 0x3E)

The fishing pond, the casino machines, the Baka Fighter booth, the dance floor: stepping onto those is a different kind of transition. The script hands over a small number instead of a name, the game swaps in that minigame's whole code overlay, and remembers where you came from.

• Op 0x3E with op0 ≥ 100 stores sub_id = op0 - 100 and flips the game mode to OTHER INIT.
• The handler backs up the active scene name and id, loads the per-sub-id minigame overlay, and calls its init entry.
• Only 7 destinations exist (sub_id 0..6): fishing, slot machine, Baka Fighter, dance, plus two dev modules and the monster-roster arena.
• The op carries no destination name: on exit the return handler restores the backed-up name, commits casino winnings, and hands off to MAIN INIT, which reloads the restored scene.

Full chain and provenance: field VM § 0x3E WARP; the mode-word trap ("0x19 alone cannot tell fishing from dance") is on the boot page. Play them on the minigames page.

Battle bundle

A battle starts from inside a field scene, so its loader (an 11-case state machine) stacks on top of what's already resident: monsters, their sound banks, effect scripts, and the side-band streams that summons and special attacks pull from mid-fight.

The party's own battle meshes are not loaded here: they are assembled per character from the player battle files' equipment sections - see battle-data-pack and character-mesh.

Filling VRAM: the targeted upload

A PS1 texture is useless without its palette, and Legaia keeps the two in different places: a character's mesh sits in one PROT entry while the palette rows it samples come from another. Retail uploads only the texture bytes the current scene's meshes need, in a fixed order; the port reproduces that policy rather than blasting every TIM into VRAM.

SceneResources::build_targeted parses every TMD in the scene's block, collects the union of CLUT rows and texture-page boxes the meshes sample, then uploads each TIM block only where it will not collide with a referenced palette row. Field and battle differ in scope:

• Battle uploads everything, including the meshes and TIM chunks inside scene_tmd_stream entries and the player battle files.
• Field skips both - those are battle-init residents. Retail field saves carry VRAM row 479 as zeros, which is the boundary the engine matches.
• Two CDNAME blocks (init_data, player_data) stay resident across field transitions - they carry the field-form party meshes and atlas from PROT 0874.
• Two entry classes are never uploaded: v12 trigger sidecars (they are trigger data, not textures) and pochi filler slots (reserved one-sector fills; see pochi).

Music selection (BGM lookup)

When a scene asks for "music track 2016", there is no music table to consult. A global id is an offset into the shared music bank. A scene-local id (below 2000) looks like an offset into the scene's own CDNAME block, but that index only drives the "did the track change" test - the load itself is overwritten with global slot 2.

// FUN_800243F0
if (bgm_id < 2000) {
    change_idx = scene_block + 6 + bgm_id;         // compared only
    load_idx   = global_pool_base + 2;             // 0x800245A4..0x800245BC
} else {
    change_idx = load_idx = global_pool_base + (bgm_id - 2000);
}

Global id 2000+i is sound-test track i, but the music_01 bank is piecewise in extraction space (988+i for i ≤ 67, 990+i for i ≥ 68, gap at 1056/1057) - not a flat base. Resolver: engine-core::music_labels; the full cue list is on music tracks.

Sound and stream loaders

Full breakdown in Audio. The offline twin of the whole ladder is legaia-extract: verify → disc → PROT → categorize → extract → TIM → PNG - per-stage invocations on the extraction page, results browsable in the asset viewer.

How we know

Full write-up: docs/subsystems/asset-loader.md.

See also