Actor / sprite VM

At a glance

Driver

FUN_801D6628, dispatch table at 0x801CED70

Lives in

Menu overlay, PROT 0899 - resident whenever the pause menu, shop, inn or save UI can appear

Instruction

Fixed 4 bytes: [opcode u8][window id u8][operand u16 LE]; opcode 0x00 ends the program

Programs

Data in the same overlay image - see window widget scripts

Targets

Windows from the menu overlay's 52-record descriptor table (field menu)

In the port

engine-vm (run over a Host trait), hosted by engine-menus::menu_widget::MenuWidgetState; live on both play hosts

Confidence

Confirmed - disassembly + live shop-transition captures (how we know)

How it works

A caller hands the VM a pointer to a program and the VM executes the whole thing in one call. It installs targets; the sliding itself happens over the following frames, in the window system's per-frame walker.

A packed position is x = (w >> 7) & 0x1FE, y = w & 0xFF, so x is always even. The programs are data resident in the overlay itself, not a scene file: the shop's picker runs its open program (slide in the vendor plate, picker, gold box and two panels) on entry and the slide-away program on the Sell transition.

Creation and the park edge

Every window is created off screen. The create helper keeps the window list sorted by id, re-initialises a window already on it, and parks a new one past an edge of the display picked by the descriptor's park class: 0 below the bottom, 2 past the left, 4 above the top, 6 past the right, each by the window's size plus a small clearance. The odd classes are diagonals that move both axes, and a class of 8 or more creates the window at home. The live position and the slide source take the park, the target the home, and every slide lasts 12 frames. Op 01's "already home" test therefore compares the real park with the home.

Closing reverses the slide. Begin-close leaves a closing window alone; a still window starts its close from the beginning, and one still sliding in turns round from where it is, its progress mirrored (12 − progress), so it backs out along the way it came.

Menus wait on the slides. The per-frame motion pass that animates them counts the windows it moved, and every menu sub-screen waits for that count to fall to zero before it reads the pad (field menu). In the port the pass is MenuWidgetState::step_motion, windows are created at menu_widget::park_position, and the kernel differential runs the interpreter and all seven helpers against the retail bytes.

There is no branching and no cross-context targeting - a program is a flat command list. That contrast is the reason it is a separate VM from the field VM, a 43-opcode variable-length dispatcher with halt-acquire semantics and sub-dispatcher families: UI widgets at the presentation layer, scripts at the gameplay layer.

The per-actor anim tick (a separate system)

FUN_80021DF4 is the per-actor animation and physics tick, related to the VM above only in that both touch actor records. It lives in the main executable and runs once per game tick for every active actor, laddering through a dispatch byte at actor+0x5A that selects which side-effects fire. It is also where the move VM gets stepped.

The tick reads three fixed fields: the record pointer at +0x4C, the dispatch byte at +0x5A, and the frame counter at +0x68 (seeded to 100 when an animation is registered). In the port it is engine-vm::actor_tick, a layered pipeline with a typed ActorPhysics struct; the keyframe arm is legaia_anm::AnimPlayer.

Per-arm physics

Every dispatch byte shares a common pre-update (timer drain, rotation accumulator) and late-update (envelope caps, optional move-VM kick, visibility cull, per-arm render); the arms differ in the middle.

1. Pre-updateEvery byte: drain the per-frame timer at +0x54 and the rotation accumulator at +0x22.
2. Arm0x02 / 0x06 fold acceleration into the shake envelopes; 0x05 runs the SFX emitter; 0x03 integrates the path velocity.
3. Default movementEvery byte except 0x03 and 0x05: add the angular rates, the trig-LUT world update, and step render scale and depth-cue by their rates.
4. Late-updateCap the envelopes; kick the move VM; cull; render the arm (line draws for 0x04, a triangle for 0x07, the keyframe pose for 0x06).

One pointer, several meanings (actor+0x4C)

The field at +0x4C is a multi-purpose pointer whose meaning depends on the spawn path that created the actor. A morph actor spawned from a VDF record keeps its spawn bytes there (read once, at spawn, to size and fill the vertex pool); a keyframe-animated actor keeps its pose-output buffer there, read by the renderer's per-bone interpolator. Retail relies on the actor classes never colliding. The window VM above never reads +0x4C, and nothing ticks a VDF body's bytes as opcodes.

A VDF body is [u32 record_count] followed by 12-byte records, each beginning [u32 group_idx] - there is no 16-byte header, only the 4-byte count. The port keeps the bytes in a retention slot (Actor::spawn_record); what consumes them is the per-actor vertex-pool allocator. One detail of that allocator is open: its first pass advances a 12-byte cursor while the second advances vertex_count * 8.

Field-overlay actor families

Two field-overlay (PROT 0897) pool-actor families hang off a parent actor's +0x90 back-link on the shared actor list the field VM walks. Neither is an opcode of the window VM.

• Scripted arc (FUN_801D25EC, reached only from field-VM op 0x43; its standalone spawn half is FUN_801D5780). Given a source actor, a landing point, an arc height and a frame count, it spawns an actor that hops along a quadratic Bézier: the X and Z midpoints are plain, but the Y control point is 2*apex - mid, which puts the curve through apex at its halfway point. The arc height is how far above the higher endpoint the hop peaks - a lob, not a straight tween. The per-frame step is 0x1000 / duration.
• Attached light (tick FUN_801E4470, field-VM op 0x34 sub-1). Each frame it adds the parent's world position to its own offset, screen-projects it, and draws an untextured semi-transparent light pool. Of the parent's state it reads only two bits of +0x10 (0x801E4490..0x801E44B8): 8 retires the light and 2, the visibility cull FUN_801D79E8, skips a frame. A zero render scale hides nothing, so a light can hang on an invisible marker: the light Noa follows in her first dream (dream P2[1]) rides a marker whose prologue zeroes its scale. Ported in engine-vm::field_actor_billboard and drawn on both play hosts.

At scene load, the re-hydration pass FUN_801D7518 walks each of the seven actor lists and allocates the runtime side-buffers a freshly loaded actor record does not carry - retiring three handler classes, rebuilding object tables, a VRAM staging buffer for anim-tick actors on dispatch byte 3, and a two-key interpolation table for those on byte 6. The field overlay's MAN-load reset hook FUN_801D9C3C reseeds its globals and find-or-spawns one actor.

How we know

Full write-up: docs/subsystems/actor-vm.md; program byte-spec on window scripts.

See also