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.
- Landblock streaming never edits the live collision world incrementally.
  `PreparedLandblockCollisionGeneration` owns an off-side cache, CellGraph,
  engine snapshot, buildings, statics, and versioned retained-owner refloods.
  Retained means every non-suspended dynamic or adjacent-root static touching
  (or withdrawn from) the target prefix; only authored target-root statics are
  superseded. All scans and replacement construction run through bounded
  capture/seal cursors. `RuntimePhysicsState.CommitCollisionGeneration` does
  one final mutation-version check and activates the sealed generation without
  managed allocation on the single update thread. Cancellation tears down only
  the named staging generation. The old generation remains queryable until
  commit. See
  `docs/research/2026-07-31-atomic-collision-generation.md`.
- `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.