acdream/docs/research/2026-08-04-remote-landing-investigation.md

2026-08-04 — Remote landing investigation (Bug A / Bug B, route 4a live test)

Status: Report-only. No fix applied. Companion to docs/ISSUES.md #32 (the two symptoms below were both already named by that row's "lands on roof in falling animation, can't slide off" line) and to the ACDREAM_PROBE_REMOTE_LANDING probe added in PhysicsDiagnostics.cs.

Background

The user's live two-client route 4a test surfaced two PLAYER-remote defects:

• Bug A — a remote stays in the falling animation after landing, then visibly lands (the pose clears) only after a delay.
• Bug B — a remote jumping onto a house plants on the roof where retail slides off, then blips to the slid-down position.

Neither is a route 4a regression (44830a0e, 2026-08-04). The landing block in LiveEntityNetworkUpdateController.cs that both bugs touch is byte-identical to the pre-4a version — verified via git show 19d95094:src/AcDream.App/Physics/LiveEntityNetworkUpdateController.cs, which shows the same unconditional Body.TransientState |= Contact | OnWalkable at the same landing site before route 4a existed. Do not revert 44830a0e.

Bug B — root-caused, not yet fixed

See docs/ISSUES.md #32's 2026-08-04 addendum and docs/architecture/retail-divergence-register.md rows AD-10 and AP-87 for the full citation chain. Summary: the landing block force-sets OnWalkable unconditionally, where retail derives it from the contact plane (CPhysicsObj::SetPositionInternal @0x00515330, pseudo-C :283501-283509 — on_walkable = contact_plane.N.z >= floor_z). A steep roof is Contact but not on_walkable; forcing both suppresses the slide, and the body sits until AP-87's 4 m drift-snap backstop blips it to the server's already-slid position. A correct fix additionally depends on #173's remote collision-velocity reflect (shipped, its dedicated gate folded into the unrun Campaign P matrix scenario 8) and on AD-10's slope projection, which is terrain-only and cannot see building/EnvCell geometry at all.

Bug A — three hypotheses, no overlapping fix

The falling-pose-lingers symptom has three candidate root causes. Each points at a different code path with a non-overlapping fix, so guessing which one applies risks fixing the wrong thing (or "fixing" all three and losing track of which one mattered). The ACDREAM_PROBE_REMOTE_LANDING=1 probe (added 2026-08-04, src/AcDream.Core/Physics/PhysicsDiagnostics.cs: LogRemoteLanding/LogRemoteLandingGateNoOp) was built specifically to discriminate them from one live capture at both landing-detection sites: LiveEntityNetworkUpdateController.cs's UpdatePosition-driven landing block (site=controller) and RuntimeRemotePhysicsUpdater.cs's per-tick VectorUpdate landing branch (site=per-tick, ~:493-551).

H1 — Gravity state bit wiped mid-air, HitGround's gate silently no-ops (CONFIRMED mechanism, occurrence unconfirmed)

MotionInterpreter.HitGround() (MotionInterpreter.cs:2426, retail CMotionInterp::HitGround 0x00528ac0) starts with:

if (!PhysicsObj.State.HasFlag(PhysicsStateFlags.Gravity))
    return;

This mirrors retail's own gate (state & 0x400, decomp raw 305996-306014) — retail requires Gravity still set at landing, same as we do. If something clears the Gravity bit on a remote's body BEFORE its landing edge fires, HitGround() returns immediately: no RemoveLinkAnimations, no apply_current_movement re-dispatch, and the sequencer never receives the command that would swap Falling → the landing link → the grounded cycle. The falling pose then only clears once some LATER event forces a cycle (a subsequent UpdateMotion, or the generic per-tick funnel eventually reasserting a grounded stance by a different path) — matching the observed "delay."

Both known Gravity-clear sites in the codebase are the POST-HitGround "DR bookkeeping" clears (LiveEntityNetworkUpdateController.cs and RuntimeRemotePhysicsUpdater.cs, both guarded by IsCurrentStateAuthority/IsCurrentOwner version checks) — i.e. the intended clear happens AFTER HitGround, not before. No third site was found that clears Gravity early in this pass; if H1 is the live culprit, the probe should catch a case where an inbound authority-version race (a second UP superseding the landing packet, or the state-authority version check failing) caused the clear to land ahead of a re-entrant landing detection. Discriminator: gravitySet=false in the [remote-landing] line, paired with a [remote-landing-gate] NOOP line at the same site.

H2 — No DefaultSink bound at the landing edge (hypothesized, plausible)

HitGround()'s apply_current_movement dispatches through Motion.DefaultSink. The controller site only calls EnsureRemoteMotionBindings (which creates the sink) when _animatedEntities.TryGetValue(entity.Id, out var aeForLand) finds an entry AND aeForLand.Sequencer is not null (LiveEntityNetworkUpdateController.cs, right before the probe call added 2026-08-04). A remote whose LiveEntityAnimationState/Sequencer hasn't been created yet at the exact frame its landing UP arrives (freshly streamed-in, or a presentation race) would reach HitGround() with Gravity still set but no sink to drive — the re-apply computes correctly but has nowhere to write, so nothing visible changes until the sink is bound on a later frame and something else (the stale VU.land per-tick branch, or the next ordinary UpdateMotion) catches the pose up. Discriminator: gravitySet=true, hasDefaultSink=false in the [remote-landing] line.

H3 — HitGround dispatches correctly; the delay is downstream in animation-scheduler consumption (hypothesized, weakest evidence)

If both Gravity and the sink are fine at the landing edge, the failure (if it still reproduces) is not in the physics/motion-interpreter layer at all — HitGround() successfully queues the landing link, but the render-side animation scheduler (LiveEntityAnimationScheduler/ LiveEntityAnimationPresenter) doesn't drain and apply that queued transition for several frames, so the falling pose visibly persists even though the underlying MotionInterpreter state is already correct. Discriminator: gravitySet=true, hasDefaultSink=true, sequencer seqStyle/seqMotion at the landing edge necessarily still reads the pre-landing (Falling) values (the read happens immediately before HitGround runs, so this alone doesn't distinguish success from H3) — confirming/refuting H3 requires cross-referencing the SAME guid's subsequent [remote-landing]/VU.land/ACDREAM_DUMP_MOTION SetCycle lines over the next several frames to see whether the cycle swap is applied promptly or lags.

Decision table for tomorrow's capture

Run with ACDREAM_PROBE_REMOTE_LANDING=1 (pair with ACDREAM_DUMP_MOTION=1 for the existing VU.land/SetCycle lines) across a route 4a session that reproduces Bug A, then read the first [remote-landing] line for the affected guid at its landing edge:

gravitySet	hasDefaultSink	Falling pose clears next frame?	Implicates
false (+ [remote-landing-gate] NOOP)	—	—	H1 — fix where Gravity gets cleared/never-set before this landing edge
true	false	—	H2 — fix the sink-binding race (bind before the landing block runs, or defer the landing block until a sink exists)
true	true	No — lags several frames in the VU.land/SetCycle trail	H3 — fix the animation-scheduler consumption path, not physics
true	true	Yes	Landing worked correctly on this instance — Bug A did not reproduce here; re-run to catch the failing case

Whichever row fires, the fix belongs in a DIFFERENT file/method than the other two rows, so this table should be read for exactly one row per capture before deciding where to touch code — the whole point of the probe was to avoid fixing all three speculatively.