acdream/docs/research/2026-06-24-sphere-intersects-pseudocode.md

CSphere::intersects_sphere — swept-sphere-vs-sphere pseudocode

Date: 2026-06-24
Task: Task 2 — true sphere collision primitive (collision-inclusion phase)

---

Oracles consulted

1. Named-retail decomp acclient_2013_pseudo_c.txt:

   • CSphere::collides_with_sphere @ 0x005369E0 — static overlap test
   • CSphere::intersects_sphere (primary) @ 0x00537A80 — the full 6-path dispatcher
   • CSphere::intersects_sphere (Position variant) @ 0x00537FD0

2. ACE C# port references/ACE/Source/ACE.Server/Physics/Sphere.cs:

   • CollidesWithSphere(Vector3 otherSphere, float radsum) — static overlap
   • FindTimeOfCollision(Vector3 movement, Vector3 spherePos, float radSum) — swept solve
   • IntersectsSphere(Vector3 center, float radius, Transition transition, bool isCreature) — 6-path dispatcher

---

CSphere::collides_with_sphere (static overlap test)

Retail @ 0x005369E0:

collides_with_sphere(this, disp_vec3, radsum_float):
    lenSq = disp_vec3.x² + disp_vec3.y² + disp_vec3.z²
    if radsum² > lenSq:  // i.e. lenSq < radsum²
        return 1 (true — overlapping)
    return 0 (false)

ACE equivalent: disp.LengthSquared() <= radsum * radsum
Note: retail uses > (strictly greater-than radsum²), ACE uses <=. These are the same predicate — the retail FPU instruction emits "collides" when radsum² is NOT less than lenSq, which is lenSq <= radsum².

---

FindTimeOfCollision (swept quadratic, from ACE)

ACE Sphere.FindTimeOfCollision(Vector3 movement, Vector3 spherePos, float radSum):

Interprets "mover starts at origin, travels by movement; target is at spherePos relative to mover".

distSq   = |movement|²           // if < EPSILON: no sweep (degenerate), return -1
nonCollide = |spherePos|² - radSum²   // if < EPSILON: already overlapping → no forward collision needed, return -1
similar  = -dot(spherePos, movement)  // projection of separation onto movement direction
disc     = similar² - nonCollide * distSq   // discriminant of quadratic
if disc < 0: return -1            // no real intersection
cDist    = sqrt(disc)
if similar - cDist < 0:
    return -(cDist + similar) / distSq
else:
    return -(similar - cDist) / distSq

This returns a time in the range [0, 1] for the first contact. A return of -1 means no hit (miss or already overlapping). Values > 1 mean the sweep doesn't reach the target within the movement step.

---

SweptSphereHitsSphere — our primitive (pure function)

Wraps FindTimeOfCollision with a clean bool/out API for the narrow-phase dispatch:

SweptSphereHitsSphere(moverCenter, moverRadius, sweepDelta, targetCenter, targetRadius, out float t):
    movement = sweepDelta              // vector the mover travels
    spherePos = targetCenter - moverCenter    // target relative to mover's start
    radSum = moverRadius + targetRadius
    t = (float) FindTimeOfCollision(movement, spherePos, radSum)
    return t > 0 && t <= 1

t is the parametric fraction of sweepDelta at which surfaces first touch. t <= 0: target is behind or already overlapping (use static test separately). t > 1: sweep misses (target too far in this step).

---

Retail dispatch order for Sphere objects

From CSphere::intersects_sphere @ 0x00537A80 — the same 6-path structure as for CylSpheres:

1. obstruction_ethereal || insert_type == PLACEMENT_INSERT:
   Static overlap test only (collides_with_sphere). Return Collided or OK.

2. step_down != 0:
   Delegates to step_sphere_down (for non-creature movers).

3. check_walkable != 0:
   Static overlap test. Return Collided or OK.

4. collide == 0:
   Sub-dispatch on object_info.state & 3 (Contact/OnWalkable):

   • Contact: step_sphere_up or slide_sphere
   • PathClipped: collide_with_point
   • Default: land_on_sphere or collide_with_point

5. collide != 0 + isCreature:
   Return OK (creatures don't block each other via sphere-sphere in this path).

6. collide != 0 + not creature:
   Full swept quadratic. Set contact plane, adjust check_pos.

For our narrow-phase dispatch in FindObjCollisionsInCell, the "narrow-phase Sphere branch" maps directly to ACE's IntersectsSphere — which acdream already implements for Cylinder objects via CylinderCollision. The sphere primitive just provides the swept check without the cylinder's height clipping.

---

Acdream adaptation note

The SweptSphereHitsSphere primitive is PURE (no Transition state). The actual 6-path dispatch (step-up, land-on, slide, etc.) is handled by the existing CylinderCollision infrastructure — for Sphere-typed shadow entries we call through the same dispatcher after the overlap check, using 3-D distance for the broad-phase (not XY-only cylinder distance).

The primitive's narrow phase: static overlap (CollidesWithSphere) is the gate; the swept quadratic from FindTimeOfCollision resolves the time-of-contact for the walkable landing path.

For the initial ship (Task 2), we implement the static overlap test in the dispatch (matching the obstruction_ethereal/check_walkable/Contact paths that don't use the swept form), plus SweptSphereHitsSphere for the swept narrow-phase. The full 6-path wiring for sphere objects mirrors the cylinder path already in CylinderCollision, extended to use 3-D distance instead of XY-only.