open-wc/docs/modules/player-input.md

Player Input

Metadata

Field	Value
Status	Partial
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	435e1c9, 2026-07-14
Profiles/capabilities	Current render-sandbox defaults; Blizzlike335 binding semantics not yet verified

Purpose

Convert remappable Godot Input Map actions into an immutable, scene-free MoveIntent that can be consumed by the current player controller and a later independently testable local movement controller.

Non-goals

• Define authoritative server movement, prediction or reconciliation.
• Own character transform, terrain queries, camera state or animation state.
• Claim that the current W/S/A/D sandbox mapping exactly matches build 12340.
• Make sprint or free flight available to the production compatibility profile; their profile gate remains a later M02 package.

Context and boundaries

flowchart LR
    Devices[Keyboard and mouse] --> InputMap[Godot Input Map]
    InputMap --> Source[PlayerInputSource]
    Source --> Intent[MoveIntent]
    Intent --> Movement[LocalPlayerMovementController]
    Movement --> Controller[ThirdPersonWowController adapter]
    Controller --> Camera[Current camera adapter]

Allowed dependencies:

• PlayerInputSource may read Godot's process-wide Input adapter.
• The scene controller may consume MoveIntent and camera-specific action names.
• MoveIntent may contain scalar axes and request flags only.

Forbidden dependencies:

• MoveIntent must not read Input, inherit Node/Resource, or contain world coordinates.
• The input source must not mutate player transforms, camera nodes or animation state.
• Renderer, terrain parsers and network codecs must not read Input Map actions.

Public API

Symbol	Kind	Purpose	Thread/lifetime	Errors
MoveIntent	Immutable value	Carries normalized forward, strafe and vertical axes plus the sandbox sprint request	Created and consumed on the main physics tick; caller retains reference	Constructor clamps axes; no I/O failure
MoveIntent.has_translation()	Query	Reports whether any translation axis is non-zero	Any thread while value remains immutable	None
PlayerInputActions	Constants	Provides stable action names shared by configuration and adapters	Process lifetime	Missing project actions are detected by verification
PlayerInputSource.sample_move_intent()	Adapter method	Samples configured actions for one physics tick	Main thread; returned intent is independent of adapter lifetime	Missing actions resolve to zero strength and are a configuration defect
PlayerInputSource.compose_move_intent(...)	Pure factory	Clamps strengths, cancels opposites and normalizes diagonal planar input	Any thread with scalar inputs	None

Inputs and outputs

Direction	Contract/data	Producer	Consumer	Ownership	Thread/lifetime
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	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:

• PlayerInputSource has no side effects beyond reading current engine input.
• The existing controller still mutates player/camera transforms and mouse mode; those responsibilities are intentionally not moved by this package.
• No filesystem, cache, network, database or renderer-resource mutation occurs.

Data flow

flowchart LR
    Project[project.godot action defaults] --> Map[InputMap]
    Remap[User or editor remapping] --> Map
    Map -->|movement strengths| Source[PlayerInputSource]
    Source -->|clamp cancel normalize| Intent[MoveIntent]
    Intent --> Consumer[LocalPlayerMovementController]
    Consumer --> Adapter[ThirdPersonWowController]

Lifecycle/state

The adapter is stateless. The scene composition root creates one 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

sequenceDiagram
    participant Engine as Godot Input
    participant Source as PlayerInputSource
    participant Intent as MoveIntent
    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->>Move: advance(intent, selected basis, delta)
    Move-->>Player: displacement and velocity state

Ownership, threading and resources

• The controller owns the input-source reference for its scene lifetime.
• Each MoveIntent is immutable and retained only by its consumer.
• Sampling and controller mutation occur on the main physics thread.
• The module creates no Nodes, Resources, RIDs, workers or background jobs.
• Input Map definitions are project configuration; runtime remapping remains engine-owned and does not mutate the domain value.

Errors, cancellation and recovery

Failure	Detection	Behavior	Diagnostic	Recovery
Required action missing	Headless contract verifier	Godot returns zero input for that action	PLAYER_INPUT failure naming action	Restore action or user mapping
Conflicting opposite actions	Pure composition	Strengths cancel deterministically	Covered by contract test	Release/remap one action
Strength outside range	Pure composition	Value clamps to [0, 1] before axis calculation	Covered by contract test	Input adapter may be corrected independently
Controller disabled/unloaded	Scene lifecycle	Sampling stops with physics processing	Existing scene lifecycle	Re-enable or recreate scene

There is no asynchronous operation to cancel and no persisted state to roll back.

Configuration and capabilities

Setting/capability	Default	Profile	Runtime mutable	Effect
Forward/backward	Physical W/S	Current render sandbox	Yes, through Input Map	Produces signed forward axis
Strafe left/right	Physical A/D	Current render sandbox	Yes	Produces signed right axis
Camera rotate	Right mouse button	Current render sandbox	Yes	Captures/releases mouse for orbit
Camera zoom	Mouse wheel	Current render sandbox	Yes	Adjusts current camera distance
Debug sprint	Shift	Sandbox debug only by intent; profile gate pending	Yes	Requests existing speed multiplier
Debug flight up/down/toggle	E/Q/Space	Sandbox debug only by intent; profile gate pending	Yes	Requests existing free-flight controls

Persistence, cache and migration

The action names are additive project configuration. No saved binding schema, cache or migration exists yet. Renaming an action is a contract change and must provide a settings migration once user settings are persisted.

Diagnostics and observability

• Logs: dedicated verifier emits PLAYER_INPUT PASS or one failure per invariant.
• Metrics: none; sampling cost is one small value allocation per physics tick.
• Debug views: none.
• Correlation IDs: not applicable to local synchronous input.

Verification

• Unit/contract tests: src/tools/verify_player_input.gd validates all actions, default bindings, axis cancellation/clamping/normalization and debug request flags.
• Integration/E2E: src/tests/scenes/player_input_regression.tscn is loaded by the verifier, which drives forward, camera-zoom and immediate sandbox-flight actions through the real scene controller and also rejects direct physical-key polling.
• Fidelity evidence: current sandbox defaults retain W/S/A/D, E/Q, Shift, Space, right mouse and wheel bindings. This is observable-regression coverage only.
• Performance budgets: no I/O, jobs or scene lookup per sample; one immutable intent allocation per physics tick.
• Manual diagnostics: run the Eastern Kingdoms scene and remap one movement action in Project Settings before checking movement.

Extension points

• A gamepad/accessibility adapter may call compose_move_intent without changing movement consumers.
• A later input-context owner may suppress gameplay actions while preserving the same intent contract.
• 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	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

Known gaps and risks

• The defaults preserve the pre-M02 sandbox behavior, not verified original-client semantics.
• Sprint and free flight are still executable by the sandbox controller until a typed build-profile gate is introduced.
• Camera input is action-mapped but camera state/collision remains in the monolithic controller.
• There is no persisted user keybinding format or UI yet.

Source map

Path	Responsibility
project.godot	Additive default Input Map bindings
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/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

Related decisions and references

• ADR: none; this implements the existing architecture and M02 seam.
• Upstream/reference: targets/02-player-decomposition.md, targets/roadmap/04-gameplay-systems.md, docs/ARCHITECTURE.md.