Move-table opcode VM

At a glance

Driver

FUN_80023070 in SCUS_942.54 (the main executable - always resident, unlike overlays)

Opcodes

71 (0x00..0x46), plus 61 sub-ops in an overlay extension via op 0x2F

Program

Per-actor "move buffer" at actor+0x48, program counter at actor+0x70

Operand width

u16 stream - PC and sizes count in 16-bit units, not bytes

Fed by

Field-VM op 0x22 EXEC_MOVE; records come from MDT move tables

Engine port

crates/engine-vm/src/move_vm.rs - all 71 outer + 61 extension ops, host callbacks via MoveHost

Confidence

Confirmed - full per-case disassembly (how we know)

The runtime VM family

Legaia runs five bytecode / state VMs that share the actor model (an actor is the engine's record for one on-screen entity - a party member, an enemy, a menu window). Confusing them is the classic mistake in this corpus. Five is an orientation, not a census - the full list is the VM inventory.

The extension dispatcher exists in many overlays (town, world-map, dialog, cutscene) at the same RAM address; each overlay supplies its own jump-table contents. The motion VMs run alongside but consume a separate per-actor motion buffer - no shared opcodes.

Dispatch and control flow

short* op = (short*)(actor[+0x48] + actor[+0x70] * 2);   // u16-aligned PC
if (op[0] >= 0x47) goto exit;                             // out-of-range = end of buffer
goto jump_table[op[0]];                                   // JT at 0x80010778

The interpreter loops: read the opcode at the PC, dispatch, add the handler's size (in u16 units) to the PC, continue - until an op clears the loop flag. Three things break the loop:

• 0x08 HALT - sets flag bit 0x8 and exits without advancing.
• 0x09 WAIT_SET - arms the wait timer at +0x54; the actor tick counts it down across frames before re-entering.
• End of buffer - any opcode value ≥ 0x47 reads as "done", not "unknown opcode".

What the opcodes touch

The move VM rewrites a wide swath of the actor struct. The important fields, with the ops that write them:

The full per-opcode reference (all 71, with sizes and exact stores) is in docs/subsystems/move-vm.md.

The overlay extension (opcode 0x2F)

Op 0x2F reads a 16-bit sub-opcode and dispatches through a 61-entry jump table inside the field overlay. The sub-opcode is bounds-checked before the indirect jump, so this escape has no out-of-bounds path even though some sub-ops write into the move buffer itself. The extension is where the scene-specific tricks live:

• A 16-slot shared scratch table that actors use to hand positions and render banks to each other.
• World-position lerps and gates - glide an actor toward the player or a map origin; bounding-box and squared-distance predicates around the player.
• Self-modifying bytecode - ops that write the actor's world position, or arithmetic results, back into the move buffer a few instructions ahead.
• HSV colour ramps - cycle a packed RGB colour through hue/saturation/value space (the ambient "pulsating flesh" and lightning effects idle on these).
• The fourth flag bank - conditional branches on the same system bitfield the field VM's story flags live in.

A sibling that is not the move VM: puzzle rooms run a discrete tile-board mode in the same overlay - a byte-cell grid where each d-pad press moves exactly one cell. It reads the pad too, which is how it was once mistaken for town locomotion (that is field locomotion). See tile-board.md.

Screen-effect widget family (PROT 0900)

The resident slot-B overlay PROT 0900 hosts a four-kind family of 2D screen widgets - the cutscene-style presentation layer of iris wipes, letterboxes and tweened panels. Widgets are ordinary actors on the effect-actor list, spawned with a per-frame handler bound at actor+0xC. Engine port: engine-core::screen_fx.

On disc, only the ten ending-sequence (ed*) scenes invoke the family (field-VM op 0x43 sub-ops); battle casts leave it dormant. The count used to read "eight" here and in the subsystem docs, which omitted edbubu and eddoman; it is now a measurement, taken by decoding every partition record of every MAN carrier of every scene. All tweens share one four-mode interpolator, ported as screen_fx::interp. The engine ticks the family per Field/Cutscene frame and composites it above the 3D scene on both hosts, feather strips included - their subtractive blend rides the same screen-primitive path the browser page already used for the battle transition.

Where the pieces live

• crates/mdt parses the MDT format; the per-frame data inside an MDT record is exactly this VM's bytecode.
• crates/engine-vm/src/move_vm.rs is the from-scratch port - all 71 outer + 61 extension ops, actor callbacks behind the MoveHost trait, and an actor_tick mirroring the retail per-frame entry gate.
• Field-VM op 0x22 EXEC_MOVE is the gateway in: it resolves a move id to a record and stages the buffer + PC on the actor.

How we know

Full opcode-by-opcode reference: docs/subsystems/move-vm.md and move-vm-overlay-ext.md.

See also