acdream/docs/superpowers/specs/2026-04-13-movement-completion-design.md

# Movement Completion — Design Spec

Complete Phase B.2/B.3: retail-faithful outdoor movement with proper
speed, jump, and full object collision.

**Methodology:** Decompile → pseudocode → cross-reference ACE → port.
The decompiled acclient.exe is ground truth. ACE (server) is an
interpretation aid. When they disagree, the decompiled code wins.

---

## Problem Statement

Current movement is a minimal MVP:
- Run speed hardcoded to `ForwardSpeed = 1.0` instead of skill-derived
  RunRate. Player moves at 4.0 m/s regardless of Run skill.
- No jump implementation despite physics formulas being ported.
- No object collision — player walks through trees, buildings, NPCs,
  and walls. CollisionPrimitives.cs is ported but completely unwired.

The result: movement doesn't feel like AC and the client is not
functionally playable.

---

## Architecture: Four Layers, Built Bottom-Up

```
Layer 4: Object-Object Collision (cell-based ShadowObject + per-object BSP)
Layer 3: Transition System (sphere-sweep pipeline from decompiled CTransition)
Layer 2: Physics Data Loading (PhysicsBSP + PhysicsPolygons from dats)
Layer 1: Movement Speed + Jump (wire skill values into existing physics)
```

Each layer ships independently with build+test green and visual
verification.

---

## Layer 1: Movement Speed + Jump

### Speed

**How retail works:**
1. Client sends MoveToState with `HoldKey.Run` (raw input).
2. Server computes RunRate from Run skill + encumbrance:
   `RunRate = (burdenMod * (runSkill / (runSkill + 200)) * 11 + 4) / 4`
   Capped at 4.5 when runSkill >= 800.
3. Server broadcasts UpdateMotion with `ForwardSpeed = RunRate`.
4. Client's `MotionInterpreter.apply_current_movement()` stores
   `MyRunRate = InterpretedState.ForwardSpeed`.
5. `get_state_velocity()` produces: `velocity.Y = RunAnimSpeed(4.0) * ForwardSpeed`.

**What we change:**
- When we receive our own UpdateMotion from the server, feed the
  ForwardSpeed into `MotionInterpreter.InterpretedState.ForwardSpeed`.
  The existing `apply_current_movement()` will update `MyRunRate`.
- `get_state_velocity()` already uses `MyRunRate` — no change needed
  in the velocity computation.
- The MoveToState we send already has `ForwardSpeed: 1.0` for run,
  which is correct (raw input speed, server replaces with RunRate).

**Burden system (deferred):**
`GetBurdenMod(burden)` where `burden = encumbrance / capacity`. This
affects both run speed and jump height. For the initial implementation,
assume burden = 0 (unencumbered). Wire burden when inventory is
implemented (Phase B.4+).

### Jump

**Retail jump flow:**
1. Spacebar press → start charging. Internal `extent` rises from 0.0
   toward 1.0 over ~1 second.
2. Spacebar release → `MotionInterpreter.jump(extent)`.
3. `jump()` calls `WeenieObj.InqJumpVelocity(extent, out vz)`.
4. Applies vertical velocity `vz` to PhysicsBody. Clears ground contact.
5. Client sends jump packet to server with extent value.

**Jump height formula (from decompiled + ACE cross-reference):**
```
GetJumpHeight(burden, jumpSkill, extent, scaling=1.0):
  extent = clamp(extent, 0, 1)
  height = GetBurdenMod(burden) * (jumpSkill / (jumpSkill + 1300) * 22.2 + 0.05) * extent
  height = max(height, 0.35)
  return height

InqJumpVelocity(extent):
  height = GetJumpHeight(burden, jumpSkill, extent, 1.0)
  vz = sqrt(height * 19.6)   // v = sqrt(2*g*h), g=9.8
```

**IWeenieObj implementation:**
Create `PlayerWeenie : IWeenieObj` that reads Run skill and Jump skill
from the WorldSession's cached character properties (sent in
CreateObject). Wire into `MotionInterpreter` constructor.

**Jump bar UI:** Deferred to Phase D (UI overlay). Internally we track
the charge float and jump on key release.

### Acceptance
- Run speed matches retail for the character's Run skill level.
- Walk speed is 3.12 m/s (fixed, no skill scaling).
- Spacebar hold + release produces a jump whose height scales with
  hold duration and Jump skill.
- Other players' movement speed looks correct (they use their own
  ForwardSpeed from UpdateMotion).

---

## Layer 2: Physics Data Loading

### What to load from dats

DatReaderWriter already parses these types. We just don't read them.

**Per GfxObj (collision mesh):**
- `PhysicsPolygons: Dictionary<ushort, Polygon>` — low-poly collision faces
- `PhysicsBSP: BSPTree` — BSP tree over those polygons
- `PhysicsSphere: Sphere` — bounding sphere for broad-phase

**Per CellStruct (indoor rooms):**
- `PhysicsBSP: PhysicsBSPTree` — room collision BSP (walls, floors)
- `CellBSP: CellBSPTree` — containment/portal BSP (point-in-cell)

**Per Setup (creatures/players):**
- `CylSphere: List<CylSphere>` — collision cylinders
- `Sphere: List<Sphere>` — fallback collision spheres
- `Height, Radius` — dimensions
- `StepUpHeight, StepDownHeight` — movement tolerances

### Storage

`PhysicsDataCache` — singleton, keyed by dat ID. Populated during
streaming alongside render mesh uploads. Shared across all instances
of the same GfxObj (same pattern as TextureCache).

```csharp
public sealed class PhysicsDataCache
{
    // Per-GfxObj physics mesh + BSP
    ConcurrentDictionary<uint, GfxObjPhysics> _gfxObjPhysics;

    // Per-CellStruct collision BSP (keyed by EnvCell dat ID)
    ConcurrentDictionary<uint, CellPhysics> _cellPhysics;
}
```

### BSP Tree Representation

Port BSP node types from the dat format. DatReaderWriter already
deserializes `PhysicsBSPNode` / `PhysicsBSPLeaf`. We wrap these in
query-friendly classes:

```csharp
public class PhysicsBSPTree
{
    BSPNode Root;

    // Core queries (ported from decompiled client):
    bool SphereIntersectsPoly(Sphere sphere, Vector3 movement, out CollisionResult result);
    bool FindWalkable(Sphere sphere, out Polygon walkable, out float adjustedZ);
    bool StepSphereUp(Sphere sphere, Vector3 up, out float stepHeight);
    bool SphereIntersectsSolid(Sphere sphere);   // for ethereal/placement checks
}
```

### Acceptance
- PhysicsBSP loaded for every GfxObj that has physics data.
- CellStruct physics BSP loaded for every EnvCell.
- Setup collision volumes (CylSphere) loaded for creature entities.
- No rendering impact — physics data is separate from render data.

---

## Layer 3: Transition System

### What it replaces

Current `PhysicsEngine.Resolve()` which only snaps Z to terrain/floor.

### Core types (from decompiled CTransition + ACE cross-reference)

**SpherePath** — movement descriptor threaded through the entire pipeline:
- `LocalSphere[0..1]` — player's 2 stacked collision spheres (body + head)
- `GlobalSphere[0..1]` — same in world space at check position
- `BeginPos / EndPos` — start and end of this frame's movement
- `CheckPos / CheckCell` — current candidate position being tested
- `Walkable` — polygon currently being walked on
- `StepDown / StepUp` flags
- `WalkableAllowance` — min Z-dot to count as walkable (~0.7)
- `CacheLocalSpaceSphere()` — transforms spheres into cell-local space for BSP queries

**Transition** — the driver:
- `ObjectInfo` — flags (OnWalkable, Contact, EdgeSlide, IsPlayer, step heights)
- `SpherePath` — movement descriptor
- `CollisionInfo` — results accumulator (ContactPlane, SlidingNormal)
- `FindTransitionalPosition()` — main entry point

**TransitionState** — per-step result:
- `OK` — no collision
- `Adjusted` — repositioned (step-up/down)
- `Slid` — sliding along surface
- `Collided` — hard block

### Algorithm: FindTransitionalPosition

Ported from decompiled FUN_005387c0:

```
1. Compute total_dist = distance(BeginPos, EndPos)
2. num_steps = ceil(total_dist / sphere_radius)
3. step_size = total_dist / num_steps
4. For each step:
   a. Advance CheckPos by step_size along movement direction
   b. TransitionalInsert(retries=3):
      - InsertIntoCell(CheckPos) → finds the ObjCell for this position
      - ObjCell.FindCollisions(transition):
        - FindEnvCollisions: BSP query against cell geometry
        - FindObjCollisions: iterate ShadowObject list, BSP each
      - CheckOtherCells: check neighboring cells the sphere overlaps
   c. If TransitionState == OK: continue to next step
   d. If Adjusted: validate step-up/step-down, retry
   e. If Slid: project velocity along SlidingNormal, retry
   f. If Collided: reject movement, keep previous position
5. Final CheckPos becomes new position
```

### Decompile-first requirement

Before writing any code:
1. Read FUN_005387c0 (CTransition::find_collisions) from chunk_00530000.c
2. Read the BSP traversal functions (0x539270, 0x53A550, 0x53A6A0)
3. Write pseudocode in `docs/research/transition_pseudocode.md`
4. Cross-reference ACE's `Transition.cs` for naming
5. Port from pseudocode

### Integration

Replace `PhysicsEngine.Resolve()` internals with `Transition.FindTransitionalPosition()`.
Keep the `PhysicsEngine` as the public API but delegate to Transition internally.
`PlayerMovementController` calls the same `PhysicsEngine.Resolve()` — the interface doesn't change.

### Acceptance
- Player cannot walk through terrain features (hills block movement).
- Player slides along walls instead of stopping dead.
- Step-up works (stairs, small ledges up to StepUpHeight).
- Step-down works (walking downhill maintains ground contact).
- Indoor room walls block movement.

---

## Layer 4: Object-Object Collision

### How retail finds nearby objects

No k-d tree. Cell-based ShadowObject system:
- Every entity registers into each ObjCell it overlaps
- Outdoor cells: 24m × 24m terrain grid cells
- Indoor cells: EnvCells
- During collision, iterate the current cell's shadow list

### ShadowObject Registration

During streaming, when an entity is placed:
1. Compute which cell(s) the entity's bounding sphere overlaps
2. Register a ShadowObject entry in each cell's list
3. On entity removal, deregister

For static entities (trees, buildings), this happens once at load time.
For moving entities (NPCs), update when they move (throttled, not per-frame).

### Per-Object Narrow Phase

In `FindObjCollisions`, for each object in the cell's shadow list:
1. Broad phase: does player bounding sphere overlap object bounding sphere?
2. Narrow phase (if yes):
   - If object has `PhysicsBSP`: full BSP query (buildings, trees, statics)
   - If object has `CylSphere`: cylinder-sphere intersection (creatures)
   - Else: sphere-sphere test

### Collision response

Same as environment: slide along the object's surface normal.
TransitionState `Slid` or `Collided` depending on angle.

### PK collision flag

Player-to-player collision only when both players are flagged as
Player Killers (`PlayerKillerStatus` from CreateObject properties).
Non-PK players pass through each other. This is a flag check in
`FindObjCollisions` before testing player-vs-player — easy to add
once the system works. **Deferred from initial implementation.**

### Acceptance
- Player cannot walk through trees.
- Player cannot walk through buildings (exterior walls block).
- Player cannot walk through static scenery objects.
- Player slides along objects (doesn't stop dead).
- NPCs block movement (cylinder collision).

---

## Implementation Order

| Step | Layer | What ships | Estimated complexity |
|------|-------|-----------|---------------------|
| 1 | L1 | RunRate from server, correct speed | Small — wire existing code |
| 2 | L1 | Jump with charge + skill-based height | Small — bind key, implement IWeenieObj |
| 3 | L2 | PhysicsDataCache populated from dats | Medium — read + cache BSP/polygons |
| 4 | L3 | Transition system core (env collision) | Large — decompile + pseudocode + port |
| 5 | L3 | Step-up / step-down / wall slide | Large — part of transition, complex response |
| 6 | L4 | ShadowObject registration | Medium — cell bucketing during streaming |
| 7 | L4 | Object collision in transition loop | Medium — wire into FindObjCollisions |

Steps 1-2 can ship immediately. Steps 3-5 are the critical path.
Steps 6-7 build on top of the working transition system.

---

## What We Already Have (reuse, don't rewrite)

- `CollisionPrimitives.cs` — 9 sphere/polygon functions, ported from decompiled. Wire into BSP leaf queries.
- `PhysicsBody.cs` — Euler integration, gravity, friction. Keep as-is.
- `MotionInterpreter.cs` — Motion state machine with correct constants. Wire IWeenieObj.
- `TerrainSurface.cs` — Heightmap Z sampling. Used by transition for outdoor cells.
- `CellSurface.cs` — Indoor floor Z. Used by transition for indoor cells.
- `PortalPlane.cs` — Portal crossing detection. Used by transition for cell transitions.

## What We Don't Build Yet

- Burden/encumbrance system (needs inventory, Phase B.4+)
- Jump stamina cost (needs stamina tracking)
- PK player-vs-player collision (flag check, easy to add later)
- Jump bar UI (Phase D)
- Dead reckoning for other players (separate issue, not collision)
- Projectile collision (spells/arrows, Phase E)