|
|
|
|
@ -0,0 +1,207 @@
|
|
|
|
|
# E3.M3 — Prototype story backlog (ItemizationAndInventorySchema)
|
|
|
|
|
|
|
|
|
|
Working backlog for **Epic 3 — Slice 1** ([items and inventory MVP](../decomposition/epics/epic_03_crafting_economy.md#slice-1---items-and-inventory-mvp)). Decomposition and contracts: [E3.M3 — ItemizationAndInventorySchema](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md).
|
|
|
|
|
|
|
|
|
|
**Labels (Linear):** every issue **`E3.M3`**; add **`server`** / **`Feature`** or **`Story`** as listed per issue.
|
|
|
|
|
|
|
|
|
|
**Precursor (do not re-scope):** gather **skill XP** on `resource_node` interact is **E3.M1** anchor only ([NEO-41](https://linear.app/neon-sprawl/issue/NEO-41)) — no `GatherResult` / inventory yet. This module owns **`ItemDef`**, **`ItemInstance`**, **`InventorySlot`**, and server-authoritative player inventory.
|
|
|
|
|
|
|
|
|
|
**Prototype item spine (frozen in E3M3-01):** six rows covering **material → intermediate → consumable → utility → quest token → equip stub** for the gather→refine→craft loop ([items.md](../game-design/items.md), [gathering.md](../game-design/gathering.md), [crafting.md](../game-design/crafting.md)).
|
|
|
|
|
|
|
|
|
|
**Linear issues (created):** attach `docs/plans/NEO-*-implementation-plan.md` on the same branch as implementation work.
|
|
|
|
|
|
|
|
|
|
| Slug | Linear |
|
|
|
|
|
|------|--------|
|
|
|
|
|
| E3M3-01 | [NEO-50](https://linear.app/neon-sprawl/issue/NEO-50) |
|
|
|
|
|
| E3M3-02 | [NEO-51](https://linear.app/neon-sprawl/issue/NEO-51) |
|
|
|
|
|
| E3M3-03 | [NEO-52](https://linear.app/neon-sprawl/issue/NEO-52) |
|
|
|
|
|
| E3M3-04 | [NEO-53](https://linear.app/neon-sprawl/issue/NEO-53) |
|
|
|
|
|
| E3M3-05 | [NEO-54](https://linear.app/neon-sprawl/issue/NEO-54) |
|
|
|
|
|
| E3M3-06 | [NEO-55](https://linear.app/neon-sprawl/issue/NEO-55) |
|
|
|
|
|
| E3M3-07 | [NEO-56](https://linear.app/neon-sprawl/issue/NEO-56) |
|
|
|
|
|
|
|
|
|
|
**Dependency graph in Linear:** E3M3-02 blocked by E3M3-01. E3M3-03 blocked by E3M3-02. E3M3-04 and E3M3-05 blocked by E3M3-03. E3M3-06 blocked by E3M3-05. E3M3-07 blocked by E3M3-05 (may parallel E3M3-06).
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Story order (recommended)
|
|
|
|
|
|
|
|
|
|
| Order | Slug | Depends on |
|
|
|
|
|
|-------|------|------------|
|
|
|
|
|
| 1 | **E3M3-01** | None (content spine) |
|
|
|
|
|
| 2 | **E3M3-02** | E3M3-01 |
|
|
|
|
|
| 3 | **E3M3-03** | E3M3-02 |
|
|
|
|
|
| 4 | **E3M3-04** | E3M3-03 |
|
|
|
|
|
| 5 | **E3M3-05** | E3M3-03 |
|
|
|
|
|
| 6 | **E3M3-06** | E3M3-05 |
|
|
|
|
|
| 7 | **E3M3-07** | E3M3-05 |
|
|
|
|
|
|
|
|
|
|
**Downstream (separate modules):** [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) Slice 2 gather yields → inventory grants; [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) craft I/O; [NEO-42](https://linear.app/neon-sprawl/issue/NEO-42) refine XP hook invokes after craft success.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### E3M3-01 — Prototype ItemDef starter set + schemas + CI
|
|
|
|
|
|
|
|
|
|
**Goal:** Lock content shape and CI validation for a **frozen six-item** prototype catalog before any server load.
|
|
|
|
|
|
|
|
|
|
**In scope**
|
|
|
|
|
|
|
|
|
|
- `content/schemas/item-def.schema.json` (or equivalent single-catalog schema).
|
|
|
|
|
- `content/items/prototype_items.json` with stable ids: `scrap_metal_bulk`, `refined_plate_stock`, `field_stim_mk0`, `survey_drone_kit`, `contract_handoff_token`, `prototype_armor_shell` (names/display may change; **ids frozen**).
|
|
|
|
|
- `scripts/validate_content.py`: schema validation, duplicate `id`, required bucket/tag fields, exact six-id allowlist for prototype.
|
|
|
|
|
- Designer note in [E3_M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) + `content/README.md`: stack rules, slot kinds (bag vs equip stub), v1 scope (no durability mutation).
|
|
|
|
|
|
|
|
|
|
**Out of scope**
|
|
|
|
|
|
|
|
|
|
- Server loader, inventory store, HTTP, client HUD.
|
|
|
|
|
|
|
|
|
|
**Acceptance criteria**
|
|
|
|
|
|
|
|
|
|
- [ ] PR gate validates item JSON against schema.
|
|
|
|
|
- [ ] Exactly six prototype item ids; duplicate `id` fails CI.
|
|
|
|
|
- [ ] Stable id list documented in module doc freeze box.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### E3M3-02 — Server item catalog load (fail-fast)
|
|
|
|
|
|
|
|
|
|
**Goal:** Disk → host: startup load of `content/items/*.json` with CI-parity validation.
|
|
|
|
|
|
|
|
|
|
**In scope**
|
|
|
|
|
|
|
|
|
|
- Loader + registry interface under `server/NeonSprawl.Server/Game/Items/` (path TBD in plan).
|
|
|
|
|
- Fail-fast on malformed files, duplicate ids, unknown enum values.
|
|
|
|
|
- Unit tests (AAA) for loader happy path and failure modes.
|
|
|
|
|
|
|
|
|
|
**Out of scope**
|
|
|
|
|
|
|
|
|
|
- Per-player inventory, HTTP.
|
|
|
|
|
|
|
|
|
|
**Acceptance criteria**
|
|
|
|
|
|
|
|
|
|
- [ ] Server refuses boot when item catalog invalid (mirror E2.M1 catalog behavior).
|
|
|
|
|
- [ ] Registry resolves `ItemDef` by `id`.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### E3M3-03 — Item definition registry + DI
|
|
|
|
|
|
|
|
|
|
**Goal:** Injectable `IItemDefinitionRegistry` consumed by inventory and future craft/gather paths.
|
|
|
|
|
|
|
|
|
|
**In scope**
|
|
|
|
|
|
|
|
|
|
- `ItemDefinitionRegistry` implementation + DI registration.
|
|
|
|
|
- Unit tests (AAA): lookup, unknown id, prototype row metadata.
|
|
|
|
|
|
|
|
|
|
**Out of scope**
|
|
|
|
|
|
|
|
|
|
- HTTP, persistence, stack mutation.
|
|
|
|
|
|
|
|
|
|
**Acceptance criteria**
|
|
|
|
|
|
|
|
|
|
- [ ] Host resolves registry from DI; unknown `itemId` distinguishable from valid ids in tests.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### E3M3-04 — GET world item-definitions
|
|
|
|
|
|
|
|
|
|
**Goal:** Versioned read-only catalog for client preview, Bruno, and future codegen — mirror [NEO-36](https://linear.app/neon-sprawl/issue/NEO-36) skill-definitions pattern.
|
|
|
|
|
|
|
|
|
|
**In scope**
|
|
|
|
|
|
|
|
|
|
- `GET /game/world/item-definitions` + DTOs + API tests (AAA).
|
|
|
|
|
- Bruno folder `bruno/neon-sprawl-server/item-definitions/`.
|
|
|
|
|
- `server/README.md` section.
|
|
|
|
|
|
|
|
|
|
**Out of scope**
|
|
|
|
|
|
|
|
|
|
- Per-player inventory mutation.
|
|
|
|
|
|
|
|
|
|
**Acceptance criteria**
|
|
|
|
|
|
|
|
|
|
- [ ] GET returns all six prototype defs with schema version field.
|
|
|
|
|
- [ ] Bruno happy path documented.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### E3M3-05 — Player inventory store + stack/slot rules engine
|
|
|
|
|
|
|
|
|
|
**Goal:** Server-authoritative `ItemInstance` bags with stack limits and structured deny reasons; persistence (in-memory + Postgres + migration).
|
|
|
|
|
|
|
|
|
|
**In scope**
|
|
|
|
|
|
|
|
|
|
- `IPlayerInventoryStore`, migration `V00X__player_inventory` (number in plan).
|
|
|
|
|
- Inventory operations: add stack, remove stack, slot capacity, `inventory_full` / `invalid_item` / `insufficient_quantity` reason codes.
|
|
|
|
|
- Unit + integration tests (AAA); mirror NEO-8/NEO-38 persistence policy.
|
|
|
|
|
|
|
|
|
|
**Out of scope**
|
|
|
|
|
|
|
|
|
|
- HTTP, Bruno, client HUD.
|
|
|
|
|
- Craft/gather automatic grants (callers in E3.M1 / E3.M2).
|
|
|
|
|
|
|
|
|
|
**Acceptance criteria**
|
|
|
|
|
|
|
|
|
|
- [ ] Add/remove respects `ItemDef` stack max from catalog.
|
|
|
|
|
- [ ] Full bag returns stable `reasonCode` without partial silent loss.
|
|
|
|
|
- [ ] Postgres + in-memory parity tests.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### E3M3-06 — Player inventory HTTP + Bruno
|
|
|
|
|
|
|
|
|
|
**Goal:** Versioned **GET** snapshot and **POST** grant/consume (or add/remove) for manual QA and future client.
|
|
|
|
|
|
|
|
|
|
**In scope**
|
|
|
|
|
|
|
|
|
|
- `GET /game/players/{id}/inventory` and mutating POST (exact path/shape in implementation plan).
|
|
|
|
|
- Known-player gate via `IPositionStateStore` (NEO-37 pattern).
|
|
|
|
|
- Bruno `bruno/neon-sprawl-server/inventory/`.
|
|
|
|
|
- `server/README.md`; API tests (AAA).
|
|
|
|
|
|
|
|
|
|
**Out of scope**
|
|
|
|
|
|
|
|
|
|
- Godot HUD (optional follow-up).
|
|
|
|
|
- Gather node depletion ([E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md)).
|
|
|
|
|
|
|
|
|
|
**Acceptance criteria**
|
|
|
|
|
|
|
|
|
|
- [ ] GET returns instances + slots for seeded player.
|
|
|
|
|
- [ ] POST add/remove matches engine rules from E3M3-05.
|
|
|
|
|
- [ ] Bruno exercises happy path + at least one deny (`inventory_full` or unknown item).
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### E3M3-07 — `item_created` / transfer-failure telemetry hook sites
|
|
|
|
|
|
|
|
|
|
**Goal:** Comment-only hooks on inventory mutation success/deny for future E9.M1 catalog events **`item_created`** and transfer failures.
|
|
|
|
|
|
|
|
|
|
**In scope**
|
|
|
|
|
|
|
|
|
|
- Hook placement in inventory engine (and POST path if applicable).
|
|
|
|
|
- `TODO(E9.M1)` comments; no production logging.
|
|
|
|
|
- README + module doc pointer.
|
|
|
|
|
|
|
|
|
|
**Out of scope**
|
|
|
|
|
|
|
|
|
|
- Telemetry ingest, dashboards.
|
|
|
|
|
|
|
|
|
|
**Acceptance criteria**
|
|
|
|
|
|
|
|
|
|
- [ ] Hook sites documented in code and `server/README.md`.
|
|
|
|
|
- [ ] Matches Epic 3 Slice 1 telemetry vocabulary in [epic_03](../decomposition/epics/epic_03_crafting_economy.md).
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## After this backlog
|
|
|
|
|
|
|
|
|
|
- Decompose **[E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md)** Slice 2 (gather yields → inventory) once E3M3-05+ land.
|
|
|
|
|
- Track delivery in Linear; keep `blockedBy` links synchronized if scope changes.
|
|
|
|
|
- For each issue kickoff, add `docs/plans/{NEO-XX}-implementation-plan.md` per [story-kickoff](../../.cursor/rules/story-kickoff.md).
|
|
|
|
|
- Add `docs/manual-qa/{NEO-XX}.md` when HTTP surfaces land (E3M3-06+).
|
|
|
|
|
|
|
|
|
|
## Related docs
|
|
|
|
|
|
|
|
|
|
- [E3_M3_ItemizationAndInventorySchema.md](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md)
|
|
|
|
|
- [epic_03_crafting_economy.md](../decomposition/epics/epic_03_crafting_economy.md)
|
|
|
|
|
- [items.md](../game-design/items.md)
|
|
|
|
|
- [E2_M1_SkillDefinitionRegistry.md](../decomposition/modules/E2_M1_SkillDefinitionRegistry.md) (catalog pattern precedent)
|
GitHub