acdream/docs/research/2026-08-07-s4-pseudocode.md

# `CTransition::adjust_offset` — full branch-tree pseudocode (Campaign S, S4)

> **OUTCOME NOTE (2026-08-07, appended by the session lead):** AD-66 was
> WITHHELD after this doc was written — the production code retains the
> `radius * N.z` substitution and register row AD-66 stays ACTIVE; see issue
> #341 for the measurement anomaly that blocked the landing. Statements below
> describing the bare-radius port as applied describe the IMPLEMENTED-THEN-
> PULLED state, not HEAD. The disassembly itself is unaffected and remains
> the oracle for the relanding.


Source: `docs/research/named-retail/acclient_2013_pseudo_c.txt`, function at
`0x0050a370`, pseudo-C lines 272271-272393. Companion callee
`Plane::snap_to_plane` at `0x00509c50`, lines 271852-271869. Cross-referenced
against `references/ACE/Source/ACE.Server/Physics/Animation/Transition.cs:34-87`
(`Transition.AdjustOffset`) and
`references/ACE/Source/ACE.Server/Physics/Extensions/PlaneExtensions.cs:31-37`
(`SnapToPlane`), and against `references/ACE/Source/ACE.Server/Physics/Common/Vector.cs:8-16`
(`NormalizeCheckSmall`). Written under the S4 contract
`docs/research/2026-08-07-s4-adjustoffset-contract.md` for AD-65 + AD-66.

acdream port: `src/AcDream.Core/Physics/TransitionTypes.cs`, `Transition.AdjustOffset`
(private → `internal` as of this slice, to allow direct exact-value testing —
matches the existing `SlideSphereInternal` precedent in the same file).

## Signature

```
Vector3 adjust_offset(CTransition* this, Vector3 offset)
```

Called once per sub-step from `find_transitional_position` BEFORE the offset
is applied to `check_pos` (acdream: `TransitionalInsert` reads
`CollisionInfo` state left by the PREVIOUS step, then calls `AdjustOffset`
before mutating `CheckPos`).

## Full branch tree

```
adjust_offset(offset) -> Vector3:
    result = offset
    checkSlide = false

    # ---- sliding-normal gate (0x0050a398) ----
    slidingAngle = dot(result, collision_info.sliding_normal)
    if collision_info.sliding_normal_valid:
        if slidingAngle < 0:
            checkSlide = true                      # ecx_1 = 1
        else:
            collision_info.sliding_normal_valid = false

    # ---- branch on contact plane (0x0050a3de) ----
    if collision_info.contact_plane_valid:
        collisionAngle = dot(result, contact_plane.N)          # arg3 @0x0050a408
        slideOffset = cross(contact_plane.N, sliding_normal)   # @0x0050a42a onward

        if checkSlide:                              # ecx_1 != 0 (0x0050a42a)
            # ---- crease-slide arm: verified identical to acdream, NOT changed ----
            if normalize_check_small(slideOffset):    # degenerate (len <= EPSILON)
                result = Zero
            else:
                result = dot(slideOffset, result) * slideOffset

        elif collisionAngle <= 0:                     # 0x0050a505, "ah & 0x41" != 0
            # ---- INTO-plane arm (0x0050a529) — unchanged, already correct ----
            result -= contact_plane.N * collisionAngle

        else:                                          # collisionAngle > 0
            # ---- AWAY-from-plane arm (0x0050a50e) — AD-65 FIX ----
            snap_to_plane(contact_plane, &result)       # NOT the subtraction!

        # ---- safety push-out (0x0050a571) — AD-66 FIX applies inside ----
        if not contact_plane_is_water:
            if contact_plane_cell_id != 0:
                blockOffset = get_block_offset(sphere_path.check_pos.objcell_id,
                                                contact_plane_cell_id)
                globSphere = sphere_path.global_sphere[0]
                dist = dot(globSphere.center - blockOffset, contact_plane.N)
                       + contact_plane.d
                # AD-66: retail compares/divides the BARE radius, not
                # radius*N.z, at BOTH sites below.
                if dist < globSphere.radius - F_EPSILON:            # 0x0050a5cf
                    zDist = (globSphere.radius - dist) / contact_plane.N.z  # 0x0050a5df
                    if globSphere.radius > |zDist|:                 # 0x0050a5e9
                        sphere_path.add_offset_to_check_pos((0, 0, zDist))

    # ---- no contact plane (0x0050a61e) ----
    elif checkSlide:                                    # ecx_1 != 0
        slidingAngle2 = dot(result, sliding_normal)
        result -= sliding_normal * slidingAngle2
    # else: result unchanged (no contact plane, no slide)

    return result
```

## `Plane::snap_to_plane` (0x00509c50) — the AD-65 target

```
snap_to_plane(plane, offset* /* in-out */):
    if |plane.N.z| <= F_EPSILON (0.000199999995f):
        return                              # no-op — X, Y, Z ALL unchanged

    # offset.z temporarily zeroed, then re-solved so dot(N, offset) + d == 0:
    offset.z = -(offset.x * N.x + offset.y * N.y) / N.z
    # X and Y are NEVER written — only Z changes.
```

### Deriving the formula (the `d` terms cancel)

Retail's literal decompiled expression (pc:271864-271867) is:

```
offset.z = 0                                            # temporary
A = offset.x*N.x + offset.y*N.y                          # (z already 0, so this
                                                           #  is the full dot(N,offset))
offset.z = ( -(A + d) * (1/N.z) ) - ( (1/N.z) * -d )
```

Expand:

```
offset.z = -(A+d)/N.z + d/N.z
         = [ -(A+d) + d ] / N.z
         = [ -A - d + d ] / N.z
         = -A / N.z
         = -(offset.x*N.x + offset.y*N.y) / N.z
```

The `d` terms cancel exactly, leaving the plain XY-dot-over-N.z formula
above. This matches ACE's `PlaneExtensions.SnapToPlane` byte-for-byte
(confirmed by reading `references/ACE/.../PlaneExtensions.cs:31-37`, which
carries the unsimplified `-(...+d)*(1/N.z) - (1/N.z)*-p.D` form — ACE did
not even bother to algebraically simplify it, which is good corroborating
evidence this is really what retail computes rather than an ACE
reinterpretation).

## The Binary Ninja flag-idiom ambiguity (resolve, don't guess)

Four x87 float comparisons in this function's neighborhood get turned into
the same packed-flags shape by Binary Ninja:

```
eax = (ST0<src)<<8 | (unordered)<<10 | (ST0==src)<<14 | ...
bool p = /* test ah, <mask> */          # sometimes resolved, sometimes not
```

**One of the four (the outer collisionAngle<=0 vs >0 branch) is resolved
cleanly** — Binary Ninja rendered it directly as
`if ((eax_4_ah & 0x41) != 0)` with no `/* unimplemented */` placeholder, and
mask `0x41` (bits C0|C3) is the standard x87 "ST0 <= src" idiom. The
divergence register's AD-65 row independently disassembled the raw bytes at
this exact site (`0050a4fa fcomp [0x795344]` / `0050a502 test ah,0x41` /
`0050a505 jne 0x50a515`, 0x795344 = the float constant 0.0f) and confirms:
`jne` on `ah & 0x41` takes the SUBTRACT branch when `collisionAngle <= 0` and
falls through to `call 0x509c50` (snap_to_plane) when `collisionAngle > 0`.
**No ambiguity here** — this is the branch AD-65's headline fix depends on,
and it is independently confirmed by both the contract and this doc's own
reading of the pseudo-C.

**The other three all use mask `0x5` (bits C0|C2) and ALL THREE are left as
`/* bool p = unimplemented {test ah, 0x5} */`** by Binary Ninja — it could
not resolve them into readable expressions:

1. `snap_to_plane`'s own `|N.z| <= F_EPSILON` guard (pc:271859-271862).
2. AD-66's safety-push trigger comparison, `dist` vs `radius - F_EPSILON`
   (pc:272358-272361).
3. `normalize_check_small`'s degenerate-length check (pc:91421-91424,
   unrelated to AD-65/AD-66 but in the same neighborhood and same idiom —
   documented here since the sliding-normal arm cites it).

Attempting to read the polarity directly off the packed-flag pseudocode's
`(x87_rA < x87_rB)` sub-expression is **unsound** for these three: the
subtraction operand order recorded by the decompiler
(`(x87_r6 - x87_r7)` in snap_to_plane vs `(x87_r5 - temp0)` in
normalize_check_small) is not by itself sufficient to recover which operand
was `ST(0)` in the original `fcomp`, and a naive literal reading of the two
sites against each other produces **contradictory** polarities (the two
reads cannot both be "ST0 < src means true" and remain self-consistent with
their own surrounding code's evident purpose). **This doc does not attempt
to re-derive them from the disassembly-free pseudo-C.** Instead, each is
resolved by triangulating independent evidence:

| Site | Resolved polarity used | Evidence |
|---|---|---|
| `snap_to_plane` epsilon guard | `\|N.z\| <= F_EPSILON` → no-op; else → resolve Z | (a) **the S4 contract pins this explicitly** ("if `\|N.z\| <= 0.000199999995f` do NOTHING; else..."); (b) domain reasoning — the resolve divides by `N.z`, so the guard must protect against near-zero `N.z` (a near-vertical wall), not near-full `N.z` (a floor); (c) ACE's `PlaneExtensions.SnapToPlane` (`if (Math.Abs(p.Normal.Z) <= PhysicsGlobals.EPSILON) return;`) — independently ported, agrees exactly. |
| AD-66 trigger (`dist` vs `radius - F_EPSILON`) | compute/push branch fires when `dist < radius - F_EPSILON` | (a) preserves the EXISTING acdream control-flow direction (push fires when penetrating) — the contract asks only to substitute the RADIUS term, not invert the comparison; (b) domain reasoning — a push-up-when-penetrating safety net must fire on LOW `dist`; (c) ACE's `Transition.cs:77` (`if (dist >= globSphere.Radius - PhysicsGlobals.EPSILON) return offset;`) — the negation of exactly this condition, independently ported, agrees. |
| `normalize_check_small` degenerate check | `length <= F_EPSILON` → return 1 (small); else → normalize, return 0 | ACE's `Vector.NormalizeCheckSmall` (`var dist = v.Length(); if (dist < PhysicsGlobals.EPSILON) return true; v *= 1/dist; return false;`) — independently ported, agrees, and also confirms the length is the FULL vector length, not (as the raw decompiled `this->x` alone might suggest — see next section) just the X component. |

All three triangulations AGREE with each other's implied "the guarded
branch is the geometrically meaningful one" reading and agree with the two
independently-sourced ACE ports. None of this changes what ships: (1) and
(2) are exactly AD-65's and AD-66's fixes; (3) confirms NO change is needed
to the sliding-normal arm.

## The sliding-normal arm (0x0050a42a) — verified against acdream, NOT changed

Per the contract, this arm must be verified but is out of scope to modify
unless it diverges. It does not.

**Cross product.** Retail computes (pc:272326-272328):

```
crossVec.x = sliding_normal.z * N.y - sliding_normal.y * N.z
crossVec.y = sliding_normal.x * N.z - sliding_normal.z * N.x
crossVec.z = sliding_normal.y * N.x - sliding_normal.x * N.y
```

This is algebraically `cross(N, sliding_normal)` (standard
`cross(a,b) = (a.y*b.z - a.z*b.y, a.z*b.x - a.x*b.z, a.x*b.y - a.y*b.x)` with
`a=N, b=sliding_normal`). acdream's `Vector3.Cross(ci.ContactPlane.Normal,
ci.SlidingNormal)` computes the same thing. **Match.**

**Projection.** Retail (pc:272332-272339): `dot = dot(crossVec, result)`,
then `result = crossVec * dot`. acdream: `result = Vector3.Dot(slideOffset,
result) * slideOffset`. Scalar-times-vector is commutative here — same
value. **Match.**

**Degenerate case (`normalize_check_small` returns nonzero).** Retail
(pc:272341-272345) is genuinely ambiguous in the raw pseudo-C: it shows
`x = __return_1` (the un-normalized cross-product X component, NOT zero)
followed by `memset(&s, 0, 0x14)` which zeroes `s`, `z`, and 16 more
trailing bytes of stack — it does NOT show `x` (the X component) being
zeroed by the memset span shown. Read completely literally, this would mean
X keeps a tiny nonzero leftover value while Y and Z become exactly zero,
which does not match "degenerate → whole vector is zero".

This is judged to be a **Binary Ninja decompilation artifact**, not real
retail behavior, for three independent reasons: (1) the decompiled
`normalize_check_small` itself only reads `this->x` (pc:91417) as the thing
compared against `F_EPSILON` — never `this->y` or `this->z` in a
sum-of-squares — even though lines 91415-91416 (`this->z;` / `this->y;`
bare, unassigned reads) show the decompiler DID emit memory-read
instructions for y and z that it then failed to fold into the length
expression; (2) ACE's independently-ported `NormalizeCheckSmall`
unambiguously computes the full `v.Length()`; (3) acdream's own existing
port (`slideOffset.Length() < PhysicsGlobals.EPSILON → result = Vector3.Zero`)
already implements the sensible full-zero, full-length reading and there is
no report of it producing wrong behavior. This matches the project's
documented BN-artifact class (`feedback_bn_decomp_field_names.md`): a lost
FPU sum-of-squares reduced to one leftover operand load. **No change made.**
acdream's existing `slideLen < EPSILON → result = Vector3.Zero` stands.

## The no-contact-plane branches — verified, NOT changed

- No contact plane, no slide (0x0050a3de implicit else): `result` is
  returned unmodified. acdream: `branch = "no-cp"`, no mutation. **Match.**
- No contact plane, sliding active (0x0050a61e): `result -= sliding_normal *
  dot(result, sliding_normal)`. acdream: `branch = "no-cp-slide"`,
  `result -= ci.SlidingNormal * slidingAngle`. **Match.**

## Observed but OUT OF SCOPE: the missing block-offset correction

Retail's safety push-out (pc:272354, `LandDefs::get_block_offset`) and ACE's
port (`Transition.cs:75`, `LandDefs.GetBlockOffset(SpherePath.CheckPos.ObjCellID,
CollisionInfo.ContactPlaneCellID)`) both re-express the sphere center into
the CONTACT PLANE's cell-relative frame before computing `dist`, to handle
the case where the contact plane was recorded in a different (landblock-
adjacent) cell than `check_pos`'s current cell. acdream's port
(`TransitionTypes.cs:5602-5607`, both before and after this slice's fix)
uses `sp.GlobalSphere[0].Origin` directly with no block-offset correction.

This is a THIRD potential divergence in the same safety block, but it is
**not AD-65 or AD-66** and is not one of the "two fixes" the S4 contract
scopes — flagged here per the contract's "Anything outside AdjustOffset and
its tests" OUT-of-scope clause read narrowly (in scope location, out of
scope fix). Left unchanged; worth a future register row if the session lead
wants it filed.

## Constants

- `F_EPSILON` = `0.000199999995f` (retail's exact float32 bit pattern for
  "0.0002"). acdream's `PhysicsGlobals.EPSILON = 0.0002f` compiles to the
  identical bit pattern (both are "nearest float32 to decimal 0.0002") —
  no new constant needed, reused as-is.

## Deliverable summary (what changes, what doesn't)

| Arm | Retail | acdream before S4 | acdream after S4 |
|---|---|---|---|
| `collisionAngle <= 0` (into plane) | subtract full N component | same | **unchanged** |
| `collisionAngle > 0` (away from plane) | `snap_to_plane`: XY preserved, Z re-solved, epsilon no-op | subtract full N component (AD-65 bug) | **fixed: snap semantics** |
| Safety-push trigger | bare `radius - F_EPSILON` | `radius*N.z - F_EPSILON` (AD-66 bug) | **fixed: bare radius** |
| Safety-push zDist numerator | `(radius - dist) / N.z` | `(radius*N.z - dist) / N.z` (AD-66 bug) | **fixed: bare radius** |
| Safety-push sanity bound (`radius > \|zDist\|`) | bare `radius` | bare `radius` (already correct) | unchanged |
| Sliding-normal crease arm | cross + normalize + project | same | unchanged (verified) |
| No-contact-plane arms | subtract or no-op | same | unchanged (verified) |
| Block-offset correction in safety push | present (`get_block_offset`) | absent | **unchanged — out of S4 scope, flagged above** |