acdream/docs/research/2026-07-03-session-handoff.md

Session handoff — R5-V1/V2 + world-loading fixes (2026-07-03, late)

Fresh session enters HERE. Worktree vigorous-joliot-f0c3ad, branch claude/vigorous-joliot-f0c3ad, tree CLEAN at 64f83d7c. Full suite 4007 green (+ the R5-V1 conformance tests + the #168 relocate test). Everything below is committed.

What landed this session

Commit	What
3d89446d	R5-V1 — PositionManager facade + StickyManager + ConstraintManager + the full TargetManager voyeur system ported to Core, fully tested, UNWIRED. Renamed the misnamed Physics.PositionManager combiner → RemoteMotionCombiner. Decomp/ACE/plan in docs/research/2026-07-03-r5-managers/.
2b5e8a67	R5-V1 docs: wiring handoff, register TS-35 correction, ISSUES #167 (ConstraintManager leash unarmed).
fffe90b3	R5-V2 — wired the TargetManager voyeur system per-entity via EntityPhysicsHost (App), retired the AP-79 poll adapter. Verified live — this is why remote creatures now chase the player.
315af02f	fix #168 — the pending-bucket trap (RelocateEntity couldn't recover an entity stranded in _pendingByLandblock). Invisible player / disappear-on-run-out.
9b06a9b8	fix #169 — the cold-spawn streaming "hole" (far login-spawn diffs against the half-loaded startup window; residence marked before loads land → hole). Now ForceReloadWindows on a far login-spawn.
7c5bc97c	ISSUES #168/#169 filed DONE.
64f83d7c	ISSUES #170 filed (creature chase/attack animation divergence).

The user's headline ask this session — "the world doesn't load / character disappears" — is FIXED and verified live (0xADAF loads, player transitions PENDING → DRAWSET PRESENT). Root-caused to two pre-existing streaming bugs; R5-V2 was verified line-by-line to be read-only w.r.t. position/cell/landblock/ streaming and RULED OUT as the cause. Durable lesson: feedback_streaming_residence_race.

NEXT — two ready work streams (Claude picks; both are teed up)

Option A — #170: remote creature chase+attack renders wrong vs retail

Well-scoped, user-confirmed via retail side-by-side (the oracle). A monster chasing+attacking the player glides, over-plays attacks, and shows uniform/wrong attack animations; retail (same local ACE) renders it correctly → the divergence is CLIENT-side. Motion trace (ACDREAM_DUMP_MOTION, guid 0x80000244): ACE sends mt-0 stance 0x3C → mt-6 chase spd 2.03 → a stream of mt-0 attacks 0x62/0x63/0x64 spd 0.97; acdream shows a MOTIONDONE pending=True loop. Decomposes into THREE sub-bugs (full detail in ISSUES #170):

1. Wrong/uniform attack anims → likely #159 (CombatAnimationPlanner uses 2013-decomp command numbering, not ACE/DRW — 0x10000062/63/64 misclassify). This one has a KNOWN fix path (renumber CombatAnimationMotionCommands to DatReaderWriter.Enums.MotionCommand values; parity test).
2. Over-frequency / stuck — the pending_motions queue completes+re-queues in a tight loop. R3/R4 animation-sequencer / MotionDone territory (grep the named decomp for how retail's CMotionInterp handles an attack UM stream arriving over an active moveto — attack one-shots should play over locomotion and RETURN to it, not wedge).
3. Glide — position moves (mt-6 + UP dead-reckon) but no locomotion legs play (attacks override) → smooth slide. AP-80 / #160 dead-reckon-vs-animation family. Entry points: MotionInterpreter/AnimationSequencer attack dispatch + pending_motions; CombatAnimationPlanner (#159); ServerControlledLocomotion. Start with #159 (bounded), then trace the pending-motions loop with the motion dump. Retail is the oracle — the user runs it side-by-side; ask for a frame-by-frame retail comparison, don't guess.

Option B — R5-V3: wire PositionManager sticky, retire TS-39, apply mt-0 flags

The paused R5 continuation. Full plan in docs/research/2026-07-03-r5-managers/r5-wiring-handoff.md (§V3). Bind MoveToManager.StickTo/Unstick → PositionManager (now that V2 gives each entity an EntityPhysicsHost, adding a PositionManager to it is the natural next step), integrate adjust_offset into the body tick, apply the UpdateMotion mt-0 flags (0x1 sticky-guid → stick_to_object, 0x2 → StandingLongJump). Retires TS-39. Then R5-V4 (MovementManager facade + #164 + head-stance dispatch).

Recommendation: #170 is more user-visible (they just watched it break) and is now well-scoped; R5-V3 is the "finish what we started" path. Either is fine — Claude's call per work-order autonomy. #170's part 1 (#159) is the smallest concrete win.

R5 arc status

• V1 (Core managers + tests) — DONE 3d89446d.
• V2 (voyeur wiring, retire AP-79) — DONE fffe90b3, verified live.
• V3 (sticky, retire TS-39, mt-0 flags) — PENDING. r5-wiring-handoff.md §V3.
• V4 (MovementManager facade + #164 + head-stance dispatch) — PENDING. §V4.
• Open R5-adjacent: #167 (ConstraintManager leash unarmed + 2 unknown x87 consts), TS-35 (stays open until the leash is armed), #164 (action-replay Autonomous bit).

Debug apparatus that proved decisive (reuse for #170)

• ACDREAM_PROBE_ENT=1 — EntityVanishProbe: [ent] APPEND → PENDING/LOADED, DRAWSET PRESENT/ABSENT, [dyn] player DRAWN/CULLED. Separates "not in draw set" from "present-but-culled." A one-line [lb] ADD in GpuWorldState.AddLandblock (added then stripped) exposed the streaming hole as a missing Y-band — re-add it if you chase another streaming gap.
• ACDREAM_DUMP_MOTION=1 — every inbound UM (guid, stance, cmd, speed) + the resulting SetCycle + [MOTIONDONE]. THE tool for #170 — it's how the attack-stream-over-chase was found.

Session gotchas (environment)

• The test character +Acdream (0x5000000A) is saved OUT in the wilderness (landblock ~0xADAF/0xAEAE, ~1 km SE of Holtburg), from an earlier run of the #168 disappear bug. It spawns there every login. With the #169 fix that now loads correctly (far login-spawn ForceReloadWindows), so it's testable — and there are Mite Scamps + a Mosswart Feeder right at the spawn (handy for #170). To get back to Holtburg, the user GM-teleports.
• Client lifecycle: the USER manages it. Launch with plain dotnet run --no-build in the background (never pre-close/kill). If a rebuild is locked by a running client (The file is locked by AcDream.App), ASK the user to close it — don't kill it.
• ACE stale session: a hard-closed or rapidly-relaunched client leaves ACE thinking the character is still in-world → session failed: CharacterList not received for ~3 min. Graceful close (window X / WM_CLOSE, exit 0) clears in ~5 s. Don't retry-spam; wait ~160 s if it's stuck. This session hit it once from rapid relaunches.
• PowerShell Tee-Object/Out-File write UTF-16 → the plain-text grep needs tr -d '\000' first (the launch logs read as UTF-16). Used throughout.

Pointers

• R5 decomp/plan: docs/research/2026-07-03-r5-managers/ (decomp per manager, ACE cross-ref, port plan, wiring handoff).
• ISSUES: #167 (constraint leash), #168/#169 (DONE this session), #170 (creature animation), #159 (combat command numbering), #160/#165/#166 (remote-motion).
• Memory: feedback_streaming_residence_race, and the R5 research index entry in MEMORY.md (animation-sequencer deep-dive line).
• Roadmap Phase R: R5-V1/V2 shipped; V3/V4 next.