# NEO-85 — Implementation plan

## Story reference

| Field | Value |
|--------|--------|
| **Key** | NEO-85 |
| **Title** | E5M1-11: Client combat feedback + target HP HUD |
| **Linear** | https://linear.app/neon-sprawl/issue/NEO-85/e5m1-11-client-combat-feedback-target-hp-hud |
| **Module** | [E5.M1 — CombatRulesEngine](../decomposition/modules/E5_M1_CombatRulesEngine.md) · Epic 5 Slice 1 · backlog **E5M1-11** |
| **Branch** | `NEO-85-client-combat-feedback-hp-hud` |
| **Server deps** | [NEO-82](https://linear.app/neon-sprawl/issue/NEO-82) — cast POST + nested **`combatResolution`** (**Done** on `main`); [NEO-83](https://linear.app/neon-sprawl/issue/NEO-83) — **`GET /game/world/combat-targets`** (**Done** on `main`) |
| **Pattern** | [NEO-28](https://linear.app/neon-sprawl/issue/NEO-28) / [NEO-73](https://linear.app/neon-sprawl/issue/NEO-73) — thin HTTP clients, `main.gd` HUD wiring, GdUnit mock transport |
| **Downstream** | [NEO-86](https://linear.app/neon-sprawl/issue/NEO-86) capstone playable tab-target combat loop (manual QA script) |
| **Server counterpart** | [NEO-82](https://linear.app/neon-sprawl/issue/NEO-82) + [NEO-83](https://linear.app/neon-sprawl/issue/NEO-83) — this issue is the **client** half; Bruno-only verification is not prototype-complete per [full-stack epic decomposition](../../.cursor/rules/full-stack-epic-decomposition.md) |

## Kickoff clarifications

| Topic | Question | Agent recommendation | Answer |
|--------|----------|----------------------|--------|
| **HP refresh** | Event-driven vs periodic poll for **`GET /game/world/combat-targets`**? | **Event-driven only** — refresh after successful cast accept + on target lock change; matches cooldown sync pattern and minimizes HTTP chatter ([E5M1-11 backlog](E5M1-prototype-backlog.md#e5m1-11--client-combat-feedback--target-hp-hud)). | **User:** event-driven only. |
| **Cast feedback surface** | Extend **`CastFeedbackLabel`** vs dedicated combat line? | **Extend `CastFeedbackLabel`** with resolution copy on accept — NEO-28 precedent; keep HUD compact. | **User:** extend `CastFeedbackLabel`. |
| **HP label placement** | Dedicated label vs append to **`TargetLockLabel`**? | **New `CombatTargetHpLabel`** below **`CastFeedbackLabel`** — AC requires readable HP readout; **`TargetLockLabel`** is already dense lock/range debug. | **User:** dedicated `CombatTargetHpLabel`. |

No other blocking decisions — wire field names follow NEO-82 **`combatResolution`** / NEO-83 **`targets`** row vocabulary; zero-damage accepts show **`0 dmg`** from server fields (no local combat math).

## Goal, scope, and out-of-scope

**Goal:** Godot displays authoritative cast outcomes and locked dummy HP without local combat math — player-visible damage/defeat feedback and an HP label that matches the server snapshot after casts.

**In scope (from Linear + [E5M1-11](E5M1-prototype-backlog.md#e5m1-11--client-combat-feedback--target-hp-hud)):**

- Extend **`ability_cast_client.gd`** to parse nested **`combatResolution`** on accept and surface it on **`cast_result_received`**.
- Update **`CastFeedbackLabel`** with damage / defeat messaging on accept (e.g. **`Cast: 25 dmg → 75 HP`**, **`Cast: target defeated!`** when **`targetDefeated`**).
- **`combat_targets_client.gd`** — **`GET /game/world/combat-targets`**; cache snapshot; **`target_row(target_id)`** helper.
- **`CombatTargetHpLabel`** — shows locked target **`currentHp/maxHp`** (+ **`defeated`** suffix); **`—`** when no lock.
- **`main.gd` wiring:** event-driven combat-target refresh on successful cast + **`target_state_changed`**; boot hydrate when first lock arrives.
- GdUnit tests with HTTP doubles ([testing-expectations.md](../../.cursor/rules/testing-expectations.md)).
- **`docs/manual-qa/NEO-85.md`** — Godot steps (server + client running).
- **`client/README.md`** combat HUD section.

**Out of scope (from Linear + backlog):**

- Final combat VFX, floating damage numbers art pass, player HP bar.
- Gig XP HUD row — optional in [NEO-86](https://linear.app/neon-sprawl/issue/NEO-86) capstone.
- Periodic HP polling, local damage prediction, server changes.

## Acceptance criteria checklist

- [x] Player sees damage/defeat feedback in HUD after digit-key cast (not Output-only).
- [x] Target HP label matches server snapshot after cast sequence.
- [x] Manual QA exercisable without Bruno.

## Implementation reconciliation (shipped)

- **Clients:** `ability_cast_client.gd` parses **`combatResolution`** on accept; **`combat_targets_client.gd`** GET world snapshot + **`target_row`**.
- **HUD:** **`CastFeedbackLabel`** resolution copy; **`CombatTargetHpLabel`** for locked target HP; event-driven refresh on cast accept + lock change.
- **Tests:** extended `ability_cast_client_test.gd`; new `combat_targets_client_test.gd`, `combat_feedback_refresh_test.gd`.
- **Docs:** `client/README.md` combat HUD section; [`NEO-85` manual QA](../manual-qa/NEO-85.md); E5M1 backlog + module alignment rows updated.

## Technical approach

1. **`ability_cast_client.gd` (NEO-85)**
   - Parse optional **`combatResolution`** dict when **`accepted: true`** (`abilityId`, `targetId`, `damageDealt`, `targetRemainingHp`, `targetDefeated`).
   - Extend signal: **`cast_result_received(accepted, reason_code, resolution)`** — **`resolution`** empty **`Dictionary`** on deny or missing block.
   - Add static **`parse_cast_response_json(text) -> Dictionary`** for tests (returns `{accepted, reasonCode, resolution}`).

2. **`combat_targets_client.gd` (new)**
   - Mirror **`interactables_catalog_client.gd`** / **`skill_progression_client.gd`**: injectable HTTP, **`_busy`** guard.
   - **`GET {base}/game/world/combat-targets`** — no player id segment (world route).
   - **`parse_targets_json(text)`** static: require **`schemaVersion` 1**, **`targets`** array.
   - Signals: **`targets_received(snapshot: Dictionary)`**, **`targets_sync_failed(reason: String)`**.
   - **`request_sync_from_server()`** public entry.
   - **`target_row(target_id: String, snapshot: Dictionary = {}) -> Dictionary`** — find row by **`targetId`**; uses cached last snapshot when second arg omitted.

3. **Cast feedback copy (`main.gd` → `_on_cast_result_received`)**
   - **Deny:** unchanged NEO-28 lines (`ability_cast_denied: {reasonCode}`).
   - **Accept + resolution present:**
     - If **`targetDefeated`:** **`Cast: {damageDealt} dmg → 0 HP — defeated!`**
     - Else: **`Cast: {damageDealt} dmg → {targetRemainingHp} HP`**
   - **Accept + empty resolution:** fallback **`Cast: accepted`** (defensive; should not occur post-NEO-82).
   - Keep cooldown sync on accept (existing NEO-32 path).

4. **Combat target HP HUD (`main.gd`)**
   - Cache **`_combat_targets_snapshot: Dictionary`** on **`targets_received`**.
   - **`_render_combat_target_hp_label()`** — read **`_last_target_state.lockedTargetId`**; lookup row; format **`Target HP: {id} {current}/{max}`** + **` (defeated)`** when **`defeated`**; **`Target HP: — (no lock)`** when unlocked.
   - **Refresh triggers (event-driven, kickoff decision):**
     - **`target_state_changed`** → **`combat_targets_client.request_sync_from_server()`** when lock id changes or validity transitions to a locked id.
     - **`cast_result_received`** when **`accepted`** → request combat-target sync (authoritative HP after cast; resolution fields give immediate cast feedback, GET reconciles label).
   - Re-render HP label after snapshot received and when target state changes (even if GET still in flight, show last cached row for current lock).

5. **Scene layout (`main.tscn`)**
   - Add **`CombatTargetHpLabel`** between **`CastFeedbackLabel`** and **`GatherFeedbackLabel`** (~offset_top 374, shift **`GatherFeedbackLabel`** / **`CraftFeedbackLabel`** / economy block down ~22px if needed for non-overlap).
   - Style: match existing left HUD labels (outline, font_size 15, warm tint distinct from cast line).

6. **Client boot wiring (`main.gd`)**
   - Instantiate **`CombatTargetsClient`** in hotbar/cast setup block; apply authority **`base_url`** (world GET — no **`dev_player_id`**).
   - Connect **`targets_received`** → cache + **`_render_combat_target_hp_label`**.
   - Update **`cast_result_received`** connection signature for third **`resolution`** arg.

7. **Tests (GdUnit, AAA)**
   - **`ability_cast_client_test.gd`:** extend — accept body with **`combatResolution`** → signal carries resolution dict; deny → empty resolution.
   - **`combat_targets_client_test.gd`:** mock GET 200 two-target snapshot → **`target_row("prototype_target_alpha")`** fields; schema mismatch → failure signal.
   - **`combat_feedback_refresh_test.gd`:** harness — cast accept signal triggers **`combat_targets_client.request_sync_from_server`** (spy/mock); target lock change triggers sync (mirrors **`craft_feedback_refresh_test.gd`** / **`gather_feedback_refresh_test.gd`**).

8. **Docs on land**
   - **`client/README.md`:** combat HUD subsection — cast resolution copy, HP label, event-driven GET refresh, dev fixture reset note (`POST /game/__dev/combat-targets-fixture` when enabled).
   - **`docs/manual-qa/NEO-85.md`:** Tab lock alpha → bind slot 0 pulse → cast until defeat; verify **`CastFeedbackLabel`** + **`CombatTargetHpLabel`**; optional fixture reset between runs.
   - Reconcile [E5M1-prototype-backlog.md](E5M1-prototype-backlog.md) E5M1-11 checkboxes, [E5_M1_CombatRulesEngine.md](../decomposition/modules/E5_M1_CombatRulesEngine.md), [documentation_and_implementation_alignment.md](../decomposition/modules/documentation_and_implementation_alignment.md) when implementation completes.

## Files to add

| Path | Purpose |
|------|---------|
| `docs/plans/NEO-85-implementation-plan.md` | This plan. |
| `client/scripts/combat_targets_client.gd` | GET world combat-targets snapshot; parse v1; **`targets_received`** / **`targets_sync_failed`**; **`target_row`**. |
| `client/scripts/combat_targets_client.gd.uid` | Godot uid companion (tracked). |
| `client/test/combat_targets_client_test.gd` | GdUnit: parse two-target snapshot; **`target_row`** lookup; HTTP error path. AAA layout. |
| `client/test/combat_feedback_refresh_test.gd` | GdUnit: cast accept + target lock change invoke combat-target sync (spy harness). AAA layout. |
| `docs/manual-qa/NEO-85.md` | Manual QA checklist — Godot combat feedback + HP HUD without Bruno. |

## Files to modify

| Path | Rationale |
|------|-----------|
| `client/scripts/ability_cast_client.gd` | Parse **`combatResolution`**; extend **`cast_result_received`** with resolution dict; static parse helper for tests. |
| `client/test/ability_cast_client_test.gd` | Cover resolution parsing + extended signal payload on accept/deny. |
| `client/scripts/main.gd` | Wire **`CombatTargetsClient`**; combat HP label render; cast feedback copy with resolution; event-driven refresh hooks. |
| `client/scenes/main.tscn` | Add **`CombatTargetHpLabel`** node; adjust downstream label offsets if needed. |
| `client/README.md` | Document combat HUD (cast resolution feedback + target HP label + refresh triggers). |

## Tests

| Path | Change |
|------|--------|
| `client/test/ability_cast_client_test.gd` | **Add/extend:** accept JSON with **`combatResolution`** → signal third arg has **`damageDealt`**, **`targetRemainingHp`**, **`targetDefeated`**; deny → empty resolution. |
| `client/test/combat_targets_client_test.gd` | **Add:** GET parse v1; alpha/beta rows; 404/invalid schema failure signal. |
| `client/test/combat_feedback_refresh_test.gd` | **Add:** successful cast accept triggers combat-target sync; target lock change triggers sync. |

**Manual verification:** [`docs/manual-qa/NEO-85.md`](manual-qa/NEO-85.md) — server + Godot; Tab lock **`prototype_target_alpha`**, digit cast **`prototype_pulse`**, observe stepping HP on label and defeat copy on 4th hit; **`target_defeated`** deny on 5th preserves HUD state.

## Open questions / risks

| Question or risk | Agent recommendation | Status |
|------------------|----------------------|--------|
| **Signal signature break** | Extend **`cast_result_received`** with third arg (empty dict on deny) — update **`main.gd`** + tests in same commit. | **adopted** |
| **HP label stale during in-flight GET** | Show last cached snapshot for locked id immediately after cast feedback; refresh when GET completes. | **adopted** |
| **Layout shift in `main.tscn`** | Insert HP label between cast and gather lines; bump gather/craft offsets minimally. | **adopted** |
| **Dev fixture reset for QA** | Document optional **`POST /game/__dev/combat-targets-fixture`** in manual QA when Development host enabled (NEO-83 README). | **adopted** |
