Files
Neutron/docs/analysis/patrol.md
T

261 lines
15 KiB
Markdown

# Original patrol and Goddard lab route
Static evidence from the immutable `Original/Neutron.exe`, `OMT2.dll` and
`gam/level1b.gam`, investigated 2026-10-24. Addresses below are preferred-base VAs;
the executable text file offsets are VA minus `0x400000`. No successful original
runtime comparison verifies the resulting motion. The follow-up at the end records
the bounded runtime AI implementation and its separate test/physics limits.
## Relevant dispatch and fields
Goddard's interface pointer is complete object plus `0xC0`. His interface vtable
is `0x49F480`, complete-object vtable `0x49F920`. His update `0x41DEE0` reaches
the general AI update `0x408000` at `0x41E520` for the ordinary patrol state,
after clearing interface `+0x8A8` (complete `+0x968`, animation override).
|Complete offset|Interface offset|Meaning/evidence|
|---|---|---|
|`0x6C4`|`0x604`|Movement speed, float; AI trigger integer AISpeed converted to float|
|`0x6C8`|`0x608`|Current AI state; `3` is patrol, `1` is waiting, `7` is timed waypoint wait|
|`0x6CC`|`0x60C`|Previous AI state, assigned by setter `0x4089B0`|
|`0x6E4..6EC`|`0x624..62C`|Destination minus current root position|
|`0x6F4`|`0x634`|Within arrival distance flag|
|`0x6FC`|`0x63C`|Exact square-root 3D destination distance|
|`0x708`|`0x648`|Initial PatrolPoint tag|
|`0x820`|`0x760`|Patrol/run animation alias|
|`0x870`|`0x7B0`|Waiting animation alias|
|`0x8C0`|`0x800`|Current waypoint interface pointer, initially null|
|`0x8C8`|`0x808`|Previous waypoint pointer|
|`0x8D0/8D4/8D8`|`0x810/814/818`|Euler smoothing factors X/Y/Z|
|`0x8E8..8F0`|`0x828..830`|Current destination root position|
|`0x90C`|`0x84C`|Timed waypoint wait remaining seconds|
|`0x944`|`0x884`|Arrival threshold, default `110.0f` at `0x407D9A`|
|`0x948`|`0x888`|Alternate movement mode flag, default zero; nonzero uses facing vector and threshold440|
|`0x968`|`0x8A8`|Suppress automatic animation selection while nonzero|
The normal lab Goddard path uses default arrival threshold110 and mode flag0;
the inspected Goddard constructor does not replace those defaults. His Euler
smoothing factors are explicitly overridden to `(0.3,3.2,0.3)` at
`0x41C8DB..0x41C90C`.
## State3 movement, arrival and update order
The general AI state dispatch table at `0x408980` maps state3 to `0x408518`.
Before that dispatch, `0x408000` calls animated/base update `0x40E050(dt)`.
That calls shared physical integration `0x462520`, which reaches game physics
through slot `0x130`, and then `0x458930 -> 0x473240`. The latter calls the
AI interface slot `0x3D8 -> 0x4096E0` for orientation smoothing. Thus previous
velocity and previous desired Euler angles are consumed before this update
computes the next patrol velocity and angle target. A port that immediately
integrates the newly selected velocity differs by one simulation tick.
Patrol performs the following operations in source order:
1. Complete slot `0x12C -> 0x408C90`: when current waypoint pointer is null,
resolve PatrolPoint tag (`complete+0x708`) with first case-insensitive tag
lookup `0x474070`. If still missing, set state1 and clear horizontal velocity,
preserving its Y component. Otherwise call complete slot `0x130`.
2. Slot `0x130 -> 0x408D40`: normally copy waypoint root to destination and compute
`delta = waypoint.Position - actor.Position`. Store full 3D Euclidean distance
(`sqrt(dx*dx + dy*dy + dz*dz)`) at complete `+0x6FC`. A separate movement
special flag can retain a previous destination; its nonordinary behavior is
outside this lab route.
3. Ensure the patrol/run animation is active (`0x408549..0x40856A`), looping,
unless animation override is nonzero.
4. Unless an independent temporary-target timer is positive, complete slot
`0x134 -> 0x408E40` computes `velocity = delta / quick_magnitude(delta) * speed`.
State3 has multiplier1. Full XYZ velocity is assigned, rather than retaining
old vertical velocity. If already marked arrived, assign zero XYZ instead.
5. Complete slot `0x128 -> 0x408BC0` compares exact stored distance with threshold.
**Strictly less than110** sets arrived true and calls an arrival virtual
method. Distance greater than110 clears an existing arrival flag for state3;
exactly110 leaves it unchanged. The arrival method is `0x41E580 -> 0x409890`
for Goddard and does nothing in state3 (its special branch is state10).
6. If arrived and the current pointer is a PAT, process wait/next below.
7. At `0x408958..0x40896C`, complete slot `0x138 -> 0x409140(dt)` computes new
destination Euler angles from the final destination-minus-root vector.
The velocity assignment therefore precedes the arrival comparison: on the first
update entering the arrival radius, it may retain a nonzero newly selected
velocity for the next physical step while already selecting the next waypoint.
There is no normal exact-position snapping, remaining-distance speed clamp, or
multiple-waypoint traversal loop in this branch.
When a new waypoint is selected, arrival is not immediately cleared or distance
recomputed. On the next update the old arrived flag can therefore select zero
velocity/WAG before the newly computed distance clears that flag; subsequent
update selects RUN and movement again. Avoid replacing this order with a
smooth continuous multi-segment walker while describing it as recovered.
`quick_magnitude` is the OMT export at `OMT2.dll:0x1001FF70`, imported through
`0x48D104`. It uses absolute components, largest-component selection and lookup
tables rather than a direct sqrt. The follow-up `OriginalBodySupport.QuickMagnitude`
now reconstructs those tables from their recovered initializer constants; modern
trig versus original x87 table equality remains unverified. Arrival itself uses
sqrt, not this helper. Zero delta is handled defensively by the port instead of
depending on the original invalid float-to-integer conversion behavior.
## WaitTime and NextPatrolPoint
PAT property loader `0x434DE0` operates on the PAT interface (complete plus
`0xC8`):
|Property|PAT interface offset|PAT complete offset|
|---|---|---|
|CallObjectTag|`0x520`|`0x5E8`|
|ActivateAnim|`0x584`|`0x64C`|
|SoundDatabase|`0x64C`|`0x714`|
|SoundIndex|`0x714`|`0x7DC`|
|NextPatrolPoint|`0x5E8`|`0x6B0`|
|WaitAnim|`0x6B0`|`0x778`|
|WaitTime|`0x718`|`0x7E0`|
At `0x40861F..0x408698`, **WaitTime>0** enters state7, starts PAT.WaitAnim loop1
unless animation override is active, copies WaitTime to actor wait timer and
sets XYZ velocity zero. State7 `0x408370..0x408414` subtracts dt only while the
timer was positive at entry; if the result is **less than or equal to zero** it
restores the previous state, clears arrival and resolves this waypoint's
NextPatrolPoint. It does not consume leftover time to move through the next
segment in the same update. The exact-zero case corrects an earlier report
reading: `0x40838C` uses `test ah,0x41 / jne` to skip an initially nonpositive
timer, whereas `0x4083B0` uses `test ah,0x41 / je` to keep waiting only after a
positive result. On equality x87 C3 makes `ah&0x41=0x40`, so expiry occurs.
The comparison constant at `0x48D914` is float0. A timer already zero at entry
remains in state7. The timed-wait next-point lookup at `0x408406` does not
interpret missing `WAIT`/`SCAN` names specially; the immediate branch below does.
For WaitTime<=0, `0x40869D..0x408757` immediately saves the current pointer as
previous and resolves NextPatrolPoint. If the lookup fails, the literal `WAIT`
sets state1 and literal `SCAN` sets state6. A nonexistent ordinary name, including
`none`, compares unequal to both special literals and leaves state3 until the
next `0x408C90` lookup of initial PatrolPoint; this detail is easy to miss.
`none` is not equal to `WAIT`. Consequently this path can restart a route on the
next update instead of necessarily becoming idle. Any port choosing to stop at
`NextPatrolPoint=none` is making a terminal-route policy approximation, not an
exact translation of these instructions. For the lab cutscene, a later authored
GODDARDDIS action interrupts patrol and explicitly sets state1/SIT/phone2.
CallObjectTag/ActivateAnim/SoundIndex are serialized and loaded, but their generic
execution is **not** recovered from this normal Goddard branch. PAT touch handler
`0x434EA0` calls base touch then only logs when a C3DAI is in state2. All lab PATs
have CallObjectTag=`none`; no invented callback is necessary for Goddard's route.
## Goddard animation and authored route
Goddard constructor (`0x41C9A3..0x41CA79`) sets aliases:
complete `+0x7F8=WAG`, `+0x820=RUN`, `+0x848=FLY`, `+0x870=WAG`,
`+0x7D0=WAG`, `+0x898=RUN`. Literal RUN is at `0x4ECA64`; WAG at `0x4ECA68`.
State3 update therefore replaces the trigger's AIAnim=`walk` with RUN on the
next update, without requiring an invented WALK-to-RUN asset alias. State1
setter starts WAG unless animation override is nonzero; state1's steady update
does not itself force a new alias. A trigger can therefore preserve an explicit
SIT in state1 when its animation override suppresses the setter default.
|Tag / GAM offset|Position|Next / wait|
|---|---|---|
|gstart / `0x960A`|`(4801.444336,38.160038,669.824158)`|none, wait0, WaitAnim sit|
|GODDARDPAT1 / `0x3D5F`|`(5011.098633,16.988688,716.637146)`|GODDARDPAT2, wait0|
|GODDARDPAT2 / `0x3F69`|`(5244.313477,26.268572,-249.976944)`|none, wait-1, WaitAnim sit|
GOGODDARD AIT at GAM`0x3918` sets target C3DGODDARD, AIState3, AISpeed260,
AIPatrol GODDARDPAT1 and AIAnim walk, then immediately begins WATCHGODDARD.
SITGODDARD previously positions Goddard at gstart with yaw180. GODDARDDIS at
GAM`0x48D4` later interrupts by setting AIState1, AIAnim sit, AINewPos phone2,
AINewRotY10. None of these AI triggers waits for patrol completion.
## Heading smoothing and remaining limits
Desired orientation `0x409140` calls OMT vector.angles through `0x48D108`
(`OMT2.dll:0x1001FDA0`), scales the returned integer angular units by
`360/16384 = 0.02197265625f` (`0x48E5B4`) and writes destination Euler angles
through `0x472660`. In the ordinary flat yaw case, the equivalent heading is
`atan2(-delta.X, delta.Z)` in degrees. This mathematical atan2 equivalence is an
approximation to the original table quantization.
The following frame's `0x4096E0` wraps each destination-minus-current Euler delta
at180 degrees, then adds `wrappedDelta * axisFactor * dt`; Goddard Y factor3.2
is recovered above. Factor clamping is absent in this routine. The routine first
checks enabled/dirty flags; collision/arrival conditions can skip updating desired
heading. Full pitch/table equality and actor-floor contact matching remain open.
Shared world gravity/collision also applies during the base update; replacing
the full body solver by direct waypoint interpolation or floor clamping must be
recorded as a port approximation. General stuck recovery `0x40A250`, temporary
targets and AI states other than the normal state3/7 path are not covered here.
Read-only verification checked 17 executable dispatcher/vtable/string and GAM
route assertions: state3 dispatch, patrol virtual targets, WAIT/SCAN/RUN/WAG
literals, both route links, speed260, final WaitTime-1, and absence of actors
named none/WAIT/SCAN. This establishes consistency of the static evidence, not
runtime or visual fidelity. No original files or C# source were changed.
## Runtime follow-up
`Game/ActorPatrol.cs` implements ordinary states1/3/7 plus the common base phase
for state9. Carl state6 also receives that phase; its general FOV/visibility
sensor409CC0 remains unimplemented, while SceneInteractions handles source contact
dispatch. Other states are outside the supported subset. It exchanges root position/velocity
through the injected `PatrolBodyState -> PatrolBodyState` body step. Its own
algorithm does not invent a body radius, support factor, collision solver or
floor clamp. It consumes the prior velocity, smooths the prior yaw target by3.2,
selects RUN, computes the next fullXYZ velocity, compares exact distance and then
processes one waypoint/wait transition. The recovered table magnitude helper is
the default normalizer; a separate injected metric remains available for tests.
Follow-up disassembly also verifies ordinary state1 zeroes XYZ at`0x40835D`
**after** the base physics update. The missing-initial-point transition preserves
Y at`0x408D1E..26`; its enclosing state3 branch still passes through RUN selection
after the resolver returns. States1/6/7 skip new destination-angle selection at
`0x409186..19B`. The port keeps their authored animations rather than forcing
WAG every idle tick. The subsequent TELGODDARD2 camera explicitly requests TALK
after GODDARDDIS requests SIT;40DF18..22 proves this unregistered TALK request
leaves the selected SIT clip/name unchanged. SceneActorVisuals retains that no-op.
The runtime's authored teleport synchronization resets its velocity/route cache
and preserves the authored yaw/animation. This is an explicit port reset policy;
full original teleport bookkeeping is not recovered. Camera-only animation
events do not reset the route. Heading currently changes yaw only using atan2;
full pitch, original angle quantization, dirty flags, temporary targets and stuck
recovery are not implemented here. Physics and original runtime comparison remain
separate integration/validation work.
Verification from `GamePort`:
```sh
source scripts/env.sh
dotnet run --project tests/GamePort.PatrolTests/GamePort.PatrolTests.csproj
```
All9 deterministic groups pass: prior velocity/yaw phase; velocity-before-arrival
and waypoint pause; strict110/equality behavior; wait expiry at exact zero and
discarded remainder; WAIT/SCAN/none and lookup precedence; missing initial Y
preservation and fullXYZ velocity; authored teleport/cache handling; injectable
normalization separate from sqrt arrival; and the actual GAM Goddard route plus
GODDARDDIS interruption. Free-body/held-body fixtures validate AI ordering, not
original body physics, rendering or original gameplay fidelity.
## Carl profile and live integration
Carl constructor413BCB sets speed200. It installs WALK at complete820/898 through
413BFC..1D (literal4ECA54), STOP at7F8/870 through413C22..43 (literal4ED040).
Its yaw smoothing factor remains inherited3.0 from407CF8; Goddard overrides3.2.
The shared state3/7 code is therefore reused with class-specific aliases/factors.
State9 dispatch table408980 jumps directly to408911, adding no new velocity or
animation command. State6 calls the still-unported sensor409CC0 before this
common finisher. No arbitrary proximity-to-dialogue-end task rule was added.
Live runtime bodies now use recovered Goddard130/.3 and Carl100/.75 root support,
source-winding floor queries and the exact source normal.Y<.7 wall-grid mask.
The wall response is still the port's swept sphere, not the original47BD80 solver.
Visuals use those actor roots without an additional sole-based correction.
The remaining raw-sole/root clearance difference is documented in collision notes.
Primary added a tenth test group for Carl's profile, speed, yaw factor and state9.
2026-11-04 Scooter follow-up: the opt-in VR05/LEV1 Goddard follow bridge now
applies recovered4096E0 pitch/yaw/roll smoothing toward its ordinary supported
follow target, rather than preserving dismount tilt indefinitely. Cleanup keeps
the full source Euler handoff. Nine active copied-original angle cases plus two
gate observations and actual tilted-dismount tests support this correction;
general patrol/Carl and airborne target selection retain their earlier limits.
See [scooter-dismount-leveling](../gameplay/scooter-dismount-leveling.md).