acdream/docs/research/2026-07-06-adjust-to-plane-pseudocode.md

# `BSPTREE::adjust_to_plane` + `CPolygon::adjust_sphere_to_poly` — pseudocode (#180 sawtooth fix)

Source: `docs/research/named-retail/acclient_2013_pseudo_c.txt`. Read 2026-07-06
while root-causing the #180 residual (the camera-sweep sawtooth: PathClipped
stops landing a whole transition step short of the wall contact).

| Function | VA | pseudo-C line |
|---|---|---|
| `BSPTREE::adjust_to_plane` | `0x00539bf0` | 323440 |
| `BSPTREE::collide_with_pt` (caller) | `0x0053a090` | 323615 |
| `CPolygon::adjust_sphere_to_poly` | `0x00538170` | 321999 |

## ⚠️ ACE'S PORT OF BOTH FUNCTIONS IS WRONG — do not re-import it

ACE `BSPTree.cs:43-85 adjust_to_plane` + `Polygon.cs:99-114
adjust_sphere_to_poly` decode the retail x87 control flow incorrectly, and the
result is a function that **always returns false** (trace it: `touchTime==1`
re-places the sphere at t=1 — the unchanged check position — and re-tests; any
`touchTime<1` iterates 15 times doing nothing; the `<0.02` convergence exit
returns false — inverted). ACE never noticed because `PERFECT_CLIP` (0x40) is
a viewer/camera flag the SERVER never meaningfully exercises. acdream's
pre-fix `BSPQuery.AdjustToPlane`/`AdjustSphereToPoly` copied ACE's shape and
inherited the dead machinery — the memory lesson
`feedback_bn_decomp_field_names` class 3 (ACE mush-decode wrong in branches
ACE never runs; the retail binary outranks it).

**Consequence (the #180 sawtooth / the ORIGINAL #176 strobe):** with
`AdjustToPlane` always failing, `collide_with_pt`'s PerfectClip branch always
fell to the bare `Collided` return → the transition reverted the colliding
step to the PREVIOUS step boundary. A PathClipped camera sweep therefore
stopped a whole sub-step (≤ 1 sphere radius, ~0.25–0.3 m) short of the actual
contact — quantized to step boundaries. The pre-fix full-boom camera flipped
between 1-step and 2-step backoffs on mm input drift (the measured
`pulledIn` 0.27 ↔ 0.53 = one step vs two steps of the ~1.6 m/6-step sweep);
the stateful-sought camera turned it into a re-extend/clip-0.27 m sawtooth at
~19 Hz. Same root: the stop never resolved to the contact point.

## `CPolygon::adjust_sphere_to_poly` — 0x00538170

Returns the parametric time along `movement` at which the SPHERE SURFACE
touches the polygon's plane, approaching from the side the start position is
on. (The retail tail is x87 compare-bit mush; the reconstruction below is the
only shape consistent with the visible operand loads + the caller's use.)

```
adjust_sphere_to_poly(this, CSphere* sphere, Vector3 curPos, Vector3 movement) -> float:
    dpPos = dot(plane.N, curPos) + plane.d          // plane distance of the START (0x0053818d)
    if |dpPos| < sphere.radius: return 1.0          // start already within one radius of the
                                                    // plane — no forward touch time (0x005381a4)
    dpMove = dot(plane.N, movement)                 // (0x005381ca)
    if |dpMove| <= 2e-4: return 0.0                 // moving parallel to the plane (0x005381d2)
    r = (dpPos < 0) ? -radius : +radius             // touch on the start's side (0x005381ea)
    return (r - dpPos) / dpMove                     // UNCLAMPED — retail has no [0,1] clamp
```

Divergences fixed in acdream's port: the early-out was a precise-poly overlap
test at the CHECK position (wrong test, wrong endpoint); the touch side was
hard-coded `-radius`; the result was clamped to [0,1]. ACE's version keys the
± sign on `movement.LengthSquared() <= r²` — a misdecode of the `dpPos < 0`
compare.

## `BSPTREE::adjust_to_plane` — 0x00539bf0

Finds the closest non-penetrating position along `[curPos → checkPos]` and
commits it into the sphere. Two known-time bounds: `clearTime` (var_50/var_4c,
init 0.0 — the start is clear) and `hitTime` (var_48/var_44, init **1.0** —
the check position hit). ONE iteration counter shared by both phases.

```
adjust_to_plane(this, CSphere* sphere /*in: at checkPos; out: adjusted*/,
                Vector3 curPos, CPolygon*& hitPoly, Vector3* contactPt) -> success:
    movement  = sphere.center - curPos               // (0x00539c16..0x00539c3c)
    clearTime = 0.0 ; hitTime = 1.0 ; i = 0

    // Phase 1 (0x00539c4d): walk plane-touch times.
    loop:
        t = hitPoly->adjust_sphere_to_poly(sphere, curPos, movement)
        if t == 1.0: break                           // start within radius → pure [0,1] search
        sphere.center = curPos + movement * t        // (0x00539ca8-0x00539cb9)
        if !root->sphere_intersects_poly(sphere, movement, &hitPoly, contactPt):
            clearTime = t                            // touch position clear (0x00539d02)
            break
        // still blocked — by a possibly DIFFERENT poly (the tree test wrote hitPoly)
        i += 1 ; hitTime = t                         // (0x00539cdd-0x00539ce5)
        if i >= 15: return FAIL                      // the only failure exit (0x00539ce9)

    // Phase 2 (0x00539ddb): binary-search [clearTime, hitTime]; i continues.
    do:
        avg = (clearTime + hitTime) * 0.5
        sphere.center = curPos + movement * avg
        if !sphere_intersects_poly(...): clearTime = avg
        else:                            hitTime  = avg
        if hitTime - clearTime < 0.02: break         // CONVERGED (0x00539dca) — NOT a failure
        i += 1
    while i < 15

    sphere.center = curPos + movement * clearTime    // commit the last CLEAR time (0x00539de1)
    return SUCCESS                                   // Phase 2 always succeeds (even unconverged)
```

Caller (`collide_with_pt` 0x0053a090, PERFECT_CLIP branch): on success —
`set_collision_normal(globalized hitPoly.plane)`, `add_offset_to_check_pos(
globalize(adjusted − original) · scale)`, return **Adjusted(3)**; on the rare
Phase-1 failure — return **Collided(2)** with NO normal write. acdream's
`CollideWithPt` already had this caller shape correct; only the two functions
above were broken.

## Verification

Headless replay `Issue180CorridorSweepHysteresisReplayTests` (real Facility
Hub cell 0x8A020164 BSP, the exact captured ray): pre-fix, targets embedded up
to 0.25 m into the wall behind the camera passed unclipped and the first
detection (s=1.625) stopped a full step back (eyeBack 1.354, tracking the
target); post-fix the stop must sit at the surface-contact point (eyeBack ≈
constant ≈ 1.61) for every target past first touch.