home · architecture

How the layers stack

Click any layer to see what crate handles it and what's documented for it.

The pipeline at a glance

Going top-to-bottom: a PSX disc image, then the ISO filesystem, then the project's archive (PROT.DAT), then per-entry containers, then individual sub-assets. Each layer is owned by exactly one crate.

The five runtime VMs

Legaia's runtime is driven by five independent VMs that talk to one shared actor model. Four are clean bytecode dispatchers (actor / move-table / motion / field-event); the fifth (effect) is a per-slot state machine - different shape, same architectural role. Click each card to read the dedicated subsystem page.

VM 1
Actor / sprite VM
Where
Title-screen overlay (0971)
Opcodes
13
Operands
byte stream
Status
ported not wired
Note
All 13 opcodes are ported, but nothing in the engine calls the interpreter yet - it is inert.
VM 2
Move-table VM
Where
SCUS_942.54 + town overlay
Opcodes
71 + 61 sub-ops
Operands
u16 stream
Status
ported
VM 3a
Motion VM - pursue / patrol
Where
SCUS_942.54
Opcodes
22 (JT 0x80010EE0)
Operands
byte stream
Status
ported
VM 3b
Motion VM - scripted motion
Where
SCUS_942.54 (MAN tail-section 1)
Opcodes
32 (JT 0x80010FE8, 0x01..=0x20)
Operands
byte stream
Status
partial - table decoded, port split across three crates
VM 4
Field / event script VM
Where
Town overlay (0897)
Opcodes
43 + default-route extensions
Operands
byte stream
Status
ported
VM 5
Effect VM
Where
Battle overlay (0898)
Shape
per-slot state machine (no central opcode table)
Pool
32 master + 128 child slots
Status
done

How they wire together: field-VM op 0x22 EXEC_MOVE stages a move record into the actor; the per-frame actor tick steps the move VM; move-VM opcode 0x2F escapes to an overlay-resident extension dispatcher - a single 61-sub-opcode copy that lives in the field overlay (0897) only, so op 0x2F executes only while that overlay is resident and battle-side move records cannot reach it. The motion VM runs independently per actor for NPC pathing and camera-follow paths. The effect VM is on a different track - battle-only - but shares the same actor model: every effect is bound to a master-slot actor that the script-VM and battle-action SM can reference. The linked subsystem pages carry the driver function addresses and traces.

Runtime VM call graph Per-frame scene tick Field / event VM FUN_801DE840 - 43 opcodes (town overlay) drives NPC movement, dialog, story flags op 0x22 EXEC_MOVE → FUN_800204F8 stages a move record Per-actor frame tick Actor tick FUN_80021DF4 - physics + anim per actor steps the move VM each frame step move VM for active actor Per-actor opcode dispatch Move-table VM FUN_80023070 - 71 opcodes (SCUS) JT 0x80010778 - drives Tactical Arts Move VM extension FUN_801D362C - 61 sub-ops (overlay) JT 0x801CE868 - reached via op 0x2F Independent per-actor / per-slot drivers Actor / sprite VM FUN_801D6628 - 13 opcodes menu overlay (0899) - window widgets Motion VM FUN_8003774C - 22 opcodes NPC pathing, camera follow Effect VM FUN_801E0088 walker (battle) 32 master + 128 child slots share actor model
Field VM drives the scene; per-actor ticks step the move VM; the move VM jumps into an overlay extension via op 0x2F. Actor / motion / effect VMs run independently but bind to the same actor records.