145 lines
11 KiB
Markdown
145 lines
11 KiB
Markdown
# NEO-72 — Implementation plan
|
|
|
|
## Story reference
|
|
|
|
| Field | Value |
|
|
|--------|--------|
|
|
| **Key** | NEO-72 |
|
|
| **Title** | E3.M3: Client inventory snapshot HUD (E3S5-01) |
|
|
| **Linear** | https://linear.app/neon-sprawl/issue/NEO-72/e3m3-client-inventory-snapshot-hud-e3s5-01 |
|
|
| **Module** | [E3.M3 — ItemizationAndInventorySchema](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) · Epic 3 **Slice 5** (client 1 of 4) · backlog **E3S5-01** |
|
|
| **Branch** | `NEO-72-client-inventory-snapshot-hud` |
|
|
| **Server deps** | [NEO-55](https://linear.app/neon-sprawl/issue/NEO-55) — `GET /game/players/{id}/inventory` (**Done**); [NEO-53](https://linear.app/neon-sprawl/issue/NEO-53) — `GET /game/world/item-definitions` (**Done**) |
|
|
| **Pattern** | [NEO-24](https://linear.app/neon-sprawl/issue/NEO-24) / [NEO-32](https://linear.app/neon-sprawl/issue/NEO-32) — thin HTTP client nodes, `main.gd` wiring, debug HUD labels, GdUnit mock transport |
|
|
| **Downstream** | [NEO-73](https://linear.app/neon-sprawl/issue/NEO-73) gather feedback calls inventory refresh; [NEO-74](https://linear.app/neon-sprawl/issue/NEO-74) craft UI reuses inventory + defs clients |
|
|
|
|
## Kickoff clarifications
|
|
|
|
| Topic | Question | Agent recommendation | Answer |
|
|
|--------|----------|----------------------|--------|
|
|
| **Display names** | Resolve **`displayName`** via **`GET /game/world/item-definitions`** or raw **`itemId`** only? | **Include `item_definitions_client`** + cached lookup — NEO-53 is landed; readable labels help gather/craft QA in NEO-73/74. | **User:** include defs + **`displayName`**. |
|
|
| **Failed GET UX** | How to surface inventory GET errors? | **`InventoryLabel` error line + `push_warning`** — visible in-game (NEO-28 cast deny HUD) and dev console (cooldown/interaction HTTP clients). | **User:** HUD + **`push_warning`**. |
|
|
| **Refresh key** | Manual refresh binding? | **Bind `I` → `inventory_refresh`** — E3S5 backlog QA note; public **`request_sync_from_server()`** entrypoint for NEO-73. | **User:** **`I`** key. |
|
|
|
|
## Goal, scope, and out-of-scope
|
|
|
|
**Goal:** Godot client for **`GET /game/players/{id}/inventory`** plus a readable bag/equipment debug HUD; boot hydrate and a manual refresh entrypoint for later Slice 5 stories.
|
|
|
|
**In scope (from Linear + [E3S5-01](E3S5-client-prototype-backlog.md#e3s5-01--client-inventory-snapshot-hud-e3m3)):**
|
|
|
|
- **`inventory_client.gd`:** GET snapshot, parse v1 envelope, emit signal with parsed body; public **`request_sync_from_server()`**; structured **`push_warning`** on transport/HTTP/JSON failures.
|
|
- **`item_definitions_client.gd`:** GET world item defs once (or on boot), cache **`id → displayName`** (and optional **`inventorySlotKind`** for row prefix); emit **`definitions_ready`**.
|
|
- **`InventoryLabel`** under **`UICanvas`:** lists **non-empty bag slots** + **equipment slot 0** (show **`— empty`** when quantity 0); resolve labels via defs cache when available, fall back to raw **`itemId`**.
|
|
- Boot hydrate after scene ready (chain: item defs → inventory GET, mirroring hotbar → cooldown boot order in NEO-32).
|
|
- **`I`** input → **`inventory_refresh`** in **`project.godot`**; handled in **`main.gd`** **`_unhandled_key_input`** (same pattern as E/R interact forwarding).
|
|
- GdUnit: mock HTTP — happy-path parse + error paths for both clients.
|
|
- **`client/README.md`** inventory HUD subsection.
|
|
- **`docs/manual-qa/NEO-72.md`**.
|
|
|
|
**Out of scope (from Linear):**
|
|
|
|
- Drag-drop, stack split, equip UX polish.
|
|
- POST inventory mutations from UI (gather/craft stories own refresh triggers).
|
|
- Server route or DTO changes.
|
|
|
|
## Acceptance criteria checklist
|
|
|
|
- [x] Boot shows current server inventory for **`dev-local-1`** (empty bag + empty equipment stub on fresh dev player).
|
|
- [x] HUD lists all **non-empty** **`bagSlots`** and **equipment slot 0** from GET body (with **`displayName`** when defs loaded).
|
|
- [x] Failed GET surfaces visible error on **`InventoryLabel`** and **`push_warning`** in Output.
|
|
- [x] **`I`** triggers manual inventory refresh; **`request_sync_from_server()`** callable for NEO-73 wiring.
|
|
|
|
## Technical approach
|
|
|
|
1. **`item_definitions_client.gd`**
|
|
- Injectable HTTP transport; **`base_url`** / shared authority config from **`main.gd`** (same as **`CooldownSnapshotClient`**).
|
|
- **`request_sync_from_server()`** → **`GET …/game/world/item-definitions`**.
|
|
- On 200 + v1 JSON: build **`Dictionary`** map **`itemId → { displayName, inventorySlotKind }`**; emit **`definitions_ready(map)`**.
|
|
- Errors: **`push_warning("ItemDefinitionsClient: …")`**; emit nothing (inventory HUD falls back to raw ids).
|
|
|
|
2. **`inventory_client.gd`**
|
|
- **`request_sync_from_server()`** → **`GET …/game/players/{dev_player_id}/inventory`**.
|
|
- On 200: validate **`schemaVersion` 1**, emit **`inventory_received(snapshot: Dictionary)`** with full parsed body.
|
|
- On failure (transport, non-2xx, non-JSON): **`push_warning("InventoryClient: …")`** + emit **`inventory_sync_failed(reason: String)`** so **`main.gd`** can paint the HUD error line without parsing a snapshot.
|
|
- **`_busy`** guard like **`CooldownSnapshotClient`** (ignore overlapping GETs).
|
|
|
|
3. **Boot sequence in `main.gd`**
|
|
- Add **`_setup_inventory_sync()`** from **`_ready()`** after authority is wired.
|
|
- Instantiate **`ItemDefinitionsClient`** + **`InventoryClient`** as child nodes; copy **`base_url`** / **`dev_player_id`** from **`PositionAuthorityClient`**.
|
|
- Connect **`definitions_ready`** → cache map on **`main`** (or hold ref to defs client with **`display_name_for(item_id)`** helper method).
|
|
- On boot: **`item_definitions_client.request_sync_from_server()`** then **`inventory_client.request_sync_from_server()`** (defs may still be in flight when first inventory paints — re-render label when defs arrive).
|
|
- Connect **`inventory_received`** / **`inventory_sync_failed`** → **`_render_inventory_label()`**.
|
|
|
|
4. **HUD formatting (`_render_inventory_label`)**
|
|
- Header: **`Inventory:`** + optional **`(refresh: I)`** hint for QA.
|
|
- **Bag:** iterate **`bagSlots`**; emit lines only where **`quantity > 0`**: **`slot {slotIndex}: {displayName or itemId} x{quantity}`**.
|
|
- **Equipment:** always show **`slot 0`**: item line if occupied, else **`slot 0: — empty`**.
|
|
- On **`inventory_sync_failed`**: replace body with **`Inventory: error — {reason}`** (keep header); also **`push_warning`** already fired from client.
|
|
|
|
5. **Scene + input**
|
|
- **`main.tscn`:** add **`InventoryClient`**, **`ItemDefinitionsClient`** nodes; **`InventoryLabel`** below **`CooldownSlotsLabel`** (offset ~460px top, autowrap, same font theme as sibling HUD labels).
|
|
- **`project.godot`:** **`inventory_refresh`** → **I** (physical key).
|
|
- **`main.gd` `_unhandled_key_input`:** if **`inventory_refresh`** pressed → **`inventory_client.request_sync_from_server()`**.
|
|
|
|
6. **Public refresh contract for NEO-73**
|
|
- Expose **`InventoryClient.request_sync_from_server()`** (no wrapper required in **`main`** unless we add **`refresh_inventory_from_server()`** alias — prefer direct client call from **`main`** helpers NEO-73 can reuse).
|
|
|
|
7. **Docs on land**
|
|
- Update [E3_M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) client slice note + [documentation_and_implementation_alignment.md](../decomposition/modules/documentation_and_implementation_alignment.md) E3.M3 row when implementation completes.
|
|
- **`E3S5-client-prototype-backlog.md`:** check E3S5-01 boxes.
|
|
|
|
## Files to add
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `docs/plans/NEO-72-implementation-plan.md` | This plan. |
|
|
| `client/scripts/item_definitions_client.gd` | GET world item defs; cache id → display metadata; **`definitions_ready`** signal. |
|
|
| `client/scripts/item_definitions_client.gd.uid` | Godot uid companion (tracked). |
|
|
| `client/scripts/inventory_client.gd` | GET player inventory snapshot; **`inventory_received`** / **`inventory_sync_failed`** signals. |
|
|
| `client/scripts/inventory_client.gd.uid` | Godot uid companion (tracked). |
|
|
| `client/test/item_definitions_client_test.gd` | GdUnit: parse v1 items list; lookup helper; HTTP error **`push_warning`**. |
|
|
| `client/test/inventory_client_test.gd` | GdUnit: parse bag/equipment slots; 404/500 failure emits **`inventory_sync_failed`**. |
|
|
| `docs/manual-qa/NEO-72.md` | Boot empty inventory, Bruno seed + refresh, failed GET (server stopped), **`I`** refresh. |
|
|
|
|
## Files to modify
|
|
|
|
| Path | Rationale |
|
|
|------|-----------|
|
|
| `client/scenes/main.tscn` | Add **`InventoryClient`**, **`ItemDefinitionsClient`**, **`InventoryLabel`** nodes. |
|
|
| `client/scripts/main.gd` | Boot wiring, HUD render, **`I`** refresh input, defs cache + inventory signal handlers. |
|
|
| `client/project.godot` | Register **`inventory_refresh`** input action (**I**). |
|
|
| `client/README.md` | Inventory HUD subsection: bindings, label format, boot/refresh behavior, server deps. |
|
|
|
|
## Tests
|
|
|
|
| Test file | What it covers |
|
|
|-----------|----------------|
|
|
| `client/test/item_definitions_client_test.gd` | Mock transport 200 with six-item v1 JSON → map contains **`scrap_metal_bulk`** **`displayName`**; non-200 → no **`definitions_ready`**, warning path. AAA layout. |
|
|
| `client/test/inventory_client_test.gd` | Mock 200 with empty 24+1 slot grid → **`inventory_received`** payload has **`bagSlots.size()` 24**; 404 → **`inventory_sync_failed`** + warning; malformed JSON → failure signal. AAA layout. |
|
|
|
|
No new **C#** tests (client-only; server contracts covered by NEO-55/NEO-53). No new Bruno (server already exercised).
|
|
|
|
## Open questions / risks
|
|
|
|
| Question / risk | Agent recommendation | Status |
|
|
|-----------------|----------------------|--------|
|
|
| **Defs/inventory race on boot** | First inventory paint may use raw ids; re-render on **`definitions_ready`** — acceptable for prototype. | **adopted** |
|
|
| **Empty bag UX** | Show **`Bag: (empty)`** when no occupied bag slots; equipment stub always listed. | **adopted** |
|
|
| **HUD clutter at 24 slots** | Non-empty-only rows keep label readable until NEO-75 optional collapse. | **adopted** |
|
|
| **Slice 5 module docs** | Update alignment register when NEO-72 lands, not at kickoff. | **deferred** (implementation) |
|
|
|
|
## Decisions (kickoff)
|
|
|
|
- **Include `item_definitions_client`** with **`displayName`** resolution (user confirmed).
|
|
- **Error UX:** **`InventoryLabel`** error line + **`push_warning`** (user confirmed).
|
|
- **Manual refresh:** **`I` → `inventory_refresh`** (user confirmed).
|
|
- **Equipment row:** always show slot **0** (empty or occupied) per Linear AC “equipment stub slot”.
|
|
- **No POST inventory** from UI in this story.
|
|
|
|
## Implementation reconciliation (shipped)
|
|
|
|
- **Clients:** `item_definitions_client.gd` (cached **`displayName`**), `inventory_client.gd` (**`inventory_received`** / **`inventory_sync_failed`**).
|
|
- **HUD:** `UICanvas/InventoryLabel`; boot hydrate; **`I` → `inventory_refresh`**; error line + **`push_warning`** on failed GET.
|
|
- **Tests:** `client/test/item_definitions_client_test.gd`, `client/test/inventory_client_test.gd`.
|
|
- **Docs:** `client/README.md` inventory section; [`NEO-72` manual QA](../manual-qa/NEO-72.md); E3.M3 module + alignment register updated.
|