acdream/docs/superpowers/specs/2026-05-20-indoor-bsp-worldorigin-fix-design.md

# Indoor BSP world-origin / world-rotation fix (Bug B)

**Date:** 2026-05-20
**Status:** Spec — awaiting user review before plan-writing.
**Phase:** Indoor walking, ContactPlane retention investigation, slice 1 of 2.
**Author:** Claude Opus 4.7 (session sad-aryabhata-2d2479).

## Summary

The indoor cell BSP collision call at `TransitionTypes.cs:1442` invokes
`BSPQuery.FindCollisions` without passing the cell's world rotation or
world origin. The parameters default to `Quaternion.Identity` and
`Vector3.Zero`. Inside `BSPQuery`, the per-poly world-space plane built
by `TransformVertices` + `BuildWorldPlane` for `StepSphereDown` (Path 3)
and Path 4 land-on-surface uses those defaults, so for any rotated or
translated indoor cell the produced plane is in cell-local space, not
world space. The resulting `ContactPlane` is written with the cell's
local floor-Z as its `D` component (often ≈ 0) instead of the world
floor-Z (e.g. -94.02 for Holtburg cottages). The bug fires every
step-down inside an indoor cell during movement.

Fix: decompose `cellPhysics.WorldTransform` once, pass the rotation as
`localToWorld` and the translation as `worldOrigin` to
`BSPQuery.FindCollisions`. Mirrors the existing correct pattern at
`TransitionTypes.cs:1808` for object BSP queries.

## Problem

### Evidence

Session capture 2026-05-20, `launch-cp-probe.log` (51k lines, 39k
`[cp-write]` entries), Holtburg-area walking scenarios. Caller
distribution of `[cp-write]` lines:

```
37470 caller=PhysicsEngine.ResolveWithTransition:583   ← per-tick seed
  456 caller=BSPQuery.FindCollisions:1615              ← Path 4 land
  320 caller=BSPQuery.StepSphereDown:1123              ← Path 3 step-down
  251 caller=Transition.FindTransitionalPosition:663   ← sub-step reset
  224 caller=Transition.ValidateWalkable:1629          ← outdoor / synth
  146 caller=Transition.ValidateWalkable:1606
   76 caller=Transition.TransitionalInsert:853
   76 caller=Transition.TransitionalInsert:815
```

Smoking-gun excerpt from an indoor walking sequence:

```
... ContactPlane: n=(0,0,1) D=-94.020   ← correct floor (from prior tick)
[indoor-bsp] cell=0xA9B40150 wpos=(132.628,16.893,94.500) result=OK
[indoor-walkable] cell=0xA9B40150 wpos=(132.628,16.893,94.500) result=MISS
[cp-write] ContactPlaneValid: True -> False caller=Transition.FindTransitionalPosition:663
[indoor-bsp] cell=0xA9B40150 wpos=(132.628,16.893,94.500) result=OK
[indoor-walkable] cell=0xA9B40150 wpos=(132.628,16.893,94.500) result=MISS
[cp-write] ContactPlaneValid: False -> True caller=BSPQuery.StepSphereDown:1123
[cp-write] ContactPlane: n=(0,0,1) D=-94.020 -> n=(0,0,1) D=-0.000 caller=BSPQuery.StepSphereDown:1123
[cp-write] LastKnownContactPlane: n=(0,0,1) D=-94.020 -> n=(0,0,1) D=-0.000 caller=BSPQuery.StepSphereDown:1123
[indoor-bsp] cell=0xA9B40150 wpos=(132.628,16.893,93.750) result=Adjusted poly=n/a
```

Before the step-down, `ContactPlane.D = -94.020` (the Holtburg cottage
floor at world Z = 94.02). After `StepSphereDown:1123` writes,
`ContactPlane.D = -0.000` (the world Z=0 plane). The plane's `Normal` is
unchanged at `(0, 0, 1)` because the cell rotation is identity-ish along
its Z axis for this particular cell — but the `D` component
(`-Dot(Normal, worldVertices[0])`) is wrong by the cell's full world-Z
offset.

The corrupted plane writes back to `body.ContactPlane` via
`PhysicsEngine.ResolveWithTransition:625`. The next tick's seed at
`PhysicsEngine.ResolveWithTransition:583` propagates the corruption:

```
[cp-write] ContactPlane: 0.000 -> n=(0,0,1) D=-0.000 caller=PhysicsEngine.ResolveWithTransition:583
```

320 corrupt step-down writes per session.

### Why this hadn't surfaced before

The Phase 2 indoor-walkable synthesis (`TryFindIndoorWalkablePlane`,
shipped 2026-05-19) applies `cellPhysics.WorldTransform` manually after
the BSP returns (TransitionTypes.cs:1260-1268). So the 6 HIT cases out
of 616 indoor BSP OK results wrote a *correct* plane via the synthesis
path; the 610 MISS cases fell through to outdoor terrain (also writes
a "correct" but wrong-Z plane). The 320 BSP-internal `StepSphereDown`
writes are independent of the synthesis path — they fire from inside
`BSPQuery.FindCollisions` during Path 3 step-down, where the
caller-supplied `localToWorld` + `worldOrigin` are used directly to
build the plane. That code path was never inspected during the
Phase-2 work.

## Root cause

`BSPQuery.FindCollisions` signature (BSPQuery.cs:1505-1516):

```csharp
public static TransitionState FindCollisions(
    PhysicsBSPNode?                      root,
    Dictionary<ushort, ResolvedPolygon>  resolved,
    Transition                           transition,
    DatReaderWriter.Types.Sphere         localSphere,
    DatReaderWriter.Types.Sphere?        localSphere1,
    Vector3                              localCurrCenter,
    Vector3                              localSpaceZ,
    float                                scale,
    Quaternion                           localToWorld = default,
    PhysicsEngine?                       engine       = null,
    Vector3                              worldOrigin  = default)
```

`localToWorld` defaults to `Quaternion.Identity` (treated by the body
at line 1520) and `worldOrigin` defaults to `Vector3.Zero`. Both are
used inside the BSP traversal to convert local-space hit polygons into
world-space planes:

```csharp
// BSPQuery.cs:1120-1123 (StepSphereDown, Path 3)
var worldNormal = TransformNormal(polyHit.Plane.Normal, localToWorld);
var worldVertices = TransformVertices(polyHit.Vertices, localToWorld, scale, worldOrigin);
var worldPlane = BuildWorldPlane(worldNormal, worldVertices);
collisions.SetContactPlane(worldPlane, path.CheckCellId, false);
```

```csharp
// BSPQuery.cs:439-449 (TransformVertices)
private static Vector3[] TransformVertices(
    ReadOnlySpan<Vector3> vertices,
    Quaternion            localToWorld,
    float                 scale,
    Vector3               worldOrigin)
{
    var result = new Vector3[vertices.Length];
    for (int i = 0; i < vertices.Length; i++)
        result[i] = Vector3.Transform(vertices[i] * scale, localToWorld) + worldOrigin;
    return result;
}
```

```csharp
// BSPQuery.cs:451-456 (BuildWorldPlane)
private static Plane BuildWorldPlane(Vector3 worldNormal, ReadOnlySpan<Vector3> worldVertices)
{
    float d = worldVertices.Length > 0
        ? -Vector3.Dot(worldNormal, worldVertices[0])
        : 0f;
    return new Plane(worldNormal, d);
}
```

With `localToWorld = Identity` and `worldOrigin = Zero`, `worldVertices[i] == localVertices[i]`. For a cell-local floor poly at local Z ≈ 0, `worldPlane.D ≈ 0` instead of the cell's actual world floor Z.

## Indoor BSP call sites

Grep for `BSPQuery.FindCollisions\s*\(` in `src/AcDream.Core/Physics/`
returns two callers:

| Line | Call site | localToWorld | worldOrigin |
|---|---|---|---|
| `TransitionTypes.cs:1442` | Indoor cell BSP | `Quaternion.Identity` | (not passed → `Vector3.Zero`) |
| `TransitionTypes.cs:1808` | Object BSP (`FindObjCollisions`) | `obj.Rotation` | `obj.Position` |

Only `:1442` is broken. `:1808` correctly passes the object's
rotation + position because objects always have non-trivial world
transforms.

## Fix

Single change at `TransitionTypes.cs:1442`. Decompose
`cellPhysics.WorldTransform` to extract the rotation quaternion and
translation vector, then pass them to `FindCollisions`. Pattern
mirrors `:1808`:

```csharp
// New: decompose the cell's world transform.
if (!Matrix4x4.Decompose(
        cellPhysics.WorldTransform,
        out _,                        // scale ignored — see Risks
        out var cellRotation,
        out var cellOrigin))
{
    // Decompose returned false: matrix has shear or non-uniform scale.
    // Log + fall through with safe defaults (current broken behavior).
    // Should never happen for valid EnvCell data.
    Console.WriteLine(System.FormattableString.Invariant(
        $"[indoor-bsp] WARN cellPhysics.WorldTransform did not decompose cleanly for cell 0x{sp.CheckCellId:X8}"));
    cellRotation = Quaternion.Identity;
    cellOrigin   = cellPhysics.WorldTransform.Translation;
}

// Existing FindCollisions call, updated args.
var cellState = BSPQuery.FindCollisions(
    cellPhysics.BSP.Root,
    cellPhysics.Resolved,
    this,
    localSphere,
    localSphere1,
    localCurrCenter,
    Vector3.UnitZ,
    scale: 1.0f,
    localToWorld: cellRotation,
    engine: engine,
    worldOrigin: cellOrigin);
```

## Verification

### Pre-fix probe data (baseline)

- `BSPQuery.StepSphereDown:1123` cp-writes: 320, all with `D` close to
  the cell's local floor Z (≈ 0) instead of world Z (≈ -94.02 for
  Holtburg).
- `[indoor-bsp]` lines: 616 OK, 230 Adjusted, 31 Slid, 8 Collide.

### Post-fix expected probe data

Rerun the same scenarios (cottage entry, indoor standstill, cellar
descent, 2nd-floor walk) with `ACDREAM_PROBE_CONTACT_PLANE=1
ACDREAM_PROBE_INDOOR_BSP=1`. Expect:

- `BSPQuery.StepSphereDown:1123` cp-writes: still ~320 but with `D`
  matching the world floor Z of the cell where the step-down fired.
  Sample expected line:
  `[cp-write] ContactPlane: n=(0,0,1) D=-94.020 -> n=(0,0,1) D=-94.020 caller=BSPQuery.StepSphereDown:1123`
  — i.e., the write would be a no-op (suppressed by the property-
  setter's value-equality guard) because the new write matches the
  prior tick's seed value. In practice the write count drops sharply
  because the value-equality suppression hides duplicate writes.
- `[indoor-bsp]` Adjusted/OK distribution should stay similar; Slid /
  Collide should change only at the margin (the corrupt CP previously
  may have triggered spurious wall-collide downstream).
- Visual: 2nd-floor walking should stop intermittent falling-stuck on
  random spots (the BSP-internal step-down now writes correct planes
  during movement). Stationary case (cellar entry, cottage standstill)
  may still glitch — that's Bug A, out of scope for this slice.

### Unit test

`tests/AcDream.Core.Tests/Physics/BSPQueryTests.cs` — add
`StepSphereDown_RotatedTranslatedCell_WritesWorldSpacePlane`:

1. Fixture: a single-poly BSP at cell-local Z = 0.5, single floor
   triangle at cell-local Z = 0.0.
2. Cell `WorldTransform`: rotation = `Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI / 4)` (45° around world Z), translation = `(100, 50, 94)`.
3. Sphere at cell-local (0, 0, 0.5), radius 0.48.
4. Call `BSPQuery.FindCollisions` with the decomposed rotation +
   translation.
5. Assert: returned `TransitionState.Adjusted`, and
   `transition.CollisionInfo.ContactPlane.D == -94.0` within 1e-4
   tolerance (= world Z of the floor poly after applying the cell's
   translation).

### Visual verification scenarios

Re-use from prior phase:

1. **Cottage entry** (outdoor → indoor) — `[cell-transit]` line shows
   transition; no immediate falling-stuck.
2. **Indoor standstill** in a single-floor Holtburg cottage — stable
   grounding for 10 seconds. *Stationary case — may still glitch.*
3. **2nd-floor walking** — climb stairs, walk around upstairs.
   *Primary success criterion for Bug B alone.*
4. **Cellar descent** — walk down stairs to cellar. *Stationary glitch
   may persist; movement should be smoother.*
5. **Single-floor cottage regression check** — confirm M1 baseline is
   not regressed.

## Risks

### R1: Cell scale

`Matrix4x4.Decompose` returns the cell's scale as the first out-param.
This spec uses the hardcoded `scale: 1.0f` regardless. If any indoor
cell ships with a non-unit scale (extremely unlikely — never observed
in the AC dat), the produced world plane will be wrong.

Mitigation: low-confidence assumption, leave for now. If a probed run
ever shows a cell with scale ≠ 1, add a Console.WriteLine warning at
the decompose site and file a follow-up issue.

### R2: Decompose returns false

`Matrix4x4.Decompose` returns false if the matrix has shear or other
non-decomposable parts. EnvCell `WorldTransform` is always a rigid
rotation + translation per the dat format. If decompose fails, we log
a warning and fall back to `Quaternion.Identity` + the matrix's
`.Translation` — better than `Vector3.Zero` but still wrong if cell
is rotated.

### R3: BSP traversal still uses `localSphere` (local space)

The fix changes the OUTPUT transformation (local poly → world plane)
but the INPUT to BSP (`localSphere`) is already in cell-local space.
That's correct and matches retail: the BSP traversal itself works in
local coordinates, but the `set_contact_plane` write must produce a
world-space plane (the equivalent retail call is `Plane::localtoglobal`
at acclient_2013_pseudo_c.txt:323708 / :323921). The fix aligns our
behavior with retail's.

### R4: Bug A still in play

After Bug B fix, `TryFindIndoorWalkablePlane` still runs every indoor
OK frame, still 99% MISS, still falls through to outdoor terrain
backstop and writes the wrong plane for the stationary case. The
M2-blocker scenarios may not be fully fixed by Bug B alone. Bug A is a
separate phase (next slice).

## Out of scope (file as follow-ups if observed)

- **Bug A (per-frame synthesis):** Remove `TryFindIndoorWalkablePlane`
  + outdoor-terrain fallthrough from the indoor OK branch. Separate
  phase after Bug B retest. ISSUES #83 stays OPEN until that ships.
- **Sub-step `contact_plane_valid = 0` reset at FindTransitionalPosition:663:**
  Retail also does this (decomp :273733). Not a bug. The 251 writes
  per session are expected.
- **Per-tick seeding at PhysicsEngine.cs:583:** Working correctly. Not
  touched in this slice. The 37,470 writes are the
  `SetContactPlane(plane, cellId, isWater)` helper firing 4-6 sub-field
  writes per call × ~6-9k resolve calls.
- **`AcDream.Core.Physics.Transition.FindObjCollisions` (line 1808):**
  Already correct. Not touched.
- **Bug B in other callers:** Grep confirmed only `:1442` and `:1808`
  call `BSPQuery.FindCollisions`. The 1850 `FindCollisions` overload
  is a different signature (takes raw polygons, not resolved).
  Out-of-scope for this slice; visit if probe data ever surfaces a
  symptom traceable to it.

## Retail anchors

- `BSPTREE::find_collisions` — decomp `acclient_2013_pseudo_c.txt:323924`.
  Inside the BSP traversal, calls `COLLISIONINFO::set_contact_plane`
  with a world-space plane (after `Plane::localtoglobal` at :323921).
- `BSPTREE::step_sphere_down` — decomp `:323565`. Same pattern:
  `localtoglobal` (at :323708) before `set_contact_plane`.
- `Plane::localtoglobal` — applies the cell's world transform to the
  plane before storing. Our `TransformNormal` + `TransformVertices` +
  `BuildWorldPlane` chain is the equivalent.

## Files touched

- `src/AcDream.Core/Physics/TransitionTypes.cs` — one call site at
  `:1442`, ~10 new lines for the Decompose + arg pass.
- `tests/AcDream.Core.Tests/Physics/BSPQueryTests.cs` — one new test
  `StepSphereDown_RotatedTranslatedCell_WritesWorldSpacePlane`,
  ~30 lines including fixture setup.

No other code touched. The `[cp-write]` probe stays in place (still
useful for retest verification + future Bug A work).

## Commit shape

Single commit:

```
fix(physics): pass cell world-transform to indoor BSP collision

Indoor cell BSP queries at TransitionTypes.cs:1442 were calling
BSPQuery.FindCollisions with Quaternion.Identity + defaulted
Vector3.Zero worldOrigin. Inside the BSP, Path 3 (step_sphere_down)
and Path 4 (land-on-surface) use those params to build the
world-space ContactPlane. Result: planes written with D ≈ 0 instead
of the cell's world floor Z (e.g. -94.02 for Holtburg cottages).
320 corrupt CP writes per Holtburg session.

Fix: decompose cellPhysics.WorldTransform once at the call site,
pass the rotation as localToWorld and the translation as
worldOrigin. Mirrors the existing correct pattern at :1808
(FindObjCollisions, passes obj.Rotation + obj.Position).

Retail oracle: BSPTREE::find_collisions (acclient_2013_pseudo_c.txt:323924)
calls Plane::localtoglobal at :323921 before set_contact_plane.
Our TransformNormal + TransformVertices + BuildWorldPlane chain is
the equivalent — it just needs the right rotation + origin.

Spec: docs/superpowers/specs/2026-05-20-indoor-bsp-worldorigin-fix-design.md.
Evidence: launch-cp-probe.log capture 2026-05-20, [cp-write] probe.

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