# E1.M4 — AbilityInputScaffold

## Summary

| Field | Value |
|--------|--------|
| **Module ID** | E1.M4 |
| **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)) |
| **Linear** | Story slugs **E1M4-01** through **E1M4-05** in [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md); label **`E1.M4`** per [decomposition README — Linear alignment](../README.md#linear-alignment) |

## Purpose

Hotbar bindings, cooldown slot UI hooks, and the client/input path that issues `AbilityCastRequest` into [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md), using targeting from [E1.M3](E1_M3_InteractionAndTargetingLayer.md).

## Responsibilities

- Map hotbar slots to abilities and emit `AbilityCastRequest` with validation hints.
- Surface `HotbarLoadout` and `CooldownSnapshot` for UI sync.

## Key contracts

| Contract | Role |
|----------|------|
| `AbilityCastRequest` | Intent sent to combat resolution. |
| `HotbarLoadout` | Bound abilities per slot. |
| `CooldownSnapshot` | Client/server-visible cooldown state for UI. |

## Module dependencies

- **E1.M3** — InteractionAndTargetingLayer: target lock and cast validity.
- **E5.M1** — CombatRulesEngine: authoritative accept/deny of casts.

## Dependents (by design)

- Consumed by UX and telemetry; combat engine remains the authority.

## Related implementation slices

Epic 1 **Slice 3** — `ability_cast_requested`, `ability_cast_denied` with reason codes.

## Implementation snapshot

- **Current state:** NEO-29 landed prototype `HotbarLoadout` v1 contract and hydration path (`GET`/`POST /game/players/{id}/hotbar-loadout`, fixed 8 slots, deny reason codes). NEO-31 landed prototype **`POST /game/players/{id}/ability-cast`** plus client digit hotbar → cast payload wiring (target id from server-ack target state). `CooldownSnapshot` wiring is still pending.
- **Prototype persistence policy (NEO-29):** per-player loadout key; Postgres when `ConnectionStrings:NeonSprawl` exists, in-memory fallback otherwise.
- **Prototype backlog:** [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md) defines five vertical slices from hotbar loadout contract to cast telemetry hooks.
- **Dependency expectation:** first implementation stories assume E1.M3 target selection flow exists and E5.M1 provides minimum cast accept/deny contract.

## Linear backlog

Parent epic: [Epic 1 — Core Player Runtime](https://linear.app/neon-sprawl/project/epic-1-core-player-runtime-client-controls-character-loop-66bd590cd016).

**Stories:** full acceptance checklists in **[docs/plans/E1M4-prototype-backlog.md](../../plans/E1M4-prototype-backlog.md)**.

| Slug | Linear |
|------|--------|
| **E1M4-01** | [NEO-29](https://linear.app/neon-sprawl/issue/NEO-29/e1m4-01-hotbarloadout-v1-contract-baseline-persistence-path) — `HotbarLoadout` v1 contract + baseline persistence path |
| **E1M4-02** | [NEO-31](https://linear.app/neon-sprawl/issue/NEO-31/e1m4-02-input-to-abilitycastrequest-path) — Input to `AbilityCastRequest` path |
| **E1M4-03** | TBD — Combat accept/deny integration + reason-code UX |
| **E1M4-04** | TBD — `CooldownSnapshot` sync + slot presentation |
| **E1M4-05** | TBD — Slice 3 telemetry hooks for cast funnel |

Issues should carry label **`E1.M4`** per [Linear alignment](../README.md#linear-alignment).

## Source anchors

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