139 lines
9.8 KiB
Markdown
139 lines
9.8 KiB
Markdown
# NEO-75 — Implementation plan
|
||
|
||
## Story reference
|
||
|
||
| Field | Value |
|
||
|--------|--------|
|
||
| **Key** | NEO-75 |
|
||
| **Title** | E3: Playable gather→refine→make loop in client (E3S5-04) |
|
||
| **Linear** | https://linear.app/neon-sprawl/issue/NEO-75/e3-playable-gatherrefinemake-loop-in-client-e3s5-04 |
|
||
| **Module** | Epic 3 **Slice 5 capstone** — [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) + [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) + [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) · backlog **E3S5-04** |
|
||
| **Branch** | `NEO-75-e3-playable-gather-refine-make-loop` |
|
||
| **Server deps** | NEO-63 gather interact, NEO-70 craft POST, NEO-55 inventory GET, NEO-37 skill-progression GET (**Done** on `main`) |
|
||
| **Client deps** | [NEO-72](https://linear.app/neon-sprawl/issue/NEO-72) inventory HUD (**Done**); [NEO-73](https://linear.app/neon-sprawl/issue/NEO-73) gather feedback (**Done**); [NEO-74](https://linear.app/neon-sprawl/issue/NEO-74) craft UI (**Done**) |
|
||
| **Pattern** | Capstone integration — reuse NEO-72–74 wiring; docs + manual QA primary; HUD collapse per kickoff |
|
||
|
||
## Kickoff clarifications
|
||
|
||
| Topic | Question | Agent recommendation | Answer |
|
||
|--------|----------|----------------------|--------|
|
||
| **Implementation scope** | Docs-only vs code changes? | **Docs + manual QA first**; add code only if QA fails — loop already wired in NEO-72–74. | **User:** docs + manual QA first; code only if QA fails. |
|
||
| **HUD collapse** | Build toggle now or defer? | **Defer** — optional per backlog; left scroll usable for capstone. | **User:** **implement** collapsible HUD sections in this story. |
|
||
| **Capstone session start** | Fresh player without Bruno? | **Restart server** (in-memory dev store resets) before Godot **F5** — no curl/Bruno seeding. | **Adopted** (Linear AC + kickoff default). |
|
||
| **Progression gate smoke** | Filter recipes by skill level? | **Visible XP only** — salvage/refine rows refresh after gather/craft; no recipe gating UI (explicit NEO-74 out-of-scope). | **Adopted** (decomposition default). |
|
||
|
||
## Goal, scope, and out-of-scope
|
||
|
||
**Goal:** Prove Epic 3 prototype acceptance **in Godot**: gather **`scrap_metal_bulk`** → **`refine_scrap_standard`** → **`make_field_stim_mk0`** without Bruno; satisfies vision **crafting loop** + **progression gate** smoke test.
|
||
|
||
**In scope (from Linear + [E3S5-04](E3S5-client-prototype-backlog.md#e3s5-04--playable-gatherrefinemake-loop-in-client-capstone)):**
|
||
|
||
- **`docs/manual-qa/NEO-75.md`**: numbered **single-session** capstone script — fresh dev player, four-node gather route, two refines + one make, final **`field_stim_mk0`** assertion; **no Bruno/curl** steps.
|
||
- **`client/README.md`**: **End-to-end economy loop** section — integration checklist (boot → **R** gather → craft panel → inventory/skill refresh chain); input keys; material math (11 scrap minimum).
|
||
- **Collapsible economy HUD**: toggle to hide/show **`InventoryLabel`**, **`SkillProgressionLabel`**, **`CraftRecipePanel`** block so prototype scene stays playable on smaller viewports.
|
||
- **Module alignment** (on story completion): update [`documentation_and_implementation_alignment.md`](../decomposition/modules/documentation_and_implementation_alignment.md) E3.M1/M2/M3 rows + Epic 3 Slice 5 “complete” note in [`epic_03_crafting_economy.md`](../decomposition/epics/epic_03_crafting_economy.md).
|
||
- **Integration fixes only if capstone QA fails** on current `main` wiring (unexpected deny, refresh gap, etc.).
|
||
|
||
**Out of scope (from Linear):**
|
||
|
||
- Quest UI (E7); combat consumable **use** of **`field_stim_mk0`** (E5 follow-up); art pass.
|
||
- New HTTP routes or economy clients; recipe quantity spinner; station placement.
|
||
- Bruno-only verification as prototype-complete proof.
|
||
|
||
## Acceptance criteria checklist
|
||
|
||
- [ ] Manual QA checklist completable by a human in **one session** with server + client running (**`docs/manual-qa/NEO-75.md`**).
|
||
- [ ] **`field_stim_mk0`** quantity ≥ **1** in inventory at end of script.
|
||
- [ ] Epic 3 Slice 3 AC re-read satisfied in Godot: player (not Bruno) completes **gather → refine → usable item**; **salvage** / **refine** XP visible after actions.
|
||
- [ ] Economy HUD collapse toggle documented and functional.
|
||
|
||
## Technical approach
|
||
|
||
### 1. Capstone manual QA script (`docs/manual-qa/NEO-75.md`)
|
||
|
||
**Preconditions:** Stop any running server; start fresh (`dotnet run`) so in-memory **`dev-local-1`** inventory/skills/nodes reset. Godot **F5** with no prior session curl seeding.
|
||
|
||
**Material math** (from [`content/recipes/prototype_recipes.json`](../../content/recipes/prototype_recipes.json)):
|
||
|
||
| Step | Action | Scrap consumed | Plates gained | Scrap remaining |
|
||
|------|--------|----------------|---------------|-----------------|
|
||
| Gather ×4 | **R** at alpha (+1), beta (+2), gamma (+3), delta (+5) | — | — | **11** |
|
||
| Refine #1 | Craft **`refine_scrap_standard`** | 5 | +1 | **6** |
|
||
| Refine #2 | Craft **`refine_scrap_standard`** | 5 | +1 | **1** (+ **2** plates) |
|
||
| Make | Craft **`make_field_stim_mk0`** | 1 | −2 plates | **0** (+ **`field_stim_mk0` ×1**) |
|
||
|
||
**Checklist outline:**
|
||
|
||
1. Start server + client; confirm empty bag and skill rows on HUD.
|
||
2. Walk each resource anchor (coords from [NEO-73 manual QA](../manual-qa/NEO-73.md)); **R** once per node — verify **`GatherFeedbackLabel`**, inventory scrap, **salvage** XP without **I**.
|
||
3. Craft **`refine_scrap_standard`** twice; verify **`CraftFeedbackLabel`**, **refine** XP, plate stock.
|
||
4. Craft **`make_field_stim_mk0`**; verify consumable in **`InventoryLabel`**.
|
||
5. Optional: collapse economy HUD, expand again — panel still populated.
|
||
|
||
### 2. HUD collapse (`prototype_economy_hud_section.gd`)
|
||
|
||
- Add **`UICanvas/EconomyHudSection`** (`VBoxContainer` + script):
|
||
- Header row: **`CheckButton`** text **`Economy HUD`** (default **pressed** / expanded).
|
||
- Body **`VBoxContainer`**: reparent existing **`InventoryLabel`**, **`SkillProgressionLabel`**, **`CraftRecipePanel`** from flat **`UICanvas`** (remove fixed **`offset_top`** stacking — use container layout).
|
||
- **`toggled(pressed)`** → set body **`visible = pressed`**; header stays visible.
|
||
- **`main.gd`**: no signal rewiring — `@onready` paths update to new hierarchy (or export node refs unchanged if reparent preserves names).
|
||
- Document toggle in **`client/README.md`** and capstone manual QA step.
|
||
|
||
**Keep expanded by default** so capstone QA matches NEO-72–74 expectations; collapse is optional UX for viewport space.
|
||
|
||
### 3. README integration checklist
|
||
|
||
New **`## End-to-end economy loop (NEO-75)`** section after NEO-74 craft subsection:
|
||
|
||
- Flow diagram in prose: boot GETs → **R** nearest resource node → gather feedback + inventory/salvage refresh → scroll craft panel → **Craft** → craft feedback + inventory/refine refresh.
|
||
- Cross-links: NEO-72 (**I**), NEO-73 (**R** + anchors), NEO-74 (recipes).
|
||
- Pointer to **`docs/manual-qa/NEO-75.md`** as authoritative capstone script.
|
||
|
||
### 4. Module alignment (implementation batch or story end)
|
||
|
||
When acceptance criteria pass:
|
||
|
||
- **`documentation_and_implementation_alignment.md`**: E3.M1/M2/M3 — note **NEO-75 landed**, Epic 3 Slice 5 client capstone complete.
|
||
- **`epic_03_crafting_economy.md`**: Slice 5 AC checkboxes / status if not already marked.
|
||
|
||
### 5. Integration fixes (conditional)
|
||
|
||
Run capstone QA on **`main`** wiring before collapse refactor; if any step fails, fix minimal **`main.gd`** / client bug in this branch and note in plan **Decisions**. Expected path: **no logic changes** beyond HUD layout.
|
||
|
||
## Files to add
|
||
|
||
| Path | Purpose |
|
||
|------|---------|
|
||
| `docs/manual-qa/NEO-75.md` | Capstone single-session manual QA (zero Bruno). |
|
||
| `client/scripts/prototype_economy_hud_section.gd` | Collapse toggle + body visibility for economy HUD block. |
|
||
| `client/scripts/prototype_economy_hud_section.gd.uid` | Godot UID companion (same commit as `.gd`). |
|
||
| `client/test/prototype_economy_hud_section_test.gd` | GdUnit: toggle hides/shows body container. |
|
||
|
||
## Files to modify
|
||
|
||
| Path | Rationale |
|
||
|------|-----------|
|
||
| `client/scenes/main.tscn` | Add **`EconomyHudSection`**; reparent inventory/skills/craft panel under collapsible body. |
|
||
| `client/scripts/main.gd` | Update `@onready` node paths if hierarchy changes; wire collapse only if script needs refs from root. |
|
||
| `client/README.md` | End-to-end economy loop section + economy HUD toggle note. |
|
||
| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | Record NEO-75 / Slice 5 capstone complete when shipped. |
|
||
| `docs/decomposition/epics/epic_03_crafting_economy.md` | Slice 5 prototype client completion note (if needed). |
|
||
|
||
## Tests
|
||
|
||
| File | Coverage |
|
||
|------|----------|
|
||
| **`client/test/prototype_economy_hud_section_test.gd`** (add) | **`# Arrange`**: scene with section + body child. **`# Act`**: toggle **`CheckButton`**. **`# Assert`**: body **`visible`** matches pressed state. |
|
||
| Existing NEO-72–74 client tests | No change expected — capstone reuses their clients; run suite in CI. |
|
||
|
||
**No `main.gd` automated test** — orchestration verified via capstone manual QA (same policy as NEO-72–74).
|
||
|
||
## Open questions / risks
|
||
|
||
| Question / risk | Agent recommendation | Status |
|
||
|-----------------|---------------------|--------|
|
||
| **Loop already works on `main`** | Run capstone QA before collapse refactor; expect pass. | **pending** (implementation) |
|
||
| **HUD reparent breaks `@onready` paths** | Update paths in **`main.gd`** + **`craft_recipe_panel.gd`** exports in same commit as **`main.tscn`**. | **adopted** |
|
||
| **Depleted nodes block repeat QA** | Capstone script uses **one R per node** (11 scrap); delta node has capacity 10 — single pass sufficient. Re-run requires **server restart**. | **adopted** |
|
||
| **Vertical layout shift after collapse container** | Use **`VBoxContainer`** layout instead of absolute **`offset_top`** for economy block only; combat/debug labels above unchanged. | **adopted** |
|