# Phase B.3 Complete — Movement and World Navigation Design

**Status:** Spec, 2026-04-12, brainstormed with user.
**Scope:** Make the physics collision engine and movement system fully functional: CellPortal-based indoor/outdoor transitions, multi-landblock boundary crossing, jump with momentum-preserving gravity arc, portal-space state machine for teleports, Setup.StepUpHeight, and scenery-on-road fix. Replaces the current "outdoor heightmap sampler with disabled indoor transitions" with a complete world-navigation system.
**Parent:** `docs/plans/2026-04-11-roadmap.md` — Phase B (Gameplay), sub-piece B.3 completion.
**Depends on:** Phase B.2 (player movement mode) — already shipped. Phase B.3 partial (TerrainSurface, CellSurface, PhysicsEngine skeleton) — already shipped.

## Goals

1. Walk through a doorway into a building (outdoor→indoor via CellPortal plane crossing).
2. Walk between rooms inside a building (indoor→indoor via CellPortal).
3. Walk back out of a building (indoor→outdoor via CellPortal with OtherCellId=0xFFFF).
4. Walk from one landblock to the next seamlessly.
5. Jump while walking with momentum-preserving arc.
6. Jump off a ledge and land on terrain below (gravity when not on ground).
7. Enter a game portal → portal-space state → arrive at destination.
8. Step-height from Setup.StepUpHeight (not hardcoded).
9. No trees/stones on roads.
10. ACE console shows no movement rejection errors.

## Non-goals

- Charge jump (hold Space for higher jump) — deferred.
- Wall sliding (deflecting off walls at oblique angles) — deferred.
- Swimming / water depth detection — deferred.
- NPC/entity collision (only terrain + cell surfaces) — deferred.
- BSP tree acceleration for polygon lookups — brute-force polygon iteration is sufficient at cell-level polygon counts (< 20 per cell).

## 1. Cell Transition System

### Data model

Each loaded EnvCell's portals are precomputed into portal planes at landblock-load time:

```csharp
public readonly record struct PortalPlane(
    Vector3 Normal,           // plane normal (from portal polygon vertices)
    float D,                  // plane distance (dot(normal, v0))
    uint TargetCellId,        // OtherCellId (0xFFFF = outdoor)
    uint OwnerCellId,         // the EnvCell that owns this portal
    PortalFlags Flags);       // PortalSide flag for disambiguation
```

Stored in `PhysicsEngine` per landblock alongside the existing `TerrainSurface` + `CellSurface` entries:
```csharp
sealed record LandblockPhysics(
    TerrainSurface Terrain,
    IReadOnlyList<CellSurface> Cells,
    IReadOnlyList<PortalPlane> Portals,  // NEW: all portals across all cells
    float WorldOffsetX,
    float WorldOffsetY);
```

Portal planes are computed at load time in `GameWindow.ApplyLoadedTerrainLocked` from `EnvCell.CellPortals` + `CellStruct.Polygons`:
1. For each EnvCell in the landblock
2. For each CellPortal in the cell
3. Look up `CellStruct.Polygons[portal.PolygonId]`
4. Extract the first 3 vertex positions (from `CellStruct.VertexArray`)
5. Transform to world space using `EnvCell.Position` (orientation + origin + landblock offset)
6. Compute plane: `normal = normalize(cross(v1-v0, v2-v0))`, `d = -dot(normal, v0)`
7. Store as `PortalPlane` with the portal's `OtherCellId`, `OwnerCellId`, and `Flags`

### Three transition types

**Outdoor → Indoor (entering a building):**
- Player is in an outdoor cell (cellId & 0xFFFF < 0x0100).
- Each frame, test the player's movement vector against all portal planes in the current landblock that belong to cells with `OtherCellId = 0xFFFF` (outside-facing portals — these are the building entry points viewed from outside).
- Crossing test: `sign(dot(normal, oldPos) + d) != sign(dot(normal, newPos) + d)`.
- On crossing: transition to the `OwnerCellId` of the portal (the EnvCell the doorway belongs to). Switch to that cell's `CellSurface` for Z resolution.

**Indoor → Indoor (room to room):**
- Player is in an indoor cell (cellId & 0xFFFF >= 0x0100).
- Test only the current cell's portals (not all portals in the landblock).
- `OtherCellId != 0xFFFF` — points to the adjacent room.
- On crossing: transition to the target cell's `CellSurface`.

**Indoor → Outdoor (exiting a building):**
- Same as indoor→indoor test, but `OtherCellId = 0xFFFF`.
- On crossing: switch back to `TerrainSurface.SampleZ` for Z resolution. Compute the outdoor cell ID from coordinates.

### Outdoor → Outdoor (landblock crossing)

No portals involved. When the candidate position falls outside the current landblock's [0, 192) local coordinate range, the existing `PhysicsEngine.Resolve` landblock-lookup loop picks up the adjacent landblock's `TerrainSurface`. This should work with the existing code — needs verification testing.

## 2. Jump + Gravity

### New state on PlayerMovementController

```csharp
float VerticalVelocity;          // current vertical speed (positive = up)
bool IsAirborne;                  // true from jump/fall until landing
const float JumpImpulse = 10f;   // tunable initial upward velocity
const float Gravity = 20f;        // downward acceleration per second squared
const float AirControlFactor = 0.2f;  // horizontal steering while airborne
```

### Per-frame logic

```
1. If on ground AND Space pressed AND NOT airborne:
     verticalVelocity = jumpImpulse
     isAirborne = true

2. If airborne:
     verticalVelocity -= gravity * dt
     candidateZ = position.Z + verticalVelocity * dt
     
     // Resolve ground Z at the candidate XY
     groundZ = resolve terrain/floor Z at (candidateX, candidateY)
     
     if candidateZ <= groundZ:
         // Landed
         position.Z = groundZ
         verticalVelocity = 0
         isAirborne = false
     else:
         position.Z = candidateZ
         // Skip terrain Z snap — still in the air
         
     // Horizontal input at reduced speed
     horizontal delta *= airControlFactor

3. If NOT airborne AND resolved terrain Z is significantly below
   current Z (> stepUpHeight gap):
     // Walked off a ledge — enter falling state
     isAirborne = true
     verticalVelocity = 0  // start falling, not jumping
```

### Server interaction

While airborne, still send `AutonomousPosition` heartbeats with the actual position. The server tracks the player's "in-air" state separately. `MoveToState` is sent at the start of the jump (motion command changes).

## 3. Portal Space State Machine

### States

```csharp
enum PlayerState { InWorld, PortalSpace }
```

### Flow

1. Server sends `PlayerTeleport(sequence)` game message.
2. `WorldSession.ProcessDatagram` fires a new `TeleportStarted(uint sequence)` event.
3. `GameWindow` handler: set `PlayerState = PortalSpace`.
4. In PortalSpace:
   - All WASD/mouse movement input is ignored.
   - No `MoveToState` / `AutonomousPosition` messages are sent.
   - The player entity is optionally hidden (set a flag to skip rendering it).
5. Server sends `UpdatePosition` with the new landblock + position.
6. `OnLivePositionUpdated` handler detects the position is far from the current location (different landblock) and:
   - Recenters the streaming controller on the new landblock.
   - Resolves the new position through PhysicsEngine.
   - Snaps the player entity to the resolved position.
   - Sets `PlayerState = InWorld`.
7. Send `LoginComplete` (GameAction 0x00A1) to tell the server "I've finished loading" — same message as initial login, reused for teleport completion (per holtburger's PlayerTeleport handler). Reset the `_loginCompleteSent` latch to allow this.

### TeleportStarted event on WorldSession

New opcode handler in `ProcessDatagram`:
```csharp
else if (op == 0xF7B0u)  // PlayerTeleport (GameEvent container)
{
    // Parse the teleport sequence from the event body.
    // Fire TeleportStarted event.
}
```

Note: `PlayerTeleport` may arrive as a `GameEvent` (opcode 0xF7B0) with an inner event type, not as a standalone game message. Check holtburger's `GameEvent` enum for the exact inner opcode. Implementation will read the reference code to determine the wire layout.

## 4. Remaining Fixes

### Setup.StepUpHeight

- `Setup` dat has a `float StepUpHeight` field.
- When entering player mode (Tab), read `setup.StepUpHeight` and set it on `PlayerMovementController.StepUpHeight`.
- If zero or missing, default to 2.0 (standard human height).

### Scenery-on-road fix

In `src/AcDream.Core/World/SceneryGenerator.cs`, the terrain type is extracted per vertex:
```csharp
uint terrainType = (uint)((raw >> 2) & 0x1F);
```

Road type in the raw terrain value has a specific bit pattern. Check if the vertex is a road terrain type and skip scenery generation:
```csharp
// Road check: terrain types with road flag set should not spawn scenery.
// The exact road type value needs to be verified against the
// Region.TerrainInfo dat data, but the road bit is typically
// indicated by specific terrain type indices that the original
// client excludes from scenery placement.
```

Implementation will verify the exact road terrain type value from the dat and add the exclusion check.

### PhysicsEngine refactoring

- Remove the `if (false)` disabled indoor-transition branch.
- Replace with real CellPortal plane-crossing logic from Section 1.
- Add `IReadOnlyList<PortalPlane> Portals` to `LandblockPhysics`.
- `Resolve` gains a `Vector3 oldPos` parameter (or derives it from `currentPos`) to test the movement vector against portal planes.
- Cell tracking: the engine needs to know which cell the player is currently in to test only that cell's portals (for indoor→indoor transitions). The `cellId` parameter already serves this purpose.

## Testing Strategy

### Unit tests (~20 new)

**Portal plane extraction:**
- Given 3 known vertices, assert correct plane normal and distance.
- Test crossing detection: position on each side of the plane → `sign` differs.
- Test no crossing: positions on the same side → `sign` matches.

**Indoor transition integration:**
- Construct a fake two-cell building (cell A with portal to cell B at a known plane).
- Start in cell A, move through the portal → assert cell ID changes to B.
- Move back through the portal → assert cell ID returns to A.

**Outdoor→indoor transition:**
- Construct a fake EnvCell with an outside-facing portal (OtherCellId=0xFFFF).
- Start outdoors, move through the portal → assert cell ID changes to the EnvCell.

**Indoor→outdoor transition:**
- Start inside the cell, move through the outside-facing portal → assert cell ID changes to outdoor.

**Landblock boundary crossing:**
- Two adjacent landblocks registered in the engine.
- Walk from X=190 to X=194 → assert the engine picks up the second landblock's terrain Z.

**Jump arc:**
- Start at Z=50 on flat terrain, jump → assert Z increases above 50.
- Continue frames → assert Z peaks then decreases.
- Assert landing: Z returns to 50, IsAirborne = false.

**Falling off ledge:**
- Terrain drops from Z=50 to Z=30 at a step. Walk off the edge.
- Assert: IsAirborne becomes true, Z decreases toward 30, lands at Z=30.

**Portal space state:**
- Simulate TeleportStarted → assert PlayerState = PortalSpace.
- Simulate UpdatePosition with new location → assert PlayerState = InWorld, position updated.

**Scenery road exclusion:**
- Construct terrain data with a road-type vertex.
- Assert SceneryGenerator produces no scenery at that vertex.

## Acceptance Criteria

Phase B.3 Complete is done when ALL of the following pass:

1. Walk outdoors on terrain following heightmap Z.
2. Walk from one landblock to the next seamlessly.
3. Walk through a doorway into a building (outdoor→indoor via CellPortal).
4. Walk around inside a building on the correct floor.
5. Walk back out of a building (indoor→outdoor via CellPortal).
6. Walk between rooms inside a building (indoor→indoor via CellPortal).
7. Jump while walking (momentum-preserving arc).
8. Jump off a ledge and land on terrain below.
9. Enter a game portal → portal-space state → arrive at destination.
10. Step-height read from Setup.StepUpHeight.
11. No trees/stones on roads.
12. ACE console shows no movement rejection errors.
13. All new unit tests pass (~20). Total test count increases.

## Open Questions (resolved during implementation)

- **Portal polygon vertex winding:** the plane normal direction determines which side is "inside." The `PortalFlags.PortalSide` flag disambiguates. Implementation will read ACViewer's `EnvCell.cs` to confirm the convention.
- **Outdoor→indoor portal detection radius:** testing every portal in the landblock each frame could be expensive with many buildings. If profiling shows this, add a spatial hash or AABB pre-filter. Expected to be fine for Holtburg (< 50 portals per landblock).
- **PlayerTeleport wire format:** may be a GameEvent (0xF7B0) with inner type, or a standalone message. Check holtburger's opcode table during implementation.
- **Exact road terrain type value:** verify from the Region.TerrainInfo dat during implementation.
- **Jump impulse / gravity tuning:** start with JumpImpulse=10, Gravity=20. Tune to match retail feel during visual verification.