acdream/docs/research/2026-05-21-a6-p3-slice1-retail-mech-b-research.md

A6.P3 Slice 1 — Retail Mechanism B Oracle for Indoor CP Retention

Date: 2026-05-21
Author: Claude (research agent)
Task: Pre-fix research grounding the indoor ContactPlane-retention refactor in retail's exact LKCP-restore pattern before the synthesis path is removed.

---

1. CEnvCell::find_env_collisions Shape

Retail decomp at acclient_2013_pseudo_c.txt lines 309573–309593 (address 0052c130). The complete function is 10 functional lines:

// 0052c130  enum TransitionState __thiscall CEnvCell::find_env_collisions(
//               class CEnvCell const* this, class CTransition* arg2)
{
    // Check entry restrictions (object ethereal? door closed? etc.)
    enum TransitionState result = CObjCell::check_entry_restrictions(this, arg2);

    if (result == OK_TS) {
        // 0052c144 Clear obstruction-ethereal so BSP collision is live.
        arg2->sphere_path.obstruction_ethereal = 0;

        if (this->structure->physics_bsp != 0) {
            // 0052c169 Project sphere into cell-local space.
            SPHEREPATH::cache_localspace_sphere(&arg2->sphere_path, &this->pos, 1f);

            // 0052c175 Run BSP: INITIAL_PLACEMENT → placement_insert path;
            //          all other insert_types → find_collisions path.
            if (arg2->sphere_path.insert_type != INITIAL_PLACEMENT_INSERT)
                result = BSPTREE::find_collisions(this->structure->physics_bsp, arg2, 1f);
            else
                result = BSPTREE::placement_insert(this->structure->physics_bsp, arg2);

            // 0052c1a5 On collision with environment (non-Contact objects only).
            if (result != OK_TS && (arg2->object_info.state & 1) == 0)
                arg2->collision_info.collided_with_environment = 1;
        }
    }
    return result;
}

Key observation: find_env_collisions itself does not write contact_plane. It either returns OK (BSP path OK or no BSP) or returns a collision state. ContactPlane is written ONLY inside BSPTREE::find_collisions via Path 6 (land/step-down) — that is Mechanism A. There is no per-frame synthesis path anywhere in this function.

---

2. Retail Mechanism B Location

Function: CTransition::validate_transition
Retail address: 0050aa70
Decomp line range: acclient_2013_pseudo_c.txt lines 272547–272700
Identified via: The validate_transition function header appears at line 272547 (0050aa70). Line 272538 is inside the preceding CTransition::check_collisions function.

The LKCP-restore block runs at lines 272565–272582 (addresses 0050aaed–0050ab4c).

---

3. Retail Mechanism B Trigger Condition

Mechanism B fires when ALL of the following are true:

1. result > OK_TS && result <= SLID_TS — the transition ended in Collided, Adjusted, or Slid (not OK, not Invalid).
2. collision_info.last_known_contact_plane_valid != 0 — there is a remembered floor plane from a prior frame.
3. Proximity guard: |dot(global_curr_center, LKCP.N) + LKCP.d| <= radius + 0.000199f — the sphere's current position center (global_curr_center, NOT the check-position sphere global_sphere) is still geometrically close to the last-known plane.

When all three pass, retail:

// 0050ab37
COLLISIONINFO::set_contact_plane(
    &this->collision_info,
    &this->collision_info.last_known_contact_plane,
    this->collision_info.last_known_contact_plane_is_water);

// 0050ab42
this->collision_info.contact_plane_cell_id =
    this->collision_info.last_known_contact_plane_cell_id;

Then result = OK_TS at 0050ab9f — the collision is resolved by restoring the floor and treating the transition as successful.

After that block, at 0050acff–0050ad7d, retail sets last_known_contact_plane_valid = contact_plane_valid (unconditional overwrite, NOT "only when valid") and then sets Contact + OnWalkable flags based on whether contact_plane_valid is non-zero. The LKCP update strategy is unconditional in retail (even if current CP is invalid, LKCP gets cleared).

The epsilon constant: 0.000199999995f — effectively 2e-4. This is a tight epsilon for floating-point error in the dot product; the sphere radius already provides the geometric margin.

---

4. Our Equivalent Function

From grep -rn "ValidateTransition" src/AcDream.Core/Physics/:

TransitionTypes.cs:2751  private TransitionState ValidateTransition(TransitionState transitionState)
TransitionTypes.cs:670   transitionState = ValidateTransition(result);

Our C# ValidateTransition (TransitionTypes.cs lines 2751–2873) is the correct equivalent. The call at line 670 is inside FindTransitionalPosition's step loop: each call to TransitionalInsert is immediately followed by ValidateTransition(result).

---

5. Decision — Where to Add Mechanism B in Our Code

Gap analysis

Our ValidateTransition has TWO divergences from retail's Mechanism B:

Gap 1: Missing SetContactPlane write in the Collided/Slid/Adjusted branch.

Retail's validate_transition (lines 272565–272582) calls COLLISIONINFO::set_contact_plane(LKCP, LKCP_is_water) and sets contact_plane_cell_id = LKCP_cell_id before returning OK_TS.

Our ValidateTransition at TransitionTypes.cs:2821–2866 (the else if (ci.LastKnownContactPlaneValid) block) only reads LastKnownContactPlane to update oi.State flags (Contact, OnWalkable) — it does not call ci.SetContactPlane(...). This means ContactPlane stays invalid even when we know the LKCP is close, while ci.LastKnownContactPlane holds the value. The PhysicsEngine fallback at PhysicsEngine.cs:668–674 partially compensates (it reads LKCP to populate body.ContactPlane cross-frame), but it only does so after FindTransitionalPosition returns — not per-step inside the loop.

Gap 2: Wrong sphere used for proximity dot product.

Retail uses global_curr_center (pointer to the sphere center at the current frame-start position) for the dot product. Our code at TransitionTypes.cs:2843 uses sp.GlobalSphere[0].Origin (the check position — where we want to move to). For the proximity check against a retained floor plane, the correct center is sp.GlobalCurrCenter[0].Origin, matching retail's global_curr_center.

This distinction matters when the player is near a cell/floor boundary: if the check position has stepped slightly off the floor but the current position is still on it, retail correctly restores the CP; our code might fail the proximity guard spuriously.

Insertion point (exact)

File: src/AcDream.Core/Physics/TransitionTypes.cs
Method: ValidateTransition (line 2751)
Target block: The else if (ci.LastKnownContactPlaneValid) block at lines 2821–2866 (the LKCP proximity-guard branch).

Change required: Within the if (radius + PhysicsGlobals.EPSILON > MathF.Abs(angle)) branch (currently at line 2848), BEFORE setting oi.State flags:

1. Add ci.SetContactPlane(ci.LastKnownContactPlane, ci.LastKnownContactPlaneCellId, ci.LastKnownContactPlaneIsWater);
2. Change the proximity sphere center from sp.GlobalSphere[0].Origin (line 2843) to sp.GlobalCurrCenter[0].Origin to match retail's global_curr_center.

The addition goes at TransitionTypes.cs approximately line 2849 (just before the oi.State |= ObjectInfoState.Contact at current line 2852), producing:

// Retail Mechanism B (validate_transition:0050ab37): restore CP from LKCP
// when sphere is still near the plane. This writes ContactPlane valid so
// the end-of-function LastKnown-update block (below) re-latches it,
// and ObjectInfoState.Contact is set from contact_plane_valid.
ci.SetContactPlane(ci.LastKnownContactPlane,
                   ci.LastKnownContactPlaneCellId,
                   ci.LastKnownContactPlaneIsWater);
// Then set Contact + OnWalkable (same logic as retail's 0050ad6a block):
oi.State |= ObjectInfoState.Contact;
if (ci.LastKnownContactPlane.Normal.Z >= PhysicsGlobals.FloorZ)
    oi.State |= ObjectInfoState.OnWalkable;
else
    oi.State &= ~ObjectInfoState.OnWalkable;

Note: SetContactPlane also re-latches LastKnownContactPlane, LastKnownContactPlaneCellId, and LastKnownContactPlaneIsWater (TransitionTypes.cs:258-261). Passing LKCP as the source means the re-latch is a no-op on those fields — functionally safe, but worth knowing if you later decide to inline the writes instead of using SetContactPlane.

Note on the LKCP-update strategy divergence (Gap 3): Retail's validate_transition at 0050acff does last_known_contact_plane_valid = contact_plane_valid unconditionally — this means when contact is invalid and stays invalid, LKCP is cleared. Our code at TransitionTypes.cs:2801 only updates LKCP when current CP is valid (L.2.3c deliberate divergence from 2026-04-29 to prevent animation flicker on failed step-ups). Do not change this in slice 1 — the Mechanism B SetContactPlane call above feeds into the standard contact-valid branch (lines 2801–2819), which then re-latches LKCP normally. The net effect is equivalent to retail's unconditional overwrite in the success case, without the flicker regression of clearing LKCP on transient failures.

---

6. Risk — First-Frame Fall-Through

Scenario: Player teleports into a new indoor cell (or crosses a cell boundary). On frame 0 in the new cell: LKCP is invalid (no prior frame data), BSP returns OK (no wall collision, player is standing on a floor poly). With the synthesis path stripped (Task 5) and Mechanism B requiring a valid LKCP, this frame will have ContactPlane invalid for the indoor case.

Consequence: Frame 0 post-cell-cross → ContactPlane invalid → outdoor terrain fallback fires → ValidateWalkable evaluates outdoor terrain Z → outdoor Z is below indoor floor (due to +0.02f Z-bump) → player appears 0.02+ m above the outdoor plane → ValidateWalkable decides they're airborne → OnWalkable=false → falling animation for one frame. Retail avoids this via Mechanism A: when BSP Path 6 (step-down/land) fires on the first indoor frame, it writes CP directly from the floor polygon.

Assessment for slice 1: Mechanism A is already wired in BSPQuery.FindCollisions (calls SetContactPlane at BSPQuery.cs lines 1204 + 1713 for Path 6). If the player's foot sphere is close enough to a floor polygon on the first frame (within step_sphere_down's probe distance), Path 6 will write CP and LKCP will be primed via the ci.ContactPlaneValid branch (TransitionTypes.cs:2801). Frame 1 will have LKCP valid and Mechanism B can take over.

Risk is LOW for normal walking (player stays near the floor, Path 6 fires on the first frame in any cell). Risk is HIGHER for teleport-into-air edge cases where the player spawns slightly above the floor and the step-down probe misses. Accept for slice 1; slice 2 (Mechanism C) adds a direct floor-plane probe from the new cell's geometry on first entry, closing the gap completely.

Mitigation hedge: When stripping TryFindIndoorWalkablePlane in Task 5, do NOT strip the ValidateWalkable call — keep it guarded by walkableHit being true. The fall-through to outdoor terrain remains as a last-resort backstop for the single-frame miss (wrong Z, one frame of falling animation, then Mechanism A re-grounds on the next frame). This is one visible frame of glitch vs the current 86,748 CP writes per walk sequence. Acceptable for slice 1.

---

Summary Table

Item	Retail	Our Code (pre-fix)
find_env_collisions writes CP?	No — only via BSP Path 6 (Mechanism A)	Yes — synthesis path writes CP every frame indoors
Mechanism B location	CTransition::validate_transition, Collided/Slid/Adjusted branch	Present but INCOMPLETE — sets flags only, no SetContactPlane call
Mechanism B proximity sphere	global_curr_center (frame-start center)	GlobalSphere[0].Origin (check position — wrong)
LKCP update strategy	Unconditional overwrite	Only on valid CP (L.2.3c deliberate fix)
First-frame risk	Mechanism C closes; Mechanism A covers normal cases	Same risk; accept for slice 1

---

References

• acclient_2013_pseudo_c.txt lines 309570–309595 (CEnvCell::find_env_collisions)
• acclient_2013_pseudo_c.txt lines 272547–272700 (CTransition::validate_transition)
• src/AcDream.Core/Physics/TransitionTypes.cs lines 2751–2873 (ValidateTransition)
• src/AcDream.Core/Physics/TransitionTypes.cs lines 1514–1777 (FindEnvCollisions)
• src/AcDream.Core/Physics/PhysicsEngine.cs lines 640–692 (RunTransitionResolve)
• src/AcDream.Core/Physics/BSPQuery.cs lines 1204, 1713 (Mechanism A SetContactPlane)