# Epic 3 - Crafting, Gathering, and Itemization Economy

## Source Anchors

- Master epic reference: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, System Modules Epic 3
- Related modules: E3.M1, E3.M2, E3.M3, E3.M4, E3.M5

## Ownership and success (Level 1)

- **Ownership focus:** Economy Design + Content Engineering + **Client presentation (Godot)**
- **Success criteria:** Crafting is a primary progression lane with healthy supply-demand loops and consistent item relevance — **playable in the client**, not server/Bruno-only proof.

## Objective

Implement gathering from world nodes, item/inventory representation, recipe execution, and later durability/sinks and economy policy so players can complete gather-refine-craft-use loops that matter for combat and quests.

## Module Breakdown

### E3.M1 - ResourceNodeAndGatherLoop

- Responsibility: Node spawning, gather interaction, resource output events.
- Key contracts: `ResourceNodeDef`, `GatherResult`, `ResourceYieldTable`
- Dependencies: E1.M3, E2.M2
- Stage target: Prototype

### E3.M2 - RefinementAndRecipeExecution

- Responsibility: Raw-to-refined processing and recipe crafting execution pipeline.
- Key contracts: `RecipeDef`, `CraftRequest`, `CraftResult`
- Dependencies: E3.M1, E3.M3
- Stage target: Prototype

### E3.M3 - ItemizationAndInventorySchema

- Responsibility: Item definitions, rarity/quality fields, stackability and equipment metadata.
- Key contracts: `ItemDef`, `ItemInstance`, `InventorySlot`
- Dependencies: None
- Stage target: Prototype

### E3.M4 - SinkAndDurabilityLifecycle

- Responsibility: Item decay/consumption/repair sinks that sustain market demand.
- Key contracts: `DurabilityState`, `ItemSinkEvent`, `RepairCostRule`
- Dependencies: E3.M3, E8.M3
- Stage target: Pre-production

### E3.M5 - EconomyBalancePolicy

- Responsibility: Faucet/sink parameter set and guardrails for inflation/deflation.
- Key contracts: `EconomyPolicy`, `PriceBandRule`, `FaucetSinkRatio`
- Dependencies: E3.M4, E9.M2
- Stage target: Pre-production

## Implementation Slices (Backlog-Ready)

### Slice 1 - Items and inventory MVP

- Scope: E3.M3 with equipment/consumable slots sufficient for prototype loadouts and quests.
- Dependencies: None
- Acceptance criteria:
  - Craft outputs and quest rewards land in inventory deterministically.
  - Item schema versioned for forward-compatible migrations.
- Telemetry hooks: `item_created`, `inventory_full` / transfer failures.

<a id="epic-3-slice-2"></a>

### Slice 2 - Gather nodes and outputs

- Scope: E3.M1 with 4-6 node types and yield tables; awards crafting/gathering XP via E2.M2.
- Dependencies: E3.M3, E1.M3, E2.M2
- Acceptance criteria:
  - Full gather interaction in prototype region without dupes or free resources.
- Telemetry hooks: `resource_gathered`, `gather_node_depleted`.

<a id="epic-3-slice-3"></a>

### Slice 3 - Recipes and crafting pipeline

- Scope: E3.M2 with 8-12 starter recipes per prototype minimums.
- Dependencies: E3.M1, E3.M3
- Acceptance criteria:
  - Player completes gather to refine to usable item used in combat or quest.
- Telemetry hooks: `item_crafted`, `craft_failed` with reason, time-to-first-craft.

<a id="epic-3-slice-5"></a>

### Slice 5 - Client economy integration (prototype)

- Scope: Godot clients + HUD for **E3.M3** inventory, **E3.M1** gather feedback, **E3.M2** craft UI; playable **gather → refine → make** session in the client (vision prototype gates).
- Dependencies: Slice 1–3 server APIs landed ([NEO-55](https://linear.app/neon-sprawl/issue/NEO-55), [NEO-63](https://linear.app/neon-sprawl/issue/NEO-63), [NEO-70](https://linear.app/neon-sprawl/issue/NEO-70)); [E2.M2](https://linear.app/neon-sprawl/issue/NEO-37) skill-progression GET for XP visibility.
- Acceptance criteria:
  - Inventory HUD reflects server state after gather and craft.
  - Player completes **gather → refine → usable item** in Godot without Bruno.
  - **Salvage** / **refine** skill progression visible after gather/craft (Epic 2 Slice 3 integration AC).
- Telemetry hooks: reuse Slice 1–3 server hook sites; client dev **`print`** / HUD feedback only until E9.M1 ingest.

**Linear backlog:** [E3S5-client-prototype-backlog.md](../../plans/E3S5-client-prototype-backlog.md) — [NEO-72](https://linear.app/neon-sprawl/issue/NEO-72) → [NEO-75](https://linear.app/neon-sprawl/issue/NEO-75).

**Status:** Slice 5 client capstone landed — [NEO-75](../../manual-qa/NEO-75.md) manual QA; NEO-72→NEO-75 complete; prototype gather→craft loop playable in Godot (not Bruno-only).

<a id="epic-3-slice-4"></a>

### Slice 4 - Sinks and economy policy (pre-production)

- Scope: E3.M4 + E3.M5 with tuning hooks and validation against outliers.
- Dependencies: E8.M3 (market settlement optional), E9.M2
- Acceptance criteria:
  - At least one durable sink is live; policy alerts on faucet/sink ratio breaches.
- Telemetry hooks: `item_sink`, `repair_performed`, economy KPI aggregates.

## Risks and Mitigations

- Risk: Crafting bypassed by drops or NPC vendors.
  - Mitigation: Prototype quest requires crafted item; monitor gather-to-craft conversion.
- Risk: Exploit duplication or negative stacks.
  - Mitigation: Server-authoritative craft and inventory; integrity signals via E9.M4.

## Definition of Done

- Prototype gather-craft loop meets plan pass/fail gates **in the Godot client** (Slice 5), not Bruno-only.
- Slices 1–3 + Slice 5 together satisfy [vision prototype in-scope features](../../../neon_sprawl_vision.plan.md) for crafting loop and progression visibility.
- Pre-production adds sinks and policy with dashboard visibility (Slice 4).