erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
acdream/memory/project_collision_port.md
Erik 0a429a980c docs(workflow): align CLAUDE.md + memory + roadmap with named-retail foundation 
CLAUDE.md edits (6 surgical ranges):
  - Goal section: introduce named-retail/ as primary; old chunks
    remain as fallback for chunk-by-chunk address-range navigation.
  - Workflow renamed to "grep named -> decompile -> verify -> port"
    with a new STEP 0 GREP NAMED FIRST. Decompile demoted to a
    fallback (Step 1) for the rare obfuscated/packed minority that
    pseudo-C lacks.
  - Function-map citation updated to point at symbols.json + the
    cross-port hand-curated table.
  - "Do not guess" rule strengthened: PDB has the answer for almost
    everything; guessing is now negligence.
  - Phase completion checklist accepts named symbols + addresses.
  - Reference hierarchy table gets a new top row pointing at
    docs/research/named-retail/ as the primary oracle for any
    AC-specific algorithm — beats every other reference.

memory/project_named_decompilation.md (new): evergreen crib-sheet
with file inventory, grep examples, hard rules. Pattern matches
project_ui_architecture.md.

memory/project_retail_research_index.md: updated preamble to point
named-retail/ as first stop; older slices remain useful for
pseudocode + C# port sketches.

memory/project_collision_port.md: rewrote the "Decompiled ground
truth" section to put named-retail/ first, chunks second. The
"DECOMPILE FIRST" mandate becomes "GREP NAMED FIRST, then DECOMPILE
FALLBACK".

docs/architecture/acdream-architecture.md: Guiding Principle text
updated to introduce named-retail as the primary decomp source.

docs/plans/2026-04-11-roadmap.md: new Phase R block — Retail
research infrastructure. R.1 (corpus, shipped a9a01d8), R.2
(pdb-extract, shipped 69d884a), R.3 (actestclient vendored,
shipped a9a01d8). All marked SHIPPED 2026-04-25.

Auto-loaded MEMORY.md index updated with a new entry pointing at
project_named_decompilation.md so post-compaction sessions inherit
the workflow change automatically.

Acceptance verified:
  - grep -c "named-retail" CLAUDE.md = 9 (>= 3 required)
  - grep -c "named-retail" MEMORY.md = 1
  - dotnet build green (docs-only commit, but verified)

Foundation phases A + B + C all landed. Next: Phase D files
ISSUES #8/#9/#11 + closes #10 (KillerNotification orphan parser).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 17:36:53 +02:00

6.3 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 (named-retail is now primary, 2026-04-25):

  • docs/research/named-retail/acclient_2013_pseudo_c.txt — grep for BSPTree::, BSPNode::, BSPLeaf::, CPolygon::, CCylSphere::, Transition::, CPhysicsObj::, SpherePath:: to find named bodies.
  • docs/research/named-retail/acclient.h — verbatim retail struct layouts for the BSP / Sphere / Transition types.
  • docs/research/named-retail/symbols.json — name↔address lookup.
  • docs/research/decompiled/chunk_00530000.c — older Ghidra fallback for BSP / Polygon / Sphere collision (FUN_xxx names).
  • docs/research/decompiled/chunk_00500000.c — older Ghidra fallback for PhysicsObj / transition callers.
  • docs/research/acclient_function_map.md — hand-curated cross-port index (ACE / ACME mappings + struct-offset notes).

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. GREP NAMED FIRST, then DECOMPILE FALLBACK. Search the named retail decomp first: grep -n "ClassName::Method" docs/research/named-retail/acclient_2013_pseudo_c.txt. For struct layouts: grep -n "^struct ClassName" docs/research/named-retail/acclient.h. Only if the named pseudo-C lacks a function (rare), fall back to the older docs/research/decompiled/ chunks via the function map at docs/research/acclient_function_map.md.

  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