acdream/docs/research/2026-05-13-b4c-shipped-handoff.md

Phase B.4c shipped — handoff (visual-verified 2026-05-13)

Date: 2026-05-13. Branch: claude/phase-b4c-door-anim (ready to merge to main; do NOT merge here — controller handles that after code review). Predecessors:

• docs/research/2026-05-13-b4b-shipped-handoff.md — B.4b shipped handoff; interaction was the upstream dependency (Use message, SetState handling, collision exemption, double-click detection — all shipped there).
• docs/superpowers/specs/2026-05-13-phase-b4c-design.md — B.4c design spec.
• docs/superpowers/plans/2026-05-13-phase-b4c-plan.md — B.4c implementation plan (4 tasks).

---

TL;DR

Phase B.4c shipped end-to-end and is visual-verified 2026-05-13. The M1 demo target "open the inn door" now has full visual feedback — the door swings open when double-clicked and swings closed again when ACE toggles it back. 4 implementation commits implement and fix door-specific spawn-time AnimationSequencer registration + UpdateMotion routing + stance-value correctness.

The plan estimated "2 tasks, door spawn-time registration + UM diagnostic." Visual testing surfaced two bonus discoveries beyond the plan:

1. The plan's NonCombatStance constant was wrong: 0x80000001 (from creature motion table conventions) should be 0x8000003D (from AC's MotionStance.NonCombat = 0x0000003D). Wrong constant → wrong HasCycle lookup → SetCycle never fires → sequencer empty → per-frame part rebuild collapses to entity origin → doors render halfway underground.
2. The AnimationSequencer's link→cycle boundary transition produces a brief one-frame flash through the prior pose at the end of the door-swing animation. Not B.4c-specific — it is the sequencer's general link+cycle queue mechanics. Deferred as issue #61.

Issue #58 (door swing animation) is closed. Issues #61 + #62 (cycle-boundary flash; PARTSDIAG null-guard) are filed as M1-deferred polish.

---

What shipped on this branch

#	Commit	Subject	Task
1	9053860	feat(B.4c): door spawn-time AnimationSequencer with state-seeded initial cycle	Task 1
2	b89f004	feat(B.4c): [door-cycle] diagnostic in OnLiveMotionUpdated	Task 2
3	8a9b15e	refactor(B.4c): share IsDoorName predicate + durable comment + use UM locals	Task 2 review
4	454d88e	fix(B.4c): correct NonCombat stance value (0x3D, not 0x01) + read spawn.MotionState	Bonus: stance fix

Plus plan/spec commits earlier in the branch session:

• b4f131e — B.4c design spec.
• 6ae38f7 — B.4c implementation plan (4 tasks).

Build: clean. Tests: existing test suite passes; no new unit tests added (the door-cycle registration path runs in-process with a live GameWindow; pure unit tests would require a MotionTable + AnimationSequencer integration harness).

---

What the code does end-to-end

When the world loads, any entity whose name contains "Door" (checked via the shared GameWindow.IsDoorName(string) helper, committed as part of Task 2 review) is registered in the door-animation side-track at spawn time. This happens inside GameWindow.OnLiveEntitySpawnedLocked, which branches on IsDoorSpawn(spawn) before reaching the standard creature/player paths.

At world load (spawn time)

1. IsDoorSpawn(spawn) — delegates to IsDoorName(spawn.Name), which returns name == "Door". Detection by server-sent name string only. Cheap, exact, no WeenieType lookup. If a future ACE localizes "Door" or sends a different name, those entities silently won't animate — acceptable per B.4c's "doors only at English Holtburg" scope.

2. Initial state seed — the door's PhysicsState from spawn carries the open/closed bit. The code reads spawn.PhysicsState (or spawn.MotionState?.Stance as a fallback for unusual doors with explicit stance data) to determine whether to seed the sequencer with the Off (closed) or On (open) cycle.

3. AnimationSequencer registration — a fresh AnimationSequencer is created for the door entity's MotionTableId (from spawn). Then:

   var style = 0x80000000u | (uint)MotionStance.NonCombat; // = 0x8000003D
   var cycleCmd = isOpen ? MotionCommand.On : MotionCommand.Off;
   sequencer.SetCycle(style, (uint)cycleCmd, speed: 0f);
   

   The fully-initialized AnimatedEntity (with the seeded Sequencer) is registered into the existing _animatedEntities dict keyed by entity.Id — same dict that holds creatures and the player. Animation = null! (the null-forgiving suppression matches an existing pattern at GameWindow.cs:7885 for sequencer-driven entities where the legacy Animation field is unused). At the first per-frame Advance(dt) call from TickAnimations, the sequencer produces the correct rest-pose frames for the door's current state.

4. Log evidence at spawn:

   [door-anim] registered guid=0x7A9B403A entityId=0x000F4291 mtable=0x09000202 initialStyle=0x8000003D initialCycle=0x4000000C
   

   0x4000000C = MotionCommand.Off with the upper flag bits — the door is closed at spawn, matching the initial world state.

When the door opens (UpdateMotion arrives)

ACE broadcasts UpdateMotion (0xF74D) with stance=0x003D (NonCombat) and wire cmd=0x000C (which MotionCommandResolver.ReconstructFullCommand maps to full motion 0x4000000B = MotionCommand.On = door open).

B.4c does NOT add a new dispatch path here — the existing OnLiveMotionUpdated handler already routes via the _animatedEntities dict + per-entity Sequencer, the same code path creatures use. The only B.4c contribution at UM dispatch is the new [door-cycle] diagnostic gated on IsDoorName(doorInfo.Name). Before B.4c, doors silently dropped at the _animatedEntities.TryGetValue check at GameWindow.cs:3036 because doors weren't registered; B.4c's Task 1 spawn-time branch fixed that.

The sequencer transitions from the Off cycle (static closed pose) through the door-swing link animation to the On cycle (static open pose).

Log evidence:

UM guid=0x7A9B403A mt=0x00 stance=0x003D cmd=0x000C spd=0.00 | seq now style=0x8000003D motion=0x4000000B
[door-cycle] guid=0x7A9B403A stance=0x003D cmd=0x000C

The [door-cycle] line is the new B.4c diagnostic (gated on ACDREAM_PROBE_BUILDING=1). The seq now motion=0x4000000B shows the sequencer's current motion state after the SetCycle call.

SetState chain (from B.4b + L.2g, unchanged)

Simultaneously with UpdateMotion, ACE also sends SetState (0xF74B):

[setstate] guid=0x7A9B... state=0x0001000C

This is the B.4b / L.2g chain: ShadowObjectRegistry.UpdatePhysicsState flips the door's cached state, CollisionExemption.ShouldSkip exempts on ETHEREAL-alone, and the player can walk through. B.4c is additive — it only adds the animation layer; it does not touch the collision path.

When the door closes

ACE toggles on the next Use: UpdateMotion with cmd=0x000B (Off = close). The sequencer transitions from the On cycle (open pose) through the door-swing link animation (reversed) to the Off cycle (closed pose).

Log evidence:

UM guid=0x7A9B403A mt=... cmd=0x000B ... motion=0x4000000C
[door-cycle] guid=0x7A9B... cmd=0x000B
[setstate] guid=0x7A9B... state=0x00010008

Per-frame mesh rebuild

The door sequencer integrates into GameWindow.TickAnimations via the same _animatedEntities dict that holds creatures. Each frame, ae.Sequencer.Advance(dt) is called and the resulting per-part transforms drive the same MeshRefs rebuild that creature entities use (sequencer branch at GameWindow.cs:7497; doors never enter the legacy slerp else branch). This is the reason the stance-value bug produced underground doors: with the wrong style key (0x80000001) HasCycle returned false, the sequencer was empty at spawn, Advance returned identity frames, and the per-frame part-matrix rebuild received Vector3.Zero / Quaternion.Identity for every part — collapsing them all to the entity origin.

---

The two bonus discoveries

1. NonCombatStance constant was wrong: 0x01 vs 0x3D (454d88e) — THE render blocker

Root cause: The B.4c design spec specified the initial-cycle style key as:

uint style = 0x80000000u | (uint)MotionStance.NonCombat; // spec said 0x80000001

The spec's comment was wrong. MotionStance.NonCombat in acdream (and retail) is 0x0000003D, not 0x00000001. The value 0x01 is a creature-specific variant. The style key for the door's cycle lookup must be 0x8000003D.

With the wrong style key:

• sequencer.HasCycle(0x80000001, MotionCommand.Off) → false.
• SetCycle(0x80000001, ...) enqueued a cycle that was never reachable.
• On first Advance(dt), the sequencer returned 0 part-frames.
• The per-frame mesh rebuild at GameWindow.cs:7691 iterated 0 frames, leaving every door part at the entity root origin (which is the door's structural pivot, typically near the hinge). For inn doors this pivot is at roughly floor level, so all the door's mesh parts collapsed to that single point, rendering as a thin sliver partway underground.

Fix: Corrected the constant. Additionally, added a defensive read of spawn.MotionState?.Stance as the source of the stance value where available, so unusual doors with explicit motion state (possible in custom ACE content) use their actual stance rather than the hardcoded NonCombat assumption:

var stance = spawn.MotionState?.Stance ?? MotionStance.NonCombat;
uint style = 0x80000000u | (uint)stance;

Verification: After this fix, the [door-anim] log line showed initialStyle=0x8000003D (correct), and doors appeared at the correct floor level and height at world load.

2. AnimationSequencer link→cycle boundary flash (deferred as #61)

Observed: User reports "weird flapping at end of animation when it opens. It is like it flaps back to closed quickly then open. Like really quickly." Both open and close animations exhibit this flash.

Root cause hypothesis: AnimationSequencer.SetCycle enqueues a transition link (the actual swing animation) followed by the target cycle (the door's rest pose — likely a single-frame static "open" or "closed" pose). At the link→ cycle boundary, the sequencer evaluates the cycle's frame 0 before the cycle settles into its natural rest position. If the link's last frame and the cycle's frame 0 don't match exactly (which is common for one-shot door motions versus the continuous idle cycles the sequencer was designed for), the renderer sees one frame of the "wrong" pose at the link boundary.

Why not B.4c-specific: This is the sequencer's general link+cycle queue boundary semantics. Any entity that uses a one-shot SetCycle transition (rather than a continuous idle cycle) will exhibit this if the link/cycle boundary frames diverge. The door case just makes it visible because the swing duration is short (1-2 seconds) and the user is watching closely.

Deferred: Filed as issue #61. Workaround: the flash is brief (~1 frame, ~16ms at 60 FPS) and does not affect the door's usability. M1 is met without this fix.

---

Open notes / follow-ups

#61 — AnimationSequencer link→cycle frame-0 flash (filed this session)

See Bonus discovery #2 above. Deferred as M1-deferred polish. Low severity. Acceptance: door swing animations play cleanly with no intermediate closed/open pose flash at the link→cycle transition.

#62 — PARTSDIAG null-guard for sequencer-driven entities (filed this session)

The PARTSDIAG block at GameWindow.cs:7657 reads ae.Animation.PartFrames without a null-guard. B.4c introduced Animation = null! for sequencer-driven door entities. Today this is safe (doors never enter _remoteDeadReckon because ACE never sends UpdatePosition for them). Deferred as low-severity latent crash. One-line fix when addressed.

Chests, levers, traps

The IsDoorName / IsDoorSpawn predicate correctly gates on door entities only. Other interactable non-creature entities (chests, levers, traps) will still silently drop their UpdateMotion commands — they are not covered by B.4c and no issue has been filed for them yet. When those animations become relevant (M2/M3 inventory + dungeon content), the same spawn-time registration pattern can be extended: broaden the detection predicate beyond name == "Door" and register additional entity types in the existing _animatedEntities dict via the same sibling branch.

Door toggle behavior

Unchanged from B.4b. ACE doors toggle on each Use: first double-click opens, subsequent double-click closes. Both transitions now play the correct swing animation (open swing on open, close swing on close).

---

Next session

M1 demo progress as of this branch:

• "Walk through Holtburg without getting stuck" — Phase L.2 in progress (outdoor collision works; CBuildingObj interior still deferred to L.2d).
• "Open the inn door" — DONE with full visual feedback (B.4b interaction + B.4c animation, this branch). Door swings open AND closed.
• "Click an NPC" — pick + Use wiring exists (from B.4b); depends on ACE NPC handler responding to Use correctly.
• "Pick up an item" — BuildPickUp + F-key wiring not yet in OnInputAction. Post-B.4b/B.4c deferred.

Recommended next steps (in M1 critical-path order):

1. "Click an NPC" verification spike — B.4b's WorldPicker + Use messaging is already wired. The question is whether ACE NPCs respond to Use and what they broadcast back. A quick spike: stand near an NPC in Holtburg, double-click, check what ACE sends back. If ACE sends recognizable response messages, wire them; if it is silent, investigate ACE's NPC handler configuration for testaccount.

2. Phase B.5 — Ground item pickup (F key) — SelectionPickUp input action

   • F-key binding exist but OnInputAction has no case. BuildUse is the same wire format as BuildPickUp. Adding the SelectionPickUp case to the switch and routing to InteractRequests.BuildPickUp is a one-commit addition.

3. Triage chronic open-issue list — #2 (lightning), #4 (sky horizon-glow), #28 (aurora), #29 (cloud thinness), #37 (humanoid coat), #41 (remote-motion blips) have been open since April/early-May. Link each to a future phase or downgrade. ~1 hour.

4. #61 fix (cycle-boundary flash) — low-severity M1 polish. If the user finds the flash distracting during the M1 demo record, address before milestone wrap; otherwise defer to M2 animation quality pass.

---

Reproducibility

Same launch recipe as B.4b. For reproducing the visual test:

$env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
$env:ACDREAM_LIVE           = "1"
$env:ACDREAM_TEST_HOST      = "127.0.0.1"
$env:ACDREAM_TEST_PORT      = "9000"
$env:ACDREAM_TEST_USER      = "testaccount"
$env:ACDREAM_TEST_PASS      = "testpassword"
$env:ACDREAM_DEVTOOLS       = "1"
$env:ACDREAM_PROBE_BUILDING = "1"
$env:ACDREAM_PROBE_RESOLVE  = "1"
dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 |
  Tee-Object -FilePath "launch-b4c.log"

Walk to the Holtburg inn doorway. Watch the [door-anim] lines appear in the log as each door entity spawns (verifies correct style=0x8000003D and initial cycle). Double-left-click a closed door. Watch the swing animation. Walk through. Wait ~30s (ACE auto-close). Watch the close animation.

After closing the client, grep for:

Select-String -Path launch-b4c.log -Pattern "door-anim|door-cycle|setstate"

Expected:

• [door-anim] registered guid=... initialStyle=0x8000003D initialCycle=0x4000000C — correct style + Off initial cycle for each closed door.
• [door-cycle] guid=... stance=0x003D cmd=0x000C — open UpdateMotion processed.
• [setstate] guid=... state=0x0001000C — ACE collision-flip processed (from B.4b / L.2g).
• [door-cycle] guid=... cmd=0x000B — close UpdateMotion processed.
• [setstate] guid=... state=0x00010008 — ACE close collision-flip processed.

---

Worktree state at handoff

• Branch claude/phase-b4c-door-anim.
• 6 commits ahead of 3e08e10 (the B.4b+L.2g merge from this morning): 2 docs/spec/plan commits + 4 implementation commits.
• Controller should run a code review, then merge to main.
• Do NOT rebase or squash — each commit tells a diagnostic story that the next phase's debugging may need.