acdream/memory/project_collision_port.md

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 (MANDATORY — per CLAUDE.md)

For EVERY function:

1. DECOMPILE FIRST. Find the matching function in the decompiled client (docs/research/decompiled/). Use the function map at docs/research/acclient_function_map.md. If not mapped, search by characteristic constants or struct offsets.

2. CROSS-REFERENCE ACE. Read ACE's C# port of the same function. ACE provides naming and structure. Note any differences.

3. WRITE PSEUDOCODE. Translate the decompiled C into readable pseudocode BEFORE porting to C#. Add to docs/research/collision_port_pseudocode.md.

4. PORT FAITHFULLY. Translate pseudocode to C# line-by-line. Same variable names, same control flow, same boundary conditions. Do NOT "improve" or "simplify" the algorithm.

5. VERIFY. When ACE and the decompiled code disagree, the decompiled code wins. Document the difference.

Execution order:

1. Sphere collision (Sphere.cs) — FUN_005387c0 and sub-functions
2. BSP tree (BSPTree/Node/Leaf) — find_collisions dispatcher
3. Polygon tests (Polygon.cs) — pos_hits_sphere, adjust_sphere_to_plane
4. Transition orchestrator (Transition.cs) — FindTransitionalPosition
5. Cell collision (LandCell/EnvCell/ObjCell) — FindEnvCollisions, FindObjCollisions
6. Wire into PhysicsEngine.ResolveWithTransition
7. Test: terrain → indoor walls → objects → step-up → every object type