don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/docs/plans/E3M3-prototype-backlog.md

8.3 KiB
Raw Blame History

E3.M3 — Prototype story backlog (ItemizationAndInventorySchema)

Working backlog for Epic 3 — Slice 1 (items and inventory MVP). Decomposition and contracts: E3.M3 — ItemizationAndInventorySchema.

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) — 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, gathering.md, 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
E3M3-02 NEO-51
E3M3-03 NEO-52
E3M3-04 NEO-53
E3M3-05 NEO-54
E3M3-06 NEO-55
E3M3-07 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 Slice 2 gather yields → inventory grants; E3.M2 craft I/O; 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 + 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 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).

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.

After this backlog

  • Decompose E3.M1 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.
  • Add docs/manual-qa/{NEO-XX}.md when HTTP surfaces land (E3M3-06+).

Related docs