# 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** | In Progress (see [dependency register](module_dependency_register.md); [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); **NS-19** server-side step + optional district bounds validation with **`reasonCode`** rejections ([NS-19](../../plans/NS-19-implementation-plan.md), `MoveCommandValidation`, [server README — Move command](../../../server/README.md#move-command-ns-16-ns-19)); default **in-memory** store; optional **PostgreSQL** persistence when `ConnectionStrings:NeonSprawl` is set ([NS-17](../../plans/NS-17-implementation-plan.md)); Godot client **`POST`/`GET`** move flow ([NS-15](../../plans/NS-15-implementation-plan.md), [NS-16](../../plans/NS-16-implementation-plan.md), `server/NeonSprawl.Server/Game/PositionState/`, `client/scripts/`). **NS-23** — client **`NavigationRegion3D` / `NavigationAgent3D`** path-follow for click-to-move visuals while server authority unchanged ([NS-23](../../plans/NS-23-implementation-plan.md); [client README](../../../client/README.md#authoritative-movement-ns-16-ns-23)). **`InteractionRequest`** + server-side horizontal range check ([NS-18](../../plans/NS-18-implementation-plan.md); `Game/Interaction/`, `Game/World/HorizontalReach.cs`, [server README — Interaction](../../../server/README.md#interaction-ns-18)). See [server README — Position persistence](../../../server/README.md#position-persistence-ns-17).
- **Not yet:** Prediction/reconciliation, full Epic 1 Slice 1 movement loop and telemetry.
- **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)