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

131 lines
6.3 KiB
Markdown
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
Reference in a new issue View git blame Copy permalink