acdream/docs/research/2026-06-24-collision-object-detection-vs-retail-deepdive-handoff.md

# Handoff — collision-object-detection vs retail: a unifying audit ("1 fix for all collision") — 2026-06-24

**Branch/worktree:** `claude/thirsty-goldberg-51bb9b`. Named-retail + references live in the MAIN repo
`C:\Users\erikn\source\repos\acdream\`.

## The ask (user, 2026-06-24)

> "Deep-dive in how we detect what objects have collision compared to retail. I expect/know there are
> deviations vs retail. Thorough checking of how retail checks what objects have collision and how it
> deviates from our implementation. This should be **1 fix for all collision**."

So: **NOT another whack-a-mole symptom fix.** Build the retail model of *"which objects collide, and how
the engine decides that"*, map acdream's model against it, enumerate every deviation, and design **one
unified, retail-faithful collision-inclusion mechanism** that replaces acdream's scattered per-channel
hand-rolled filters. This is a research → brainstorm → multi-commit phase. **Brainstorm-gate it**
(`superpowers:brainstorming`) before writing the port. **No guess-patches** — this is the DO-NOT-RETRY
collision area; grep named-retail FIRST, decompile, pseudocode, port, conformance-test.

## Why now — the pattern the 2026-06-24 session exposed

This session fixed three collision bugs, and **two of them were the *same shape*: an ad-hoc per-channel
filter that diverges from retail's unified model.**

| Commit | Issue | The deviation it revealed |
|---|---|---|
| `afd5f2a` | #138-B | Avatar relocated into a dead landblock during PortalSpace (lifecycle, not inclusion) |
| `49d743f` | #146 | **Building collision shell cached at a stale `_liveCenter` frame** — terrain re-bases per apply, the building cache didn't. Streaming-relative-frame staleness. |
| `9743537` | #147 | **Portal-less buildings (city/perimeter walls) skipped** by `if (building.Portals.Count == 0) continue;` — a *transit-feature* filter that wrongly gated *collision*. We used "has a doorway" to decide "is solid". |

#147 is the smoking gun for the user's intuition: **acdream decides "does this object collide" with
per-channel attributes that have nothing to do with retail's actual predicate.** There are almost
certainly more of these. The goal is to replace the lot with retail's real rule.

## The retail model — what to research (the oracle)

Retail (`docs/research/named-retail/acclient_2013_pseudo_c.txt` — grep by `class::method`) decides
collision in two layers. Map BOTH precisely:

### A. The inclusion predicate — "does this object participate in collision at all?"
- **`PhysicsState` flags** on `CPhysicsObj` (grep `acclient.h` for the `PhysicsState` enum). The
  load-bearing ones:
  - **`ETHEREAL`** → no collision (pass-through). Confirm acdream honors this on EVERY channel, not just
    interaction-pick. (See `[[project_interaction_pipeline]]` ETHEREAL-alone exemption — that's
    *selection*, not *collision*; verify the collision side.)
  - **`HAS_PHYSICS_BSP` / `HAS_PHYSICS_BSP_PS`** → the object collides via its BSP; otherwise via a
    cylinder/sphere. This is the binary dispatch (`[[feedback_retail_binary_dispatch]]`,
    `BspOnlyDispatch` flag `0x00010000`).
  - Other gates to check: `STATIC`, `REPORT_COLLISIONS`, `IGNORE_COLLISIONS`, `MISSILE`, `NODRAW` (NODRAW
    is render-only — confirm it does NOT gate collision), `SCRIPTED_COLLISION`.
- **The object's physics shape**: does it have a `CPhysicsBSP` (collision BSP) vs a `CylSphere`? Retail
  uses whatever the dat/weenie says — it does NOT fabricate collision from a render mesh AABB. (acdream's
  `IsPhantomGfxObjSource` / mesh-AABB-fallback is a known divergence — #101.)

### B. The registration / dispatch model — "where does the engine look for colliders?"
- **`CPhysicsObj::FindObjCollisions`** (the per-tick collider) — picks BSP-only vs cyl+sphere on the
  flag above, iterates the **per-cell `shadow_object_list`**.
- **`CObjCell::add_shadows_to_cells` / `find_cell_list` / `calc_cross_cells`** — an object registers a
  *shadow* into every cell its sphere overlaps; the per-cell list is the broad phase. (acdream ported
  this as the A6.P4/BR-7 `ShadowObjectRegistry` flood — see `[[project_physics_collision_digest]]`.)
- **`CBuildingObj::find_building_collisions`** (`0x006b5300`) — the building **shell** BSP, tested on
  `part_array->parts[0]`, **independent of the portal list**. (This session's #147 fix aligned acdream
  to this.) `CLandBlock::init_buildings` (`0x0052fd80`) builds one building per origin landcell.
- **Terrain**: `CLandCell::find_env_collisions` (terrain polys) + the eye-side cull.
- **EnvCell (indoor)**: `CEnvCell::find_env_collisions` (`0x0052c100`) — the cell's own BSP; **no
  building leg** (acdream matches this at `TransitionTypes.cs:2807`).

**Deliverable from this layer:** a single table — for each object class (terrain, building shell,
EnvCell shell, static stab, scenery, server weenie/door/NPC/item, missile) — *what makes it collide in
retail* (which flags, which shape, which registration), with the named-retail function + address.

## The acdream model — the code map to audit against the table

acdream has **separate channels with different inclusion filters**. Walk each and record its de-facto
"does it collide" predicate, then diff against retail's:

1. **Terrain** — `PhysicsEngine.SampleTerrainWalkable` / `TransitionTypes.cs:2229` (`// no terrain loaded
   → allow pass-through`, `:2247`). Re-bases per apply via `AddLandblock(origin)` (so no #146-style
   staleness). Filter: terrain residency only.
2. **Buildings** — `TransitionTypes.FindBuildingCollisions` (`:2805`), `PhysicsDataCache.CacheBuilding`
   (`:441`), the cache loop (`GameWindow.cs` ~`:6958`). Post-session: re-bases per apply (#146) +
   includes portal-less (#147). Remaining filter: `ModelId == 0 → inert` (`:2813`); the `[bldg-channel]`
   probe (`ACDREAM_PROBE_BUILDING`, logs `bldOrigin`) is the live lens.
3. **Shadow objects** (statics, scenery, server weenies) — `Core/Physics/ShadowObjectRegistry.cs`
   (per-cell flood, BR-7). Registration sites: `GameWindow.cs` `ShadowObjects.Register*` (~`:7196–7526`),
   `RefloodLandblock` (`:7595`), `RegisterMultiPart` (`:3835`). Server weenies register via
   `OnLiveEntitySpawnedLocked` → Register. **Filters to scrutinize for divergence:**
   - `LandblockLoader.IsSupported` (GfxObj/Setup mask only) — does it match retail's "has a physics
     shape"? What about `0x0D`/other types?
   - **mesh-AABB fallback** / `IsPhantomGfxObjSource` (#101) — acdream fabricates a collision box from
     the render mesh when no physics BSP exists. **Retail does not.** Prime deviation.
   - cyl-vs-BSP dispatch (A6.P7, `Transition.BspOnlyDispatch`) — verify it matches `HAS_PHYSICS_BSP_PS`.
   - editor-marker degrade-hide (#136) — those are render-hidden; confirm collision treatment matches.
   - ETHEREAL: does the live-spawn path exclude ETHEREAL weenies from shadow registration?
4. **EnvCell (indoor)** — cell BSP via the transition; `CellTransit` per-cell iteration.
5. **The streaming-relative frame** — #146 proved a cached collision transform can go stale on recenter.
   **Audit every cached collision transform** (shadow objects? EnvCell? portal planes?) for the same
   staleness; or fold into the #145 cell-relative-frame port so collision frames can NEVER go stale.

## Suspected deviations to confirm/refute (seed list)

- **Attribute-as-filter category errors** (the #147 pattern): grep the registration/collision paths for
  any `continue`/skip gated on a NON-collision property (portals, name, render flags, degrade, item
  type). Each is a candidate divergence.
- **mesh-AABB phantom collision** (#101) — retail-absent; should it exist at all?
- **ETHEREAL not honored on the collision side** of one or more channels.
- **`IsSupported`/type filters** excluding objects retail collides with (or including ones it doesn't).
- **Stale cached collision transforms** beyond buildings (#146 class).
- **Static vs dynamic registration mismatch** — landblock stabs/scenery vs server weenies taking
  different inclusion paths with different rules.

## The unifying target ("1 fix for all collision")

One retail-faithful **collision descriptor per object**, derived once from its `PhysicsState` + physics
shape (BSP vs cyl, or none = ethereal/no-collide), and **one registration rule** (overlap-based per-cell
shadow lists) used by **every** channel — replacing the per-channel ad-hoc filters. Concretely the
output is likely: (a) a single `ObjectCollides(state, shape)` predicate matching retail's flag logic,
(b) a single registration path all object sources funnel through, (c) deletion of the mesh-AABB phantom
fallback and the attribute-as-filter skips. Expect multi-commit; gate with brainstorming; conformance-
test against named-retail golden values + the existing replay harnesses (`CellarUp*`, `HouseExitWalk*`,
`CornerFlood*`, the new `Issue147ArwicBuildingsDumpTests` fixture).

## Method (mandatory — CLAUDE.md workflow)

1. `superpowers:brainstorming` to scope the phase + agree the unified model BEFORE code.
2. **Grep named-retail FIRST** for every function in the retail-model table; decompile via Ghidra MCP
   (`patchmem.gpr`, port 8081) for any single function that's noisy in the bulk text.
3. Cross-reference **ACE** `Physics/Common` (PhysicsObj, ObjCell, shadow lists) + **ACViewer**
   `Physics/Common` + **holtburger** `spatial/physics.rs` for the client-side read.
4. Write pseudocode (`docs/research/*_pseudocode.md`), port faithfully, conformance-test, then one
   comprehensive user visual gate.

## Apparatus already in place (use it, don't rebuild)
- `ACDREAM_PROBE_BUILDING` → `[bldg-channel]` (now logs `bldOrigin`) + `[entity-source]` (BSP vs Cylinder
  classification per static — directly shows what collision shape each object got).
- `ACDREAM_CAPTURE_RESOLVE=<path>` → per-player-resolve JSONL (grounded / contactPlane / collisionNormal
  per frame). Heavy (FPS) — short targeted runs only; the `analyze_*` streaming-tally pattern works
  (255k records in seconds).
- `ACDREAM_PROBE_ENT` / `EntityVanishProbe` → avatar draw-set lifecycle (#138-B).
- `Issue147ArwicBuildingsDumpTests` → the dat-dump pattern for `LandBlockInfo.Buildings`/`.Objects`
  (portal counts, model ids); clone it for any landblock/object-class inventory.
- Live client: user `notan` / `MittSnus81!`, ACE `127.0.0.1:9000`; graceful close before rebuild.

## Context — what shipped this session (the motivation)
`afd5f2a` #138-B avatar-vanish, `49d743f` #146 building-frame re-base, `9743537` #147 portal-less-wall
collision. ISSUES #146 DONE, #147 walls DONE (terrain-3%-grounded residual re-scoped LOW — verify it's
even real before acting; see #147). The deep #145 cell-relative-frame port is still its own future phase
and is the natural home for "collision frames can never go stale."

## Paste-ready prompt for the next session

> Deep-dive + unifying fix: **how retail decides which objects have collision, vs acdream.** Read this
> handoff (`docs/research/2026-06-24-collision-object-detection-vs-retail-deepdive-handoff.md`) and the
> physics digest (`claude-memory/project_physics_collision_digest.md`) FIRST. Goal: build retail's
> collision-inclusion model (the `PhysicsState`/ETHEREAL/HAS_PHYSICS_BSP predicate + the per-cell
> shadow-list registration + the building-shell/terrain/EnvCell channels — grep named-retail, cite
> addresses), map acdream's per-channel filters against it (terrain / FindBuildingCollisions /
> ShadowObjectRegistry / EnvCell / mesh-AABB phantom / IsSupported / the cyl-BSP dispatch), enumerate
> every deviation, and propose ONE unified retail-faithful collision-inclusion mechanism to replace the
> ad-hoc filters. **Report-first / brainstorm-gated, no guess-patches** (DO-NOT-RETRY collision area).
> Recent precedent (the per-channel filter divergences this is meant to end): #146 (`49d743f`),
> #147 (`9743537`).