# E1.M1 — InputAndMovementRuntime

## Summary

| Field | Value |
|--------|--------|
| **Module ID** | E1.M1 |
| **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) |
| **Stage target** | Prototype |
| **Status** | Ready — prototype milestone complete ([E1.M1](https://linear.app/neon-sprawl/project/e1m1-inputandmovementruntime-20eb28dd3db4) Done); see [dependency register](module_dependency_register.md) and [implementation snapshot](#implementation-snapshot) |

## Purpose

**Authority:** [Client vs server](client_server_authority.md#e1m1-inputandmovementruntime) — server owns `PositionState`; client sends move intent and may predict; reconcile to server.

Provides the foundational client/runtime path for character locomotion and world interaction: click-to-move or path-follow baseline, interaction trigger range checks, and the authoritative reconciliation surface for where the player is in the world. Other epics attach gameplay (gathering, combat, quests) on top of stable position and movement contracts.

## Responsibilities

- Character locomotion and movement command handling.
- Interaction trigger range checks using a single source of truth for distance.
- Emitting or consuming movement-related state suitable for server reconciliation in multiplayer tests.

## Key contracts

| Contract | Role |
|----------|------|
| `MoveCommand` | Client or input layer requests movement; server (or sim) validates and applies. |
| `PositionState` | Current authoritative (or reconciled) position for the avatar. |
| `InteractionRequest` | Optional path for interaction attempts; pairs with range checks. |

Contract readiness is tracked in the [module dependency register](module_dependency_register.md).

## Implementation snapshot

- **Done (prototype):** Server-side authoritative **`PositionState`** read + **`MoveCommand`** apply (HTTP JSON v1, snap-to-target, `sequence` increments); **`POST …/move-stream`** (NEO-22) for ordered multi-target applies with the same validation rules; **NEO-10** server-side step + optional district bounds validation with **`reasonCode`** rejections ([NEO-10](../../plans/NEO-10-implementation-plan.md), `MoveCommandValidation`, [server README — Move command](../../../server/README.md#move-command-neo-7-neo-10)); default **in-memory** store; optional **PostgreSQL** persistence when `ConnectionStrings:NeonSprawl` is set ([NEO-8](../../plans/NEO-8-implementation-plan.md)); shared **NpgsqlDataSource** disposed on application shutdown ([NEO-13](../../plans/NEO-13-implementation-plan.md)); Godot client **`move-stream`** + **WASD** default locomotion and legacy **`POST`/`GET`** move for **debug** click-to-move ([NEO-22](../../plans/NEO-22-implementation-plan.md), [NEO-6](../../plans/NEO-6-implementation-plan.md), [NEO-7](../../plans/NEO-7-implementation-plan.md), `server/NeonSprawl.Server/Game/PositionState/`, `client/scripts/`). **NEO-11** — client **`NavigationRegion3D` / `NavigationAgent3D`** for **debug** click-to-move visuals while server authority unchanged; **single-click obstacle detours not guaranteed** (see plan tradeoff) ([NEO-11](../../plans/NEO-11-implementation-plan.md); [client README](../../../client/README.md#authoritative-movement-neo-7-neo-11-neo-22)). **`InteractionRequest`** + server-side horizontal range check ([NEO-9](../../plans/NEO-9-implementation-plan.md); `Game/Interaction/`, `Game/World/HorizontalReach.cs`, [server README — Interaction](../../../server/README.md#interaction-neon-6)). See [server README — Position persistence](../../../server/README.md#position-persistence-neon-5). Jira **[E1.M1](https://linear.app/neon-sprawl/project/e1m1-inputandmovementruntime-20eb28dd3db4)** (E1.M1 Feature) is **Done** for this prototype scope.
- **Follow-on:** Client prediction/reconciliation; Epic 1 Slice 1 telemetry and movement-loop polish; optional **Protobuf** wire promotion for `MoveCommand` / `PositionState` per [contracts.md](contracts.md).
- **Alignment:** [Documentation and implementation alignment](documentation_and_implementation_alignment.md).

## Module dependencies

- **None** — root of the player runtime stack.

## Dependents (by design)

- **E1.M2** — [IsometricCameraController](E1_M2_IsometricCameraController.md): stable player anchor / position.
- **E1.M3** — [InteractionAndTargetingLayer](E1_M3_InteractionAndTargetingLayer.md): interaction and targeting on movement/position.
- **Downstream epics** — Gathering (E3.M1), zone transitions (E4.M1), and others consume position implicitly via higher layers.

## Related implementation slices

See Epic 1 **Slice 1 — Movement and position sync**: server-authoritative or client-predicted baseline with `MoveCommand` / `PositionState` reconciliation; interaction range single source of truth; telemetry hooks such as `session_start`, lightweight position samples, and `interaction_attempt` failures.

## Risks and telemetry

- Desync between client prediction and server authority: mitigate with one reconciliation ruleset and log desync via [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md) when schema exists.

## Source anchors

- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 1.
- [Module dependency register](module_dependency_register.md)
