acdream/memory/project_collision_port.md

Collision System Port - Status and Plan

Current State (2026-04-29)

The collision system is no longer a pure placeholder and should not be treated as "delete everything and start over." A partial retail transition port exists:

• PhysicsEngine.ResolveWithTransition is the active player movement resolver.
• BSPQuery contains a partial retail-style BSP dispatcher.
• TransitionTypes carries the active SpherePath, CollisionInfo, transition, step, contact, and partial slide logic.
• PhysicsDataCache loads GfxObj, Setup, and CellStruct physics data.
• ShadowObjectRegistry gives the resolver a broadphase over nearby objects.
• TerrainSurface uses triangle-aware terrain contact.

This foundation is useful, but it is not complete retail collision parity. The project now tracks the remaining work as Phase L.2 - Movement & Collision Conformance:

• Plan: docs/plans/2026-04-29-movement-collision-conformance.md
• Roadmap owner: docs/plans/2026-04-11-roadmap.md
• Tactical follow-ups: docs/ISSUES.md #30-#34

Durable Lesson

Do not guess at AC physics, movement packets, terrain/cell ownership, or collision constants. The previous patchwork failures came from simplified approximations:

• static overlap instead of swept-sphere transition behavior
• custom object collision instead of retail CSphere / CCylSphere
• incomplete BSP dispatch
• ad-hoc push-out instead of retail slide / edge / precipice handling
• server "no rubber-band" treated as proof of local collision correctness

The named retail decomp is now the primary source. Search docs/research/named-retail/acclient_2013_pseudo_c.txt by class::method before using older decompiled chunks or reference repos.

Active Approach

Continue by conformance lanes rather than rewriting blindly:

1. Truth & diagnostics (L.2a). Add local placement/contact/cell, object-hit, outbound-packet, server echo, and correction-delta probes.
2. Movement wire/contact authority (L.2b). Fix contact byte and full-cell truth before using ACE acceptance as evidence.
3. Transition parity (L.2c). Port edge-slide, cliff-slide, precipice-slide, step-up/down slide, and NegPolyHit dispatch.
4. Shape fidelity (L.2d). Finish CSphere / CCylSphere semantics, live-entity shapes, and building object identity.
5. Cell ownership (L.2e). Port CELLARRAY, find_cell_list, check_other_cells, adjust_check_pos, low-cell updates, and cell_bsp.
6. Real-DAT and live observer conformance (L.2f). Promote every synthetic case to real-world fixtures and retail-observer checks.

What To Preserve

• CollisionPrimitives.cs low-level helpers, while auditing remaining shape gaps against named retail.
• PhysicsDataCache.cs DAT-backed collision data loading.
• ShadowObjectRegistry.cs broadphase concept.
• TransitionTypes.cs data structures and partial transition port.
• BSPQuery.cs partial dispatcher as the current porting surface.
• PhysicsBody.cs, MotionInterpreter.cs, and PlayerWeenie.cs foundations.

Known Gaps

• Full CELLARRAY and adjacent-cell ownership are missing.
• cell_bsp is not yet a first-class runtime owner.
• Building portal transit and building entry/exit collision are incomplete.
• edge_slide, cliff_slide, precipice_slide, and NegPolyHit behavior are incomplete.
• Live entity shape fidelity is simplified.
• Outbound movement contact/cell fields can be overconfident.
• Routine local/server correction diagnostics are missing.

Retail Anchors

Primary:

• docs/research/named-retail/acclient_2013_pseudo_c.txt
• docs/research/named-retail/acclient.h
• docs/research/named-retail/symbols.json

Key names:

• CTransition::find_transitional_position
• CTransition::transitional_insert
• CTransition::step_up
• CTransition::step_down
• CTransition::edge_slide
• CTransition::cliff_slide
• SPHEREPATH::step_up_slide
• SPHEREPATH::precipice_slide
• SPHEREPATH::adjust_check_pos
• CTransition::check_other_cells
• CObjCell::find_cell_list
• CPhysicsObj::is_valid_walkable
• CBuildingObj::find_building_collisions
• CCellStruct::sphere_intersects_cell
• CCylSphere::intersects_sphere
• CSphere::intersects_sphere
• CSphere::slide_sphere

Older fallback:

• docs/research/decompiled/chunk_00530000.c
• docs/research/decompiled/chunk_00500000.c
• docs/research/acclient_function_map.md

Reference aids:

• references/ACE/Source/ACE.Server/Physics/
• references/holtburger/ for movement wire behavior
• references/AC2D/ for the older client-side movement packet reference

Mandatory Workflow

For every AC-specific function:

1. Grep named retail first.
2. Cross-reference ACE / holtburger / AC2D where relevant.
3. Write readable pseudocode before porting.
4. Port faithfully; do not simplify.
5. Add conformance tests.
6. Integrate surgically into the active L.2 lane.
7. Verify with synthetic tests, real-DAT fixtures, and live observer evidence.