diff --git a/.cursor/rules/docs-review-agent.md b/.cursor/rules/docs-review-agent.md index e51e321..941597f 100644 --- a/.cursor/rules/docs-review-agent.md +++ b/.cursor/rules/docs-review-agent.md @@ -26,7 +26,7 @@ Use this rule when the user is working in **`docs/`** (design, decomposition, pl ## Ground truth (required to check) 1. **Same folder and upstream links** — Read every `docs/...` link from the target doc(s); verify paths exist and headings match intent. -2. **Hybrid progression** — `docs/game-design/progression.md`, `skills.md`, `gigs.md`, `abilities.md`, `items.md`, `gathering.md`: **Gig** = combat role; **Skill** = non-combat; **combat abilities** = gig kit (+ item channels per data); **Seams** live in `skills.md` unless a dedicated doc supersedes. **Combat encounters** → **gig XP** only (no default skill XP from the fight loop). **Gather / craft** → **skill XP** (see `gathering.md`, Epic 3)—not **gig** XP. **Mission/quest rewards** may still grant **skill XP** when explicitly defined—separate from the encounter **gig XP** path. +2. **Hybrid progression** — `docs/game-design/progression.md`, `skills.md`, `gigs.md`, `abilities.md`, `items.md`, `gathering.md`, `crafting.md`: **Gig** = combat role; **Skill** = non-combat; **combat abilities** = gig kit (+ item channels per data); **Seams** live in `skills.md` unless a dedicated doc supersedes. **Combat encounters** → **gig XP** only (no default skill XP from the fight loop). **Gather / craft** → **skill XP** (see `gathering.md`, `crafting.md`, Epic 3)—not **gig** XP. **Mission/quest rewards** may still grant **skill XP** when explicitly defined—separate from the encounter **gig XP** path. 3. **Decomposition** — Map claims to `docs/decomposition/epics/` and `docs/decomposition/modules/` where relevant; flag **conflicts** (e.g. “combat skill” vs skills-as-non-combat). **CI** enforces a minimal guard via [`scripts/check_decomposition_language.py`](../../scripts/check_decomposition_language.py) in the **PR gate** (extend the script if a vetted exception is needed). 4. **Plans** — If work maps to `docs/plans/`, check for **acceptance criteria** vs design doc (same spirit as [code-review-agent](code-review-agent.md) plan alignment). diff --git a/docs/game-design/README.md b/docs/game-design/README.md index 6a68ed6..a977e7e 100644 --- a/docs/game-design/README.md +++ b/docs/game-design/README.md @@ -6,6 +6,6 @@ **Brainstorm-only** (not specs): [`brainstorm/`](brainstorm/README.md). -Non-implementation notes: **gigs** (combat roles), **skills** (non-combat), **[abilities](abilities.md)** (what players trigger), **[items](items.md)** (loot, craft, equip), **[gathering](gathering.md)** (resource nodes, yields), zones, mechanics, and other design artifacts before they are tied to concrete systems or tickets. +Non-implementation notes: **gigs** (combat roles), **skills** (non-combat), **[abilities](abilities.md)** (what players trigger), **[items](items.md)** (loot, craft, equip), **[gathering](gathering.md)** (resource nodes, yields), **[crafting](crafting.md)** (recipes, pipeline), zones, mechanics, and other design artifacts before they are tied to concrete systems or tickets. Implementation-facing breakdowns stay under [`docs/decomposition/`](../decomposition/README.md) and plans under [`docs/plans/`](../plans/). diff --git a/docs/game-design/abilities.md b/docs/game-design/abilities.md index fccfe7d..c4b3c23 100644 --- a/docs/game-design/abilities.md +++ b/docs/game-design/abilities.md @@ -59,6 +59,7 @@ Vision for **what the player triggers** in play: combat **kits**, non-combat **s | Gig roster, hub swap, XP | [gigs.md](gigs.md) | | Item categories, craft vs loot | [items.md](items.md) | | Gathering (skill XP, nodes—not gig) | [gathering.md](gathering.md) | +| Crafting (bench skill vs gig combat use) | [crafting.md](crafting.md) | | Seams (gear, craft, consumables) | [skills.md](skills.md) | | Hybrid vocabulary | [progression.md](progression.md) | | Encounter rewards + combat hooks | [Epic 5](../decomposition/epics/epic_05_pve_combat.md), [Epic 7](../decomposition/epics/epic_07_quest_faction.md) | diff --git a/docs/game-design/crafting.md b/docs/game-design/crafting.md new file mode 100644 index 0000000..6a04ae1 --- /dev/null +++ b/docs/game-design/crafting.md @@ -0,0 +1,75 @@ +# Crafting & recipes + +Vision for **turning inputs into outputs at benches** (and similar stations): **recipe shape**, **skill gates**, **multi-step pipelines**, and how crafting stays **skill** progression while **combat use** of products follows **gig** rules. + +**Runtime ownership:** [E3.M2 — RefinementAndRecipeExecution](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) validates **`CraftRequest`** against **`RecipeDef`**, produces **`CraftResult`** (success/failure, outputs, reason codes), and mutates inventory **server-authoritatively** with [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md). Inputs include [gathering.md](gathering.md) outputs, drops, and trade. + +**Skill roster:** **Process** and **Make** tables in [skills.md](skills.md#skill-roster-draft-ideas-by-category) (**Refine**, **Fab tech**, **Data scrub**, **Make** skills, etc.). **Chain shape:** [skills.md](skills.md) **Production chains** (**Gather → Process → Make**, branching and depth). **Seams (bench vs combat):** [skills.md — Seams](skills.md#seams-gigs-skills). **Item buckets from outputs:** [items.md](items.md). **Hybrid vocabulary:** [progression.md](progression.md). + +## Gig vs skill + +- **Crafting and refining are skills**, not **gigs**. **No gig XP** from recipe execution—**skill XP** from successful craft/refine (and related activity) via [E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md) ([progression.md](progression.md), [Epic 2 — Skills](../decomposition/epics/epic_02_skills_and_progression.md) **Slice 3**). +- **Bench = skill / recipe gate**; **equip, wear, combat-deploy** for most **non-consumable** products stays **gig**-tagged when brought into combat ([items.md](items.md), [Seams](skills.md#seams-gigs-skills)). **Consumables** and **general utility** may have **no** gig **use** gate per item data. +- **World gates** (rep, licenses, station access) add **content** without “you picked the wrong class” for the whole economy ([skills.md](skills.md) **Pillars**). + +## Pipeline (design-facing) + +Authoritative **recipe graph** is **data** (`RecipeDef`); design intent: + +| Idea | Meaning | +|------|---------| +| **Depth** | **Gather → Process → Process → Make** (or longer)—intermediates feed intermediates ([skills.md](skills.md) **Multi-stage processing**). | +| **Branching** | Same inputs can route to **different** skills or recipes for **different** outputs (**overlapping chains**)—dense economy, not a single trunk. | +| **Skill per recipe** | Each recipe names **required skill** (and level band **TBD**); one **Process** skill is not the only mid-pipeline actor. | + +**Prototype scope:** [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) **Slice 3** targets a **starter recipe set** (e.g. 8–12 minimums in epic text) proving **gather → refine → item used in combat or quest**. + +## Stations, co-op, and UX + +- **Station types** (personal bench, public fab, corp line, mobile kit)—**open**; `RecipeDef` may carry **station** or **tag** requirements as scope grows. +- **Crafting for others** (commission, party assist)—**valid** fantasy aligned with [items.md](items.md) **Trade** and [Seams](skills.md#seams-gigs-skills); **implementation** **open**. +- **Queue, batch, cancel**—**open** UX; server remains authoritative on **`CraftResult`**. + +## Failure, quality, and mastery + +- **Craft failure** (lost materials vs returned partials vs soft fail)—**open**; must play nicely with **exploit** review and **E9** integrity patterns when live. +- **Quality** on output (tier within `ItemDef`, bonus stats, durability band)—aligns with [items.md](items.md) **Rarity, quality**; whether **skill level**, **recipe mastery**, **input grade**, or **RNG** mix—**open** math. +- **Recipe discovery** (trainers, experimentation, rep unlocks, data theft **fiction**)—**open**; **mission grants** may teach recipes without replacing **do the loop** as primary fantasy ([skills.md](skills.md) **XP**). + +## Module map (crafting-focused) + +| Module | Role | Ties to this doc | +|--------|------|-------------------| +| [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) | `RecipeDef`, craft execution | **Core** | +| [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) | Gather outputs | **Inputs** | +| [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | Costs, outputs, stacks | **Inventory** | +| [E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md) | Skill XP on craft | **Progression** | +| [E3.M5](../decomposition/modules/E3_M5_EconomyBalancePolicy.md) | Faucets/sinks | Craft vs drop **parity** (later) | +| [E7.M1](../decomposition/modules/E7_M1_QuestStateMachine.md) | Quest steps | Craft **objectives** / hand-ins | +| [E6.M4](../decomposition/modules/E6_M4_RewardParityEnforcer.md) | Reward parity | Craft vs other reward **lanes** | + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Bench vs combat | **Craft** on **skill**; **combat field use** of most **non-consumable** **Make** = **gig**-gated | Agreed ([Seams](skills.md#seams-gigs-skills)) | +| Pipeline shape | **Gather → Process → Make** with **branching** and **multi-hop** depth | Agreed ([skills.md](skills.md)) | +| Craft → skill XP | **Skill** XP from craft/gather pipes; not **gig** XP | Agreed ([progression.md](progression.md)) | +| Player-made relevance | **Crafting** is a **primary** progression lane | Agreed ([Epic 3](../decomposition/epics/epic_03_crafting_economy.md)) | + +## Open questions + +- **Critical success / crit craft**—flavor vs economy distortion. +- **Time gating** (real-time jobs, offline queue)—fantasy vs session pacing. +- **Ammo and consumable churn**—how much **Make** is **repeatable grind** vs **milestone** crafts. +- **Cross-character recipe locks** (account, legacy blueprint)—social and alt policy. + +## Where to read next + +| Topic | Document / module | +|--------|-------------------| +| Process / Make skill names | [skills.md](skills.md) **Process** and **Make** tables | +| Raw inputs from the world | [gathering.md](gathering.md) | +| Item categories & tooltips | [items.md](items.md) | +| Epic 3 craft slice | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) — *Slice 3 — Recipes and crafting pipeline* | +| Gather slice (inputs) | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) — *Slice 2 — Gather nodes and outputs* | diff --git a/docs/game-design/gathering.md b/docs/game-design/gathering.md index 4b26cbb..b64c78a 100644 --- a/docs/game-design/gathering.md +++ b/docs/game-design/gathering.md @@ -41,7 +41,7 @@ Directional goals (implementation **open**): ## Pipeline position -**Gather → Process → Make** is the agreed chain shape ([skills.md](skills.md) **Production chains**). This doc stops at **raw outputs**; **refine / fab / recipes** are [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) and a future **crafting & recipes** vision doc. +**Gather → Process → Make** is the agreed chain shape ([skills.md](skills.md) **Production chains**). This doc stops at **raw outputs**; **recipes, benches, and pipeline vision:** [crafting.md](crafting.md); **runtime contracts:** [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md). ## Module map (gathering-focused) @@ -74,6 +74,7 @@ Directional goals (implementation **open**): |--------|-------------------| | Gather skill names & merge notes | [skills.md](skills.md) **Gather** table | | Items & materials buckets | [items.md](items.md) | +| Crafting & recipes (vision) | [crafting.md](crafting.md) | | Epic 3 gather slice | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) — *Slice 2 — Gather nodes and outputs* | | Interaction contracts | [E1.M3](../decomposition/modules/E1_M3_InteractionAndTargetingLayer.md) | | Zone ecology | [E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md), [Epic 4](../decomposition/epics/epic_04_world_topology.md) | diff --git a/docs/game-design/gigs.md b/docs/game-design/gigs.md index 4a905fe..5934582 100644 --- a/docs/game-design/gigs.md +++ b/docs/game-design/gigs.md @@ -133,4 +133,5 @@ Detail: seams table in [skills.md](skills.md). - [Combat pillars](overview.md) — PvE readability, TTK, risk ([overview](overview.md); stub until a dedicated doc ships). - [items.md](items.md) — **combat gear** vs chrome vs consumables; craft vs loot; loadout + swap ([Seams](skills.md#seams-gigs-skills)). - [gathering.md](gathering.md) — **not** gig progression; **skill** nodes and yields feed economy ([progression.md](progression.md)). +- [crafting.md](crafting.md) — **bench** = **skill**; **combat use** of most crafted **gear** still **gig**-gated ([Seams](skills.md#seams-gigs-skills)). - [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) — group content where **gigs** hold security while **skills** run the hack (brainstorm). diff --git a/docs/game-design/items.md b/docs/game-design/items.md index 8b88549..362665b 100644 --- a/docs/game-design/items.md +++ b/docs/game-design/items.md @@ -20,7 +20,7 @@ These overlap in data; they are **lenses** for writers and systems. ## Acquisition -- **Crafted:** Primary fantasy for **durables** that matter in combat and economy—**player-made goods stay relevant** across stages ([Epic 3](../decomposition/epics/epic_03_crafting_economy.md) success criteria). +- **Crafted:** Primary fantasy for **durables** that matter in combat and economy—**player-made goods stay relevant** across stages ([Epic 3](../decomposition/epics/epic_03_crafting_economy.md) success criteria). **Recipe pipeline & benches:** [crafting.md](crafting.md). - **Dropped / looted / salvaged:** Feed **gather–refine–craft** loops and **world fiction**; tuning is **content + economy policy** (**open** drop tables). **World-sourced raw** (nodes, yields): [gathering.md](gathering.md). - **Mission & vendor rewards:** Can grant **items** or **skill XP** separately from combat XP pipes ([progression.md](progression.md)); avoid double-dipping the same milestone without intent (**open** reward UX). - **Trade:** Craft-for-others is **valid** even when the buyer cannot **equip** or **combat-deploy** the product ([Seams](skills.md#seams-gigs-skills) **Crafting combat gear**). @@ -75,7 +75,8 @@ Design **buckets** above are not 1:1 types in data—they inform tags and metada | Epic 3 loop & slices | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) | | Gathering vision (nodes, contesting) | [gathering.md](gathering.md) | | Gather module | [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) | -| Recipes & craft pipeline | [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) | +| Crafting vision (recipes, pipeline, quality) | [crafting.md](crafting.md) | +| Recipes & craft pipeline (runtime) | [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) | | Item schema & inventory | [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | | Sinks & durability | [E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) | | Economy policy | [E3.M5](../decomposition/modules/E3_M5_EconomyBalancePolicy.md) | diff --git a/docs/game-design/overview.md b/docs/game-design/overview.md index 2a29a3b..3ea0e34 100644 --- a/docs/game-design/overview.md +++ b/docs/game-design/overview.md @@ -6,7 +6,7 @@ This folder holds **vision-level** design: what we want players to feel, do, and Neon Sprawl’s design work here starts from **concrete visions** of progression, places, risk, economy, social play, combat, and the items/abilities that express them. Documents below are added as we write them; each should stay opinionated and specific enough to argue with, without pretending to be a full GDD. -**Hybrid progression:** [progression.md](progression.md) (vocabulary + why gigs + skills). **Gig** detail: [gigs.md](gigs.md). **Skills** + **seams**: [skills.md](skills.md). **Abilities** (combat vs non-combat actions): [abilities.md](abilities.md). **Items** (loot, craft, equip): [items.md](items.md). **Gathering** (nodes, skill XP, ecology): [gathering.md](gathering.md). **Loose ideas:** [`brainstorm/`](brainstorm/README.md). +**Hybrid progression:** [progression.md](progression.md) (vocabulary + why gigs + skills). **Gig** detail: [gigs.md](gigs.md). **Skills** + **seams**: [skills.md](skills.md). **Abilities** (combat vs non-combat actions): [abilities.md](abilities.md). **Items** (loot, craft, equip): [items.md](items.md). **Gathering** (nodes, skill XP, ecology): [gathering.md](gathering.md). **Crafting** (recipes, pipeline, benches): [crafting.md](crafting.md). **Loose ideas:** [`brainstorm/`](brainstorm/README.md). ## Presentation and target rating (vision) @@ -28,6 +28,7 @@ Neon Sprawl’s design work here starts from **concrete visions** of progression | [abilities.md](abilities.md) | **Combat** gig kits vs **skill** interactions vs **item** channels; Seams hooks | With [gigs.md](gigs.md), [skills.md](skills.md); [Combat pillars (vision stub)](#combat-pillars-vision-stub) | | [items.md](items.md) | Buckets (gear, chrome, consumables, mats); craft vs drops; rarity/readability | **Seams** in [skills.md](skills.md); **Epic 3 module map** in [items.md](items.md#epic-3-module-map) | | [gathering.md](gathering.md) | Resource **nodes**, **Gather** skills, contesting, pipeline to refine/craft | **E3.M1** + **E4.M2**; with [skills.md](skills.md), [items.md](items.md) | +| [crafting.md](crafting.md) | **Recipes**, **Process/Make** pipeline, bench vs **gig** combat use | **E3.M2**; with [gathering.md](gathering.md), [items.md](items.md), [skills.md](skills.md) **Seams** | | [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) | Split **skill** (hack) + **gig** (bodyguard) instances—idea capture | Brainstorm | | *(add rows as files land)* | | | @@ -42,7 +43,7 @@ Link new files here when they exist; remove or rewrite this subsection once the - **Items** — [items.md](items.md): categories, rarity philosophy, crafting vs. drops; **Seams** for gig/skill gates. - **Abilities** — [abilities.md](abilities.md): inputs, timing; combo with items; **gig** vs **skill** gates (see [progression.md](progression.md) vocabulary). **Combat context:** [Combat pillars (vision stub)](#combat-pillars-vision-stub). - **Gathering & resources** — [gathering.md](gathering.md): nodes, competition, exhaustion, open-world contesting; **skill XP** not **gig** XP. -- **Crafting & recipes** — depth vs. breadth, failure, specialization; pairs with items but is its own loop. +- **Crafting & recipes** — [crafting.md](crafting.md): depth vs breadth, failure, quality, stations; **skill XP**; [items.md](items.md) for output buckets. - **Economy** — currency velocity, sinks, trade vs. self-sufficiency, how wealth shows up in play. - **Factions & reputation** — who remembers you, grudges, access gates; **gig** story arcs: [gigs.md](gigs.md), rep + seams: [skills.md](skills.md). - **Combat pillars** — [Vision stub below](#combat-pillars-vision-stub): PvE vs. PvP stance, readability, time-to-kill, fairness; **items in combat** in [items.md](items.md). diff --git a/docs/game-design/progression.md b/docs/game-design/progression.md index 73df53d..9929919 100644 --- a/docs/game-design/progression.md +++ b/docs/game-design/progression.md @@ -29,6 +29,7 @@ Use these terms in **design specs and tools** (fiction may say *job*, *contract* | Combat vs non-combat **actions** (kits, skill interactions, items) | [abilities.md](abilities.md) | | **Items** (craft, loot, equip, gig/skill gates) | [items.md](items.md) | | **Gathering** (nodes, yields, skill XP—not gig) | [gathering.md](gathering.md) | +| **Crafting** (recipes, pipeline, bench vs gig) | [crafting.md](crafting.md) | | Skill domains, categories, XP curves, gates, mastery | [skills.md](skills.md) | | **Seams** (combat gear vs craft, consumables, rep, alts) | [skills.md](skills.md) (section *Seams (gigs ↔ skills)*) | | Loose ideas | [brainstorm/](brainstorm/README.md) | diff --git a/docs/game-design/skills.md b/docs/game-design/skills.md index a001a1f..3653d15 100644 --- a/docs/game-design/skills.md +++ b/docs/game-design/skills.md @@ -1,6 +1,6 @@ # Skills (non-combat progression) -Design for **non-combat skills** only. **Shared vocabulary**, **why we use gigs + skills**, and the **hybrid overview** are in **[progression.md](progression.md)**. **Combat gigs** (roster, hub swap, sub-gig, etc.) are **[gigs.md](gigs.md)**. **What counts as a combat vs non-combat action** (kits, interactions, items): **[abilities.md](abilities.md)**. **Item buckets and acquisition** (loot, craft, equip): **[items.md](items.md)**. **Gathering & resource nodes** (competition, ecology, gig vs skill): **[gathering.md](gathering.md)**. +Design for **non-combat skills** only. **Shared vocabulary**, **why we use gigs + skills**, and the **hybrid overview** are in **[progression.md](progression.md)**. **Combat gigs** (roster, hub swap, sub-gig, etc.) are **[gigs.md](gigs.md)**. **What counts as a combat vs non-combat action** (kits, interactions, items): **[abilities.md](abilities.md)**. **Item buckets and acquisition** (loot, craft, equip): **[items.md](items.md)**. **Gathering & resource nodes** (competition, ecology, gig vs skill): **[gathering.md](gathering.md)**. **Crafting & recipes** (pipeline, benches, failure/quality): **[crafting.md](crafting.md)**. **This file also owns the [Seams (gigs ↔ skills)](#seams-gigs-skills)** section—rules where **gigs** and **skills** meet (gear, crafting, consumables, rep, alts). **Brainstorm-only** ideas: [`brainstorm/`](brainstorm/README.md). @@ -251,4 +251,5 @@ Explicit **bonuses** when skill A + B cross a threshold vs **pure fiction** (“ - **[abilities.md](abilities.md)** — **gig** combat kits vs **skill** interactions vs **item** channels (written). - **[items.md](items.md)** — buckets, craft vs drops, rarity/readability; detail still in [Seams](#seams-gigs-skills). - **[gathering.md](gathering.md)** — nodes, yields, **skill** XP from gather; **E3.M1** / **E4.M2** hooks (written). +- **[crafting.md](crafting.md)** — **Process/Make** pipeline, **RecipeDef** vision, bench vs **gig**; **E3.M2** (written). - [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) — group **skill** (hack) + **gig** (bodyguard) instances (brainstorm).