Field locomotion

At a glance

Controller

One routine in the field overlay (PROT 0897), shared by towns, dungeons and the overworld walk mode. Not the tile-board puzzle mode that shares the overlay.

Collision grid

Per-scene, one byte per 128-unit tile: high nibble = four sub-cell wall bits, low nibble = floor tier. Streamed from the scene's .MAP file at load; scripts paint story-conditional changes on top.

Speed

480 units (3.75 tiles) per second walking, 720 running - counted in vsyncs, so the same on a busy frame as an empty one.

Height

A second controller after the walk: floor sampled from the grid's low nibble, or from per-tile ramp records; ledges trigger a scripted hop.

Engine

World::step_field_locomotion (engine-core); opt-in enhancements --edge-collision, --solid-npcs, precise movement (R).

Confidence

Confirmed - runtime write-watchpoints on the player position, wall-press captures, disassembly (how we know).

One frame of walking

• Direction. The remapped mask names axes: 0x1000 Z+, 0x4000 Z−, 0x2000 X+, 0x8000 X−. Diagonals are two axes resolved independently. The heading (+0x26) snaps to one of eight angles.
• Wall slide. When the pad's direction is blocked, three probes 62 units ahead (centre, ±33 lateral) sweep an offset table across the travel axis and add the slide direction the sweep's sign picks - so the player skids along walls instead of sticking. Pure diagonals and symmetric dead ends add nothing.
• Step loop. speed = ((base × mult) >> 12) × frame_scalar units are spent 2 at a time; each axis is committed only if its probe is clear. The loop plays no sound - walking and wall contact are silent.
• Animation follows motion. A committed step selects the walk (or run) clip; no step selects idle. The pad is never consulted for the clip.

How fast is a frame?

Retail runs two clocks: the vsync (60/s) and the game tick, one pass of the master frame driver. A scratchpad byte, the frame scalar, says how many vsyncs the last tick spanned (1..4, floored at 2 in field scenes and 3 on the overworld). Every duration and velocity inside the tick is multiplied by it, so a cadence change moves the sample rate, never the speed.

The port ticks once per vsync with the scalar at 1 - 60 steps of 8 instead of 30 of 16 - and both hosts drive that tick at 60 Hz from a wall clock. Reading a per-frame number in the wrong clock is where "the player moves 1.67× too fast" comes from.

The field buffer: where walls come from

Nothing in a town's script says "this is a wall". The scene loader streams the scene's .MAP file into a per-scene buffer; the collision grid is one region of it.

Collision: how a step is tested

Each 2-unit sub-step asks one function whether the tile ahead is a wall and whether an actor is in the way. The world position becomes a tile by (coord + bias) >> 6; the byte's high nibble is masked by the quadrant the point falls in. Three points along the player's leading edge are probed (48 units ahead, ±16 lateral), so the footprint is tested, not the centre. The Z bias is authored into the wall bits: the floor sampler reads the same bytes with plain indexing, so one byte's two nibbles live under two different mappings.

Pressing the action button runs a third probe: a radius-64 compass point in the facing sector against a ±72 NPC box; a hit posts the touch event (engaged flag, facing saved) and turns the player toward the NPC. Props fire the same event on contact, no button needed.

Height: two floor models

The walk controller only writes X and Z. After it commits, a second controller re-samples the floor under the new position and glides Y toward it; a third probes ahead along the last step and starts a scripted hop when the floor rises a ledge.

The kind-2 record replaces the bilinear branch, it is not a fast path on top of it. Rim Elm's shore ramps sit on sea-level nibbles and hold their whole elevation in kind-2 records; interpolating their nibbles walks the player under the drawn stairs. Engine: World::sample_field_floor_height carries both branches (--flat-y opts out).

Triggers: doors, beats and teleports

Crossing onto a new tile (tile = (world − 0x40) >> 7, compared against last frame's) looks the tile up in the trigger block. Scene entry marks the compare stale, so the arrival tile fires on the first tick.

A beat that should play once self-latches: its script sets the very flag its C1 gate lists, so it runs on the crossing that finds the flag clear and blocks itself afterwards. Rim Elm's dinner chain is the canonical example. The gate bitmap is the field VM's own story-flag bank, so a set is visible to the next record immediately.

Walking into a house

A town house is not a scene change: the interior is a sub-area of the same 128×128 grid parked in an unused corner, and the door repositions the player. Two door mechanisms exist and one house can use one of each.

Map doors are the larger class; a MAN-only census cannot see them. Vahn's house is the mixed case: script door in, map door out.

NPCs: facing and glide speed

Initial facing

The placement record has no facing byte. At spawn, the placement installer pre-runs the record's leading ops (a 0x24/0x25 marker up to the first 0x21), and two of them write the heading from the 8-direction LUT at SCUS 0x80073F04: the NPC move-to-tile op 4C 51 (operand +3, low nibble) and CAM_CFG's simple path. Town prologues route that leg through story-flag tests, so the fall-through branch is the fresh-game facing. Rim Elm's side-by-side villagers at tiles (29,22) / (30,22) derive indices 6 and 2 - they face each other.

Heading space: retail 0 = Z−, 0x400 = X−, 0x800 = Z+, 0xC00 = X+; the engine's convention is the same rotated a half-turn. After spawn, walking snaps the heading and the rotate ops ramp it; the last writer in the frame draws (motion VM).

Glide speed

An NPC's pace is not the player's walk step - the walk kernel never reads the speed multiplier. Both NPC walk kernels carry the base step in the walk op's own operands, on the ladder numerator >> (2 + bits) units per vsync.

Base steps run 32 / 16 / 8 / 4 / 2 / 1 for bits 0..5. There is no synthesised motion bytecode: the field VM parks the op's address on the actor and the walk kernel reads the record bytes in place each frame. Engine: placement_glide_speed decodes the placement's bound motion stream first, then its own yield ops, with a base-step-8 stand-in when neither decodes.

The port

• Faithful path. step_field_locomotion rotates the pad by the camera azimuth (quantised to 90°, which agrees with the 45° remap for every axis-aligned retail camera) and steps through the same per-axis 2-unit collision. Wall-press captures rest byte-exact.
• Opt-in fidelity. --edge-collision enables the three-probe leading edge; --solid-npcs enables the actor boxes (static props and moving NPCs). The slide resolver is ported standalone (resolve_field_slide), not yet in the live pad path.
• Enhancements. Precise movement (R, default off): continuous azimuth, true 45° diagonals at unit speed, analog stick angle, sub-step remainder carried across frames. Camera distance presets (T) never touch the simulation.
• Scene entry. .MAP resolved as the slot two below the scene's CDNAME block start (its 0x12000 footprint identifies it); the MAN's entry script runs on channel 0xFB; the MAN's encounter table is installed; input is locked while an opening-cutscene timeline drives the player.
• Spawn. Cold entry (New Game, Rim Elm) creates the player at (0xA40, 0, 0xA40), the centre of the camera window; warp entry lands on the saved door coordinates.

How we know

Full write-up, including the hop-arc controller, the door-swing clip binding and the scripted-scene actor programs: docs/subsystems/field-locomotion.md.

Details

See also