neon-sprawl/docs/game-design/overview.md

# Game design overview

This folder holds **vision-level** design: what we want players to feel, do, and discover before we lock schemas, APIs, or content pipelines. Use it for brainstorming and alignment; when something is ready to drive implementation, it should gain a path in [`docs/decomposition/`](../decomposition/README.md) or [`docs/plans/`](../plans/).

**Governing axioms** (same as the master plan): **(1) it must be fun** — player experience is the ultimate filter for design choices. **(2) it must be distinctly cyberpunk in theme** — setting, tone, and flavor should read as cyberpunk, not generic sci-fi. Full wording: [Vision and Product Intent — Design axioms](../../neon_sprawl_vision.plan.md#design-axioms-governing) in [`neon_sprawl_vision.plan.md`](../../neon_sprawl_vision.plan.md).

## Summary

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). **Crafting** (recipes, pipeline, benches): [crafting.md](crafting.md). **Economy** (faucets, sinks, trade, policy): [economy.md](economy.md). **Death / loss / recovery:** [death-loss-recovery.md](death-loss-recovery.md). **Risk & security bands:** [risk-security-bands.md](risk-security-bands.md). **Zones** (place identity, tone, hooks): [zones.md](zones.md). **Loose ideas:** [`brainstorm/`](brainstorm/README.md).

## Presentation and target rating (vision)

**Intent:** The world and systems can carry **very grim** **ideas** (e.g. noir crime, body horror *as fiction*, exploitation as something the story *condemns or resists*). **On-screen presentation** stays **restrained**—implication, silhouette, report text, off-camera beats—not graphic **adult-only** depiction. **Overall product goal** is roughly a **teen-oriented** band (think **ESRB Teen–class** framing); **exact** labels, cuts, and territory rules are **out of scope** for per-skill design docs.

**TODO**

- Lock **target band** with stakeholders and (when relevant) compliance counsel—not a commitment to a specific board outcome until submission.
- Write **content guidelines**: grim **concept** vs acceptable **depiction** (UI, cinematics, props, loot naming) before heavy production on sensitive beats.
- Track **regional ratings and storefront policy** (PEGI, CERO, platform rules, etc.) when we approach release—do not block skill or quest design on that in early vision work.

## Artifact index

| Document | Focus | Notes |
|----------|--------|--------|
| [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 (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** |
| [economy.md](economy.md) | **Faucets/sinks**, trade, **E3.M5** policy, mission vs loot **faucets** | With [items.md](items.md), [crafting.md](crafting.md); **E8.M3** trade, **E6.M4** parity |
| [death-loss-recovery.md](death-loss-recovery.md) | **Death** stakes, **durability**/drops, **recovery**, **PvP** loss (**E6.M3**) | With [items.md](items.md), [economy.md](economy.md), [risk-security-bands.md](risk-security-bands.md) |
| [risk-security-bands.md](risk-security-bands.md) | **Security tiers**, **PvP** **eligibility**, **consent** UX (**E4.M4**, **E6.M1**–**M2**) | With [death-loss-recovery.md](death-loss-recovery.md), [gathering.md](gathering.md), [zones.md](zones.md) |
| [zones.md](zones.md) | **District** **identity**, tone, economy/faction **hooks**, **E4.M1** graph | With [risk-security-bands.md](risk-security-bands.md), [gathering.md](gathering.md); **travel** stub in planned topics |
| [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) | Split **skill** (hack) + **gig** (bodyguard) instances—idea capture | Brainstorm |

### Planned topics (stubs)

**Shipped vision docs** are listed in the [Artifact index](#artifact-index) above—update that table when a new first-class file lands.

The bullets below are **roadmap / not-yet-first-class-file** topics (or pointers into existing docs for cross-cutting angles):

- **Travel & connections** — how places link (gates, costs, downtime, danger en route); complements [zones.md](zones.md) and [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md).
- **Mechanics** — loops, constraints, what the server vs. client must honor (no dedicated vision file yet).
- **Factions & reputation** — who remembers you, grudges, access gates; ties [gigs.md](gigs.md), [skills.md](skills.md), future faction doc.
- **Combat pillars** — [Vision stub below](#combat-pillars-vision-stub); **items in combat** in [items.md](items.md).
- **Social play** — squad scale, corps, trust, betrayal affordances, async cooperation.
- **Encounters & enemy roles** — archetypes, what a fight teaches, variety without noise. **Skill + gig split runs:** [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md).
- **Onboarding** — first session hook, clarity vs. mystery, how much systems the new player sees.
- **Tone & narrative** — how lore shows up (quests, environment, UI), voice of the world. **Presentation / ~teen rating target:** [Presentation and target rating (vision)](#presentation-and-target-rating-vision).

## Combat pillars (vision stub)

Combat is still missing a **single** pillar doc. Until then, use this table for **where** vision lives:

| Pillar | Where to read |
|--------|----------------|
| **Gig kits, inputs, skill vs item actions** | [abilities.md](abilities.md) |
| **Combat gear, loadouts, hub swap, consumables** | [items.md](items.md) (with [skills.md](skills.md) **Seams**) |
| **Roster, roles, party, sub-gig** | [gigs.md](gigs.md) |
| **PvE readability, TTK, encounter fairness** | Stub—future dedicated combat doc; implementation direction in [Epic 5 — PvE combat](../decomposition/epics/epic_05_pve_combat.md) |
| **Death, durability, recovery** | [death-loss-recovery.md](death-loss-recovery.md) (with [Epic 6](../decomposition/epics/epic_06_pvp_security.md) for **PvP** loss) |
| **Risk tiers, PvP eligibility, warnings** | [risk-security-bands.md](risk-security-bands.md) ([Epic 4](../decomposition/epics/epic_04_world_topology.md) **Slice 2**) |

**Items in fights:** [items.md](items.md) **Combat gear** is **gig**-tagged for equip/deploy; **consumables** baseline is not gig-gated; **chrome** persists across gig swap. Aligns with [abilities.md](abilities.md) **Item-linked actions**. **Stakes on defeat:** [death-loss-recovery.md](death-loss-recovery.md).

## Related repo docs

| Area | Location |
|------|----------|
| Module / epic breakdown | [`docs/decomposition/`](../decomposition/README.md) |
| Implementation plans | [`docs/plans/`](../plans/) — [README (NEO vs NEON filenames)](../plans/README.md) |
| Architecture | [`docs/architecture/`](../architecture/tech_stack.md) |