# Collision System Port — Status and Plan

## Current State (2026-04-14)

The collision system has been patched multiple times but does NOT match
retail. The user has explicitly requested a **full faithful port** of
the retail collision system — no shortcuts, no simplifications.

## What Went Wrong

Instead of porting the decompiled code line-by-line (as CLAUDE.md
mandates), I wrote simplified approximations:
- Static overlap instead of swept-sphere FindTimeOfCollision
- Custom FindObjCollisions instead of porting Sphere.IntersectsSphere
- Custom BSP query instead of porting BSPTree.find_collisions dispatcher
- Ad-hoc push-out instead of proper SlideSphere crease-projection
- Incremental patches that don't address root architectural issues

Each patch fixed one symptom but introduced new edge cases. The result
is a patchwork that handles ~60-70% of cases but fails on the rest.

## What Must Happen Next

**Delete the existing collision code and start fresh.** Port from ACE's
complete C# implementation, cross-referencing the decompiled code for
ground truth. ACE has the ENTIRE system already in C#:

### Files to port from ACE (in order):

1. **Sphere.cs** — `IntersectsSphere` (FUN_005387c0), `SlideSphere` (both variants), `StepSphereUp`, `StepSphereDown`, `LandOnSphere`, `CollideWithPoint`, `CollidesWithSphere`

2. **BSPTree.cs** — `find_collisions` (6-path dispatcher)

3. **BSPNode.cs** — `sphere_intersects_poly` (tree traversal with movement), `find_walkable`, `hits_walkable`, `sphere_intersects_solid`

4. **BSPLeaf.cs** — leaf-level polygon tests

5. **Polygon.cs** — `pos_hits_sphere`, `adjust_sphere_to_plane`, `check_walkable`

6. **Transition.cs** — `FindTransitionalPosition`, `TransitionalInsert`, `StepUp`, `StepDown`, `ValidateTransition`, `AdjustOffset`

7. **SpherePath.cs** — `SetCheckPos`, `AddOffsetToCheckPos`, `CacheLocalSpaceSphere`, `SetCollide`, `SetWalkable`, `SetNegPolyHit`

8. **CollisionInfo.cs** — `SetContactPlane`, `SetSlidingNormal`, `SetCollisionNormal`

9. **ObjectInfo.cs** — `ValidateWalkable`

10. **LandCell.cs** — `FindEnvCollisions` (outdoor terrain)

11. **EnvCell.cs** — `FindEnvCollisions` (indoor BSP)

12. **ObjCell.cs** — `FindObjCollisions`, `find_cell_list`

### ACE source locations:
- `references/ACE/Source/ACE.Server/Physics/Sphere.cs`
- `references/ACE/Source/ACE.Server/Physics/BSP/BSPTree.cs`
- `references/ACE/Source/ACE.Server/Physics/BSP/BSPNode.cs`
- `references/ACE/Source/ACE.Server/Physics/BSP/BSPLeaf.cs`
- `references/ACE/Source/ACE.Server/Physics/Polygon.cs`
- `references/ACE/Source/ACE.Server/Physics/Transition.cs`
- `references/ACE/Source/ACE.Server/Physics/SpherePath.cs`
- `references/ACE/Source/ACE.Server/Physics/Collision/CollisionInfo.cs`
- `references/ACE/Source/ACE.Server/Physics/Collision/ObjectInfo.cs`

### Decompiled ground truth:
- `docs/research/decompiled/chunk_00530000.c` — BSP, Polygon, Sphere collision
- `docs/research/decompiled/chunk_00500000.c` — PhysicsObj, transition callers
- `docs/research/acclient_function_map.md` — mapped functions

### Pseudocode (already written):
- `docs/research/transition_pseudocode.md` — full system documented

## What to Keep

- `CollisionPrimitives.cs` — 9 low-level functions already faithfully ported from decompiled code. These are CORRECT and match retail.
- `PhysicsDataCache.cs` — GfxObj/Setup/CellStruct physics data loading from dats. Correct.
- `ShadowObjectRegistry.cs` — cell-based spatial index. Correct concept, may need refinement.
- `TransitionTypes.cs` data structures — SpherePath, CollisionInfo, ObjectInfo, PhysicsGlobals. Mostly correct, may need field additions.
- `PhysicsBody.cs` — Euler integration. Correct.
- `MotionInterpreter.cs` — Motion state machine. Correct.
- `PlayerWeenie.cs` — Run/Jump formulas. Correct.

## What to Replace

- `BSPQuery.cs` — replace with faithful port of BSPTree/BSPNode/BSPLeaf
- `TransitionTypes.cs` Transition methods — replace FindTransitionalPosition, TransitionalInsert, FindEnvCollisions, FindObjCollisions, SlideSphere, AdjustOffset with faithful ports
- `PhysicsEngine.ResolveWithTransition` — may need restructuring

## Approach

1. Read ACE's Sphere.cs fully (it's the object collision dispatcher)
2. Read ACE's BSPTree.cs/BSPNode.cs/BSPLeaf.cs fully
3. Read ACE's Transition.cs fully
4. Port each class method-by-method, preserving ACE's logic exactly
5. Cross-reference each method against the decompiled function address
6. Test incrementally: terrain → indoor walls → objects → step-up → full