From 940cc71840f0bd94bcf4fcf14dd5564005c72c7b Mon Sep 17 00:00:00 2001 From: VinPropane Date: Fri, 3 Apr 2026 21:42:18 -0400 Subject: [PATCH] chore: add game-design items doc and cross-links - Add items.md (buckets, acquisition, rarity, loadouts, open questions) - Link from overview, progression, skills, gigs, abilities, README - Include items.md in docs-review-agent ground-truth list - Fix content README path in items.md --- .cursor/rules/docs-review-agent.md | 2 +- docs/game-design/README.md | 2 +- docs/game-design/abilities.md | 3 +- docs/game-design/gigs.md | 2 +- docs/game-design/items.md | 61 ++++++++++++++++++++++++++++++ docs/game-design/overview.md | 5 ++- docs/game-design/progression.md | 1 + docs/game-design/skills.md | 4 +- 8 files changed, 72 insertions(+), 8 deletions(-) create mode 100644 docs/game-design/items.md diff --git a/.cursor/rules/docs-review-agent.md b/.cursor/rules/docs-review-agent.md index 054ec43..197df3c 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`: **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). **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`: **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). **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 33459ed..faeca6c 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), zones, mechanics, items, 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), 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 2fdfe52..3036de3 100644 --- a/docs/game-design/abilities.md +++ b/docs/game-design/abilities.md @@ -2,7 +2,7 @@ Vision for **what the player triggers** in play: combat **kits**, non-combat **skill interactions**, and **item**-carried actions—and how those map to **gigs**, **`SkillDef`**, and **Seams**. This is **not** a full ability list or data schema; it steers combat design, UX, and implementation boundaries. -**Framing:** [progression.md](progression.md) (**gig** vs **skill**). **Combat roles:** [gigs.md](gigs.md). **Gear, craft, consumables:** [skills.md](skills.md) **Seams** ([anchor](skills.md#seams-gigs-skills)). +**Framing:** [progression.md](progression.md) (**gig** vs **skill**). **Combat roles:** [gigs.md](gigs.md). **Gear, craft, consumables:** [skills.md](skills.md) **Seams** ([anchor](skills.md#seams-gigs-skills)). **Item buckets & acquisition:** [items.md](items.md). ## Vocabulary @@ -57,6 +57,7 @@ Vision for **what the player triggers** in play: combat **kits**, non-combat **s | Topic | Document | |--------|----------| | Gig roster, hub swap, XP | [gigs.md](gigs.md) | +| Item categories, craft vs loot | [items.md](items.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/gigs.md b/docs/game-design/gigs.md index cddc4a4..06d7666 100644 --- a/docs/game-design/gigs.md +++ b/docs/game-design/gigs.md @@ -131,5 +131,5 @@ Detail: seams table in [skills.md](skills.md). - [abilities.md](abilities.md) — **gig-locked** kits, sub-gig ability rules, telegraphs ([Epic 5](../decomposition/epics/epic_05_pve_combat.md)). - [Combat pillars](overview.md) — PvE readability, TTK, risk ([overview](overview.md); stub until a dedicated doc ships). -- [Items](overview.md) — equip tags per gig; crafted vs dropped. +- [items.md](items.md) — **combat gear** vs chrome vs consumables; craft vs loot; loadout + swap ([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 new file mode 100644 index 0000000..61cb2f8 --- /dev/null +++ b/docs/game-design/items.md @@ -0,0 +1,61 @@ +# Items (loot, craft, equip) + +Vision for **what exists in the world as tangible “things”**: how items are **categorized**, **acquired**, **gated** by **gigs** vs **skills**, and how they connect to **combat**, **economy**, and **quests**. Not an `ItemDef` schema—that lives under [Epic 3 — Crafting economy](../decomposition/epics/epic_03_crafting_economy.md) and [`content/`](../../content/README.md) when wired. + +**Seams (authoritative detail):** [skills.md — Seams (gigs ↔ skills)](skills.md#seams-gigs-skills). **Actions from items:** [abilities.md](abilities.md) **Item-linked actions**. **Hybrid vocabulary:** [progression.md](progression.md). + +## Buckets (design-facing) + +These overlap in data; they are **lenses** for writers and systems. + +| Bucket | Role | Gig vs skill (summary) | +|--------|------|-------------------------| +| **Combat gear** | Weapons, **Hardshell** / **Softshell** / **Rigging**-built powered shells worn as loadout, **combat deployables** (e.g. fight drones)—**swap-friendly** | **Craft:** **skills** only. **Equip / wear / combat-deploy / activation in combat:** **gig**-tagged ([Seams](skills.md#seams-gigs-skills)). | +| **Cybernetics** | Body-integrated augments—**semi-permanent** | **Craft / install:** **skills** + world gates. **Not** removed by **gig swap**; **not** the same bucket as external armor ([Seams](skills.md#seams-gigs-skills)). | +| **Consumables** | Stims, patches, ammo-adjacent one-shots, etc. | **Carry / use** baseline **not** gig-gated; **passive** amps may scale with **main or sub** gig match (**open** actives per item). | +| **Non-combat Make** | Tools, **Food synth** outputs, civ gear, **utility Rigging** (harnesses, survey drones, **backpacks**) | **Craft:** recipe **skills**. **Use:** **skill**-gated when the item defines a **specialty**; some utilities have **no** use gate ([Seams](skills.md#seams-gigs-skills)). | +| **Materials & intermediates** | Ores, refinery grades, components, data objects, organics | Feed **recipes** and **economy depth**; usually **no** gig hook unless a piece is explicitly hybrid (**open**). | + +## 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). +- **Dropped / looted / salvaged:** Feed **gather–refine–craft** loops and **world fiction**; tuning is **content + economy policy** (**open** drop tables). +- **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**). + +## Rarity, quality, and readability + +- **Rarity** (or tier) signals **expectations**: availability, mod slots, repair cost, **faction** hooks—exact bands **data-driven** later. +- **Quality** within a tier may reflect **craft skill**, **recipe mastery**, or **material grade**—**open** math; directionally **crafting should compete with drops** where the economy needs it. +- **Tooltips** should expose **gig** match for **combat gear** and **consumable** amps, **intended skill** for specialty **non-combat** tools, and a **clear** lane for **cybernetics** vs **external armor** ([skills.md](skills.md) **Player-facing readability**). + +## Gig swap and loadouts + +- **Hub-only** [gig swap](gigs.md#hub-swap): **combat gear** may **invalidate** until the player **re-banks or re-equips**; **cybernetics** stay. +- **Presets** (per gig pair, per role) vs **manual** fix-up—**open** UX ([gigs.md](gigs.md), [abilities.md](abilities.md)). + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Craft vs equip split | **Bench** = **skill**/recipe; **combat field use** of most **non-consumable** **Make** = **gig**-gated | Agreed ([Seams](skills.md#seams-gigs-skills)) | +| Cybernetics vs armor | **No** bucket overlap; chrome is **character**-scoped; plates are **loadout** | Agreed | +| Consumable baseline | Anyone can **use**; **optional** gig-tuned **passive** potency | Agreed direction | +| Craft without gig | Allowed; **trade** and **group** play supported | Agreed | +| Player crafting relevance | **Crafting** is a **primary** progression lane—not only consumables | Agreed ([Epic 3](../decomposition/epics/epic_03_crafting_economy.md)) | + +## Open questions + +- **Durability, repair, sinks**—when items leave the economy ([E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md)); how hard **death** hits gear (**open** with death doc). +- **Binding**, **insurance**, **theft** in which **security tiers** ([overview.md](overview.md) risk stubs). +- **Named crafter**, **provenance**, **counterfeits**—social/economy flavor vs implementation cost. +- **Stacking**, **charges**, **mod slots**—per category defaults. + +## Where to read next + +| Topic | Document / module | +|--------|-------------------| +| Gig ↔ item rules (detail) | [skills.md](skills.md) **Seams** | +| Abilities from items | [abilities.md](abilities.md) | +| Gathering & recipes (runtime) | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md), [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md), [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | +| Encounter loot routing | [E5.M3](../decomposition/modules/E5_M3_EncounterAndRewardTables.md), [E7.M2](../decomposition/modules/E7_M2_RewardAndUnlockRouter.md) | diff --git a/docs/game-design/overview.md b/docs/game-design/overview.md index 72191cd..64c48db 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). **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). **Loose ideas:** [`brainstorm/`](brainstorm/README.md). ## Presentation and target rating (vision) @@ -26,6 +26,7 @@ Neon Sprawl’s design work here starts from **concrete visions** of progression | [skills.md](skills.md) | Non-combat **skills**; seams; **v0 skill roster** by category | With [gigs.md](gigs.md); roster encodes **Hardshell** / **Softshell** / **Edgesmith** / **Rigging** equip vs **combat-deploy** rules ([Seams](skills.md#seams-gigs-skills)) | | [gigs.md](gigs.md) | **9-gig roster** (v1 cyberpunk names); hub, sub-gig, party | Recruitment **deferred**; PvP **open indefinite**; niche LFG **if** tool ships | | [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** still stub in this overview | +| [items.md](items.md) | Buckets (gear, chrome, consumables, mats); craft vs drops; rarity/readability | **Seams** in [skills.md](skills.md); **Epic 3** for implementation | | [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) | Split **skill** (hack) + **gig** (bodyguard) instances—idea capture | Brainstorm | | *(add rows as files land)* | | | @@ -37,7 +38,7 @@ Link new files here when they exist; remove or rewrite this subsection once the - **Zones** — tone, danger, faction or economic role of a place. - **Travel & connections** — how places link (gates, costs, downtime, danger en route); complements zone identity. - **Mechanics** — loops, constraints, what the server vs. client must honor. -- **Items** — categories, rarity philosophy, crafting vs. drops. +- **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 pillars** stub remains below until written. - **Gathering & resources** — nodes, competition, exhaustion, what “open world” contesting feels like. - **Crafting & recipes** — depth vs. breadth, failure, specialization; pairs with items but is its own loop. diff --git a/docs/game-design/progression.md b/docs/game-design/progression.md index 23288a0..5d5daec 100644 --- a/docs/game-design/progression.md +++ b/docs/game-design/progression.md @@ -27,6 +27,7 @@ Use these terms in **design specs and tools** (fiction may say *job*, *contract* |--------|-----------| | Gig roster, hub swap, sub-gig, XP, party/PvP notes | [gigs.md](gigs.md) | | Combat vs non-combat **actions** (kits, skill interactions, items) | [abilities.md](abilities.md) | +| **Items** (craft, loot, equip, gig/skill gates) | [items.md](items.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 03c1e6c..cd296dc 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)**. +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)**. **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). @@ -249,5 +249,5 @@ Explicit **bonuses** when skill A + B cross a threshold vs **pure fiction** (“ - **[gigs.md](gigs.md)** — gig roster, hub UX, recruitment **deferred**; **PvP** gig rules **open indefinite** (overall PvP scope TBD). - **[abilities.md](abilities.md)** — **gig** combat kits vs **skill** interactions vs **item** channels (written). -- **Items** — **equip / combat-deploy:** gig rules for **combat gear**; **non-combat** **Rigging** / **utility** **use** vs specialty **skills**; **cybernetics** character-wide; **craft:** **skills** only—never gig level ([Seams](#seams-gigs-skills)). +- **[items.md](items.md)** — buckets, craft vs drops, rarity/readability; detail still in [Seams](#seams-gigs-skills). - [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) — group **skill** (hack) + **gig** (bodyguard) instances (brainstorm).