acdream/docs/superpowers/specs/2026-04-12-player-movement-design.md

# Phase B.2 — Player Movement Mode Design

**Status:** Spec, 2026-04-12, brainstormed with user.
**Scope:** A new player-controlled movement mode where WASD walks the character on collision-resolved terrain, the server sees valid movement, other clients see the character at the correct position, and the character plays walk/run/turn/idle animations locally. Toggled with Tab; coexists with the existing fly and orbit camera modes.
**Parent:** `docs/plans/2026-04-11-roadmap.md` — Phase B (Gameplay), sub-piece B.2.
**Depends on:** Phase B.3 (physics collision engine) — already shipped.

## Goals

1. Walk the player character on the server with WASD controls.
2. The server accepts the movement (no rejection / rubber-banding).
3. Other clients (original AC client or another acdream instance) see the character at the correct position.
4. The character plays walk/run/turn/idle animations locally (not sliding).
5. Third-person chase camera follows behind the character.
6. Mouse + A/D keyboard turning rotates the character; the turn is sent to the server.
7. Toggle between player mode and fly mode with Tab.

## Non-goals

- Jump (physics arc + landing — adds gravity state complexity, deferred).
- Combat stance switching (deferred to Phase B.4+).
- Indoor movement (B.3's PhysicsEngine supports it; we just don't test it in the acceptance criteria).
- NPC/entity collision (only terrain + EnvCell floor collision via PhysicsEngine).
- Smooth position interpolation for other players' movement (existing `UpdatePosition` snap behavior is acceptable for now).

## Input Mapping (Player Mode Active)

| Key | Action |
|---|---|
| **W / S** | Walk forward / backward (~4 u/s) |
| **Shift + W / Shift + S** | Run forward / backward (~7 u/s) |
| **A / D** | Turn left / right (keyboard turning) |
| **Z / X** | Strafe left / right |
| **Mouse X** | Turn (mouse turning, same yaw axis as A/D) |
| **Mouse Y** | Adjust chase camera pitch (look up/down) |
| **Tab** | Exit player mode, return to fly mode |

Speed values are approximate — the exact values should match what ACE's `MovementHandler` accepts. Check `references/ACE/Source/ACE.Server/` and `references/holtburger/` for the validated run/walk rates.

## Outbound Server Messages

### `MoveToState` (GameAction, opcode 0xF61C)

Sent when the player's motion state *changes*: starts walking, stops, starts turning, changes speed (walk↔run), starts strafing.

**Payload (per holtburger `MoveToStateActionData`):**
- `RawMotionState`:
  - `flags: RawMotionFlags` — bitmask of which fields are present
  - `current_hold_key: Option<u32>` — hold key (Run = shift held)
  - `current_style: Option<u32>` — combat stance (NonCombat for MVP)
  - `forward_command: Option<u32>` — WalkForward (0x0005) / RunForward (0x0007)
  - `forward_speed: Option<f32>` — movement speed multiplier
  - `sidestep_command: Option<u32>` — SideStepRight (0x000F) / SideStepLeft (0x0010)
  - `sidestep_speed: Option<f32>`
  - `turn_command: Option<u32>` — TurnRight (0x000D) / TurnLeft (0x000E)
  - `turn_speed: Option<f32>`
- `WorldPosition`:
  - `cell_id: u32` — full landblock+cell ID (from PhysicsEngine.Resolve)
  - `position: Vector3` — world XYZ
  - `rotation: Quaternion` — world orientation
- Sequence numbers: `instance_sequence`, `server_control_sequence`, `teleport_sequence`, `force_position_sequence` (all u16)
- `contact_long_jump: u8` — ground contact flag

### `AutonomousPosition` (GameAction, opcode 0xF753)

Periodic heartbeat sent every ~200ms while the player is moving. Carries the current `WorldPosition` + sequence numbers + ground contact flag. Does NOT carry motion commands — the server already knows those from `MoveToState`.

### Wrapping in GameAction

Both messages are sent as `GameAction` (game message opcode 0xF7B1):
```
u32 game_message_opcode = 0xF7B1
u32 action_sequence     = next game action sequence
u32 action_type_opcode  = 0xF61C (MoveToState) or 0xF753 (AutonomousPosition)
... payload ...
```

This matches how `GameActionLoginComplete` (0x00A1) is already sent in Phase 4.10. The difference is that MoveToState/AutonomousPosition carry a structured payload after the action type opcode.

**Note on game action sequence:** holtburger increments a `game_action_sequence` counter per outbound game action. WorldSession already has `_fragmentSequence` for fragment-level sequencing; a new `_gameActionSequence` counter is needed for the action-level sequence field.

## Third-Person Chase Camera

New `ChaseCamera` class implementing `ICamera`:

- **Position:** behind + above the player at a configurable offset. In player-local space: `(-distance * cos(pitch), 0, distance * sin(pitch))` rotated by the player's yaw. Default distance ~8 units, default pitch ~20 degrees above horizontal.
- **LookAt:** the player's position + a small vertical offset (eye height, ~1.5 units).
- **Update per frame:** receives the player's current world position + yaw + mouse-Y-driven pitch delta. Recomputes the camera's world position from the offset math.
- **Projection:** same parameters as FlyCamera (FovY = PI/3, near = 1, far = 5000).

Camera does NOT collide with terrain/buildings — if the camera clips through a hill behind the player, that's acceptable for the MVP. Camera collision is Phase C polish.

## Walk Animation (Local)

When player mode is active:
- Detect which motion command the current input maps to:
  - W held → `WalkForward` (0x45000005), or `RunForward` (0x44000007) if Shift held
  - S held → `WalkForward` with negative speed (backward)
  - Z held → `SideStepLeft` (0x65000010)
  - X held → `SideStepRight` (0x6500000F)
  - A held (no mouse) → `TurnLeft` (0x6500000E)
  - D held (no mouse) → `TurnRight` (0x6500000D)
  - Nothing held → `Ready` (0x41000003, idle breathing)
- Use `MotionResolver.GetIdleCycle` with the command as `commandOverride` to resolve the animation cycle from the player's motion table.
- Register/update the player entity in `_animatedEntities` so `TickAnimations` plays the resolved cycle with slerp interpolation (existing infrastructure from Phase 6.4/6.5).
- Only update the cycle when the motion command *changes* (idle→walk, walk→run, etc.) — don't re-resolve every frame.

**Priority when multiple keys are held:** forward/backward takes priority over sidestep; sidestep takes priority over turn. Matches retail client behavior.

## Architecture

### New Files

| File | Responsibility |
|---|---|
| `src/AcDream.App/Input/PlayerMovementController.cs` | Per-frame input → physics → position update + outbound message decision logic |
| `src/AcDream.App/Rendering/ChaseCamera.cs` | Third-person camera implementing `ICamera` |
| `src/AcDream.Core.Net/Messages/MoveToState.cs` | Outbound `MoveToState` message builder |
| `src/AcDream.Core.Net/Messages/AutonomousPosition.cs` | Outbound `AutonomousPosition` heartbeat builder |

### Modified Files

| File | Changes |
|---|---|
| `src/AcDream.App/Rendering/GameWindow.cs` | Tab toggle, wire PlayerMovementController + ChaseCamera into OnUpdate/OnRender, local animation cycle switching, identify player entity by guid |
| `src/AcDream.App/Rendering/CameraController.cs` | Add chase camera as a third mode (orbit / fly / chase) |
| `src/AcDream.Core.Net/WorldSession.cs` | Add `_gameActionSequence` counter, add `SendGameAction(byte[])` method that wraps payload in the 0xF7B1 GameAction envelope with incrementing sequence |

### Data Flow (Per Frame, Player Mode)

```
OnUpdate:
  1. Read keyboard (WASD/ZX/Shift/AD) + mouse delta
  2. PlayerMovementController.Update(dt, inputState):
     a. Compute yaw delta from mouse X + A/D keyboard turn
     b. Update player yaw
     c. Compute movement delta from W/S + Z/X in the player's
        facing direction (yaw-rotated), scaled by walk/run speed * dt
     d. PhysicsEngine.Resolve(currentPos, currentCellId, delta, stepUpHeight)
        → resolvedPos, resolvedCellId, isOnGround
     e. Update playerEntity.Position = resolvedPos
     f. Update playerEntity.Rotation = Quaternion.CreateFromAxisAngle(UnitZ, yaw)
     g. Detect motion state change (compare current vs previous command)
     h. If changed: build MoveToState → WorldSession.SendGameAction
     i. Every ~200ms: build AutonomousPosition → WorldSession.SendGameAction
  3. Update walk animation on playerEntity:
     - If motion command changed: re-resolve cycle via MotionResolver
     - Update _animatedEntities entry
  4. ChaseCamera.Update(playerEntity.Position, yaw, cameraPitch)

OnRender:
  - _cameraController.Active returns ChaseCamera when in player mode
  - Frustum culling + terrain + static mesh draw as usual
```

### Player Entity Identification

The player's own character is identified by matching the `EntitySpawn.Guid` from the `CreateObject` received at login against the character's GUID from `CharacterList`. GameWindow already stores `_entitiesByServerGuid` — the player entity is `_entitiesByServerGuid[chosenCharacterGuid]`. Store the player's server guid as a field on GameWindow when `EnterWorld` is called.

### Coordinate Space for Server Messages

AC positions on the wire use `(landblock cell ID, local XY, Z, rotation)`. The cell ID is the full 32-bit value: `(landblockX << 24) | (landblockY << 16) | cellIndex`. `PhysicsEngine.Resolve` currently returns a cell index (0x0001–0x0040 outdoor, 0x0100+ indoor) without the landblock prefix. The message builder needs to compose the full cell ID from the entity's world position (to get the landblock coordinates) + the engine's cell index.

acdream's internal world coordinates are center-landblock-relative. Converting back to AC wire coordinates requires:
- `landblockX = _liveCenterX + floor(worldPos.X / 192)`
- `landblockY = _liveCenterY + floor(worldPos.Y / 192)`
- `localX = worldPos.X - (landblockX - _liveCenterX) * 192`
- `localY = worldPos.Y - (landblockY - _liveCenterY) * 192`
- `localZ = worldPos.Z`
- `cellId = (landblockX << 24) | (landblockY << 16) | resolvedCellIndex`

This is the inverse of the `OnLiveEntitySpawned` coordinate translation.

## Testing Strategy

### Unit Tests

- **`PlayerMovementControllerTests`** — with a fake PhysicsEngine:
  - Forward input → position advances in facing direction
  - Shift+forward → position advances at run speed (faster)
  - Turn input → yaw changes
  - Motion state change detection: idle→walk→idle transitions
  - Heartbeat timing: AutonomousPosition sent every ~200ms during movement

- **`MoveToStateTests`** — message builder:
  - Build with a known RawMotionState + WorldPosition → assert byte layout
  - Verify GameAction envelope (0xF7B1 + sequence + 0xF61C)

- **`AutonomousPositionTests`** — message builder:
  - Build with a known WorldPosition → assert byte layout
  - Verify GameAction envelope (0xF7B1 + sequence + 0xF753)

- **`ChaseCameraTests`** — offset math:
  - Player at origin, yaw=0 → camera at (-8, 0, ~3)
  - Player at origin, yaw=PI/2 → camera at (0, -8, ~3)
  - Pitch adjustment changes camera height

### Integration / Visual Verification

- Log in at Holtburg.
- Press Tab to enter player mode.
- Walk with W → character walks forward on terrain, walk animation plays.
- Shift+W → run animation, faster movement.
- A/D → character turns, camera follows.
- Release all keys → character returns to idle breathing.
- Open original AC client with different account → see acdream's character at the correct position, visually moving.
- ACE console shows no movement rejections or errors.
- Close acdream → graceful logout (already working).

## Acceptance Criteria

Phase B.2 is done when:

1. Tab toggles between fly mode and player mode.
2. WASD/ZX walks/strafes the character on collision-resolved terrain.
3. A/D + mouse turns the character.
4. Shift toggles walk/run speed.
5. Walk/run/turn/idle animations play correctly on the player's character.
6. The server accepts the movement (no ACE-side rejections in the console log).
7. Other clients see the character at the correct position.
8. Third-person chase camera follows the character smoothly.
9. All new unit tests pass. Total test count increases by ~15-20.

## Open Questions (Resolved During Implementation)

- **Exact walk/run speed values:** check ACE's `MovementHandler` for the server-side validation thresholds. Use holtburger's default speeds as a starting point.
- **RawMotionState flag encoding:** the exact bitmask layout comes from holtburger's `RawMotionFlags`. Implementation will read `references/holtburger/crates/holtburger-protocol/src/messages/movement/types.rs` for the canonical encoding.
- **Sequence number management:** the four sequence counters (instance, server_control, teleport, force_position) need to be tracked per-session. Start at the values ACE sends in the initial handshake and increment as holtburger does. If exact behavior is unclear, start at 0 and adjust if ACE rejects.
- **WorldPosition rotation encoding:** AC wire quaternion order is (W, X, Y, Z). Our internal `System.Numerics.Quaternion` is (X, Y, Z, W). The message builder must swap the order — same transform already used in `OnLiveEntitySpawned`.