70 lines
5.0 KiB
Markdown
70 lines
5.0 KiB
Markdown
# 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). **NEO-28** extends that cast POST with **server lock + registry + range** validation (`invalid_target`, `out_of_range`) and a **HUD cast feedback** line on deny/accept. **NEO-30** documents Epic 1 Slice 3 **telemetry hook sites** for `ability_cast_requested` / `ability_cast_denied`: comment markers + payload notes in [`AbilityCastApi.cs`](../../../server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs); client dev **`print`** / **`push_warning`** in [`main.gd`](../../../client/scripts/main.gd) and [`ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd) (all **TODO(E9.M1)** for cataloged ingest). **NEO-32** landed **`CooldownSnapshot`**: `GET /game/players/{id}/cooldown-snapshot` (`CooldownSnapshotResponse` v1: `serverTimeUtc`, eight `slots` with optional `cooldownEndsAtUtc`), prototype **global cooldown** on successful accept, JSON deny **`on_cooldown`**, Godot [`cooldown_snapshot_client.gd`](../../../client/scripts/cooldown_snapshot_client.gd) + [`cooldown_state.gd`](../../../client/scripts/cooldown_state.gd) + **`CooldownSlotsLabel`** HUD + client cast guard ([`main.gd`](../../../client/scripts/main.gd)); plan [NEO-32](../../plans/NEO-32-implementation-plan.md), manual QA [`NEO-32.md`](../../manual-qa/NEO-32.md).
|
|
- **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** | [NEO-28](https://linear.app/neon-sprawl/issue/NEO-28/e1m4-03-combat-acceptdeny-integration-reason-code-ux) — Combat accept/deny integration + reason-code UX |
|
|
| **E1M4-04** | [NEO-32](https://linear.app/neon-sprawl/issue/NEO-32/e1m4-04-cooldownsnapshot-sync-slot-presentation) — `CooldownSnapshot` sync + slot presentation |
|
|
| **E1M4-05** | [NEO-30](https://linear.app/neon-sprawl/issue/NEO-30/e1m4-05-slice-3-telemetry-hooks-for-cast-funnel) — 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)
|