Per-actor motion VMs

At a glance

An actor is the engine's record for one on-screen entity (the player, an NPC, a prop, a camera target). Every frame the field actor tick visits every actor and, depending on flag bits in the actor's word at +0x10, hands it to one of two interpreters - both in the main executable.

Both are distinct from the window-widget VM and the move-table VM; the whole family is on the VM family table.

The driver: one tick, two arms

The height arm runs first, for any live, non-frozen actor, and picks one law for its Y from the flag word: write a stored override, hold, step toward the sampled floor with a per-frame clamp, or snap straight onto it. The dispatch arm then fires the routines in the figure - unless a global suppress bit skips it wholesale.

The first routine, the cutscene pump, is not a motion VM: it steps a field/event-VM script one authored beat per cutscene phase tick. Any motion it causes is issued by the field-VM ops inside the script.

The pursue VM

A motion script is a stream of small instructions - "walk one tile south", "rotate to this angle", "move toward your target" - each addressed at an actor:

+0  u8 op_byte         ; bits 0x7F = opcode, bit 0x80 = "select target"
+1  u8 target_id       ; only present if bit 0x80 set
+N  u8 operand[...]    ; opcode-specific

With the high bit set, the VM resolves a target actor first: 0xF8 means "the player", 0xFB follows the system actor list for a class match, and any other id scans the actor list matching the placement bind index at actor +0x50. The per-frame speed budget comes from the shared frame-time scratchpad; each step returns Yield (resume next tick) or Done.

How an actor's facing changes

Watch a villager walk and they only ever face one of eight directions, yet a scripted turn in a cutscene glides smoothly. That is two different laws, and which one an NPC gets is a property of the bytecode, not the situation.

• Snap (walking). Every frame a 0x47 leg moves, it reduces the step to its axis signs, maps them through the eight-entry compass LUT, and writes the heading outright. Entry i is i × 0x200, so a walking actor's facing is always a compass point - there is no walk-turn interpolation anywhere in retail. A cold-boot town sample confirms it: every on-field actor's heading is a multiple of 0x200.
• Ramp (the rotate ops). 0x38 and 0x4C interpolate over a frame budget: each tick, heading += arc × speed / remaining measured from the live heading, and the terminal frame snaps exactly onto the target so rounding can never leave the actor short.

Talk-time facing is not this VM

The NPC turning to face you on the action button is the easiest thing in the game to mis-attribute to FaceTarget - and it is not that op. It is a save / snap / restore triple in the per-actor dialog state machine: the heading is saved aside, one store snaps it toward the player in a single frame (no ramp), and the exit paths write the saved heading back. It runs only for moving-class actors - static props never turn.

The second motion VM: ambient life and story flags

This is the interpreter behind a town's ambient life - villagers wandering inside an invisible box, idle turns, waits, tile teleports during a scene change - and, less visibly, the story flags a scene flips as its choreography plays: op 0x07 sets a system story flag, op 0x08 clears one, written straight into the same flag bank the field VM uses.

Dispatch is a 32-entry jump table indexed by op - 1; grouped by instruction width:

The disc carrier is MAN tail-section 1 - a record chain in the scene's script-and-data bundle that binds each motion stream to a placed actor at scene entry. This is the only disc source of this bytecode. Parser: legaia_asset::man_motion.

Three behaviours worth knowing before reading the deep dive:

• Walking uses an axis-bitmask table sitting sixteen bytes past the compass LUT - every walk op reduces its heading index through it, which is why diagonal steps move both axes by the same per-tick amount.
• Walk ops collide with the player only - not the walkability grid, not other NPCs.
• The ambient facing ops have no shortest-arc override, so an authored idle turn can deliberately take the long way round.
• Most ops do not end the frame. The interpreter loops until an arm sets its did-work register, so a stream can raise a story flag, swap a model and start three tweens between two frames. Only the walks, the waits, the facing ramps' stepping ticks and the bit-wait ever stop it - and the bit-wait stops it even on the frame it retires.
• Op 0x12 waits for its bit to change, not to be set: the first tick seeds the wait from the bit's current value and the op then waits for the opposite state.

The port

• engine-vm::motion_vm ports all six pursue opcodes; the shared facing law lives in one LUT module so spawn-time and runtime facings cannot drift apart. A per-step yaw_written signal keeps an idle leg from clobbering a heading posed by another writer (the interact bearing).
• Two deliberate departures: LUT indices 8..=15 are no-ops rather than reproducing retail's overread into adjacent executable data, and an unrecognised FaceTarget sub-mode terminates the leg instead of yielding forever like retail's inert arm.
• World::tick_field_npc_motions drives MAN-placed NPCs through the MoveTowardTarget step, one step per tick, moving the collision and interact boxes with them. Three start paths feed it: autonomous patrol routes (on by default in play-window and the browser play page; play-window --no-live-npcs turns them off, paused during dialogue), interaction-prologue walks, and the widget-VM glide.
• The camera consumes the same machinery: field-VM op-0x45 events for high-level state, plus optional motion-VM scripts for cinematic paths (Camera::tick_script). The default mode follows a target actor at a configured distance and height - the retail "follow the player" shape.
• NPC pacing is decoded, not guessed: each placement's glide speed comes from its real walk-kernel step operands (man_field_scripts::placement_glide_speed), falling back to the facing-nibble heuristic only when a placement has no walk-kernel op at all - see field locomotion.

How we know

Full write-up: docs/subsystems/motion-vm.md.

See also