acdream/docs/research/2026-07-07-csphere-collision-family-pseudocode.md

CSphere collision family — retail pseudocode (port prep)

Date: 2026-07-07 · Trigger: the user's live report — "in a packed crowd of monsters it's too easy to get stuck; you can't wiggle free. In retail the same crowd leaves a bit more room to shuffle/slide out." Humanoid creatures/players collide as body spheres (Setup.Spheres, no CylSpheres → ShadowShapeBuilder.FromSetup emits ShadowCollisionType.Sphere), so the crowd contact runs through Transition.SphereCollision — which was a hand-rolled 3-D wall-slide with a forced fixed de-penetration, NOT a port of the retail CSphere::intersects_sphere family. Register row TS-45 already documented this divergence and predicted the exact symptom ("absorbs to a zero offset … until an oblique input clears it"); it was deferred to avoid disturbing the freshly-gated #171 sticky-melee work.

This is the direct analog of the 2026-07-05 CCylSphere family port (docs/research/2026-07-05-ccylsphere-collision-family-pseudocode.md). Same shape, same siblings, same ACE-as-readable-oracle method. The transition loop (transitional_insert) is unchanged — only the per-contact Sphere response is replaced.

Sources: named-retail pseudo-C (addresses below) = ground truth; references/ACE/Source/ACE.Server/Physics/Sphere.cs = readable cross-reference (settles the x87 garbles). One ACE quirk noted in §8.

Retail function inventory

Function	Address	pseudo-C line
CSphere::intersects_sphere(Position*, scale, CTransition*, isCreature) — wrapper	0x00537fd0	:321881
CSphere::intersects_sphere(CTransition*, isCreature) — dispatcher	0x00537a80	:321678
CSphere::collides_with_sphere(disp, radsum)	0x005369e0	:320964
CSphere::step_sphere_up	0x00537900	:321611
CSphere::slide_sphere(sp, ci, normal, currCenter) — core crease slide	0x00537440	:321403
CSphere::land_on_sphere	0x005379a0	:321642
CSphere::collide_with_point	0x00537230	:321327
CSphere::step_sphere_down	0x00536d20	:321133

Dispatch context — CPhysicsObj::FindObjCollisions (0x0050f050, pc:276776): isCreature = (target.state & MISSILE_PS 0x40) || target.IsCreature() (pc:276846-276853; ACE PhysicsObj.cs:409). The target's shape is chosen CylSphere-first, else Sphere (pc:276868/276917; ACE PhysicsObj.cs:414-436). Humanoids have GetNumCylsphere()==0 + GetNumSphere()>0 → the sphere branch, isCreature passed in.

1. collides_with_sphere (0x005369e0) — pure 3-D overlap

collides_with_sphere(disp, radsum):        // disp = globalSphere.center − this.center
    return |disp|² <= radsum²              // full 3-D distance (unlike CCylSphere's XY+Z-band)

radsum at every call site = globalSphere.radius + this.radius − F_EPSILON (ε shaved ONCE in the dispatcher preamble, 0x00537acd). The ε is what makes resting exactly touching a non-overlap, so a shuffle that ends flush against a monster settles instead of re-colliding every frame. The hand-rolled version omitted this ε — the first stickiness source.

2. Dispatcher (0x00537a80)

intersects_sphere(this, CTransition* t, isCreature):   // this.center in world frame
    sp = t.sphere_path;  oi = t.object_info
    s0 = sp.global_sphere[0];  disp0 = s0.center − this.center
    if sp.num_sphere > 1: s1 = sp.global_sphere[1]; disp1 = s1.center − this.center
    radsum = s0.radius + this.radius − F_EPSILON

    // ── branch 1: placement / ethereal — detection only ──
    if (sp.obstruction_ethereal || sp.insert_type == PLACEMENT_INSERT):
        if collides(disp0) → COLLIDED
        if num_sphere>1 && collides(disp1) → COLLIDED
        return OK

    // ── branch 2: step-down probe — land on the top ──
    if (sp.step_down):
        if isCreature → OK                 // §8.1 — you never stand ON a creature/missile
        return step_sphere_down(this, s0, disp0, radsum)

    // ── branch 3: walkable probe — occupancy blocks ──
    if (sp.check_walkable):
        if collides(disp0) → COLLIDED
        if num_sphere>1 && collides(disp1) → COLLIDED
        return OK

    // ── branch 4: normal sweep (collide flag clear) ──
    if (!sp.collide):
        if (oi.state & (CONTACT|ON_WALKABLE)):             // grounded
            if collides(disp0) → step_sphere_up(this, disp0, radsum)
            if num_sphere>1 && collides(disp1) → slide_sphere(this, disp1, sphereNum=1)
        elif (oi.state & PATH_CLIPPED):
            if collides(disp0) → collide_with_point(this, s0, radsum, 0)
        else:                                              // airborne
            if collides(disp0) → land_on_sphere(this)
            if num_sphere>1 && collides(disp1) → collide_with_point(this, s1, radsum, 1)
        return OK

    // ── branch 5: collide-flag re-test — exact-TOI cap landing ──
    if isCreature → OK                     // §8.1 — never land ON a creature/missile
    if !collides(disp0) && !(num_sphere>1 && collides(disp1)) → OK
    movement = sp.global_curr_center[0] − s0.center − block_offset(cur→check)
    radsum += F_EPSILON
    lenSq = |movement|²
    diff  = −dot(movement, disp0)
    if |lenSq| < F_EPSILON → COLLIDED
    t = sqrt(diff² − (|disp0|² − radsum²)·lenSq) + diff       // quadratic solve for TOI
    if t > 1: t = diff·2 − t
    time = t / lenSq
    timecheck = (1 − time)·sp.walk_interp
    if timecheck >= sp.walk_interp || timecheck < −0.1 → COLLIDED
    movement *= time
    disp0 = (disp0 + movement) / radsum
    if !is_walkable_allowable(disp0.z) → OK                   // too steep to rest on
    contactPt = s0.center − disp0·s0.radius
    ci.set_contact_plane(Plane(n=disp0, d=−dot(disp0, contactPt)), is_water=1)
    ci.contact_plane_cell_id = sp.check_pos.objcell_id
    sp.walk_interp = timecheck
    sp.add_offset_to_check_pos(movement, s0.radius)
    return ADJUSTED

State bits (verified against our ObjectInfoState): CONTACT=0x1, ON_WALKABLE=0x2, PATH_CLIPPED=0x8. Note branch 5's landing surface is a tilted plane (n = disp0, the sphere-to-sphere direction) — unlike the cylinder's flat top — because a sphere top is curved.

3. step_sphere_up (0x00537900)

step_sphere_up(this, disp0, radsum):
    radsum += F_EPSILON
    if (oi.step_up_height < radsum − disp0.z)         // too tall to step over
        → slide_sphere(this, disp0, 0)
    n = sp.global_curr_center[0] − this.center
    if CTransition::step_up(t, n) → OK
    else → sp.step_up_slide(t)

For a full-height creature the head clearance radsum − disp0.z far exceeds step_up_height (~0.4 m) → always slide_sphere. This is the grounded-crowd path: slide, don't stop.

4. slide_sphere (grounded) — the wiggle-room primitive

The grounded foot/head hit reduces to CSphere::slide_sphere (0x00537440), which acdream already has as Transition.SlideSphere(normal, currPos, sphereNum) (Ghidra-confirmed via #116). It computes the collision normal n = global_curr_center[sphereNum] − this.center, normalizes, then projects the displacement onto the crease = cross(n, contactPlane.normal) — the tangent where the monster's side meets the ground — and slides ALONG it. Returns SLID (or COLLIDED when the projected offset degenerates < ~1.41 cm).

This is the whole fix. The hand-rolled version projected onto the plane ⊥ the raw 3-D normal and then FORCE-pushed to a fixed combinedR + 0.01 m shell (radial de-penetration). Radial pushes from neighbours on opposite sides cancel/fight; the crease slide moves you tangentially toward the gap.

slide_sphere(this, disp, sphereNum):
    n = sp.global_curr_center[sphereNum] − this.center
    if normalize_check_small(n) → COLLIDED
    return SlideSphere(n, sp.global_curr_center[sphereNum], sphereNum)   // shared crease slide

5. land_on_sphere (0x005379a0) — airborne foot hit

land_on_sphere(this):
    n = sp.global_curr_center[0] − this.center
    if normalize_check_small(n) → COLLIDED
    sp.set_collide(n)                        // backup + Collide flag → next attempt runs branch 5
    sp.walkable_allowance = LANDING_Z (0.0871557)
    return ADJUSTED

Identical shape to CCylSphere::land_on_cylinder.

6. collide_with_point (0x00537230) — PathClipped / airborne head hits

collide_with_point(this, checkSphere, radsum, sphereNum):
    globalOffset = sp.global_curr_center[sphereNum] − this.center
    if !PerfectClip:
        if !normalize_check_small(globalOffset): ci.set_collision_normal(globalOffset)
        return COLLIDED
    // PerfectClip → exact TOI reposition (missiles only; §8.2)
    blockOffset = get_block_offset(cur, check)
    checkOffset = checkSphere.center − global_curr_center[sphereNum] + blockOffset
    collisionTime = find_time_of_collision(checkOffset, globalOffset, radsum + F_EPSILON)
    if collisionTime < F_EPSILON || collisionTime > 1 → COLLIDED
    collisionOffset = checkOffset·collisionTime − checkOffset
    old_disp = collisionOffset + checkSphere.center − this.center
    ci.set_collision_normal(old_disp / radsum)
    sp.add_offset_to_check_pos(old_disp, checkSphere.radius)
    return ADJUSTED

Non-PerfectClip = set_collision_normal + COLLIDED (decomp-verified). The PerfectClip TOI tail is dead code in M1.5 (no mover sets PerfectClip) — same status as the cylinder family's AP-83.

7. step_sphere_down (0x00536d20) — land on the top during a step-down probe

step_sphere_down(this, s0, disp0, radsum):
    if !collides(disp0) && !(num_sphere>1 && collides(disp1)) → OK
    stepDown = sp.step_down_amt · sp.walk_interp
    if |stepDown| < F_EPSILON → COLLIDED
    radsum += F_EPSILON
    val = sqrt(radsum² − (disp0.x² + disp0.y²))          // curved-top height at this XY
    scaledStep = (val − disp0.z) / stepDown
    timecheck = (1 − scaledStep)·sp.walk_interp
    if timecheck >= sp.walk_interp || timecheck < −0.1 → COLLIDED
    interp = stepDown · scaledStep
    disp0 = (disp0.x, disp0.y, disp0.z + interp) / radsum
    if disp0.z <= sp.walkable_allowance → OK              // too steep — sphere top is a dome
    contactPt = disp0·this.radius + this.center
    ci.set_contact_plane(Plane(n=disp0, d=−dot(disp0, contactPt)), is_water=1)
    ci.contact_plane_cell_id = sp.check_pos.objcell_id
    sp.walk_interp = timecheck
    sp.add_offset_to_check_pos((0,0,interp), checkSphere.radius)
    return ADJUSTED

Gated OFF for creatures at the dispatcher (branch 2: isCreature → OK), so in M1.5 this only lands the player on non-creature Sphere-shape statics. Ported for completeness/faithfulness (ACE Sphere.cs:617).

8. Divergences + settled ambiguities (register-relevant)

1. isCreature gates "stand-on/land-on" (branches 2 and 5). A creature or missile is a solid you push against horizontally but never rest on vertically. Retail short-circuits both to OK for isCreature (0x00537b8c / 0x00537af5). Port verbatim.
2. PerfectClip TOI tail is dead in M1.5 — no mover arms PerfectClip (players never do). The load-bearing path is non-PerfectClip set_collision_normal + COLLIDED (decomp-verified). Same status/row style as the cylinder family's AP-83; re-decompile 0x00537230 in Ghidra before shipping missiles (F.3).
3. is_water=1 on contact planes is RETAIL (0x00536ecf / branch-5 site; set_contact_plane arg3 → contact_plane_is_water). Port verbatim; do not "fix" — same as the cylinder family §8.1.
4. Block offset = 0 in branch 5 / collide_with_point: retail subtracts the cur→check landblock offset; acdream's physics frame is continuous world-space → 0. Standing adaptation (same note as SlideSphere's gDelta and the cylinder family §8.3).
5. ACE bug NOT copied: ACE Sphere.cs has no equivalent of the cylinder family's foot-vs-head disp mixup; the grounded head slide passes globSphere_ (the head sphere) at IntersectsSphere:348 — correct. Retail 0x00537ec4 agrees. No divergence here.
6. normalize_check_small = normalize; returns true (fail) when |v| < F_EPSILON — maps to our existing NormalizeCheckSmall.

9. acdream port surface

Transition.SphereCollision(ShadowEntry, SpherePath, bool isCreature) becomes the branch-2/3/4/5 dispatcher body (branch 1 ethereal keeps the existing early-OK consume + the caller's Layer-2 override, identical to the cylinder family). New private siblings mirror the Cyl* set: SphereCollidesWithSphere, SphereStepSphereUp, SphereSlideSphere, SphereLandOnSphere, SphereCollideWithPoint, SphereStepSphereDown. Reused as-is: the shared SlideSphere (crease projection), DoStepUp (= CTransition::step_up), SpherePath.StepUpSlide, NormalizeCheckSmall, CollisionInfo.SetContactPlane/SetCollisionNormal. The caller (FindObjCollisionsInCell, Sphere branch) computes isCreature = (obj.State & 0x40) != 0 || (obj.Flags & IsCreature) != 0 and passes it in. The BspOnlyDispatch gate and the ethereal step-down skip sit ABOVE this dispatch and are unaffected. Retires TS-45.