From c90c5baa41bf56ba8cda25a044ca3a76185b2ef5 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Fri, 3 Apr 2026 21:39:43 -0400 Subject: [PATCH] docs: add game-design abilities.md and wire cross-links - Taxonomy: gig combat abilities, skill interactions, item channels - Decisions log + open questions; links to Seams, E1.M4, E5.M1, Epic 2/5/7 - overview, progression, gigs, skills, README; docs-review-agent ground truth --- .cursor/rules/docs-review-agent.md | 2 +- docs/game-design/README.md | 2 +- docs/game-design/abilities.md | 63 ++++++++++++++++++++++++++++++ docs/game-design/gigs.md | 4 +- docs/game-design/overview.md | 5 ++- docs/game-design/progression.md | 1 + docs/game-design/skills.md | 4 +- 7 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 docs/game-design/abilities.md diff --git a/.cursor/rules/docs-review-agent.md b/.cursor/rules/docs-review-agent.md index 39c756d..054ec43 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`: **Gig** = combat role; **Skill** = non-combat; **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`: **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 f52af3e..33459ed 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), zones, mechanics, items, abilities, 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), zones, mechanics, items, 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 new file mode 100644 index 0000000..2fdfe52 --- /dev/null +++ b/docs/game-design/abilities.md @@ -0,0 +1,63 @@ +# Abilities (player actions) + +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)). + +## Vocabulary + +| Term | Means | +|------|--------| +| **Combat ability** | An action **resolved in the combat loop** (damage, heal, control, buff, movement trick, etc.) that is **authorized by the player’s gig kit**—not by a non-combat **`SkillDef`** line. Unlocks and tuning track **gig level** (and **sub-gig** rules below). | +| **Skill interaction** | A **non-combat** action gated by **skills** and content: gather, craft, hack a door, use a bench, run a **skill-based encounter** slice. Uses **world / economy** systems; **not** the same contract as tab-target **combat** abilities unless we deliberately unify UX later (**open**). | +| **Item channel** | An effect delivered **through an item**: use a consumable, trigger a **weapon or gear** special, **combat-deploy** a Rigging drone, etc. **Whether** it counts as a “combat ability” for the engine is **data-defined** per item and gig match—see **Seams** and **Consumables** in [skills.md](skills.md). | + +## Gig abilities (combat kit) + +- **Source of truth:** the player’s **main gig** defines the **primary** combat kit: which abilities exist, their **unlock rungs** on that gig’s level track, and baseline **party readability** (tank, heal, control, damage, etc.—[gigs.md](gigs.md)). +- **Sub-gig:** adds a **limited** set of **cross-gig** abilities at **effective sub level** (capped vs main—[gigs.md](gigs.md) **Main gig + sub-gig**). Sub supports expression; it does **not** earn **gig XP** while equipped as sub. +- **Progression:** **gig XP** and **gig level** unlock kit rows; **`SkillDef`** XP does **not** replace gig unlocks for combat buttons ([progression.md](progression.md), [Epic 2 — Skills and Progression Framework](../decomposition/epics/epic_02_skills_and_progression.md) Slice 3). +- **Input / UX:** client **hotbar** and targeting feed **combat cast intent** into the authoritative combat rules ([E1.M4 — AbilityInputScaffold](../decomposition/modules/E1_M4_AbilityInputScaffold.md) → [E5.M1 — CombatRulesEngine](../decomposition/modules/E5_M1_CombatRulesEngine.md)). + +## Skill interactions (non-combat) + +- **No combat `SkillDef`:** raising **Salvage** or **Intrusion** does **not** by itself add buttons to the **combat** hotbar; it opens **non-combat** loops and gates ([skills.md](skills.md)). +- **Exception carve-out (design space):** **Tech** that **looks** like “hacking in a fight” may be implemented as **gig** kit (netrunner gig) **or** as **skill-gated** world/object interactions **around** combat—**split** is documented in [skills.md](skills.md) **Tech** / **gig kit** notes; avoid silent double-stacking the same fantasy (**open** until kits are authored). +- **Mission / instance design:** same run can mix **skill** objectives and **gig** combat ([brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md)). + +## Item-linked actions and Seams + +- **Combat gear** (weapons, armor, **Rigging** combat deployables) can **enable**, **modify**, or **channel** abilities according to **gig** allow lists—**craft** stays **skill**/recipe; **field use** stays **gig**-gated where [skills.md](skills.md) **Seams** say so. +- **Consumables:** baseline **use** is not gig-gated; **passive** amps may scale with **main or sub** gig match; **active** consumable abilities—**open** per item ([skills.md](skills.md) **Consumables** row). +- **Cybernetics:** **not** gig-gated for **having** chrome; whether an implant adds a **combat** button is **content**—must still respect server authority and gig readability (**open** catalog). + +## Readability (PvE baseline) + +- **Party scan:** players should infer **role** from **gig** + visible **ability bar** / cast patterns, not from hidden skill grinds. +- **Telegraphs and tab-target:** combat abilities favor **clear** enemy-facing signals and **readable** timing—detail lives in future **combat pillars** ([overview.md](overview.md) stub) and [Epic 5 — PvE combat](../decomposition/epics/epic_05_pve_combat.md). + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Combat ability ownership | **Gig kit** + **item channels** per data; **not** unlocked by **`SkillDef`** XP | Agreed | +| Sub-gig combat abilities | **Limited** kit at **effective sub level**; no sub **gig XP** from combat | Agreed ([gigs.md](gigs.md)) | +| Non-combat actions | **`SkillDef`** / world gates; **separate** from combat hotbar by default | Agreed | +| Consumable actives | Per-item rules; **passive** gig amp from main or sub where designed | Agreed direction ([skills.md](skills.md)) | +| Same fantasy, two systems (e.g. netrun) | **Gig** vs **skill** split explicit in content; avoid duplicate **open** | Open | + +## Open questions + +- **Combat pillars** doc: TTK bands, interrupt rules, friendly-fire posture—stub in [overview.md](overview.md). +- **Ability count per gig**, **resource types** (energy, ammo, heat), and **ground-target** vs **single-target** mix for isometric presentation. +- **Pets / summons / persistent deployables** as ability carriers vs pure **item deploy**—Rigging + gig kit intersection. + +## Where to read next + +| Topic | Document | +|--------|----------| +| Gig roster, hub swap, XP | [gigs.md](gigs.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) | +| Input → combat | [E1.M4](../decomposition/modules/E1_M4_AbilityInputScaffold.md), [E5.M1](../decomposition/modules/E5_M1_CombatRulesEngine.md) | diff --git a/docs/game-design/gigs.md b/docs/game-design/gigs.md index 96a8807..cddc4a4 100644 --- a/docs/game-design/gigs.md +++ b/docs/game-design/gigs.md @@ -129,7 +129,7 @@ Detail: seams table in [skills.md](skills.md). ## Next artifacts -- [Abilities](overview.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)). +- [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. - [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/overview.md b/docs/game-design/overview.md index ab3c89a..72191cd 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). **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). **Loose ideas:** [`brainstorm/`](brainstorm/README.md). ## Presentation and target rating (vision) @@ -25,6 +25,7 @@ Neon Sprawl’s design work here starts from **concrete visions** of progression | [progression.md](progression.md) | Shared **gig + skill** vision, vocabulary, links | Start here for 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 | | [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 - **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. -- **Abilities** — inputs, timing; combo with items; **gig** vs **skill** gates (see [progression.md](progression.md) vocabulary). +- **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. - **Economy** — currency velocity, sinks, trade vs. self-sufficiency, how wealth shows up in play. diff --git a/docs/game-design/progression.md b/docs/game-design/progression.md index 1368ffb..23288a0 100644 --- a/docs/game-design/progression.md +++ b/docs/game-design/progression.md @@ -26,6 +26,7 @@ Use these terms in **design specs and tools** (fiction may say *job*, *contract* | Topic | Document | |--------|-----------| | 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) | | 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 fbd1de9..03c1e6c 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)**. +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)**. **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). @@ -248,6 +248,6 @@ Explicit **bonuses** when skill A + B cross a threshold vs **pure fiction** (“ ## Next artifacts - **[gigs.md](gigs.md)** — gig roster, hub UX, recruitment **deferred**; **PvP** gig rules **open indefinite** (overall PvP scope TBD). -- **Abilities** — **gig-locked** vs. **item-locked** vs. **skill-gated**. +- **[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)). - [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) — group **skill** (hack) + **gig** (bodyguard) instances (brainstorm).