gmp(M02): extract local player movement

Work-Package: M02-GMP-MOVEMENT-001
Agent: sindo-main-codex
Tests: local movement and player input regressions; asset-free scene; renderer dry-run; coordinate, streaming, documentation and coordination gates
Fidelity: preserves current sandbox speed, acceleration, sprint and camera-relative flight behavior; build-12340 parity remains unverified

docs/modules/README.md

@@ -10,6 +10,7 @@
 | Coordinate mapping | Implemented | [`coordinate-mapping.md`](coordinate-mapping.md) |
 | Domain identities | Implemented contract | [`domain-identities.md`](domain-identities.md) |
 | Player input | Partial | [`player-input.md`](player-input.md) |
+| Local player movement | Implemented | [`local-player-movement.md`](local-player-movement.md) |
 | Renderer | Partial | [`world-renderer.md`](world-renderer.md), [`../../RENDER.md`](../../RENDER.md) |
 | Network/session | Planned | [`../../targets/roadmap/03-network-and-session.md`](../../targets/roadmap/03-network-and-session.md) |
 | Gameplay | Prototype/Planned | [`../../targets/roadmap/04-gameplay-systems.md`](../../targets/roadmap/04-gameplay-systems.md) |

docs/modules/local-player-movement.md

@@ -0,0 +1,242 @@
+# Local Player Movement
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Implemented |
+| Target/work package | M02 / M02-GMP-MOVEMENT-001 |
+| Owners | Gameplay local movement state; scene composition owns the instance |
+| Last verified | `working tree`, 2026-07-14 |
+| Profiles/capabilities | Current render sandbox; production/debug profile gate pending |
+
+## Purpose
+
+Own current local velocity, acceleration and sandbox flight state independently
+of the player scene. Convert an immutable `MoveIntent` plus an explicit
+Godot-world movement basis into deterministic per-tick displacement without
+querying terrain, cameras, input devices or visual assets.
+
+## Non-goals
+
+- Apply world transforms or own a `CharacterBody3D`.
+- Query terrain height, collision, water or slopes.
+- Implement jump, fall, swim, server prediction or reconciliation.
+- Select the player basis versus camera-pivot basis; the scene adapter owns that decision.
+- Claim build-12340 movement fidelity from sandbox regression alone.
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Input[MoveIntent] --> Movement[LocalPlayerMovementController]
+    Basis[Explicit local movement Basis] --> Movement
+    Delta[Physics delta seconds] --> Movement
+    Movement --> Displacement[Godot-world displacement]
+    Movement --> Velocity[Read-only velocity state]
+    Scene[ThirdPersonWowController] --> Basis
+    Displacement --> Scene
+    Scene --> Transform[Player world transform]
+    Scene --> Terrain[Ground snap adapter]
+    Velocity --> Presentation[Visual facing and animation adapter]
+```
+
+Allowed dependencies:
+
+- `MoveIntent` from the gameplay input boundary.
+- Godot value types `Basis` and `Vector3` for renderer world-space direction math.
+- Main-thread scene adapter for basis selection and displacement application.
+
+Forbidden dependencies:
+
+- `Node`, `Resource`, `Input`, `Camera3D`, `ADTLoader` or scene lookup.
+- World-coordinate conversion or manual ADT/tile formulas.
+- Character assets, animation players, materials, packets or server state.
+
+## Public API
+
+| Symbol | Kind | Purpose | Thread/lifetime | Errors |
+|---|---|---|---|---|
+| `LocalPlayerMovementController.new(...)` | Constructor | Sets explicit speeds, acceleration and sandbox sprint multiplier | Created by composition root; retained for player scene lifetime | Caller owns configuration validation |
+| `godot_world_velocity_units_per_second` | Read-only state | Current Godot-world velocity after the last update | Stable until next mutation on owning thread | None |
+| `is_flight_enabled` | Read-only state | Current sandbox free-flight mode | Stable until toggle | None |
+| `toggle_sandbox_flight()` | Command | Toggles flight and clears velocity | Owning physics/input thread | Returns new flight state |
+| `advance(move_intent, godot_world_movement_basis, delta_seconds)` | Stateful update | Accelerates toward requested velocity and returns displacement for the tick | Owning physics thread; one call per tick | Negative delta is treated as zero |
+
+Constructor units:
+
+| Parameter | Unit/meaning |
+|---|---|
+| `run_speed_units_per_second` | Forward Godot units per second |
+| `backward_speed_units_per_second` | Backward Godot units per second |
+| `strafe_speed_units_per_second` | Lateral Godot units per second |
+| `flight_vertical_speed_units_per_second` | Sandbox vertical Godot units per second |
+| `acceleration_units_per_second_squared` | Velocity change per second |
+| `sandbox_sprint_multiplier` | Dimensionless debug multiplier |
+
+## Inputs and outputs
+
+| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
+|---|---|---|---|---|---|
+| Input | `MoveIntent` | `PlayerInputSource` | Movement controller | Immutable caller-held value | One physics tick |
+| Input | Godot-world `Basis` | Player scene adapter | Movement controller | Value copy | One physics tick |
+| Input | Delta seconds | Godot physics loop | Movement controller | Scalar value | One physics tick |
+| Input | Flight toggle command | Remappable sandbox action via scene adapter | Movement controller | Synchronous command | Input event dispatch |
+| Output | Displacement `Vector3` | Movement controller | Player scene adapter | Value copy | Applied in same tick |
+| Output | Velocity `Vector3` | Movement controller | Facing/animation adapter | Read-only value copy | Until next update |
+| Output | Flight state | Movement controller | Basis/terrain scene adapter | Read-only boolean | Until next toggle |
+
+Side effects:
+
+- Mutates only controller-owned velocity and flight state.
+- Does not mutate scene tree, transforms, resources, filesystem, network or cache.
+- The scene adapter remains responsible for transform mutation and ground snap.
+
+## Data flow
+
+```mermaid
+flowchart LR
+    Intent[MoveIntent axes] --> Target[Calculate target velocity]
+    Basis[Player or camera-pivot Basis] --> Directions[Forward/right directions]
+    Directions --> Target
+    Config[Speeds and sprint multiplier] --> Target
+    Previous[Owned velocity] --> Integrate[move_toward by acceleration × delta]
+    Target --> Integrate
+    Integrate --> Current[Updated velocity]
+    Current --> Step[velocity × delta]
+    Step --> Displacement[Scene-applied displacement]
+```
+
+## Lifecycle/state
+
+```mermaid
+stateDiagram-v2
+    [*] --> GroundedSandbox
+    GroundedSandbox --> FlyingSandbox: toggle / clear velocity
+    FlyingSandbox --> GroundedSandbox: toggle / clear velocity
+    GroundedSandbox --> GroundedSandbox: advance
+    FlyingSandbox --> FlyingSandbox: advance
+```
+
+The names describe the existing sandbox mode only. They are not authoritative
+gameplay movement states and do not imply terrain contact or server permission.
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant Input as PlayerInputSource
+    participant Scene as ThirdPersonWowController
+    participant Move as LocalPlayerMovementController
+    participant Present as Facing/Animation adapter
+    Input-->>Scene: MoveIntent
+    Scene->>Move: advance(intent, selected basis, delta)
+    Move-->>Scene: displacement
+    Scene->>Scene: apply global position and ground snap
+    Scene->>Move: godot_world_velocity_units_per_second
+    Scene->>Present: horizontal motion
+```
+
+## Ownership, threading and resources
+
+- The player scene creates and exclusively owns one movement controller.
+- Velocity and flight state have the same lifetime as that controller.
+- All mutations currently occur on the main input/physics thread.
+- Read-only value returns are copies; consumers cannot mutate owned state.
+- No Nodes, Resources, RIDs, files, jobs or worker threads are created.
+- The supplied `Basis` is a Godot-world direction basis, not a typed world-position contract or coordinate conversion.
+
+## Errors, cancellation and recovery
+
+| Failure | Detection | Behavior | Diagnostic | Recovery |
+|---|---|---|---|---|
+| Negative physics delta | `advance` guard | Returns zero displacement; velocity unchanged | Unit regression | Resume with valid non-negative delta |
+| Missing scene basis owner | Scene composition defect | Controller cannot be called correctly | Scene/parser error or boundary test | Restore explicit scene dependency |
+| Flight toggle during motion | Command path | Velocity clears before next step | State-transition regression | Continue from zero velocity |
+| Missing terrain data | Outside module | Scene skips existing ground snap | Existing terrain diagnostics | TerrainQuery extraction will own policy |
+
+There is no asynchronous cancellation, retry or rollback. Recreating the
+controller resets velocity and flight state deterministically.
+
+## Configuration and capabilities
+
+| Setting/capability | Default | Profile | Runtime mutable | Effect |
+|---|---|---|---|---|
+| Forward speed | `7.0` units/s | Current sandbox | Fixed for controller lifetime | Target forward velocity |
+| Backward speed | `4.5` units/s | Current sandbox | Fixed for controller lifetime | Target backward velocity |
+| Strafe speed | `4.5` units/s | Current sandbox | Fixed for controller lifetime | Target lateral velocity |
+| Acceleration | `28.0` units/s² | Current sandbox | Fixed for controller lifetime | Acceleration and deceleration |
+| Flight vertical speed | `7.0` units/s | Sandbox debug | Fixed for controller lifetime | Vertical free-flight target |
+| Sprint multiplier | `6.0` | Sandbox debug | Fixed for controller lifetime | Multiplies planar and vertical targets |
+| Camera-relative basis | Selected only while flight is enabled | Sandbox debug | Per tick | Preserves existing pitched flight direction |
+
+## Persistence, cache and migration
+
+Movement state is transient and not serialized. No schema, cache, migration or
+saved settings change is introduced. Future reconnect/replay state requires a
+separate versioned movement snapshot contract.
+
+## Diagnostics and observability
+
+- Logs: verifier emits `LOCAL_PLAYER_MOVEMENT PASS` or named invariant failures.
+- Metrics: none yet; update is constant-time vector math.
+- Debug views: current character facing and animation remain observable scene outputs.
+- Correlation IDs: not applicable to synchronous local sandbox state.
+
+## Verification
+
+- Unit/contract: `src/tools/verify_local_player_movement.gd` covers forward,
+  backward, strafe, rotated basis, acceleration, deceleration, sprint, flight,
+  pitched camera basis, state reset and invalid delta.
+- Boundary: verifier rejects Node/Input/Camera/ADT dependencies and movement
+  integration/state remaining in the player scene.
+- Scene integration: `verify_player_input.gd` drives the asset-free player
+  regression scene through forward motion and immediate flight toggle.
+- Fidelity evidence: default values and formulas are regression-locked against
+  the pre-extraction sandbox. No original-client comparison is claimed.
+- Performance budget: constant-time vector math, no per-tick I/O or scene lookup;
+  `MoveIntent` allocation remains owned by the input package.
+
+## Extension points
+
+- Terrain/collision policy can consume displacement without changing input or velocity ownership.
+- A future server-aware predictor may replace this controller behind the scene composition boundary.
+- A typed movement snapshot may expose deterministic replay state when M08/M09 require it.
+- Sandbox debug capability gating can reject sprint/flight before commands reach this controller.
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+| Scene-free local velocity state | Implemented | Pure controller and source boundary regression | Integrate target checklist after review |
+| Existing planar acceleration/speeds | Implemented | Exact numeric unit cases and real scene regression | Compare with build 12340 before fidelity claim |
+| Existing camera-relative free flight | Implemented | Pitched-basis and toggle/reset cases | Restrict to sandbox profile |
+| Terrain/collision movement policy | Planned | Outside module by design | Extract `TerrainQuery` next |
+| Jump/fall/swim | Planned | M02/M09 roadmap | Requires terrain/liquid and server contracts |
+| Prediction/reconciliation | Planned | M08/M09 roadmap | Requires movement snapshot/network contract |
+
+## Known gaps and risks
+
+- Numeric defaults preserve the existing sandbox but are not original-client evidence.
+- Configuration is captured at scene `_ready`; runtime mutation of exported speed
+  properties does not reconfigure an existing controller.
+- Ground snap remains in the player scene until `TerrainQuery` extraction.
+- Sprint and free flight still lack a typed sandbox capability gate.
+- The module uses Godot math value types; a future engine-independent gameplay
+  predictor may require scalar/domain movement contracts.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/gameplay/movement/local_player_movement_controller.gd` | Owned velocity/flight state and deterministic integration |
+| `src/scenes/player/third_person_wow_controller.gd` | Composition, basis selection, displacement/terrain/presentation adapters |
+| `src/tools/verify_local_player_movement.gd` | Pure numeric, state-transition and dependency regression |
+| `src/tests/scenes/player_input_regression.tscn` | Asset-free integrated player fixture |
+| `src/tools/verify_player_input.gd` | Input-to-movement scene regression |
+
+## Related decisions and references
+
+- ADR: none; this follows the existing M02 decomposition boundary.
+- Upstream/reference: `targets/02-player-decomposition.md`,
+  `targets/roadmap/04-gameplay-systems.md`, `docs/ARCHITECTURE.md`.

docs/modules/player-input.md

@@ -5,9 +5,9 @@
 | Field | Value |
 |---|---|
 | Status | Partial |
-| Target/work package | M02 / M02-GMP-INPUT-001 |
+| Target/work package | M02 / M02-GMP-INPUT-001, M02-GMP-MOVEMENT-001 consumer update |
 | Owners | Gameplay input boundary; `sindo-main-codex` for current package |
-| Last verified | `6bd2e84`, 2026-07-14 |
+| Last verified | `working tree`, 2026-07-14 |
 | Profiles/capabilities | Current render-sandbox defaults; `Blizzlike335` binding semantics not yet verified |
 
 ## Purpose
@@ -31,8 +31,8 @@ flowchart LR
     Devices[Keyboard and mouse] --> InputMap[Godot Input Map]
     InputMap --> Source[PlayerInputSource]
     Source --> Intent[MoveIntent]
-    Intent --> Controller[ThirdPersonWowController]
-    Controller --> Movement[Current sandbox movement]
+    Intent --> Movement[LocalPlayerMovementController]
+    Movement --> Controller[ThirdPersonWowController adapter]
     Controller --> Camera[Current camera adapter]
 ```
 
@@ -64,7 +64,7 @@ Forbidden dependencies:
 |---|---|---|---|---|---|
 | Input | Movement action strengths | Godot `InputMap`/`Input` | `PlayerInputSource` | Engine-owned snapshot | Sampled on main physics tick |
 | Input | Mouse action events | Godot `_unhandled_input` dispatch | Current scene controller | Engine-owned event | Current input dispatch only |
-| Output | `MoveIntent` | `PlayerInputSource` | Current controller; later local movement controller | Immutable caller-held value | One physics tick |
+| Output | `MoveIntent` | `PlayerInputSource` | `LocalPlayerMovementController` through scene composition | Immutable caller-held value | One physics tick |
 | Output | Camera action names | `PlayerInputActions` | Current scene controller | Static constants | Process lifetime |
 
 Side effects:
@@ -82,15 +82,16 @@ flowchart LR
     Remap[User or editor remapping] --> Map
     Map -->|movement strengths| Source[PlayerInputSource]
     Source -->|clamp cancel normalize| Intent[MoveIntent]
-    Intent --> Consumer[ThirdPersonWowController]
+    Intent --> Consumer[LocalPlayerMovementController]
+    Consumer --> Adapter[ThirdPersonWowController]
 ```
 
 ## Lifecycle/state
 
 The adapter is stateless. The scene composition root creates one
-`PlayerInputSource` in `_ready`; each physics tick produces a new immutable
-intent. Flight enabled/disabled state remains owned by the current sandbox
-controller and is not hidden in the input adapter.
+`PlayerInputSource` and `LocalPlayerMovementController` in `_ready`; each physics
+tick produces a new immutable intent. Flight enabled/disabled state is owned by
+the movement controller and is not hidden in the input adapter.
 
 ## Main sequence
 
@@ -99,11 +100,13 @@ sequenceDiagram
     participant Engine as Godot Input
     participant Source as PlayerInputSource
     participant Intent as MoveIntent
-    participant Player as ThirdPersonWowController
+    participant Move as LocalPlayerMovementController
+    participant Player as ThirdPersonWowController adapter
     Engine->>Source: movement action strengths
     Source->>Intent: compose normalized axes and requests
     Source-->>Player: sample_move_intent()
-    Player->>Player: update current sandbox movement state
+    Player->>Move: advance(intent, selected basis, delta)
+    Move-->>Player: displacement and velocity state
 ```
 
 ## Ownership, threading and resources
@@ -171,15 +174,15 @@ provide a settings migration once user settings are persisted.
   movement consumers.
 - A later input-context owner may suppress gameplay actions while preserving the
   same intent contract.
-- The local movement controller may replace the current scene consumer without
-  changing `PlayerInputSource`.
+- A future server-aware movement predictor may replace the current local
+  movement consumer without changing `PlayerInputSource`.
 
 ## Capability status
 
 | Capability | Status | Evidence | Gap/next step |
 |---|---|---|---|
 | Remappable current sandbox controls | Implemented | `verify_player_input.gd` action/default checks | Add persisted user binding settings later |
-| `PlayerInputSource → MoveIntent` seam | Implemented | Pure composition and controller boundary checks | Extract local movement controller |
+| `PlayerInputSource → MoveIntent` seam | Implemented | Pure composition and controller boundary checks | Local movement consumer is now extracted |
 | Exact 3.3.5a default semantics | Unknown | No original-client binding fixture in this package | Capture build-12340 defaults and mouse-turn/strafe policy |
 | Production profile exclusion of sprint/flight | Partial | Debug actions are named explicitly | Add typed profile/capability gate in M02 |
 | Jump/fall/swim/fly gameplay semantics | Planned | M02 target and gameplay roadmap | Implement after terrain/movement state extraction |
@@ -200,7 +203,8 @@ provide a settings migration once user settings are persisted.
 | `src/domain/input/move_intent.gd` | Immutable locomotion request contract |
 | `src/gameplay/input/player_input_actions.gd` | Stable project action names |
 | `src/gameplay/input/player_input_source.gd` | Engine Input Map adapter and pure composition |
-| `src/scenes/player/third_person_wow_controller.gd` | Current consumer and camera-event adapter |
+| `src/gameplay/movement/local_player_movement_controller.gd` | Scene-free movement consumer |
+| `src/scenes/player/third_person_wow_controller.gd` | Composition and camera/input-event adapter |
 | `src/tests/scenes/player_input_regression.tscn` | Asset-free controller movement/camera regression fixture |
 | `src/tools/verify_player_input.gd` | Headless contract/integration regression |