docs: collision port handoff — full retail system needed

Document current state (patchwork ~60-70%) and plan for clean port
from ACE's complete C# implementation. Lists all 12 files to port,
what to keep vs replace, and the correct approach.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

memory/project_collision_port.md

@@ -0,0 +1,96 @@
+# 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