acdream/docs/research/2026-04-28-remote-moveto-pseudocode.md

Phase L.1c — Remote MoveTo body-driver pseudocode

Date: 2026-04-28 Goal: Port the minimum viable subset of retail MoveToManager so the body position of server-controlled chasing creatures (movementType 6/7) tracks the server-supplied destination smoothly, instead of freezing at zero velocity between sparse UpdatePosition snaps.

Problem (root cause from systematic-debugging Phase 1)

The 882a07c stabilizer holds rm.Body.Velocity = 0 while ServerMoveToActive is true, on the principle "do not let apply_current_movement free-run with incomplete MoveTo state." The state IS incomplete: our parser at UpdateMotion.cs:280-290 keeps only speed/runRate/flags from the 7-DWORD MovementParameters block and the runRate trailer, discarding Origin (destination), targetGuid (type 6 only), distance_to_object, min_distance, fail_distance, walk_run_threshhold, and desired_heading.

Symptoms (live log + user observation 2026-04-28):

• Disappearing: body frozen at Velocity=0 while RunForward animation plays; next UpdatePosition teleports body to actual server pose. If the teleport target is outside the visible window, observer sees disappear/reappear.
• Jitter: when a stale UP-derived velocity exists, body extrapolates along the OLD heading; meanwhile the server is steering the creature on a curve. Each new UP snap-corrects → visible stutter.

The fresh MoveTo packet stream (~1 Hz, seq 0x01FE→0x0204 in the live log) IS sending fresh target positions and headings each tick — we're throwing them away.

Retail behavior (named decomp + ACE port)

Sources:

• docs/research/named-retail/acclient_2013_pseudo_c.txt — citations below
• docs/research/named-retail/acclient.h — struct definitions
• references/ACE/Source/ACE.Server/Physics/Animation/MoveToManager.cs
• references/ACE/Source/ACE.Server/Physics/Animation/MovementParameters.cs

Wire layout (MovementParameters::UnPackNet @ 0x0052ac50, type 6/7)

[uint targetGuid]              // type 6 only (MoveToObject)
Origin: uint cellId            //   then 3 floats local x/y/z
        float x, y, z          //   destination position
MovementParameters (28 bytes, exact retail order):
    uint  flags                // bitfield (see below)
    float distance_to_object   // arrival far-bound (ACE default 0.6)
    float min_distance         // arrival near-bound
    float fail_distance        // abort when starting→current >= this
    float speed                // base speed multiplier
    float walk_run_threshhold  // (sic, two h's) — wire default 15.0
    float desired_heading      // final orientation (radians or degrees)
float runRate                   // CMotionInterp::my_run_rate copy

MovementParameters bit-flags (declaration order, acclient.h:31423-31443)

Bit	Mask	Name	Meaning
0	0x00001	can_walk	gait permission
1	0x00002	can_run	gait permission (we already use this for MoveToCanRun)
2	0x00004	can_sidestep	enables strafe path
3	0x00008	can_walk_backwards	gait permission
4	0x00010	can_charge	force HoldKey_Run
5	0x00020	fail_walk	fail if only walk possible
6	0x00040	use_final_heading	append final TurnToHeading after arrival
7	0x00080	sticky	MoveToObject only — StickTo on completion
8	0x00100	move_away	flee target
9	0x00200	move_towards	chase target (chase creatures set this)
10	0x00400	use_spheres	use cylinder distance vs straight-line
11	0x00800	set_hold_key	apply HoldKeyToApply
...	...	...	(autonomous, modify_*_state, cancel_moveto, stop_completely, disable_jump)

MoveToManager::HandleMoveToPosition (per-tick, 0x00529d80 lines 307187-307440)

if physics.motions_pending:
    cancel any aux turn cmd (let the queued motion complete)
else:
    targetWorld = currentTargetPosition  // last server-supplied destination
    desiredHeading = atan2(targetWorld - body.position) + get_desired_heading(currentCmd)
    headingDelta  = normalize(desiredHeading - body.heading)
    if |headingDelta| <= 20°:                      // retail tolerance
        // ACE adds set_heading(target, true) here (server-tic-rate fudge)
        cancel any aux turn cmd
    else:
        edi = (headingDelta < 180°) ? TurnLeft : TurnRight
        if edi != auxCommand:
            _DoMotion(edi)                         // -> CMotionInterp
            auxCommand = edi
dist = GetCurrentDistance()
if CheckProgressMade(dist):
    if !movingAway and dist <= min_distance:        // arrived
        popHeadNode(); _StopMotion(currentCmd); _StopMotion(auxCommand); BeginNextNode()
    if movingAway and dist >= distance_to_object:
        popHeadNode(); ...
    if !movingAway and Position.distance(starting, current) >= fail_distance:
        CancelMoveTo(0x3d)                          // YouChargedTooFar

Key insight: MoveToManager does NOT touch the body directly

Every motion start/stop is dispatched through CMotionInterp::DoInterpretedMotion (via _DoMotion/_StopMotion). The body's actual position evolves via the ordinary physics tick (PhysicsBody::UpdatePhysicsInternal). MoveToManager is purely a planner sitting above CMotionInterp, deciding which command (and which auxiliary turn) the body should be running at any given tick.

Acdream port — minimum viable subset

The server re-emits MoveTo packets ~1 Hz with fresh destinations, so we can skip:

• MoveToObject_Internal target-tracking (HandleUpdateTarget) — server does it
• Sticky / PositionManager::StickTo
• CheckProgressMade stall detection — server cancels the move
• fail_distance / WeenieError.YouChargedTooFar — server-side concern
• WeenieObj::OnMoveComplete callback
• Pending-actions queue (only ever 1-2 nodes; we treat each MoveTo packet as a fresh single-step plan)

We DO need:

1. Parser: extract the discarded fields into ServerMotionState.
2. Per-tick steer: compute heading-to-destination, turn body orientation toward it (snap when within ±20° per ACE's tic-rate fudge), then allow apply_current_movement to run — which sets Body.Velocity from the active RunForward cycle, oriented along the now-correct heading.
3. Arrival: when dist <= distance_to_object, switch animation to Ready and clear ServerMoveToActive. Server's next MoveTo packet will resume.

Pseudocode — acdream port

Parser change (UpdateMotion.TryParseMoveToPayload)

TryParseMoveToPayload(body, pos, mt, out parsed):
    if mt == 6:
        if rem < 4: return false
        parsed.TargetGuid = ReadU32; pos += 4

    if rem < 16: return false
    parsed.OriginCellId = ReadU32; pos += 4
    parsed.OriginX = ReadF32; pos += 4
    parsed.OriginY = ReadF32; pos += 4
    parsed.OriginZ = ReadF32; pos += 4

    if rem < 28: return false
    parsed.Flags             = ReadU32; pos += 4
    parsed.DistanceToObject  = ReadF32; pos += 4
    parsed.MinDistance       = ReadF32; pos += 4
    parsed.FailDistance      = ReadF32; pos += 4
    parsed.Speed             = ReadF32; pos += 4
    parsed.WalkRunThreshold  = ReadF32; pos += 4
    parsed.DesiredHeading    = ReadF32; pos += 4

    if rem < 4: return false
    parsed.RunRate = ReadF32
    return true

Per-tick driver (new RemoteMoveToDriver in AcDream.Core.Physics)

DriveOneTick(rm, dt):
    if not rm.HasMoveToDestination: return ApplyDefault

    targetWorld = rm.MoveToDestinationWorld   // pre-converted at packet time
    bodyPos     = rm.Body.Position

    // Distance check first — arrival short-circuits before any heading work
    dist = horizontalDistance(targetWorld, bodyPos)
    if dist <= rm.MoveToMinDistance + 0.05 (epsilon for float wobble):
        rm.HasMoveToDestination = false
        // animation cycle moves to Ready via the existing
        // ApplyServerControlledVelocityCycle path on next zero-velocity sample
        rm.Body.Velocity = Vector3.Zero
        return Arrived

    // Heading compute (XY plane; Z untouched — server owns Z)
    deltaXY = (targetWorld.XY - bodyPos.XY).Normalized
    desiredHeading = atan2(deltaXY)        // radians
    currentHeading = QuaternionToYaw(rm.Body.Orientation)
    headingDelta = wrapPi(desiredHeading - currentHeading)

    // Snap orientation toward target — match ACE's set_heading(target, true)
    // when within tolerance, otherwise rotate at retail-faithful turn rate.
    const float tolerance = 20° (in radians)
    if |headingDelta| <= tolerance:
        rm.Body.Orientation = QuaternionFromYaw(desiredHeading)
    else:
        // retail TurnSpeed default ≈ π/2 rad/s for monsters; clamp by dt
        float maxStep = TurnRateRadPerSec * dt
        float step = clamp(headingDelta, -maxStep, +maxStep)
        rm.Body.Orientation = QuaternionFromYaw(currentHeading + step)

    // Allow apply_current_movement to set Velocity from RunForward cycle.
    // The cycle was already seeded by PlanMoveToStart at packet receipt
    // and is being played by the AnimationSequencer. CMotionInterp's
    // apply_current_movement reads InterpretedState.ForwardCommand and
    // sets Body.Velocity = (forward axis of orientation) * RunAnimSpeed * speedMod.
    return DriveActive   // caller now invokes apply_current_movement

Integration in GameWindow.OnUpdateMotion (movementType 6/7 branch)

on receipt of MoveTo packet:
    // existing code already seeds the animation cycle via PlanMoveToStart
    // NEW: store world-converted destination + thresholds on rmState
    lbX = (originCellId >> 24) & 0xFF
    lbY = (originCellId >> 16) & 0xFF
    origin = ((lbX - liveCenterX) * 192, (lbY - liveCenterY) * 192, 0)
    rmState.MoveToDestinationWorld = (originX, originY, originZ) + origin
    rmState.MoveToMinDistance      = parsed.MinDistance
    rmState.MoveToDistanceToObject = parsed.DistanceToObject
    rmState.HasMoveToDestination   = true
    // ServerMoveToActive remains set; existing

Integration in per-tick remote update (GameWindow.cs ~line 5045)

// Replace the current Velocity = Zero hold with:
else if (!IsPlayerGuid(serverGuid) && rm.ServerMoveToActive && rm.HasMoveToDestination)
{
    var driveResult = RemoteMoveToDriver.DriveOneTick(rm, dt);
    if driveResult == Arrived:
        // signal cycle update to Ready via existing path
        ApplyServerControlledVelocityCycle(serverGuid, ae, rm, Vector3.Zero);
    else:
        rm.Body.TransientState |= Contact | OnWalkable | Active
        rm.Motion.apply_current_movement(cancelMoveTo: false, allowJump: false);
}
else if (!IsPlayerGuid(serverGuid) && rm.ServerMoveToActive)
{
    // No destination yet (very early frame, packet hasn't fully landed)
    rm.Body.Velocity = Vector3.Zero;
}
else
{
    rm.Motion.apply_current_movement(cancelMoveTo: false, allowJump: false);
}

Conformance test cases

1. Parser round-trip — type 7 (MoveToPosition)

   • Synthesize a 68-byte body with known origin + 7 params + runRate.
   • Assert all 9 new fields decode correctly.

2. Parser round-trip — type 6 (MoveToObject)

   • Synthesize a 72-byte body with target guid + origin + params + runRate.
   • Assert TargetGuid populated and shifts subsequent fields by 4 bytes.

3. DriveOneTick — heading snap within tolerance

   • body at (0,0,0) facing east, destination (10,0,0).
   • DesiredHeading=0; current=0; |delta|=0 ≤ 20° → snap.
   • assert orientation unchanged (already correct).

4. DriveOneTick — heading turn beyond tolerance

   • body at (0,0,0) facing east, destination (0,10,0).
   • desiredHeading=π/2; current=0; |delta|=π/2 > 20°.
   • dt=0.1s, TurnRate=π/2 → step = π/4 toward target.
   • assert orientation rotated by π/4 (not full snap).

5. DriveOneTick — arrival

   • body at (0,0,0), destination (0.4,0,0), MinDistance=0.6.
   • assert HasMoveToDestination cleared and Velocity zeroed.

6. Bit-flag mapping (already partially tested via MoveToCanRun)

   • assert flag 0x00200 (move_towards) is detected as MoveTowards=true.

Out of scope (future Phase L.1d if needed)

• Sticky / StickTo for MoveToObject completion
• use_final_heading (post-arrival turn-to-heading)
• fail_distance early-cancel (server already does this; we just don't flag it)
• CheckProgressMade stall detector
• Strafe / move_away / move_towards-and-away combo (towards_and_away helper)
• Sphere-cylinder distance (use_spheres bit)
• MoveToObject target-guid resolution — currently we only honor the Origin, which works because the server re-emits with refreshed Origin each tick. If the target is moving fast and the server's emit cadence falls behind, we'd see lag; a future enhancement is to look up the target entity by guid and use its current world position when fresher than Origin.