# Ambient traffic driver runtime contract, r347

This note consolidates the retail objects and live inputs that must be joined
before replacing the WebGL route follower with a traffic driver. It does not
add guessed vehicle behavior.

## Source-backed runtime chain

The streamed ambient class-2 descriptor enters the traffic manager and creates
an actor with a mode-3 `AICarController`. In the normal controller setup branch
that owns an `APsychoDriver`; controller configuration can attach
`AIActionDriveTrafficLane` (class record `0x00785820`, callback `0x004242d0`).
The class-2 initial lane-action attachment is conditional on the controller's
global-state/event path, so it is not proof that every actor starts in this
action. `AIActionObeyTrafficIntersections` and
`AIActionAvoidAvoidableAsTraffic` are distinct actions that can update route
phase or lane lookahead when their own runtime state selects them.

```text
RoutesFreeRoam 0x34121 route definitions
  + authored endpoint/intersection records 0x34122 / 0x34123
  + live per-actor route-candidate pointers and selected phase/cursor
  → context+0x31c FuturePoint queue, at most 20 XYZ samples
  → APsychoDriver 0x00416120 samples the queue into target +0x224/+0x228
  → driver turn/speed state and command outputs
  → actor+0x30 command source: throttle +0x20c, e-brake +0x210, brake +0x214
  → TrafficMover component at owner+0x34, update 0x00408820
```

The lane callback receives its actor through the AI context; actor `+0x2c`
points to route state, context `+0x308/+0x30c` carries phase/cursor state, and
context `+0x31c` contains the candidate-pointer array and FuturePoint queue.
The queue builder scans those per-actor candidates and applies selector,
phase-pair, weight, and interval checks. The queue is not a steering command.
`0x00416120` samples that queue using actor speed-like field `+0x430`, updates
the driver target and turn state, and writes the three named longitudinal
command slots through the recovered setter routines. The three filtered angle
channels and some of the command calls' virtual side effects remain unnamed.

At the mover callback, `ECX` is the mover; mover `+0x08` points to its owner,
owner `+0x30` is the command source, and owner `+0x34` holds the mover
component. Mover `+0x0c/+0x10/+0x14/+0x18` are its planar position, packed
heading, and speed-like scalar. `0x00408820` advances from command, owner, and
component state. This callback is not by itself a complete tire-force or
vehicle-physics model.

## Authored world context

Traffic geometry is authored by `RoutesFreeRoam*.bin` chunk `0x34121`; it is
not the event-race line chunk `0x34148`. `0x34122` records and walker
`0x005d8760` establish endpoint-compatible static matches, but the lane
action's next path is selected from the live actor candidate array. The
38 authored `0x34123` intersections exist in L4RA; their runtime candidate
banks are empty in the source records. Type-16 marker polygons feed vehicle
quotas, not route paths. The viewer's region-namespaced route union only adds
authored route fragments to the combined world; it cannot populate actor
candidate arrays or select a retail branch.

## Capture updates

[`tools/capture_nfsu2_traffic.gdb`](../tools/capture_nfsu2_traffic.gdb) now
follows the documented pointers at the lane-action callback, queue-to-driver
callback, and mover update. It records the host actor, route state, phase and
cursor, candidate/queue block, actor motion and forward vector, driver target
and state, command-source pointer/slots, and mover pose/scalar. The existing
intersection-action stop logs the selected candidate and active phase record.
The capture series must retain actor pointer and timer across stops; it should
cover a straight, a junction, and the same actor's next queue refresh. The
script is a capture aid only; it has not been run against live gameplay in
this turn.

## Exact remaining blocker

Static data does not include the ambient actor's candidate-pointer array,
candidate weights/interval values, selected cursor/phase, resolved live
FuturePoint XYZ queue, active action, driver filter history, actor speed and
command values, or mover/component inputs. Without those values, a branch
choice, lane change, yield/stop decision, cruise speed, or steering response
would be invented. The executable contains the relevant control flow, but the
inputs are instance-specific XP runtime state.

At the time of this inspection no XP/QEMU process was running, no GDB/VNC
listeners were present on `127.0.0.1:1234` or `127.0.0.1:5901`, and no
`/tmp/nfsu2-traffic-runtime.log` capture existed. Prior reverse-engineering
notes say the isolated XP copy stopped at activation/login before reaching the
game. Therefore no live values can be captured until that guest is running
free roam; the revised GDB script cannot replace this missing runtime sample.

For the routine-level evidence, see
[`traffic-lane-action.md`](traffic-lane-action.md),
[`traffic-intersections.md`](traffic-intersections.md),
[`traffic-car-avoidance-action.md`](traffic-car-avoidance-action.md),
[`traffic-mover.md`](traffic-mover.md), and
[`traffic-preview-driving-and-textures.md`](traffic-preview-driving-and-textures.md).