erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
acdream/memory/project_collision_port.md
Erik 6c618937cb 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>
2026-04-14 14:04:14 +02:00

4.5 KiB
Raw Blame History

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