docs: session handoff + collision port mandate in memory

Session 2026-04-14 summary: rendering rebuild complete, movement
speed+jump+facing working, collision partially working but needs
full retail port.

Memory updated with explicit user feedback: no more patching
collision, must port from decompiled code faithfully per CLAUDE.md.

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

memory/project_collision_port.md

@@ -86,11 +86,35 @@ ground truth. ACE has the ENTIRE system already in C#:
 - `TransitionTypes.cs` Transition methods — replace FindTransitionalPosition, TransitionalInsert, FindEnvCollisions, FindObjCollisions, SlideSphere, AdjustOffset with faithful ports
 - `PhysicsEngine.ResolveWithTransition` — may need restructuring
 
-## Approach
+## Approach (MANDATORY — per CLAUDE.md)
 
-1. Read ACE's Sphere.cs fully (it's the object collision dispatcher)
+For EVERY function:
-2. Read ACE's BSPTree.cs/BSPNode.cs/BSPLeaf.cs fully
+
-3. Read ACE's Transition.cs fully
+1. **DECOMPILE FIRST.** Find the matching function in the decompiled
-4. Port each class method-by-method, preserving ACE's logic exactly
+   client (`docs/research/decompiled/`). Use the function map at
-5. Cross-reference each method against the decompiled function address
+   `docs/research/acclient_function_map.md`. If not mapped, search
-6. Test incrementally: terrain → indoor walls → objects → step-up → full
+   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

memory/project_session_2026_04_14.md

@@ -0,0 +1,75 @@
+# Session Handoff — 2026-04-14
+
+## What shipped this session
+
+### Rendering rebuild (5 steps, all complete)
+- Step 1: Instanced mesh rendering (DrawElementsInstanced, 800+ FPS)
+- Step 2: Terrain chunk batching (16×16 ACME-style chunks)
+- Step 3: AdjustPlanes lighting (ACME constants)
+- Step 4: EnvCell portal visibility (BFS, conditional depth clear)
+- Step 5: Animation already in instanced pipeline
+
+### Movement (Layer 1 — working)
+- Run speed from PlayerWeenie RunRate formula (Run skill 200 → 9.5 m/s)
+- Charged jump with proper physics arc + server packet (0xF61B)
+- Facing direction quaternion convention (AC heading via holtburger)
+- Jump apex velocity zeroing bug fixed (SmallVelocity threshold)
+- Airborne momentum preservation (no velocity replacement while jumping)
+
+### Collision (partially working — needs full rewrite)
+- ShadowObjectRegistry cell-based spatial index
+- PhysicsDataCache stores GfxObj BSP + Setup CylSphere + CellStruct BSP
+- BSPQuery with 6-path dispatcher (attempted but incomplete)
+- CylSphere collision for trees/rocks
+- SlideSphere crease-projection for wall sliding
+- Multiple bug fixes (broad-phase, push-out, corner stuck, safety margins)
+
+### Infrastructure
+- docs/bugs.md for tracking known issues
+- Movement completion design spec + implementation plan
+
+## What did NOT work
+
+The collision system was built by patching symptoms instead of porting
+the retail code faithfully. After ~10 iterations of fixes, it handles
+~60-70% of cases but still clips through some buildings, trees, and
+objects. The user explicitly requested a full retail port — no shortcuts.
+
+## Build/test state
+- `dotnet build`: green, 0 errors
+- `dotnet test`: 470 passed (361 core + 109 net), 0 failures
+- All commits on main
+
+## What to do next
+
+**PORT THE RETAIL COLLISION SYSTEM FROM SCRATCH.**
+
+The full plan is in `memory/project_collision_port.md`. The approach:
+
+1. Read the decompiled function (ground truth)
+2. Cross-reference ACE's C# (naming aid)  
+3. Write pseudocode
+4. Port line-by-line to C#
+5. When ACE and decompiled disagree, decompiled wins
+
+### Files to port (ACE → acdream):
+- `Sphere.cs` → sphere-vs-sphere collision dispatcher (FUN_005387c0)
+- `BSPTree.cs` → find_collisions 6-path dispatcher
+- `BSPNode.cs` / `BSPLeaf.cs` → BSP traversal with movement
+- `Polygon.cs` → pos_hits_sphere with FindTimeOfCollision
+- `Transition.cs` → FindTransitionalPosition, TransitionalInsert
+- `SpherePath.cs` → sphere state management
+- `LandCell.cs` → outdoor terrain collision
+- `EnvCell.cs` → indoor room collision
+- `ObjCell.cs` → object collision + cell enumeration
+
+### What to keep:
+- CollisionPrimitives.cs (9 functions, faithfully ported from decompiled)
+- PhysicsDataCache.cs (dat loading — correct)
+- ShadowObjectRegistry.cs (cell bucketing — correct concept)
+- PhysicsBody.cs, MotionInterpreter.cs, PlayerWeenie.cs (correct)
+
+### What to replace:
+- BSPQuery.cs — simplified, not retail-faithful
+- TransitionTypes.cs Transition methods — patched, not retail-faithful
+- PhysicsEngine.ResolveWithTransition — may need restructuring