diff --git a/.cursor/rules/docs-review-agent.md b/.cursor/rules/docs-review-agent.md new file mode 100644 index 0000000..9cf9c7b --- /dev/null +++ b/.cursor/rules/docs-review-agent.md @@ -0,0 +1,73 @@ +--- +description: >- + Documentation review agent — coherence, links, and dev-guide fitness for docs/ + (especially game-design and decomposition). @docs-review-agent or ask for a + “docs review” / “review the design docs” using this persona. +globs: docs/**/* +alwaysApply: false +--- + +# Documentation review agent (Neon Sprawl) + +Use this rule when the user is working in **`docs/`** (design, decomposition, plans, architecture notes) and wants a **structured pass** over one or more documents: **coherence**, **cross-links**, **contradictions** with linked files, and **readiness to guide implementation** — not a quick skim. + +## Role + +- Act as a **tech writer + design lead**: trace **definitions**, **seams**, and **dependencies** across files the target doc cites or should cite. +- Be **specific** (path, section, table). Separate **blocking** (wrong or unsafe guidance), **should fix** (stale or confusing), and **nits**. +- Prefer **actionable** edits: suggest exact wording or file-level fixes; apply them only if the user asked to **fix** or **update** docs, not when they asked **review only**. + +## When this applies + +- **Primary:** `docs/game-design/**` — progression, skills, gigs, overview, brainstorm; any new vision artifact. +- **Also:** `docs/decomposition/**`, `docs/plans/**`, `docs/architecture/**` when the user is **connecting** design to implementation or reviewing doc drift. +- **Trigger:** User @-mentions this rule, asks for a **docs review**, **coherence check**, or **design-doc audit**, or has **`docs/**` files** in focus (see `globs`). + +## 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`, `crafting.md`, `economy.md`, `death-loss-recovery.md`, `risk-security-bands.md`, `zones.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 grant **skill XP**, **currency**, or **items** when explicitly defined (`progression.md`, `economy.md`)—separate from the encounter **gig XP** path. **Economy** faucets/sinks and trade (`economy.md`) do not re-gate **craft** on **gig** (see `items.md` / Seams). **Death / loss / recovery** (`death-loss-recovery.md`): server-authoritative combat death; item stakes via **E3.M4** / **E5.M1**; **PvP** loss **E6.M3** vs **PvE** **open**; **cybernetics** vs external **gear** per **Seams**. **Risk / security** (`risk-security-bands.md`): **E4.M4** `SecurityTier` + **E6.M1**/**E6.M2** for **PvP** eligibility and **consent** UX—**not** client-only PvP toggles. **Zones** (`zones.md`): **place** **fiction** and **hooks** on the **same** **E4.M1** graph—**not** a second topology. +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). + +## Review checklist + +Work through what applies (skip irrelevant briefly). + +1. **Purpose** — Who is the reader (design, eng, production)? Is the doc scoped correctly? +2. **Definitions** — Terms (gig, skill, seam, category) consistent with `progression.md` / `skills.md`. +3. **Internal coherence** — Tables, decisions log, and body text agree; roster counts vs prose if stated. +4. **Cross-doc coherence** — Linked files don’t contradict; flag **stale** epics or slices. +5. **Implementation hooks** — IDs, modules (E2.M1, …), open vs agreed; what’s missing for tickets. +6. **Links & anchors** — Broken paths; fragile `#anchors` (prefer stable HTML `id` where needed). +7. **Next steps** — Obvious follow-up artifacts or epic/plan updates. + +## Review document (required) + +**Every** invocation must produce a **saved markdown file** under `docs/reviews/`, not only chat (same spirit as [code-review-agent](code-review-agent.md)). + +1. **Directory:** `docs/reviews/` (create if missing). +2. **Filename:** `YYYY-MM-DD-{slug}.md` — use session **Today’s date** when known; slug from topic or ticket (kebab-case). +3. **Preamble:** Date, **Scope** (paths or “full game-design pass”), **Base** branch or “as of date” if relevant. +4. **Body:** Use **Output format** below. For design reviews, use **Documentation checked** instead of only “plan + modules”: list each consulted path and **matches / partially matches / conflicts / N/A**. +5. **Commits:** Write the review file **uncommitted** unless the user asks to commit it. Follow [commit-and-review](commit-and-review.md) — no tool-attribution boilerplate in PR text. + +In the saved file, use **normal fenced code blocks** and **backtick paths** — not IDE line-number citations (GitHub-friendly). + +## Output format (required) + +1. **Verdict** — e.g. `Approve for vision`, `Approve with suggestions`, `Request doc updates`. +2. **Summary** — 2–5 sentences. +3. **Documentation checked** — Table or bullets: path → **matches** / **partially matches** / **conflicts** / **N/A**. +4. **Blocking issues** — Factual errors, unsafe guidance, broken contracts; empty if none. +5. **Suggestions** — Stale links, epic drift, missing seams references. +6. **Nits** — Optional. +7. **Verification** — What humans should re-read or grep after edits. + +**Chat:** Short summary + **path to** `docs/reviews/YYYY-MM-DD-{slug}.md`. + +## Boundaries + +- Do **not** skip writing `docs/reviews/…` unless the user explicitly asks for **chat-only** (then state that exception in chat and **do not** claim full agent output). +- Do **not** rewrite entire doc trees unless asked; review is default. +- **Skills / gigs:** treat `docs/game-design/skills.md` **Seams** as the **authoritative** gig↔skill boundary unless superseded by a newer ADR or epic decision. diff --git a/.github/workflows/pr-gate.yml b/.github/workflows/pr-gate.yml index 823fd2a..717a174 100644 --- a/.github/workflows/pr-gate.yml +++ b/.github/workflows/pr-gate.yml @@ -18,5 +18,20 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: scripts/requirements-content.txt + + - name: Validate content catalogs + run: | + pip install -r scripts/requirements-content.txt + python scripts/validate_content.py + + - name: Check decomposition doc language (gig vs skill) + run: python scripts/check_decomposition_language.py + - name: Gate run: "true" diff --git a/.gitignore b/.gitignore index 8aa6685..198003a 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,6 @@ client/.godot/ # Local secrets .env .env.*.local + +# Content validation (optional local venv) +.venv-content/ diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..8fb719f --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,26 @@ +{ + "version": "0.2.0", + "configurations": [ + { + // Use IntelliSense to find out which attributes exist for C# debugging + // Use hover for the description of the existing attributes + // For further information visit https://github.com/dotnet/vscode-csharp/blob/main/debugger-launchjson.md + "name": ".NET Core Launch (console)", + "type": "coreclr", + "request": "launch", + "preLaunchTask": "build", + // If you have changed target frameworks, make sure to update the program path. + "program": "${workspaceFolder}/server/NeonSprawl.Server.Tests/bin/Debug/net10.0/NeonSprawl.Server.Tests.dll", + "args": [], + "cwd": "${workspaceFolder}/server/NeonSprawl.Server.Tests", + // For more information about the 'console' field, see https://aka.ms/VSCode-CS-LaunchJson-Console + "console": "internalConsole", + "stopAtEntry": false + }, + { + "name": ".NET Core Attach", + "type": "coreclr", + "request": "attach" + } + ] +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..d640a6d --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,41 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "dotnet", + "type": "process", + "args": [ + "build", + "${workspaceFolder}/NeonSprawl.sln", + "/property:GenerateFullPaths=true", + "/consoleloggerparameters:NoSummary;ForceNoAlign" + ], + "problemMatcher": "$msCompile" + }, + { + "label": "publish", + "command": "dotnet", + "type": "process", + "args": [ + "publish", + "${workspaceFolder}/NeonSprawl.sln", + "/property:GenerateFullPaths=true", + "/consoleloggerparameters:NoSummary;ForceNoAlign" + ], + "problemMatcher": "$msCompile" + }, + { + "label": "watch", + "command": "dotnet", + "type": "process", + "args": [ + "watch", + "run", + "--project", + "${workspaceFolder}/NeonSprawl.sln" + ], + "problemMatcher": "$msCompile" + } + ] +} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index e4552f9..9bdc9f1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ Optional **personas** for Cursor. Enable by **@ mentioning** the rule in chat or | Agent | Rule file | When to use | |--------|-----------|-------------| | **Code review** | [`.cursor/rules/code-review-agent.md`](.cursor/rules/code-review-agent.md) | PR / diff / pre-merge review; **always writes** `docs/reviews/YYYY-MM-DD-{slug}.md` with **Documentation checked** vs `docs/plans/` and `docs/decomposition/modules/`; short chat pointer | +| **Docs review** | [`.cursor/rules/docs-review-agent.md`](.cursor/rules/docs-review-agent.md) | Coherence / links / dev-guide fitness for `docs/` (especially `docs/game-design/` + decomposition); **writes** `docs/reviews/YYYY-MM-DD-{slug}.md`; use when working in **documents** or @ mention | Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). **Godot client layout** (thin `main.gd`, split by concern): [`.cursor/rules/godot-client-script-organization.md`](.cursor/rules/godot-client-script-organization.md). **PR / push text:** no “Made-with: Cursor” boilerplate — [`.cursor/rules/commit-and-review.md`](.cursor/rules/commit-and-review.md). diff --git a/README.md b/README.md index c36cd3f..4fcf3a1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Neon Sprawl -**Neon Sprawl** is the working title for a classless, crafting-focused sci-fi / cyberpunk MMORPG (solo-dev scope). Product intent and phase gates: [`neon_sprawl_vision.plan.md`](neon_sprawl_vision.plan.md). +**Neon Sprawl** is the working title for a crafting-focused sci-fi / cyberpunk MMORPG with **gigs** (combat roles) and open non-combat **skills** (solo-dev scope). Product intent and phase gates: [`neon_sprawl_vision.plan.md`](neon_sprawl_vision.plan.md). ## Tech stack (locked) diff --git a/content/README.md b/content/README.md index a16b047..958468a 100644 --- a/content/README.md +++ b/content/README.md @@ -5,6 +5,14 @@ Data-driven definitions (skills, items, recipes, quests) validated in CI with ** | Path | Purpose | |------|---------| | [`schemas/`](schemas/) | JSON Schema files (`*.schema.json`) | -| [`skills/`](skills/) | Skill catalogs and related tables | +| [`skills/`](skills/) | Skill catalogs; each row matches [`schemas/skill-def.schema.json`](schemas/skill-def.schema.json) — **stable `id`**, **`allowedXpSourceKinds`** for [E2.M1](../docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md) / [E2.M2](../docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md) | Server load path and hot-reload policy are TBD; keep files versioned here as the source of truth. + +**Validate locally** (same as PR gate): + +```bash +pip install -r scripts/requirements-content.txt +python scripts/validate_content.py +python scripts/check_decomposition_language.py +``` diff --git a/content/schemas/skill-def.schema.json b/content/schemas/skill-def.schema.json index 9a21a8d..5a2058d 100644 --- a/content/schemas/skill-def.schema.json +++ b/content/schemas/skill-def.schema.json @@ -2,18 +2,40 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://neon-sprawl.local/schemas/skill-def.json", "title": "SkillDef", + "description": "Single skill row for catalogs (e.g. content/skills/*.json). IDs are stable forever—rename display in displayName only. See docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md.", "type": "object", "additionalProperties": false, - "required": ["id", "category", "displayName"], + "required": ["id", "category", "displayName", "allowedXpSourceKinds"], "properties": { "id": { "type": "string", - "pattern": "^[a-z][a-z0-9_]*$" + "pattern": "^[a-z][a-z0-9_]*$", + "description": "Immutable skill key for saves, recipes, quests, telemetry, and XpGrantEvent.skillId. Never change after content ships; add a new id if the skill splits." }, "category": { "type": "string", - "enum": ["gathering", "crafting", "combat", "exploration", "utility", "social"] + "description": "Primary SkillCategory aligned with docs/game-design/skills.md (Gather / Process / Make / Tech).", + "enum": ["gather", "process", "make", "tech"] }, - "displayName": { "type": "string", "minLength": 1 } + "displayName": { + "type": "string", + "minLength": 1, + "description": "Player-facing label; safe to change without migrating character data." + }, + "allowedXpSourceKinds": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "description": "Which XpGrantEvent.sourceKind values may increase this skill. E2.M2 rejects grants outside this set. Combat encounters do not use skill XP—use gig progression instead.", + "items": { + "type": "string", + "enum": [ + "activity", + "mission_reward", + "trainer", + "book_or_item" + ] + } + } } } diff --git a/content/skills/prototype_skills.json b/content/skills/prototype_skills.json index bf55cbc..b6d3e9a 100644 --- a/content/skills/prototype_skills.json +++ b/content/skills/prototype_skills.json @@ -2,19 +2,22 @@ "schemaVersion": 1, "skills": [ { - "id": "gathering_scrap", - "category": "gathering", - "displayName": "Scrap Salvaging" + "id": "salvage", + "category": "gather", + "displayName": "Salvage", + "allowedXpSourceKinds": ["activity", "mission_reward"] }, { - "id": "crafting_engineering", - "category": "crafting", - "displayName": "Street Engineering" + "id": "refine", + "category": "process", + "displayName": "Refine", + "allowedXpSourceKinds": ["activity", "mission_reward", "trainer"] }, { - "id": "combat_ballistics", - "category": "combat", - "displayName": "Ballistics" + "id": "intrusion", + "category": "tech", + "displayName": "Intrusion", + "allowedXpSourceKinds": ["activity", "mission_reward", "book_or_item"] } ] } diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index fb58dce..92cd357 100644 --- a/docs/decomposition/README.md +++ b/docs/decomposition/README.md @@ -25,7 +25,7 @@ This workspace contains detailed planning artifacts derived from the finalized m | Epic | Document | |------|----------| | 1 - Core Player Runtime | [epics/epic_01_core_player_runtime.md](epics/epic_01_core_player_runtime.md) | -| 2 - Classless Progression | [epics/epic_02_classless_progression.md](epics/epic_02_classless_progression.md) | +| 2 - Skills and Progression Framework | [epics/epic_02_skills_and_progression.md](epics/epic_02_skills_and_progression.md) | | 3 - Crafting Economy | [epics/epic_03_crafting_economy.md](epics/epic_03_crafting_economy.md) | | 4 - World Topology | [epics/epic_04_world_topology.md](epics/epic_04_world_topology.md) | | 5 - PvE Combat | [epics/epic_05_pve_combat.md](epics/epic_05_pve_combat.md) | diff --git a/docs/decomposition/epics/epic_02_classless_progression.md b/docs/decomposition/epics/epic_02_classless_progression.md deleted file mode 100644 index 372a71b..0000000 --- a/docs/decomposition/epics/epic_02_classless_progression.md +++ /dev/null @@ -1,96 +0,0 @@ -# Epic 2 - Classless Skill and Progression Framework - -## Source Anchors - -- Master epic reference: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, System Modules Epic 2 -- Related modules: E2.M1, E2.M2, E2.M3, E2.M4 - -## Ownership and success (Level 1) - -- **Ownership focus:** Systems Design + Gameplay Engineering -- **Success criteria:** Any character can train all skills, and progression remains long-term without dead-end grinds. - -## Objective - -Provide a data-driven classless progression layer: skill definitions, XP awards, level curves, and eventually mastery/perk and pacing controls so gathering, crafting, and combat all feed one coherent progression model. - -## Module Breakdown - -### E2.M1 - SkillDefinitionRegistry - -- Responsibility: Central catalog for skill metadata, category tags, unlock prerequisites. -- Key contracts: `SkillDef`, `SkillCategory`, `UnlockRequirement` -- Dependencies: None -- Stage target: Prototype - -### E2.M2 - XpAwardAndLevelEngine - -- Responsibility: XP award rules, level thresholds, level-up event generation. -- Key contracts: `XpGrantEvent`, `LevelCurve`, `LevelUpEvent` -- Dependencies: E2.M1 -- Stage target: Prototype -- Note: E3.M1, E3.M2, and E5.M1 integrate by calling this engine; they are not dependencies for implementing E2.M2 (see Slice 3). - -### E2.M3 - MasteryAndPerkUnlocks - -- Responsibility: Mastery tracks and perk unlock state for non-class build expression. -- Key contracts: `MasteryTrack`, `PerkUnlockEvent`, `PerkState` -- Dependencies: E2.M2 -- Stage target: Pre-production - -### E2.M4 - ProgressionPacingControls - -- Responsibility: Tuning knobs for progression velocity and catch-up policy enforcement. -- Key contracts: `XpModifierProfile`, `CatchUpRule`, `PacingPolicy` -- Dependencies: E2.M2, E9.M2 -- Stage target: Pre-production - -## Implementation Slices (Backlog-Ready) - -### Slice 1 - Skill registry and prototype skills - -- Scope: E2.M1 with at least three skills (one gathering, one crafting, one combat) loaded from data. -- Dependencies: None -- Acceptance criteria: - - All prototype activities reference skills by stable IDs. - - Invalid skill references fail validation in CI or at load time. -- Telemetry hooks: `skill_unlock` (if gating exists), schema validation metrics. - -### Slice 2 - XP engine (E2.M2 core) - -- Scope: Implement `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`, and server-authoritative level resolution on top of `SkillDef` from E2.M1. No dependency on Epic 3 or Epic 5 modules beyond future call sites. -- Dependencies: E2.M1 (matches module-level E2.M2 → E2.M1 only). -- Acceptance criteria: - - XP and level-up can be triggered from tests or a stub caller without gathering/combat content. - - Curves and thresholds are data-driven and hot-reloadable or reloadable by policy agreed for prototype. -- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up (once integration slice fires real activity). - -### Slice 3 - XP award integration at activity sites - -- Scope: Wire gathering (E3.M1), crafting (E3.M2), and combat (E5.M1) to invoke the E2.M2 award API so the three prototype skill lines gain XP from real play. -- Dependencies: E2.M2, E3.M1, E3.M2, E5.M1 (integration prerequisites; not part of the E2.M2 module dependency list). -- Acceptance criteria: - - Visible XP and level-up feedback within first session from real gather/craft/combat actions. -- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up. - -### Slice 4 - Mastery and pacing (pre-production) - -- Scope: E2.M3 and E2.M4 for first mastery branch and global pacing policy. -- Dependencies: E2.M2, E9.M2 -- Acceptance criteria: - - At least one mastery path unlocks a perk without blocking other skills. - - Pacing policy can be toggled for test cohorts without redeploy where possible. -- Telemetry hooks: `perk_unlock`, `pacing_profile_applied`. - -## Risks and Mitigations - -- Risk: XP faucets create runaway leveling in one skill. - - Mitigation: Diminishing returns per slice; monitor skill distribution via E9.M2. -- Risk: Classless identity feels flat without mastery expression. - - Mitigation: Ship E2.M3 early in pre-production with one flagship mastery line. - -## Definition of Done - -- Prototype uses E2.M1 + E2.M2 for all three skill lines. -- Pre-production adds E2.M3/E2.M4 with documented tuning workflow. -- Events align with baseline telemetry in master plan. diff --git a/docs/decomposition/epics/epic_02_skills_and_progression.md b/docs/decomposition/epics/epic_02_skills_and_progression.md new file mode 100644 index 0000000..5c9e63d --- /dev/null +++ b/docs/decomposition/epics/epic_02_skills_and_progression.md @@ -0,0 +1,97 @@ +# Epic 2 - Skills and Progression Framework + +## Source Anchors + +- Master epic reference: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, System Modules Epic 2 +- Related modules: E2.M1, E2.M2, E2.M3, E2.M4 + +## Ownership and success (Level 1) + +- **Ownership focus:** Systems Design + Gameplay Engineering +- **Success criteria:** Any character can train all **non-combat** **skills** tracked as `SkillDef`, and **skill** progression stays long-term without dead-end grinds (**gig** combat roles are separate—see [`gigs.md`](../../game-design/gigs.md)). + +## Objective + +Provide a data-driven **non-combat skill** layer: `SkillDef` registry, **skill** XP awards, level curves, and eventually mastery/perk and pacing controls. **Gathering** and **crafting** feed **skill** progression via [E2.M2](../modules/E2_M2_XpAwardAndLevelEngine.md); **combat encounters** feed **gig** progression (not `SkillDef` XP)—see [`docs/game-design/progression.md`](../../game-design/progression.md). **Mission rewards** may still grant **skill** XP when scripted. + +## Module Breakdown + +### E2.M1 - SkillDefinitionRegistry + +- Responsibility: Central catalog for **non-combat** `SkillDef` rows: **stable `id`**, **`SkillCategory`** (`gather` / `process` / `make` / `tech`), **`displayName`**, **`allowedXpSourceKinds`** (which `XpGrantEvent.sourceKind` values may grant XP per skill), and unlock prerequisites. **Combat roles** are **gigs**, not `SkillDef`. Detail: [E2.M1 — SkillDefinitionRegistry](../modules/E2_M1_SkillDefinitionRegistry.md), [`content/schemas/skill-def.schema.json`](../../../content/schemas/skill-def.schema.json). +- Key contracts: `SkillDef`, `SkillCategory`, `UnlockRequirement`; prototype schema requires **`allowedXpSourceKinds`** per skill. +- Dependencies: None +- Stage target: Prototype + +### E2.M2 - XpAwardAndLevelEngine + +- Responsibility: XP award rules, level thresholds, level-up event generation. +- Key contracts: `XpGrantEvent`, `LevelCurve`, `LevelUpEvent` +- Dependencies: E2.M1 +- Stage target: Prototype +- Note: **E3.M1** and **E3.M2** (and mission/reward routers such as **E7.M2**) integrate as **callers** of **E2.M2** for **skill** XP. **E5.M1** resolves **combat** and advances **gig** progression **outside** **E2.M2**—see Slice 3. None of these are **hard** dependencies for implementing the **E2.M2** core (stub callers in Slice 2). + +### E2.M3 - MasteryAndPerkUnlocks + +- Responsibility: Mastery tracks and perk unlock state for **skill** build expression beyond raw levels. +- Key contracts: `MasteryTrack`, `PerkUnlockEvent`, `PerkState` +- Dependencies: E2.M2 +- Stage target: Pre-production + +### E2.M4 - ProgressionPacingControls + +- Responsibility: Tuning knobs for progression velocity and catch-up policy enforcement. +- Key contracts: `XpModifierProfile`, `CatchUpRule`, `PacingPolicy` +- Dependencies: E2.M2, E9.M2 +- Stage target: Pre-production + +## Implementation Slices (Backlog-Ready) + +### Slice 1 - Skill registry and prototype skills + +- Scope: E2.M1 with at least three **non-combat** `SkillDef` rows loaded from data—e.g. aligned with **Gather**, **Process** or **Make**, and **Tech** as in [`docs/game-design/skills.md`](../../game-design/skills.md). **Combat role progression** is **gig**-scoped, not a `SkillDef` line (see [`docs/game-design/gigs.md`](../../game-design/gigs.md), [`docs/game-design/progression.md`](../../game-design/progression.md)). +- Dependencies: None +- Acceptance criteria: + - All prototype activities reference skills by stable IDs. + - Invalid skill references fail validation in CI or at load time. +- Telemetry hooks: `skill_unlock` (if gating exists), schema validation metrics. + +### Slice 2 - XP engine (E2.M2 core) + +- Scope: Implement `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`, and server-authoritative level resolution on top of `SkillDef` from E2.M1. No dependency on Epic 3 or Epic 5 modules beyond future call sites. +- Dependencies: E2.M1 (matches module-level E2.M2 → E2.M1 only). +- Acceptance criteria: + - XP and level-up can be triggered from tests or a stub caller without gathering/combat content. + - Curves and thresholds are data-driven and hot-reloadable or reloadable by policy agreed for prototype. +- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up (once integration slice fires real activity). + +### Slice 3 - XP award integration at activity sites + +- Scope: Wire **gathering** (E3.M1) and **crafting** (E3.M2) to the **E2.M2 skill XP** award API so prototype **`SkillDef`** lines gain XP from real play. Wire **combat** (E5.M1) to **gig XP only** ([`gigs.md`](../../game-design/gigs.md), [`progression.md`](../../game-design/progression.md))—**no** hook that maps **encounter resolution** to **skill** XP or a combat `SkillDef`. **Mission / quest reward** paths may still call the **skill** XP API when the **payout** explicitly includes skill XP (**not** the same as “combat trained this skill”). +- Dependencies: E2.M2, E3.M1, E3.M2, E5.M1 (integration prerequisites; not part of the E2.M2 module dependency list). Gig XP plumbing may live beside E2.M2 or under Epic 5—**split call sites** by progression type (skill vs gig). +- Acceptance criteria: + - Visible **skill** XP and skill level-up feedback within first session from real **gather/craft** actions. + - Visible **gig** XP and gig progression feedback from **combat** (main gig only, per game-design). +- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up for **skills**; gig progression hooks as agreed when gig model lands (e.g. `gig_xp_grant`, `gig_level_up`). + +### Slice 4 - Mastery and pacing (pre-production) + +- Scope: E2.M3 and E2.M4 for first mastery branch and global pacing policy. +- Dependencies: E2.M2, E9.M2 +- Acceptance criteria: + - At least one mastery path unlocks a perk without blocking other skills. + - Pacing policy can be toggled for test cohorts without redeploy where possible. +- Telemetry hooks: `perk_unlock`, `pacing_profile_applied`. + +## Risks and Mitigations + +- Risk: XP faucets create runaway leveling in one skill. + - Mitigation: Diminishing returns per slice; monitor skill distribution via E9.M2. +- Risk: **Skill** progression feels flat without mastery expression. + - Mitigation: Ship E2.M3 early in pre-production with one flagship mastery line. + +## Definition of Done + +- Prototype uses E2.M1 + E2.M2 for three **non-combat** `SkillDef` lines (stable **`id`** + **`allowedXpSourceKinds`** per [E2.M1](../modules/E2_M1_SkillDefinitionRegistry.md)); **gig** progression for combat is separate. +- Pre-production adds E2.M3/E2.M4 with documented tuning workflow. +- Events align with baseline telemetry in master plan. diff --git a/docs/decomposition/epics/epic_03_crafting_economy.md b/docs/decomposition/epics/epic_03_crafting_economy.md index 2fc18c3..04252a9 100644 --- a/docs/decomposition/epics/epic_03_crafting_economy.md +++ b/docs/decomposition/epics/epic_03_crafting_economy.md @@ -62,6 +62,8 @@ Implement gathering from world nodes, item/inventory representation, recipe exec - Item schema versioned for forward-compatible migrations. - Telemetry hooks: `item_created`, `inventory_full` / transfer failures. + + ### Slice 2 - Gather nodes and outputs - Scope: E3.M1 with 4-6 node types and yield tables; awards crafting/gathering XP via E2.M2. @@ -70,6 +72,8 @@ Implement gathering from world nodes, item/inventory representation, recipe exec - Full gather interaction in prototype region without dupes or free resources. - Telemetry hooks: `resource_gathered`, `gather_node_depleted`. + + ### Slice 3 - Recipes and crafting pipeline - Scope: E3.M2 with 8-12 starter recipes per prototype minimums. @@ -78,6 +82,8 @@ Implement gathering from world nodes, item/inventory representation, recipe exec - 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. + + ### Slice 4 - Sinks and economy policy (pre-production) - Scope: E3.M4 + E3.M5 with tuning hooks and validation against outliers. diff --git a/docs/decomposition/epics/epic_04_world_topology.md b/docs/decomposition/epics/epic_04_world_topology.md index f72db9d..3bf7e9f 100644 --- a/docs/decomposition/epics/epic_04_world_topology.md +++ b/docs/decomposition/epics/epic_04_world_topology.md @@ -46,6 +46,8 @@ Represent the world as a zone graph with travel rules, security-tier signaling f ## Implementation Slices (Backlog-Ready) + + ### Slice 1 - Prototype district zone graph - Scope: E4.M1 defining hub, PvE pocket, and edge zones with valid transitions. @@ -55,6 +57,8 @@ Represent the world as a zone graph with travel rules, security-tier signaling f - Travel rules prevent illegal shortcuts. - Telemetry hooks: `zone_enter`, `zone_exit`, invalid transition attempts. + + ### Slice 2 - Security tier tagging and UI hooks - Scope: E4.M4 on E4.M1: per-zone `SecurityTier`, `ZonePolicyState`, and entry-warning payloads. E6.M1 subscribes to this data for PvP eligibility (implemented in Epic 6; no circular module dependency). diff --git a/docs/decomposition/modules/CT_M1_ContentValidationPipeline.md b/docs/decomposition/modules/CT_M1_ContentValidationPipeline.md index 84758a0..5e2ddb8 100644 --- a/docs/decomposition/modules/CT_M1_ContentValidationPipeline.md +++ b/docs/decomposition/modules/CT_M1_ContentValidationPipeline.md @@ -39,6 +39,12 @@ Own **content schema artifacts**, **automated validation** in CI and locally, an Content tooling **Slice 1** — schemas + CI; **Slice 4** — server parity hardening. +## CI (prototype) + +**Skill catalogs:** the repo **PR gate** workflow ([`.github/workflows/pr-gate.yml`](../../../.github/workflows/pr-gate.yml)) runs [`scripts/validate_content.py`](../../../scripts/validate_content.py) on every push and pull request. It validates each object in `content/skills/*.json` under the top-level `skills` array against [`content/schemas/skill-def.schema.json`](../../../content/schemas/skill-def.schema.json) (Python **jsonschema**, Draft 2020-12). Extend the script when additional catalogs and schemas ship. + +**Decomposition vocabulary:** the same workflow runs [`scripts/check_decomposition_language.py`](../../../scripts/check_decomposition_language.py) (stdlib only) over `docs/decomposition/**/*.md` to catch wording that treats **combat** as a leveled **`SkillDef`** line instead of **gig** progression (see script docstring for patterns). Adjust the script if a future doc needs a documented exception. + ## Source anchors - Plan: [`internal-content-authoring.md`](../../plans/internal-content-authoring.md) diff --git a/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md b/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md index b492124..585b4f9 100644 --- a/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md +++ b/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md @@ -5,39 +5,75 @@ | Field | Value | |--------|--------| | **Module ID** | E2.M1 | -| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Epic** | [Epic 2 — Skills and Progression Framework](../epics/epic_02_skills_and_progression.md) | | **Stage target** | Prototype | | **Status** | Planned (see [dependency register](module_dependency_register.md)) | ## Purpose -Central catalog for skill metadata, category tags, and unlock prerequisites. All prototype activities reference skills by stable IDs validated against this registry. +Central catalog for **non-combat** skill metadata: **stable IDs**, **categories**, **allowed XP sources**, and unlock prerequisites. All prototype activities reference skills by **`SkillDef.id`** validated against this registry. **Combat role progression** is **not** a `SkillDef`—use gig progression ([`docs/game-design/gigs.md`](../../game-design/gigs.md)). + +## Data contract (schema) + +| Artifact | Path | +|----------|------| +| **JSON Schema** | [`content/schemas/skill-def.schema.json`](../../../content/schemas/skill-def.schema.json) | +| **Sample catalog** | [`content/skills/prototype_skills.json`](../../../content/skills/prototype_skills.json) | + +**`SkillDef` fields (prototype):** + +| Field | Rule | +|--------|------| +| **`id`** | Lowercase `snake_case`, **immutable** after ship. Used in saves, recipes, quests, `XpGrantEvent.skillId`, telemetry. **Never** rename to “fix” a skill—add a new `id` and migrate content if a skill splits. | +| **`category`** | One of `gather` \| `process` \| `make` \| `tech` — aligned with [`docs/game-design/skills.md`](../../game-design/skills.md) roster buckets (not gigs). | +| **`displayName`** | Player-facing string; **may change** without migrating progression data. | +| **`allowedXpSourceKinds`** | Non-empty set of grant channels [E2.M2](E2_M2_XpAwardAndLevelEngine.md) may apply to this skill. **Combat encounters** must **not** use skill XP—those award **gig XP**; `mission_reward` covers explicit mission/contract skill payouts. | + +**`allowedXpSourceKinds` values:** + +| Kind | Meaning | +|------|--------| +| `activity` | Primary loop (e.g. gather node complete, recipe craft complete, skill-based world interaction)—callers set `XpGrantEvent.sourceKind` to match. | +| `mission_reward` | Quest/contract hand-in or other scripted payout ([`docs/game-design/progression.md`](../../game-design/progression.md) **Mission rewards vs combat XP**). | +| `trainer` | NPC or teaching beat. | +| `book_or_item` | Book, chip, training consumable, or similar one-shot grant. | + +Add new enum values only with a **schema version** / migration note in [CT.M1](CT_M1_ContentValidationPipeline.md) when CI enforces catalogs. ## Responsibilities - Load and validate `SkillDef` from data; expose `SkillCategory` and `UnlockRequirement` for gating. +- Reject unknown `skillId` or **XP grants** whose `sourceKind` is **not** listed on the target skill’s `allowedXpSourceKinds` (enforced in [E2.M2](E2_M2_XpAwardAndLevelEngine.md) at grant time). ## Key contracts | Contract | Role | |----------|------| -| `SkillDef` | Per-skill metadata and references. | -| `SkillCategory` | Grouping for UX and balance. | +| `SkillDef` | Per-skill metadata: **id**, **category**, **displayName**, **allowedXpSourceKinds** (+ future unlock fields). | +| `SkillCategory` | `gather` \| `process` \| `make` \| `tech` for UX and balance. | | `UnlockRequirement` | Prerequisites before XP or use counts apply. | +## Acceptance criteria (E2.M1 / Slice 1) + +- Every loaded `SkillDef` validates against [`skill-def.schema.json`](../../../content/schemas/skill-def.schema.json) in CI ([CT.M1](CT_M1_ContentValidationPipeline.md#ci-prototype) — [`scripts/validate_content.py`](../../../scripts/validate_content.py) in **PR gate**) or at server boot. +- **Duplicate `id`** in a catalog fails validation. +- **Roster freeze for prototype:** when Slice 1 locks three skills, their **`id`** values are treated as **stable**—downstream content (recipes, quests) may reference them; changing an `id` requires a **migration** or new row. +- Document for designers: each new skill row **must** declare **`allowedXpSourceKinds`** so engineers know which systems may grant XP (gather/craft hooks vs E7.M2 mission rewards only, etc.). + ## Module dependencies - **None** ## Dependents (by design) -- **E2.M2** — XpAwardAndLevelEngine (primary). +- **E2.M2** — XpAwardAndLevelEngine (primary): validates grants against `allowedXpSourceKinds`. ## Related implementation slices -Epic 2 **Slice 1** — skill registry and prototype skills; invalid references fail at load or in CI. +Epic 2 **Slice 1** — skill registry and prototype **non-combat** skills; invalid references fail at load or in CI. ## Source anchors +- Game design: [`docs/game-design/skills.md`](../../game-design/skills.md) — roster, **XP philosophy**, gig/skill boundary. - Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 2. - [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md index a75d636..2c9a91d 100644 --- a/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md +++ b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md @@ -5,17 +5,17 @@ | Field | Value | |--------|--------| | **Module ID** | E2.M2 | -| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Epic** | [Epic 2 — Skills and Progression Framework](../epics/epic_02_skills_and_progression.md) | | **Stage target** | Prototype | | **Status** | Planned (see [dependency register](module_dependency_register.md)) | ## Purpose -Central server-authoritative engine for classless skill progression: applying XP grants, resolving levels against data-driven curves, and emitting level-up events. Gathering, crafting, and combat integrate **as callers** of this API without being hard dependencies for implementing the engine itself (see Epic 2 Slice 2 vs Slice 3). +Central server-authoritative engine for **non-combat skill** progression: applying XP grants, resolving levels against data-driven curves, and emitting level-up events. **Gathering** and **crafting** integrate as callers for **skill** XP. **Combat encounters** advance **gigs** (gig XP), not `SkillDef` lines. **Mission rewards** may call this API for **skill** XP when the payout lists a skill grant. Callers are not hard dependencies for implementing the engine core (see Epic 2 Slice 2 vs Slice 3). ## Responsibilities -- Apply `XpGrantEvent` (or equivalent) per skill with validated skill references from [E2.M1](E2_M1_SkillDefinitionRegistry.md). +- Apply `XpGrantEvent` (or equivalent) per skill with validated **`skillId`** from [E2.M1](E2_M1_SkillDefinitionRegistry.md). Reject grants when **`sourceKind`** is not in the target `SkillDef.allowedXpSourceKinds`. - Resolve experience against `LevelCurve` / threshold tables. - Emit `LevelUpEvent` when thresholds are crossed. - Support data-driven curves; **reload policy:** [Data reload and telemetry operations policy](data_and_ops_policy.md#content-and-gameplay-data-reload) (boot load default; optional dev reload). @@ -24,17 +24,17 @@ Central server-authoritative engine for classless skill progression: applying XP | Contract | Role | |----------|------| -| `XpGrantEvent` | Structured XP award (skill id, amount, source, modifiers). | +| `XpGrantEvent` | Structured XP award: **`skillId`** (must exist in registry), **amount**, **`sourceKind`** (must appear in that skill’s **`allowedXpSourceKinds`**), optional modifiers. | | `LevelCurve` | Thresholds or formula per skill or global policy. | | `LevelUpEvent` | Notification for UI, unlocks, and downstream systems. | ## Module dependencies -- **E2.M1** — [SkillDefinitionRegistry](E2_M1_SkillDefinitionRegistry.md): `SkillDef`, categories, and validation of skill IDs. +- **E2.M1** — [SkillDefinitionRegistry](E2_M1_SkillDefinitionRegistry.md): `SkillDef`, categories, **allowedXpSourceKinds**, and validation of skill IDs. ## Dependents (by design) -- **E5.M1** — CombatRulesEngine: combat awards XP via integration (Epic 5 / Epic 2 slices). +- **E5.M1** — CombatRulesEngine: **gig XP** from combat (not `SkillDef` XP via E2.M2). - **E3.M1 / E3.M2** — Gathering and crafting award XP when wired in Slice 3. - **E7.M2** — RewardAndUnlockRouter routes quest rewards including XP through E2.M2. - **E2.M3 / E2.M4** — Mastery and pacing layers build on level/XP state (pre-production). @@ -42,7 +42,7 @@ Central server-authoritative engine for classless skill progression: applying XP ## Related implementation slices - **Epic 2 Slice 2 — XP engine (E2.M2 core)**: implement contracts and tests without requiring Epic 3 or 5 modules. -- **Epic 2 Slice 3 — XP award integration**: wire E3.M1, E3.M2, E5.M1 to the award API for three prototype skill lines. +- **Epic 2 Slice 3 — XP award integration**: E3.M1 / E3.M2 call the skill XP API with **`sourceKind`: `activity`** (where allowed per skill); E7.M2 / mission rewards use **`mission_reward`** (etc.) as configured; combat resolves **gig** progression separately from E2.M2. ## Risks and telemetry diff --git a/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md b/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md index 1dd4db8..faffe5c 100644 --- a/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md +++ b/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md @@ -5,13 +5,13 @@ | Field | Value | |--------|--------| | **Module ID** | E2.M3 | -| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Epic** | [Epic 2 — Skills and Progression Framework](../epics/epic_02_skills_and_progression.md) | | **Stage target** | Pre-production | | **Status** | Planned (see [dependency register](module_dependency_register.md)) | ## Purpose -Mastery tracks and perk unlock state so classless builds have expressive identity beyond raw level curves. +Mastery tracks and perk unlock state so **skill** builds have expressive identity beyond raw level curves. ## Responsibilities diff --git a/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md b/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md index f5bcd06..146862d 100644 --- a/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md +++ b/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md @@ -5,7 +5,7 @@ | Field | Value | |--------|--------| | **Module ID** | E2.M4 | -| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Epic** | [Epic 2 — Skills and Progression Framework](../epics/epic_02_skills_and_progression.md) | | **Stage target** | Pre-production | | **Status** | Planned (see [dependency register](module_dependency_register.md)) | diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index c633e12..6e99a08 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -17,11 +17,11 @@ Fleshed-out scope, contracts, and integration notes live in **per-module documen | E1.M3 | InteractionAndTargetingLayer | E1.M1 | TargetState, InteractableDescriptor, SelectionEvent | Prototype | Planned | | E1.M4 | AbilityInputScaffold | E1.M3, E5.M1 | AbilityCastRequest, HotbarLoadout, CooldownSnapshot | Prototype | Planned | -### Epic 2 — Classless Progression +### Epic 2 — Skills and Progression Framework | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | |---|---|---|---|---|---| -| E2.M1 | SkillDefinitionRegistry | None | SkillDef, SkillCategory, UnlockRequirement | Prototype | Planned | +| E2.M1 | SkillDefinitionRegistry | None | SkillDef, SkillCategory, UnlockRequirement, allowedXpSourceKinds | Prototype | Planned | | E2.M2 | XpAwardAndLevelEngine | E2.M1 | XpGrantEvent, LevelCurve, LevelUpEvent | Prototype | Planned | | E2.M3 | MasteryAndPerkUnlocks | E2.M2 | MasteryTrack, PerkUnlockEvent, PerkState | Pre-production | Planned | | E2.M4 | ProgressionPacingControls | E2.M2, E9.M2 | XpModifierProfile, CatchUpRule, PacingPolicy | Pre-production | Planned | diff --git a/docs/decomposition/modules/quest_scope_and_party.md b/docs/decomposition/modules/quest_scope_and_party.md index eb6e04e..04b6a51 100644 --- a/docs/decomposition/modules/quest_scope_and_party.md +++ b/docs/decomposition/modules/quest_scope_and_party.md @@ -9,7 +9,7 @@ This doc fixes **solo vs party** quest behavior: where `QuestStepState` lives, w - **Authoritative state** for a quest is stored **per character** (`QuestStepState` keyed by character / player id, plus quest id and any run id if replays exist). - There is **no** single shared “party quest row” in the prototype model; party play is expressed by **synchronizing advances** across multiple per-character states when content opts in (see below). -**Rationale:** Avoids orphan state when members leave the party, keeps abandon/reset rules simple, and matches “classless solo-friendly” progression with optional co-op credit. +**Rationale:** Avoids orphan state when members leave the party, keeps abandon/reset rules simple, and matches “solo-friendly” progression with optional co-op credit. --- diff --git a/docs/game-design/README.md b/docs/game-design/README.md new file mode 100644 index 0000000..7548323 --- /dev/null +++ b/docs/game-design/README.md @@ -0,0 +1,11 @@ +# Game design (vision) + +**Master index:** [`overview.md`](overview.md) — summary, artifact table, and links to related docs. + +**Progression (gigs + skills):** [`progression.md`](progression.md) — shared vocabulary and hybrid rationale. + +**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), **[crafting](crafting.md)** (recipes, pipeline), **[economy](economy.md)** (faucets, sinks, trade), **[death-loss-recovery](death-loss-recovery.md)** (stakes, recovery), **[risk-security-bands](risk-security-bands.md)** (tiers, PvP eligibility), **[zones](zones.md)** (place identity), travel/mechanics stubs, 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..d5dd18f --- /dev/null +++ b/docs/game-design/abilities.md @@ -0,0 +1,70 @@ +# 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)). **Item buckets & acquisition:** [items.md](items.md). **Gather → craft economy spine:** [gathering.md](gathering.md), [crafting.md](crafting.md). **Combat pillar pointers:** [overview.md — Combat pillars](overview.md#combat-pillars-vision-stub). + +## 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) | +| 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) | +| Economy (trade, sinks—gig does not gate craft) | [economy.md](economy.md) | +| Death / loss (combat death, gear stakes) | [death-loss-recovery.md](death-loss-recovery.md) | +| Risk tiers & PvP eligibility | [risk-security-bands.md](risk-security-bands.md) | +| Zones (where fights live) | [zones.md](zones.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/brainstorm/README.md b/docs/game-design/brainstorm/README.md new file mode 100644 index 0000000..9b0512a --- /dev/null +++ b/docs/game-design/brainstorm/README.md @@ -0,0 +1,9 @@ +# Brainstorm (game design) + +**Loose ideas** and **idea captures**—not specs, not committed scope. Anything here may move, merge into a proper artifact, or be dropped. + +Parent index: [`../overview.md`](../overview.md). + +| File | Topic | +|------|--------| +| [hack-bodyguard-missions.md](hack-bodyguard-missions.md) | Skill + gig split instances (hack / bodyguard) | diff --git a/docs/game-design/brainstorm/hack-bodyguard-missions.md b/docs/game-design/brainstorm/hack-bodyguard-missions.md new file mode 100644 index 0000000..455b16f --- /dev/null +++ b/docs/game-design/brainstorm/hack-bodyguard-missions.md @@ -0,0 +1,36 @@ +# Hack + bodyguard missions (idea capture) + +**Status:** brainstorm only—so the concept is not lost. Not a spec; no commitment to ship, sizing, or tech. + +## Pitch + +Certain **instances / dungeons / group quests** split party pressure across two layers at once: + +1. **Runners / hackers** — progress an objective through **non-combat skills** (intrusion, decryption, keeping a channel open, etc.). This lane is **skill**-based ([skills.md](../skills.md)), not gig-based. +2. **Bodyguards** — hold space against **physical security** (drones, guards, automated defenses). This lane is **gig**-based combat ([gigs.md](../gigs.md)). + +Both need to succeed for the run to work. The fantasy: **corporate extraction**, **data heist**, **sabotage op**—cyberpunk bread and butter. + +## Cross-lane play (examples) + +Ideas to make the two halves **talk to each other** (fun > realism until balance says otherwise): + +- **Hackers → combat:** take down **security comms** or **sensor nets** so **attack waves slow**, telegraphs get sloppy, or patrol routes blind. +- **Bodyguards → hack:** **physical breach** of an IT closet / NOC floor so the **defense stack** against the hack weakens (fewer counter-intrusion ticks, shorter firewall phases, etc.). + +Other directions **open:** power budget for the site, timers, optional side objectives, failure states (wipe vs partial success). + +## Design intent + +- Reinforces the **skills vs gigs** split in **one** memorable content type. +- Gives **non-combat specialists** a spotlight **inside** group content that still has combat teeth. +- **Open:** minimum / maximum group size, solo scaling, whether one player can straddle both roles, how this ties to **zones** and **factions**, and encounter templates ([overview](../overview.md) — encounters stub). + +## Related docs + +| Topic | Where | +|--------|--------| +| Gig roster, party language | [gigs.md](../gigs.md) | +| Skills, seams with combat gear/crafting | [skills.md](../skills.md) | +| Zone / instance tone | [zones.md](../zones.md) | +| Enemy/security archetypes later | [overview](../overview.md) planned **Encounters** | diff --git a/docs/game-design/crafting.md b/docs/game-design/crafting.md new file mode 100644 index 0000000..4594d7c --- /dev/null +++ b/docs/game-design/crafting.md @@ -0,0 +1,79 @@ +# 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 — Slice 3 (Recipes pipeline)](../decomposition/epics/epic_03_crafting_economy.md#epic-3-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 — Slice 3 (Recipes pipeline)](../decomposition/epics/epic_03_crafting_economy.md#epic-3-slice-3) | +| Gather slice (inputs) | [Epic 3 — Slice 2 (Gather nodes)](../decomposition/epics/epic_03_crafting_economy.md#epic-3-slice-2) | +| Economy (sinks, trade, tuning) | [economy.md](economy.md) | +| Death / loss (durability, repair) | [death-loss-recovery.md](death-loss-recovery.md) | +| Risk & security (trade/theft context) | [risk-security-bands.md](risk-security-bands.md) | +| Zones (bench access, district flavor) | [zones.md](zones.md) | diff --git a/docs/game-design/death-loss-recovery.md b/docs/game-design/death-loss-recovery.md new file mode 100644 index 0000000..978f8fa --- /dev/null +++ b/docs/game-design/death-loss-recovery.md @@ -0,0 +1,78 @@ +# Death, loss & recovery + +Vision for **what happens when a character fails** (especially in **combat**): **item** stakes, **durability** and **destruction**, **recovery** flow, and **anti-grief** boundaries—without duplicating **combat ability** design ([abilities.md](abilities.md)) or **security tier** / **PvP** **eligibility** ([risk-security-bands.md](risk-security-bands.md)). + +**Combat resolution & death event:** [E5.M1 — CombatRulesEngine](../decomposition/modules/E5_M1_CombatRulesEngine.md) is **server-authoritative** for outcomes including **death** ([client vs server authority](../decomposition/modules/client_server_authority.md)); telemetry includes `player_death` per [Epic 5](../decomposition/epics/epic_05_pve_combat.md). + +**Item wear and sinks:** [E3.M4 — SinkAndDurabilityLifecycle](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) (`DurabilityState`, `ItemSinkEvent`, `RepairCostRule`)—**repair** and **decay** tie into [economy.md](economy.md) **sinks** and [items.md](items.md) **rarity** expectations. + +**PvP-context loss & abuse:** [E6.M3 — LossPenaltyAndAntiGriefRules](../decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md) (`PvPLossRule`, `SpawnProtectionState`, `GriefingStrike`) with hooks to [E9.M4 — IntegrityAndAbuseResponse](../decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md) ([Epic 6](../decomposition/epics/epic_06_pvp_security.md)). Order with combat: [pvp integration](../decomposition/modules/pvp_combat_integration.md) — eligibility → resolution → **loss** rules. + +**Item schema:** per-item state lives on **`ItemInstance`** ([E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md)). **Cybernetics** vs **external armor** on death/loss follow [skills.md — Seams](skills.md#seams-gigs-skills) (**chrome** is **semi-permanent**; loadout **gear** is **swap-friendly**). + +## PvE vs PvP (design intent) + +- **PvE-first** product stance ([Epic 6](../decomposition/epics/epic_06_pvp_security.md) objective): default **loss** in **opt-in** or **high-tier** spaces can be **harsher** than in **safe** hubs; **tier** **language** in [risk-security-bands.md](risk-security-bands.md); exact **tables** **TBD**. +- **PvP death** applies **E6.M3** rules (drops, durability hits, flags)—not necessarily the same table as **PvE wipe** (**open** until PvP vision lands; [gigs.md](gigs.md) **PvP** notes). +- **Skill** and **gig** **progression** are **not** assumed to **reset** on death—loss is primarily **items**, **currency** (if any), **buffs**, and **position** unless a **hardcore** mode or **content** says otherwise (**open**). + +## Loss lenses (what can be taken or broken) + +| Lens | Design notes | +|------|----------------| +| **Durability** | Wear on use / death / repair loops ([E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md)) | +| **Drop on death / corpse** | **Lootable** body, **partial** drop, or **no** drop by **security tier**—**open**; drives **economy** and **grief** surface ([economy.md](economy.md)) | +| **Consumables** | Already **sinks**; death may **not** be the main churn—**open** | +| **Cybernetics** | **Unlikely** to fully **strip** on routine death—aligns with **character-scoped** fantasy ([skills.md](skills.md)); **damage**, **malfunction**, or **story** loss—**open** | +| **Materials / inventory** | **Full loot** vs **protected** slots vs **binding**—overlaps [items.md](items.md) **Open questions** | + +## Recovery (getting back into play) + +- **Respawn** points: **hub**, **checkpoint**, **squad**, **clinic** **fiction**—**open**; must be **clear** after **death** UX. +- **Corpse run** vs **instant** re-entry vs **mission** **fail** state—content-dependent (**open**). +- **Gig** and **loadout** after death: **same** main gig unless **content** forces **swap**; **invalid** **gear** stays governed by [gigs.md](gigs.md) **hub swap** rules when applicable. + +## Anti-grief and readability + +- **Spawn protection**, **repeated** **killing** penalties, and **escalation** to **integrity** pipeline: **E6.M3** / **E9.M4**. +- **Readable** stakes before engagement: ties to **consent / risk UX** ([Epic 6](../decomposition/epics/epic_06_pvp_security.md), [E6.M2](../decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md), [risk-security-bands.md](risk-security-bands.md)). +- **Exploits** (dupe corpse, disconnect abuse): **server** truth + [E9.M4](../decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md). + +## Module map (death / loss–focused) + +| Module | Role | Ties to this doc | +|--------|------|-------------------| +| [E5.M1](../decomposition/modules/E5_M1_CombatRulesEngine.md) | Combat outcomes, death | **Trigger** | +| [E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) | Durability, repair, item sink | **Item** consequences | +| [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | `ItemInstance`, binds | **What** can be lost | +| [E6.M3](../decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md) | PvP loss, spawn protection | **PvP** | +| [E6.M2](../decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md) | Risk prompts | **Informed** consent | +| [E9.M4](../decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md) | Abuse response | **Ops** | +| [E8.M3](../decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md) | Trade | **Recovery** via market—**optional** fiction | + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Server authority on death | **Server** resolves death and **inventory** mutations—never client-trusted | Agreed ([E5.M1](../decomposition/modules/E5_M1_CombatRulesEngine.md), [authority](../decomposition/modules/client_server_authority.md)) | +| Chrome vs external gear on loss | **Different** buckets; **chrome** not treated as **swap** **plates** | Agreed ([skills.md](skills.md) **Seams**) | +| PvE-first | **Optional** **harsh** loss where product allows; **not** “PvP required to progress” | Agreed ([Epic 6](../decomposition/epics/epic_06_pvp_security.md) framing) | + +## Open questions + +- **Exact** PvE death tax (durability %, item drop table, **currency** **cut**) by **zone** / **instance**. +- **Hardcore** or **seasonal** **rules** vs **main** shard policy. +- **Failure XP** (non-lethal) remains **open** in [skills.md](skills.md)—separate from **death** **penalties**. +- **Insurance**, **clone**, **backup** **fiction** vs implementation cost ([items.md](items.md) binding/insurance notes). + +## Where to read next + +| Topic | Document / module | +|--------|-------------------| +| Item buckets, binding, open loss questions | [items.md](items.md) | +| Sinks, repair, economy | [economy.md](economy.md), [E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) | +| Combat actions & kits | [abilities.md](abilities.md), [gigs.md](gigs.md) | +| Hybrid XP (death does not imply skill XP change) | [progression.md](progression.md) | +| PvP product stance | [Epic 6](../decomposition/epics/epic_06_pvp_security.md) | +| Risk & security tiers, PvP eligibility | [risk-security-bands.md](risk-security-bands.md) | +| Place context (hub vs frontier) | [zones.md](zones.md) | diff --git a/docs/game-design/economy.md b/docs/game-design/economy.md new file mode 100644 index 0000000..300c684 --- /dev/null +++ b/docs/game-design/economy.md @@ -0,0 +1,94 @@ +# Economy (currency, trade, sinks) + +Vision for **how value is created, destroyed, and exchanged**: **faucets**, **sinks**, **prices and fees**, **player trade**, and **live balance**—without re-specifying **item** shapes or **recipe** execution (those stay in [items.md](items.md) and [crafting.md](crafting.md)). + +**Policy & KPIs:** [E3.M5 — EconomyBalancePolicy](../decomposition/modules/E3_M5_EconomyBalancePolicy.md) encodes **`EconomyPolicy`**, **`PriceBandRule`**, **`FaucetSinkRatio`** thresholds; ties to [E3.M4 — SinkAndDurabilityLifecycle](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) and alerts via [E9.M2 — KpiDashboardsAndAlerting](../decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md); later [E9.M3 — LiveBalanceControlPlane](../decomposition/modules/E9_M3_LiveBalanceControlPlane.md). + +**Trade & settlement:** [E8.M3 — PlayerTradeAndMarketplace](../decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md) (`MarketListing`, `TradeOffer`, `SettlementEvent`)—supports **crafting economy** per [Epic 8 — Social / trade](../decomposition/epics/epic_08_social_guild.md). + +**Reward paths:** [E7.M2 — RewardAndUnlockRouter](../decomposition/modules/E7_M2_RewardAndUnlockRouter.md) (missions, bundles); [E5.M3 — EncounterAndRewardTables](../decomposition/modules/E5_M3_EncounterAndRewardTables.md) (loot). **Parity guard:** [E6.M4 — RewardParityEnforcer](../decomposition/modules/E6_M4_RewardParityEnforcer.md) (PvP ↔ PvE/craft equivalents). + +**Production spine:** [gathering.md](gathering.md) → [crafting.md](crafting.md) → [items.md](items.md). **Progression payouts:** [progression.md](progression.md) (**mission** rewards vs **combat encounter** pipes). **Epic 3** loop: [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) — [Slice 4 (sinks + policy)](../decomposition/epics/epic_03_crafting_economy.md#epic-3-slice-4) for pre-production **economy** tuning. + +## Gig vs skill (economic identity) + +- **Wealth and supply** mainly flow through **skills** (gather, process, make), **items**, **trade**, and **missions**—not through **gig level**. **Gigs** gate **combat use** of much **gear**, not the right to **craft** or **sell** ([Seams](skills.md#seams-gigs-skills), [items.md](items.md)). +- **Combat encounters** → **gig XP** by default; they are **not** the primary faucet for **skill** economy unless we explicitly add **loot** or **currency** on the encounter table ([progression.md](progression.md)). +- **Mission / contract rewards** may inject **credits**, **items**, or **skill XP** as scripted **payouts**—separate from “the fight trained my fab skill” ([progression.md](progression.md), [skills.md](skills.md)). + +## Faucets (value entering circulation) + +Design lenses (exact tables **data-driven**): + +| Source | Role | +|--------|------| +| **Gather nodes** | Raw materials into the loop ([gathering.md](gathering.md)) | +| **Loot / salvage** | Drops and world pulls ([items.md](items.md) **Acquisition**) | +| **Craft outputs** | New usable goods from benches ([crafting.md](crafting.md))—creates **items**, not necessarily net **currency** | +| **Mission / vendor payouts** | Injected **currency** or **items** for story and progression | +| **Trade** | **Redistributes** existing stock; may pair with **currency** changing hands via **fees** or **prices** | + +## Sinks (value leaving or being taxed) + +| Sink | Role | +|------|------| +| **Consumables** | Ongoing churn (stims, ammo-adjacent, etc.) | +| **Durability, repair, destruction** | [E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md); **death** stakes: [death-loss-recovery.md](death-loss-recovery.md); [items.md](items.md) open questions | +| **Fees** | Listing, transfer, **clinic** / service **fiction**—**open** rates; `PriceBandRule` in E3.M5 | +| **Currency dumps** | Fast travel, licenses, rep gates, **optional** **sinks** for inflation—**open** catalog | + +Direction: **prototype** should prove at least one **meaningful** durable sink before leaning on **auction-house** scaling ([Epic 3 — Slice 4](../decomposition/epics/epic_03_crafting_economy.md#epic-3-slice-4) intent). + +## Currency and wealth readability + +- **One primary player currency** vs **multiple** (regional, corp scrip, crypto **fiction**)—**open**; UX must stay **readable** ([items.md](items.md) **tooltips** discipline). +- **Wealth fantasy** includes **stockpiles**, **loadout value**, **workspace access**, and **social** **flex**—not only raw balance. +- **Binding**, **insurance**, **theft**, and **security tiers** change **effective** supply—see [items.md](items.md) **Open questions**, [death-loss-recovery.md](death-loss-recovery.md), [risk-security-bands.md](risk-security-bands.md). + +## Trade and prices + +- **Craft-for-others** and **face-to-face** trade are **valid**; buyers need not **equip** what they buy ([items.md](items.md) **Trade**, [Seams](skills.md#seams-gigs-skills)). +- **Market vs direct trade**—**open** product split; [E8.M3](../decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md) owns settlement **contracts**. +- **Craft vs drops vs PvP rewards** should stay **comparable** where [E6.M4](../decomposition/modules/E6_M4_RewardParityEnforcer.md) applies—**parity** is a **gate**, not the full **fun** story. + +## Module map (economy-focused) + +| Module | Role | Ties to this doc | +|--------|------|-------------------| +| [E3.M5](../decomposition/modules/E3_M5_EconomyBalancePolicy.md) | Policy, ratios, price bands | **Tuning hub** | +| [E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) | Durability, repair, item sinks | **Demand** for mats / craft | +| [E8.M3](../decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md) | Listings, settlement | **Exchange** | +| [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | Items in motion | **All** trades | +| [E7.M2](../decomposition/modules/E7_M2_RewardAndUnlockRouter.md) | Quest/mission rewards | **Faucets** | +| [E5.M3](../decomposition/modules/E5_M3_EncounterAndRewardTables.md) | Encounter loot | **Faucets** | +| [E6.M4](../decomposition/modules/E6_M4_RewardParityEnforcer.md) | Cross-path parity | **Fairness** | +| [E9.M2](../decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md) | KPIs, breaches | **Ops** visibility | +| [E9.M3](../decomposition/modules/E9_M3_LiveBalanceControlPlane.md) | Live knobs | **Later** balance | + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Crafting as primary lane | **Player-made** output stays **relevant**; not “drops only endgame” | Agreed ([Epic 3](../decomposition/epics/epic_03_crafting_economy.md), [items.md](items.md)) | +| Trade without gig | **Buy**/**sell** **craft** products without matching **combat gig** | Agreed ([items.md](items.md), [Seams](skills.md#seams-gigs-skills)) | +| Mission vs encounter payouts | **Skill**/**item**/**currency** from **missions** is explicit reward design—not default combat **skill** XP | Agreed ([progression.md](progression.md)) | + +## Open questions + +- **Starter wealth** and **new player** cadence vs **inflation** in mature shards. +- **Regional** or **instance** markets vs **global** listings—latency and **exploit** surface. +- **Tax**, **laundering**, **corruption** **fiction** vs systems cost. +- **RMT / TOS** stance—product and legal, not covered here beyond “server-authoritative **economy**.” + +## Where to read next + +| Topic | Document / module | +|--------|-------------------| +| Item buckets, rarity, trade seam | [items.md](items.md) | +| Gather / craft production | [gathering.md](gathering.md), [crafting.md](crafting.md) | +| Hybrid XP / reward pipes | [progression.md](progression.md), [skills.md](skills.md) | +| Epic 3 slices (incl. sinks/policy) | [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) | +| Social / corp context for trade | [Epic 8](../decomposition/epics/epic_08_social_guild.md) | +| Death, durability, PvP loss | [death-loss-recovery.md](death-loss-recovery.md) | +| Security tiers, PvP eligibility | [risk-security-bands.md](risk-security-bands.md) | +| Zone identity (trade hubs, black markets) | [zones.md](zones.md) | diff --git a/docs/game-design/gathering.md b/docs/game-design/gathering.md new file mode 100644 index 0000000..5ab5c1c --- /dev/null +++ b/docs/game-design/gathering.md @@ -0,0 +1,84 @@ +# Gathering & resources + +Vision for **pulling raw value from the world**: **resource nodes**, **yields**, **who can compete**, and how gathering feeds **inventory** and **skill** progression—without collapsing into **gig** combat progression. + +**Runtime ownership:** [E3.M1 — ResourceNodeAndGatherLoop](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) defines **`ResourceNodeDef`**, **`GatherResult`**, **`ResourceYieldTable`**, and ties gather interactions to [E1.M3 — InteractionAndTargetingLayer](../decomposition/modules/E1_M3_InteractionAndTargetingLayer.md). Outputs land as items via [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md). **Ecology / respawn pacing** per zone: [E4.M2 — SpawnEcologyController](../decomposition/modules/E4_M2_SpawnEcologyController.md). + +**Skill roster (Gather category):** [skills.md — Gather](skills.md#skill-roster-draft-ideas-by-category) (**Salvage**, **Extraction**, **Harvest (bio)**, **Quarry / bulk**). **Hybrid vocabulary:** [progression.md](progression.md). **Where gathered stuff goes:** [items.md](items.md) **Materials & intermediates** and **Acquisition**. + +## Gig vs skill + +- **Gathering is skill progression**, not **gig** identity. **Combat encounters** do not grant **skill XP** by default; **gather / craft** pipes do ([progression.md](progression.md), [Epic 2 — Skills](../decomposition/epics/epic_02_skills_and_progression.md) **Slice 3**). +- **No gig XP** from nodes or harvest loops—**gig XP** stays on the **combat** path ([gigs.md](gigs.md)). +- **World gates** (rep, licenses, zone access) can **gate which nodes exist or who may interact**; they must not replace “wrong class” locks—**any character** can train **Gather** skills over time ([skills.md](skills.md) **Pillars**). + +## Node lenses (design-facing) + +Nodes are **data** (`ResourceNodeDef`); these **lenses** help content and balance talk align with **Gather** skills: + +| Lens | Fiction / examples | Typical skill hook | +|------|--------------------|--------------------| +| **Consumer salvage** | Wrecks, e-waste, stripped chrome, discarded gear | **Salvage** | +| **Subsurface / geological** | Seams, drilled feedstock, rare earths | **Extraction** | +| **Bio / organic** | Fungal mats, cultured tissue, black-market organics (grim **concepts**—[overview.md](overview.md) presentation band) | **Harvest (bio)** | +| **Urban bulk / structures** | Demo recoverables, aggregate, structural mass—not consumer wrecks | **Quarry / bulk** | + +Same **physical prop** might map to **different** node types or yield tables by **zone tier** and **fiction**—**content** decides; skills table in [skills.md](skills.md) stays the **boundary** reference (e.g. **Salvage** vs **Quarry**). + +## Competition and “open world” feel + +Directional goals (implementation **open**): + +- **Depletion** and **regen** (capacity, timers) make **presence** and **timing** matter—aligned with E3.M1/E4.M2 responsibilities. +- **Contesting** the same node may be **non-combat** (arrival order, channel time, tool tier) or **high-risk** (PvP-adjacent) depending on **security tier**—see [risk-security-bands.md](risk-security-bands.md) and [gigs.md](gigs.md) **PvP** notes (**open** until PvP vision lands). +- **Instanced vs shared** world: some resources may live only in **contracts** or **dungeons**; others in **shared** overworld—**split by content**, not a single global rule (**open**). + +## Exhaustion, tools, and gates + +- **Stamina / daily caps / exhaustion** on gather—**open**; if used, should support **specialist fantasy** without hard **gig** coupling ([skills.md](skills.md) **Low-gig specialist**). +- **Tools** (pickaxes, rigs, scanners) are **items**—craft or buy via [items.md](items.md); **use** may be **skill**-gated per item data ([Seams](skills.md#seams-gigs-skills) **Non-combat Rigging / utility** pattern). +- **Skill XP** from gather: award on **successful** interaction / yield resolution—structured for telemetry ([E2.M2 — XpAwardAndLevelEngine](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md)); exact curves **open**. + +## Pipeline position + +**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) + +| Module | Role | Ties to this doc | +|--------|------|-------------------| +| [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) | Nodes, gather, yields | **Core** | +| [E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md) | Skill XP awards | Gather **skill** progression | +| [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | Items in inventory | **GatherResult** outputs | +| [E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md) | Spawn profiles, respawn, depletion bounds | Zone **density** and recovery | +| [E1.M3](../decomposition/modules/E1_M3_InteractionAndTargetingLayer.md) | Interaction range / targeting | Player **interacts** with node | + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Gather → skill XP, not gig XP | **Skill** XP from gather/craft pipes; **gig** XP from combat encounters | Agreed ([progression.md](progression.md)) | +| Gather skills vs node fiction | **Salvage** / **Extraction** / **Harvest** / **Quarry** boundaries as in [skills.md](skills.md) | Agreed | +| Pipeline | Raw from nodes feeds **Process** then **Make**—not a flat single-step economy | Agreed ([skills.md](skills.md)) | + +## Open questions + +- **Node ownership** (personal tap, party split, corp claims) vs **FFA** taps—social and exploit surface. +- **Stealing** gathered output or **harvesting under fire**—ties to **risk bands** and [death-loss-recovery.md](death-loss-recovery.md) (**TBD** tuning). +- **Bots / automation** fantasy vs anti-bot—how much **AFK** is acceptable (**open**). +- **Cross-skill nodes** (e.g. **Intrusion** to **unlock** a **Salvage** pile)—mission design vs systemic rule. + +## Where to read next + +| Topic | Document / module | +|--------|-------------------| +| 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) | +| Economy (faucets from gather + policy) | [economy.md](economy.md) | +| Death / loss (contested gather, drops) | [death-loss-recovery.md](death-loss-recovery.md) | +| Risk tiers & contest rules | [risk-security-bands.md](risk-security-bands.md) | +| Zone identity & spawn feel | [zones.md](zones.md) | +| Epic 3 gather slice | [Epic 3 — Slice 2 (Gather nodes)](../decomposition/epics/epic_03_crafting_economy.md#epic-3-slice-2) | +| 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 new file mode 100644 index 0000000..8e716e9 --- /dev/null +++ b/docs/game-design/gigs.md @@ -0,0 +1,141 @@ +# Gigs (combat roles) + +Vision-level design for **combat identity**: what you bring to a fight, how you progress, and how you swap roles. **Shared progression framing** and **vocabulary**: [progression.md](progression.md). **Gigs ↔ skills seams** (gear, crafting, consumables, rep): [skills.md](skills.md). This file is the **gig** artifact proper. + +**Implementation anchors:** [Epic 5 — PvE combat](../decomposition/epics/epic_05_pve_combat.md); gig XP/progression will need alignment with [Epic 2 — Skills and Progression Framework](../decomposition/epics/epic_02_skills_and_progression.md) when data models split. + +## What a gig is + +A **gig** is the combat **role** on an outing: which **abilities** you run, how the party reads you (tank, support, control, damage, etc.), and tuning expectations. It is **not** a non-combat profession—**skills** cover gather/craft ([skills.md](skills.md)). + +Fiction may say *contract*, *loadout*, or *job*; specs use **gig**. + +## Gig roster + +### Naming and theme + +Project priorities: **fun first**, then **distinctly cyberpunk**. Gig names should be **good in voice chat** (short, punchy, hard to confuse) and **signal the fantasy** without reading as generic fantasy MMO or pure military sim. + +**Cyberpunk flavor** here means: **street and contract work**, **net and security metaphors**, **hardware and software language**, **chrome and infrastructure**—not just “neon trim.” We avoid **Tolkien-adjacent** or **knightly** defaults unless we deliberately subvert them later. + +Names below are **v1** after a theme pass; abilities and lore can still rename a gig if playtests demand it. + +**First draft (v1):** **nine gigs**—**three** **damage**, **two each** **tank**, **heal**, **util**. + +| Archetype | Gig | Cyberpunk read (why this name) | Draft identity (mechanical) | +|-----------|-----|-------------------------------|------------------------------| +| **Damage** | **Breach** | One clean **breach**—ICE, perimeter, or priority target—then exploit it. | Focused **spike**: burst windows, priority removal, short-to-mid range in kit. | +| **Damage** | **Cascade** | Failure **propagates** like a crash or outage—noise that hits **many** nodes at once. | **AoE / cleave** pressure, packs and lanes, close or mid space. | +| **Damage** | **Sightline** | **Optics** and **LOS**—control of angle and distance, surveillance-era violence. | **Ranged** DPS: spacing, line-of-sight play, back-line read; weapon-agnostic for now. | +| **Tank** | **Hardcase** | Street **chassis** attitude: you’re the **case** that doesn’t crack. | **Anchor** tank: stand ground, hard mitigation, hold space for the group. | +| **Tank** | **Drift** | **Slip** threat and **slide** the fight—ghost through damage, street motion. | **Mobile** tank: pick up strays, reposition, mitigation through timing and movement. | +| **Heal** | **Sawbones** | Classic **street doc**—already in-genre; visceral, human, grimy. | **Direct** healing: triage spikes, raw throughput. | +| **Heal** | **Patch** | **Patch** the body *and* the run—prevent the wipe like a hotfix before prod blows. | **Preventive / layered**: shields, HoTs, slow cleanses—flatten damage before it spikes. | +| **Util** | **Blackout** | **Kill the lights** on the enemy plan—casts, buffs, coordination. | **Shutdown**: debuffs, interrupts, punish windows—offensive support. | +| **Util** | **Relay** | You’re the **bus** that **amplifies** the crew’s signal and tempo. | **Enable**: group buffs, resource or tempo hooks—make the next team play bigger. | + +**Roster scope (v1):** we **expect** to add a **fourth damage** gig eventually once a clear mechanical niche shows up in combat design (e.g. DoT, pets, or another distinct fantasy—**TBD**). **For now** the roster stays at **nine** gigs; no fourth damage row until we’re ready to name and kit it. + +**LFG / niches:** the four **archetypes** still map to “need damage / tank / heal / util.” A **conditional** LFG tool ([Party, encounters, and recruitment](#party-encounters-and-recruitment)) can treat **archetype** as the coarse tag and **gig** (or loadout) as the fine print—**open**. + +**Still open:** **weapon / gear families** per gig (especially **Sightline** vs **Breach** / **Cascade**), **sub-gig** pairings that feel bad, corp vs street **faction skins** on the same gig, future **fourth damage** gig definition, and other roster growth after launch. + +## Main gig + sub-gig + +**Agreed:** every loadout has a **main gig** and a **sub-gig** (FFXI-style). The sub adds **limited** cross-gig abilities without second-main power—a **large creative space** as the roster grows ([progression.md](progression.md) **Why hybrid**). + +- **Effective sub level:** at **main** per-gig level **X**, sub contributes abilities up to **⌊X / 2⌋**, capped by the **sub-gig’s own stored level** (see **XP** below)—exact `min` / rounding **TBD**. +- **Hub-only** changes to main or sub ([Hub swap](#hub-swap)). + +**Still open:** + +- **Combat gear:** **main-gig–restricted** for equip; sub feeds **abilities** only. **Seams** (equip / deploy / activation, crafting): [skills.md — Seams](skills.md#seams-gigs-skills). +- **Consumables (passive amp):** **Agreed** — **sub-gig** counts. **Passive** gig-tagged bonuses (e.g. extra healing from a med item when you’re a medic-type gig) apply if **either** **main** or **sub** matches the item’s gig hook. **Open:** if **both** match, **stack vs. single best** vs. **main wins**—pick at balance pass. +- **PvP:** **gig rules blocked** until we know **if** and **how much** PvP the game includes—see [PvE vs PvP](#pve-vs-pvp). +- **UI:** two gig strips, sub ability styling, loadout summary for party—**open.** + +## Progression + +**Agreed:** **per-gig** level/XP (and later **mastery/perks** on that gig). No shared **combat rank** that levels every gig at once. **Maining every gig** on one character is allowed; **slow leveling** makes that a long-term goal ([skills.md](skills.md) seams). + +**Agreed — combat encounter → gig XP, not skill XP:** the **fight loop** (encounters, clears—however combat resolves) grants **gig XP** on the **main gig** only, not **`SkillDef` / skill** XP. **Missions** may still **reward skill XP** on **turn-in** or **bonus** objectives—that is a **separate** payout from **combat → gig XP**, data-defined per contract. **Agreed — gig XP award timing:** only the **main gig** earns **gig XP** from combat (and any other gig-level awards). The **sub-gig** earns **no** XP toward its own progression while equipped as sub—it only **reads** its stored level for ability unlocks. To level a gig you ran as sub, **swap** it to **main** at a hub and play with it primary. **UI** should make clear that **gig XP** (bars, flytext) applies to **main** only. + +**Open:** + +- **Curves:** same philosophy as **skills** (soft feel, more XP per level)—per-gig tables vs global template **TBD**. +- **Mastery/perks** on gigs vs flat level gates—**open** (E2.M3-style expression). + +## Hub swap + +**Agreed:** **no on-the-fly swap.** Changing **main gig**, **sub-gig**, or both only at a **safe hub**—**city**, **home base**, or other **data-tagged swap site**. Not in the field, not mid-combat. + +**Open:** + +- Which locations qualify (faction terminals, apartments, guild halls, etc.). +- Fees, rep gates, cooldowns, tutorial exceptions. +- **Loadout UX** after swap: auto-unequip invalid combat gear vs player-managed **presets** per gig pair. +- **Party:** what happens if someone swaps while grouped—**open** (session lock vs free swap at hub). + +## Party, encounters, and recruitment + +Earlier drafts implied a **dedicated LFG UI** (tags, filters). That is **not** decided. Players might use **chat only** (zone, guild, party ads), a **future matchmaking tool**, or a **hybrid** (e.g. hub board + chat). + +**Design intent (UI-agnostic):** gigs still give **shared vocabulary**—“need mitigation,” “need cleanse,” “LF damage”—whether typed in chat or, later, picked from a structured browser. **Encounter** and **scaling** design can reason about **niches** without assuming any specific recruitment feature ships. + +**Recruitment channel — deferred:** whether we ship **chat-only**, a **built-in LFG/matchmaking** tool, or a **hybrid** is **not** something to lock now. Revisit once **social, zone, and session vision** are further along; the **conditional LFG design** below stays ready if we build a tool. + +**If we ship an LFG-style tool** (common in modern MMOs)—**agreed direction, conditional on building it:** + +- Listings and search are **niche / archetype** oriented (mitigation, heal, damage, control, etc.)—not raw gig names as the primary filter. +- **Eligibility:** the game (or data rules) decides whether your **current gig + loadout** (main/sub, gear, etc.—exact inputs **TBD**) **qualifies** you to advertise under each niche. If you qualify for **several**, you may **select multiple** niches for your listing—**player discretion** among what you’re allowed, not forced single pick. +- **Open:** eligibility tables per gig/loadout template, caps on how many niches one listing shows, how **sub-gig** factors in, and UX copy. + +**Open — rules / content (independent of LFG UI):** + +- **Mandatory niches** in instanced content vs open-world flex. +- **Group scaling** ([E5.M4](../decomposition/modules/E5_M4_GroupCombatScaling.md)) vs gig composition—pass with encounters. + +## PvE vs PvP + +**PvP scope is undecided**—how much player-vs-player content (if any) ships, and in what form, is still unsettled. Until that vision exists, **gig-specific PvP rules** (viability per gig, **sub-gig** in PvP, brackets, **templates**, **security-band** hooks—[overview](overview.md) risk stubs) stay **open with no deadline**, not a near-term design task. + +**PvE** gig design proceeds **without** assuming a particular PvP answer. + +## Story + +**Gig-scoped** storylines and **main-quest-style** arcs live per gig on one character; **faction rep** stays character-wide ([skills.md](skills.md) seams). **Open:** how much **mandatory** gig story vs optional. + +## Gear & consumables (summary) + +- **Combat gear:** **gig-restricted** equip; after hub swap, player **fixes loadout** for new main gig. +- **Crafting** combat gear: **no gig requirement**—**skills** only; can craft for trade. +- **Consumables:** anyone can use; **passive** amp checks **main or sub** (see **Main gig + sub-gig**). + +Detail: seams table in [skills.md](skills.md). + +## Decisions log (gig-focused) + +| Topic | Direction | Status | +|-------|-----------|--------| +| Sub-gig slot | FFXI-style; ~½ main effective cap; hub change | Agreed ([skills.md](skills.md)) | +| Hub swap | Safe hubs only; not in field / combat | Agreed | +| Combat progression | Per-gig tracks | Agreed | +| Gig roster | **9 gigs** (v1); **4th damage** likely later—parked until niche is clear | Draft | +| Gig XP award timing | **Main gig only**; **sub-gig** earns no XP (level that gig as main to progress it) | Agreed | +| Sub-gig + consumable amp (passive) | **Sub counts**; main **or** sub can trigger passive amp | Agreed | +| Recruitment channel | **Deferred**—revisit with broader game/social vision; options remain chat / tool / hybrid | Deferred | +| LFG tool *(if shipped)* | **Niche** listings; **gig + loadout** eligibility per archetype; **multi-select** among qualified niches (player choice) | Agreed (conditional) | +| PvP gig rules | **Blocked on overall PvP vision**—open indefinitely until product direction on PvP is clear | Open (indefinite) | + +## Next artifacts + +- [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.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)). +- [economy.md](economy.md) — **gig** does not gate **craft**/**trade**; **wealth** loops are **skill**- and **item**-heavy ([items.md](items.md)). +- [death-loss-recovery.md](death-loss-recovery.md) — **combat** death → **gig** loadout context; **PvP** loss rules **E6.M3** (not same as PvE—**open**). +- [risk-security-bands.md](risk-security-bands.md) — **where** **PvP** can apply (**E6.M1**); not defined by **gig** pick alone. +- [zones.md](zones.md) — **where** gigs feel grounded; **hub** vs **pocket** world fantasy. +- [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..a45b3b1 --- /dev/null +++ b/docs/game-design/items.md @@ -0,0 +1,87 @@ +# 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**. + +**Schema ownership:** [E3.M3 — ItemizationAndInventorySchema](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) versions **`ItemDef`** (template), **`ItemInstance`** (per-item state: stack, durability hook, binds), and **`InventorySlot`** (containers)—that is where **rarity**, **quality**, **stack rules**, and **equipment metadata** land. Broader loop and slices: [Epic 3](../decomposition/epics/epic_03_crafting_economy.md); authored data under [`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). **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**). **Faucets, sinks, listings:** [economy.md](economy.md). + +## 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)). + +## Epic 3 module map + +Design **buckets** above are not 1:1 types in data—they inform tags and metadata on **`ItemDef`** / **`ItemInstance`**. Module responsibilities from [Epic 3](../decomposition/epics/epic_03_crafting_economy.md): + +| Module | Role | Ties to this doc | +|--------|------|-------------------| +| [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) | Nodes, gather, yields | **Materials**; feeds refine/craft | +| [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) | Recipes, craft execution | **Crafted** acquisition; **skills**-only bench | +| [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) | `ItemDef` / `ItemInstance` / slots | **All buckets**; rarity/quality/stack/equip | +| [E3.M4](../decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md) | Durability, repair, sinks | [Open questions](#open-questions); [death-loss-recovery.md](death-loss-recovery.md) | +| [E3.M5](../decomposition/modules/E3_M5_EconomyBalancePolicy.md) | Faucets/sinks policy | Drops vs craft **balance**; trade velocity | + +## 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**—[death-loss-recovery.md](death-loss-recovery.md)). +- **Binding**, **insurance**, **theft** in which **security tiers** ([risk-security-bands.md](risk-security-bands.md); [death-loss-recovery.md](death-loss-recovery.md) **Open questions**). +- **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) | +| Combat pillars (vision stub) | [overview.md — Combat pillars](overview.md#combat-pillars-vision-stub) | +| 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) | +| 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) | +| Death, loss & recovery | [death-loss-recovery.md](death-loss-recovery.md) | +| Risk & security bands | [risk-security-bands.md](risk-security-bands.md) | +| Zones (vendor/loot context) | [zones.md](zones.md) | +| Economy vision (faucets, trade, policy) | [economy.md](economy.md) | +| Economy policy (runtime) | [E3.M5](../decomposition/modules/E3_M5_EconomyBalancePolicy.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 new file mode 100644 index 0000000..08f3a42 --- /dev/null +++ b/docs/game-design/overview.md @@ -0,0 +1,81 @@ +# 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/). + +## 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) + +Link new files here when they exist; remove or rewrite this subsection once the table is populated. + +- **Progression** — [progression.md](progression.md): hybrid **gig + skill** overview and vocabulary. **Gigs:** [gigs.md](gigs.md). **Skills** + seams: [skills.md](skills.md). Recruitment channel **deferred**; *professions* stay folded into **skills** + rep unless a future doc defines something separate. +- **Zones** — [zones.md](zones.md): tone, danger, faction/economic **hooks**; **graph** in [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md). +- **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** — [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** — [crafting.md](crafting.md): depth vs breadth, failure, quality, stations; **skill XP**; [items.md](items.md) for output buckets. +- **Economy** — [economy.md](economy.md): currency, sinks, trade, **E3.M5** / **E8.M3**; **mission** payouts vs **combat** loot ([progression.md](progression.md)). +- **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). +- **Death, loss & recovery** — [death-loss-recovery.md](death-loss-recovery.md): stakes, **E3.M4**/**E6.M3**, recovery UX. +- **Risk & security bands** — [risk-security-bands.md](risk-security-bands.md): **tiers**, **PvP** opt-in, **theft**/gather **contest** hooks; **place** **fiction**: [zones.md](zones.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/) | +| Architecture | [`docs/architecture/`](../architecture/tech_stack.md) | diff --git a/docs/game-design/progression.md b/docs/game-design/progression.md new file mode 100644 index 0000000..5d1784e --- /dev/null +++ b/docs/game-design/progression.md @@ -0,0 +1,40 @@ +# Progression (gigs + skills) + +Shared vision for **how characters grow** in Neon Sprawl: **combat** vs **everything else** use different systems that still live on **one avatar**. Detail docs: **[gigs.md](gigs.md)** (combat roles), **[skills.md](skills.md)** (non-combat skills and **gigs ↔ skills seams**). + +**Implementation note:** [Epic 2 — Skills and Progression Framework](../decomposition/epics/epic_02_skills_and_progression.md) (E2.M1–M4): **Slice 3** wires **gather/craft** to **skill** XP (E2.M2), **combat encounters** to **gig XP only**, and allows **mission reward** hooks to grant **skill** XP when scripted—**not** via the combat encounter pipe. **Gig** levels stay **per gig**; exact gig XP module ownership may sit beside E2.M2 or under Epic 5 until the gig data model is finalized. + +## Vocabulary + +Use these terms in **design specs and tools** (fiction may say *job*, *contract*, *loadout*, etc.): + +| Term | Means | +|------|--------| +| **Gig** | The **combat role** (combat “class”): kit, tuning band, party expectations. **Not** for crafting or gathering. | +| **Skill** | A **non-combat** trained capability only (gather, craft, intrusion loops, etc.). **Never** the combat gig. **Combat encounters** do not grant skill XP by default—only **gig XP** on the **main gig** ([gigs.md](gigs.md)). | +| **Sub-gig** | **Secondary gig** on the same loadout as **main**—limited cross-gig abilities ([gigs.md](gigs.md) **Main gig + sub-gig**). Not crafting identity. | + +## Why hybrid + +- **Gigs** answer “what are you on **this fight**?”—readable roles, **hub swap**, cyberpunk **contract** fantasy, without alts for combat variety. +- **Skills** keep **economy and crafting** **open to every character** (independent of **gig**): anyone can raise gather/craft over time; “street doc” can mean high **Medtech fab** **skill** + rep, not only tonight’s gig. +- **Specialist fantasy:** a player can **under-invest in gigs** and still **mainline the game** through **skills**—top gatherer, crafter, or tech, with **lots of options** to explore. The **skill roster** is meant to **grow** over time; see [skills.md](skills.md) **Pillars** and **Skill roster**. +- **Mission rewards vs combat XP:** **Missions** (contracts, arcs, hand-ins) may **pay skill XP** as an explicit **reward**—separate from the **combat encounter** pipe. Default flow stays **fight → gig XP**; skill XP from an op is **“this job’s payout,”** not **“kills trained my fab skill.”** + +## Where to read next + +| 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) | +| **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) | +| **Economy** (faucets, sinks, trade, policy) | [economy.md](economy.md) | +| **Death / loss / recovery** (stakes, durability, PvP loss) | [death-loss-recovery.md](death-loss-recovery.md) | +| **Risk & security bands** (tiers, PvP eligibility) | [risk-security-bands.md](risk-security-bands.md) | +| **Zones** (place identity, travel graph hooks) | [zones.md](zones.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) | +| Folder index | [overview.md](overview.md) | diff --git a/docs/game-design/risk-security-bands.md b/docs/game-design/risk-security-bands.md new file mode 100644 index 0000000..67c2d76 --- /dev/null +++ b/docs/game-design/risk-security-bands.md @@ -0,0 +1,78 @@ +# Risk & security bands + +Vision for **how dangerous a place is** and **what the rules allow**: **security tiers** on the world graph, **PvP eligibility**, **consent / risk UX**, and how **tiers** connect to **theft**, **gathering contest**, **trade**, and **death** stakes. Place fiction (tone, economic role): [zones.md](zones.md). + +**Tier data (runtime):** [E4.M4 — SecurityTierZoneFlags](../decomposition/modules/E4_M4_SecurityTierZoneFlags.md) assigns **`SecurityTier`**, **`ZonePolicyState`**, and **`ZoneEntryWarning`** per zone on the graph from [E4.M1 — ZoneGraphAndTravelRules](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md). **Server** is source of truth; **client** shows warnings on transition ([Epic 4 — Slice 2](../decomposition/epics/epic_04_world_topology.md#epic-4-slice-2)). + +**PvP gating:** [E6.M1 — PvPEligibilityAndFlagState](../decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md) maps **tier + context** to whether **player hostility** is allowed—**never** client-only toggles ([Epic 6](../decomposition/epics/epic_06_pvp_security.md)). + +**Risk UI:** [E6.M2 — ConsentAndRiskUxSignals](../decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md) consumes **tier** and **warnings** for prompts and HUD. + +**Combat pipeline order:** [pvp_combat_integration.md](../decomposition/modules/pvp_combat_integration.md) — eligibility → **E5.M1** resolution → [E6.M3](../decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md) **loss** rules. + +**Downstream design:** [death-loss-recovery.md](death-loss-recovery.md) (**loss** tables may differ by tier), [economy.md](economy.md) (**binding**, **theft**, **effective** supply), [items.md](items.md) **Open questions**, [gathering.md](gathering.md) **contesting**. **Gig** roster does not define **security**—[gigs.md](gigs.md) **PvP** stays **open** until product locks **opt-in** posture. + +## Tier lenses (design-facing) + +Tiers are **discrete** in data (`SecurityTier`); fiction may say *green zone*, *extraterritorial*, *lockdown*. Example **bands** (names **TBD**—align with content): + +| Band (illustrative) | Player expectation (directional) | +|---------------------|----------------------------------| +| **High security** | **No** optional **PvP**; **theft** / **player** **loot** **restricted** or **off**; **gather** contesting **mild** or **instanced** | +| **Low / frontier** | **Opt-in** or **conditional** **PvP**; **harsher** **death** **loss** **possible**; **contested** **nodes** | +| **Contested / special** | **Event**, **faction**, or **contract** **overrides**—explicit **warning** before entry | + +Exact **count** of tiers, **instance** vs **overworld** rules, and **mission** **pocket** **exceptions** are **content** + data (**open**). + +## What tiers gate (non-exhaustive) + +| System | Tie to tier | +|--------|-------------| +| **PvP** | **E6.M1** / **E6.M2** | +| **Death penalties** | [death-loss-recovery.md](death-loss-recovery.md) — e.g. **drop** tables **stricter** in **riskier** bands (**open**) | +| **Theft / looting players** | [items.md](items.md), [economy.md](economy.md) — only where **policy** allows | +| **Gathering contest** | [gathering.md](gathering.md) — **FFA** vs **protected** **node** **access** | +| **Trade / market fees** | [economy.md](economy.md) — optional **tier**-based **tax** **fiction** (**open**) | + +## Consent and clarity + +- **ZoneEntryWarning** must support **plain** copy: what can happen to **you** and **your** **gear** ([E4.M4](../decomposition/modules/E4_M4_SecurityTierZoneFlags.md)). +- **Opt-in** flows (flag, party, **contract**) sit with **E6.M1** / **E6.M2**; **retroactive** “I didn’t know” is a **UX** **failure** to fix in **content** or **systems**. +- **Teen-oriented** presentation ([overview.md](overview.md)) applies to **risk** **UI** and **threat** **messaging**, not only **cutscenes**. + +## Module map (risk / security–focused) + +| Module | Role | Ties to this doc | +|--------|------|-------------------| +| [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md) | Zone graph, travel | **Where** tiers attach | +| [E4.M4](../decomposition/modules/E4_M4_SecurityTierZoneFlags.md) | `SecurityTier`, warnings | **Core** | +| [E6.M1](../decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md) | PvP allow/deny | **Consumes** tiers | +| [E6.M2](../decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md) | Risk prompts, HUD | **Player** **readability** | +| [E6.M3](../decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md) | PvP loss, spawn protection | After **hostility** | +| [E5.M1](../decomposition/modules/E5_M1_CombatRulesEngine.md) | Combat | Consults **eligibility** for **PvP** | + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Server-authoritative tier | **Zone** **risk** and **PvP** **policy** from **server**; client **display** only | Agreed ([E4.M4](../decomposition/modules/E4_M4_SecurityTierZoneFlags.md)) | +| E4 → E6 direction | **Epic 4** **tags**; **Epic 6** **consumes**—**no** circular **module** **dependency** | Agreed (epic/module text) | +| PvE-first | **High-security** **default** for **new** / **core** **progression**; **harsh** **bands** **opt-in** or **signed** **entry** | Agreed direction ([Epic 6](../decomposition/epics/epic_06_pvp_security.md) framing) | + +## Open questions + +- **Instanced** **dungeons** vs **open** **world** **tier** **inheritance** (override table per **content** **type**). +- **Corporation** / **faction** **leased** **quarters** vs **public** **street** **tier** **in** **same** **district** **mesh**. +- **Skill** **activities** (**hack**, **gather**) in **high** **PvP** **zones**—**interrupt** rules and **loss** of **progress** vs **gear** only. + +## Where to read next + +| Topic | Document / module | +|--------|-------------------| +| Death, durability, PvP loss | [death-loss-recovery.md](death-loss-recovery.md) | +| Economy, theft, binding | [economy.md](economy.md), [items.md](items.md) | +| Gathering under contest | [gathering.md](gathering.md) | +| Zone graph & travel (implementation) | [Epic 4](../decomposition/epics/epic_04_world_topology.md), [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md) | +| PvP product stance | [Epic 6](../decomposition/epics/epic_06_pvp_security.md) | +| Place identity & district roles | [zones.md](zones.md) | +| Folder index | [overview.md](overview.md) | diff --git a/docs/game-design/skills.md b/docs/game-design/skills.md new file mode 100644 index 0000000..4214761 --- /dev/null +++ b/docs/game-design/skills.md @@ -0,0 +1,259 @@ +# 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)**. **Crafting & recipes** (pipeline, benches, failure/quality): **[crafting.md](crafting.md)**. **Economy** (faucets, sinks, trade, policy): **[economy.md](economy.md)**. **Death, loss & recovery** (durability, PvP loss, recovery): **[death-loss-recovery.md](death-loss-recovery.md)**. **Risk & security bands** (tiers, PvP eligibility): **[risk-security-bands.md](risk-security-bands.md)**. **Zones** (place identity, faction/econ hooks): **[zones.md](zones.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). + +## Skills outside combat roles + +Everything **outside combat role resolution** trains on **skills**. That includes gathering, refining, crafting, non-combat tech work, and other **world interactions** we choose to track as progression. + +### Pillars + +- **Any character can train any skill** over time (subject to **world gates**: discovery, rep, licenses—those **add** content, they are not “you picked the wrong class”). +- **Economy identity** is the **skill graph + reputation + gear**, not which **gig** you had equipped last night. +- **Specialist path:** it must be viable to **keep gigs low** (minimal combat-role investment) and still **meaningfully play** by pushing **gather / process / make / tech**—best supplier, best bench, best netsec in the hubs and instances that reward skills. Combat and story may still **touch** gigs; they must not **hard-require** high gig levels to participate in the **economy and skill loops** players care about for that lifestyle ([Seams](#seams-gigs-skills): e.g. **craft** without needing to **equip** what you make). +- **Long-term:** avoid dead-end grinds; slow or expensive is fine, “wrong choice forever” is not. + +### What is (and isn’t) a skill + +A **skill** is a **persistent, leveled** capability, **data-defined** (stable IDs, categories, optional prerequisites). Primary progression is **doing the activity** (gather, refine, assemble, hack a door in a skill-based encounter, etc.). **Books, trainers, or mission grants** can supplement XP—**optional** and should not replace “play the loop” as the main fantasy. + +**Not skills:** **gig** combat progression, **raw item stats** with no trained gate, and **one-off** quest flags (unless we explicitly model them as skills—**open**). + +### Skill domains (examples) + +**Domains** are a **design vocabulary**: when we brainstorm content, what *kind* of real-world activity is this skill about? They help writers and designers stay consistent (“is this **extraction** or **fabrication**?”) and stay separate from **gigs**. Domains are **not** required to match data tags 1:1. + +Domains are **content-shaped**, not a locked taxonomy. Early vision includes: + +| Domain | Examples (illustrative) | +|--------|-------------------------| +| **Extraction** | Pulling value from the world: **earth/subsurface** (mining, drilling), **consumer salvage & biology** (**Salvage**, **Harvest**), and **urban infrastructure materials** (**Quarry**) vs geological **Extraction** skill | +| **Processing** | **Refine** (ores, glass, steel, scrap → material grades); **Fab tech** (physical PCBs, chips, solenoids); **Data scrub** (abstract data—datasets, firmware, logical unlock); **Synth-chem prep** (bio/chem); other conversion | +| **Fabrication** | **Gunsmith**; **Edgesmith**; **Hardshell** / **Softshell** (rigid vs flexible armor); **Rigging** (powered/systems shells); **Cybernetics**; synth-chem, medtech fab, **Food synth** | +| **Tech / intrusion** | Hacking, netsec, counter-intrusion, bypass, diagnostics—**combat-facing** net actions stay **gig** | +| **Support craft** | Medtech fabrication, field repair kits; **implant install / tune** fiction may split **Cybernetics** **Make** vs bench maintenance (**open**) | + +New skills land here as **design + data** demand; a skill can sit in **multiple domains** in conversation before we assign its **primary category**. + +### Categories (families) + +**Categories** are **registry / UI tags**—what we put in data (e.g. E2.M1 `SkillCategory`) for **filters, sorting, and balance** knobs. Expect **one primary category per skill**; optional **secondary** tags for UI only if we need them. + +**Domains vs categories:** **domains** = “what is this skill *about* in the fiction/pipeline?” (design). **categories** = “which bucket does the **system** put it in for players and tuning?” (product). Today’s tables **overlap** on purpose while the roster is unsettled (e.g. extraction work often maps to **Gather**); when we lock a skill list, we either **merge** domain language into categories or keep domains as a **writer’s appendix** only. Categories are **not** gigs, **not** professions, and **not** caps on how many skills you can train. + +**Draft families** (can merge or rename): + +| Category | Rough scope | +|----------|-------------| +| **Gather** | Nodes, yields, field extraction | +| **Process** | **Refine**; **Fab tech** (physical fab); **Data scrub** (data/firmware); **Synth-chem prep** (bio/chem); batch; intermediate goods | +| **Make** | Finished goods, recipes, bench work—**Gunsmith**, **Edgesmith**, **Hardshell**, **Softshell**, **Rigging (gear)**, **Cybernetics**, **Medtech fab**, **Food synth**, etc. | +| **Tech** | Intrusion, netsec, counter-intrusion, exploit dev, crypto & identity, electronics, signal—**not** combat gig kit | + +Optional **secondary category** for UI sorting only—**primary** category in data drives balance defaults. + + + +### Skill roster (draft ideas by category) + +**v0 — for examination, not a commit list.** Each row is a **candidate skill** (or tight cluster we might merge). The tables below are a **solid opening roster**—on the order of **~20–26** names depending on how we **merge or split** clusters—and we **expect to add more** as we approach launch. A **wide** skill set is intentional: it gives design and live ops room to grow **loops**, **biomes**, and **specialist fantasies** without collapsing everything into a tiny tree. + +Final roster needs **stable IDs**, **XP sources**, and **gig/skill boundary** checks (especially **Tech** vs combat netrunning). **Implementation:** [`content/schemas/skill-def.schema.json`](../../content/schemas/skill-def.schema.json) (`id`, `allowedXpSourceKinds`) + [E2.M1 — SkillDefinitionRegistry](../decomposition/modules/E2_M1_SkillDefinitionRegistry.md) acceptance criteria; prototype sample [`content/skills/prototype_skills.json`](../../content/skills/prototype_skills.json). + +Layout mirrors **[gigs.md](gigs.md) gig roster**: one **table per category**, **Skill** name plus **what it covers** and **open / merge** notes. + +**Production chains (Gather → Process → Make):** Recipes can **branch** (same inputs, different outputs) and run **deep** (several **Process** steps in a row before **Make**). **Any** row in **Process**—not one named skill—may sit mid-pipeline, mixing **raw** gatherables with **earlier** intermediates from **Refine**, **Fab tech**, **Data scrub**, **Synth-chem prep**, **Bioprocess**, **Composite work**, etc. Detail in **Overlapping chains** and **Multi-stage processing** under the **Process** heading below (after **Gather**). + +#### Gather — pull raw value from the world + +| Skill | What it covers | Open / merge | +|-------|----------------|--------------| +| **Salvage** | **Consumer goods and vehicles:** cars, ships, computers, other wrecked or discarded **products**; e-waste, stripped chrome—**not** structural building stock (that’s **Quarry**). | — | +| **Extraction** | **From the earth:** mined or drilled feedstock—synth ores, rare earths, geological substrate for industry (subsurface and natural seams, not the city stack). | — | +| **Harvest (bio)** | **Organic feedstock** for chem, medtech, or food chains: cultured tissue and fungal mats **and** deliberately **grim** sourcing—e.g. **morgue** break-ins, **blood** and **tissue** theft, black-market organics. | Grim **concepts** in scope; **how we show it** and **target rating** are **vision-level**—see [overview.md](overview.md) | +| **Quarry / bulk** | **Urban infrastructure** and **built-environment mass:** bricks, concrete, wooden building supplies, aggregate, fill, demo recoverables from **structures**—**not** consumer goods or vehicle wrecks (**Salvage**). | Intentionally **not** **Extraction** (earth seam vs **city stack**) | + +#### Process — turn raw into workable intermediate + +**Overlapping chains:** **Process** and **Make** are not isolated trees. **Different** skills (or different recipes under one skill) can consume the **same** items and yield **different** intermediates or products—e.g. side streams where one batch of scrap or ore can route through **Refine**, **Synth-chem prep**, or **Bioprocess** with **different outputs** where content allows. Data-defined recipes carry the truth; overlap is **intentional** for a dense, interconnected economy. **Refine** vs **Synth-chem prep** stay **separate fantasies** (physical materials vs bio/chem)—see table. + +**Multi-stage processing (depth):** Same idea as **Overlapping chains**, but **serial**: **several** **Process** steps before **Make**—e.g. **Gather → Process → Process → Make** (or longer). **Any** **Process** skill’s recipes can require **Gather**-fresh inputs **and** outputs from **prior** **Process** steps in one pass, or consume only intermediates from an earlier hop—**intermediates feeding intermediates**, not always a single hop from node to bench. + +| Skill | What it covers | Open / merge | +|-------|----------------|--------------| +| **Refine** | **Physical material** feedstock: raw **ore**, **salvaged glass** and **steel**, scrap metals, bulk mineral inputs—**smelt, purify, grade** toward **usable material forms** (ingots, sheet, cullet, structural grades). **Not** bio/chem (**Synth-chem prep**) or component fab (**Fab tech**). | Separate from **Synth-chem prep** & **Fab tech** — **agreed** | +| **Fab tech** | **Electronics and electromechanical fab:** **chips**, **PCBs**, **solenoids**, micro-actuators, substrate and assembly steps—**built components**, not **Refine**’s job of turning raw ore/glass/steel into graded **bulk** material. Uses **Refine** outputs (and other inputs) as **feed**, but the skill fantasy is **manufacture**, not smelt/purify. | Separate from **Refine** & **Data scrub** — **agreed** (physical vs **data** layer) | +| **Synth-chem prep** | **Bio- and chemistry** streams: precursors, reagents, stable compounds, polymer feeds—inputs and outputs are **chem / organic / lab** oriented; feeds **Synth-chem (product)** and related **Make**. **Not** primary home for ore/glass/metal refinement (**Refine**). | Separate from **Refine** — **agreed** | +| **Bioprocess** | Ferment, culture, grow feedstock for medtech or consumables. | — | +| **Composite work** | Laminate layers, weave fibers, prep **Hardshell** / **Softshell** “blanks” before final **Make** assembly. | — | +| **Data scrub** | **Abstract data** work—not **Fab tech**’s physical manufacture. Clean, normalize, decrypt, or repackage **datasets** as craft inputs; **firmware wipes** and logical unlocks that make **salvaged** parts **usable** again without milling a new board. **Information and software** layer on devices and loot, not **PCBs/chips** fab. | Separate from **Fab tech** — **agreed**; **Tech** skills (e.g. **Intrusion**) for **live** hacks—**open** boundary | + +#### Make — recipes, benches, finished goods + +**Swap-friendly armor** splits **rigid** vs **flexible** (**Hardshell** / **Softshell**). **Powered** / **systems** armor—exo frames, actuator-linked shells, mechatronic tactical rigs—is **made** with **Rigging (gear)** (not a third plate/weave skill); **equip** still follows **Combat gear** (**gig-restricted**). **Open:** hybrid pieces (e.g. powered softshell) pick **primary** skill per recipe. + +| Skill | What it covers | Open / merge | +|-------|----------------|--------------| +| **Gunsmith** | Barrels, receivers, ballistics fab. | [Seams](#seams-gigs-skills): craft without gig to *use* | +| **Edgesmith** | **Non-gun** weaponry: blades, clubs and impact tools, stun batons, monofilament / vibro **melee**, **thrown** weapons that are **not** firearms—**not** **Gunsmith** (ballistics, receivers, barrels). | Same [Seams](#seams-gigs-skills) as **Gunsmith**: **craft** with skill; **combat equip** **gig-restricted** | +| **Hardshell** | **Rigid** swap-friendly armor: plates, inserts, helmets, **non-powered** hardshell, ceramic or composite face—**not** **Softshell** flexible suits; **not** **powered** frames (**Rigging (gear)**). **Gig-restricted** when equipped ([Seams](#seams-gigs-skills)). | **No** overlap with **Cybernetics** — **agreed** | +| **Softshell** | **Flexible** swap-friendly armor: kinetic-weave suits, underlayers, padded rigs, textile-forward shells without the **Rigging** mechatronics lane—**not** rigid **Hardshell**; **not** powered exo (**Rigging (gear)**). **Gig-restricted** when equipped ([Seams](#seams-gigs-skills)). | **No** overlap with **Cybernetics** — **agreed**; vs **Hardshell** on hybrid garments — **open** | +| **Synth-chem (product)** | Finish stims, chems, consumables from **Synth-chem prep** (and related **Process**) outputs. | — | +| **Medtech fab** | Field kits, injectors, trauma foam—**craft** lane. | **Gig** Sawbones = *combat use* | +| **Cybernetics** | **Body-integrated** implants and augmentation: neural hooks, sensory suites, limb lines, organ-adjacent systems—**finished** installs from **Process** inputs (e.g. **Fab tech**, **Bioprocess**, **Harvest**, **Synth-chem**). **Semi-permanent** (e.g. **ocular** suite)—**not** swap-friendly **Hardshell** / **Softshell** / **Rigging** armor. Stays **active** across **gig** changes. | **Not gig-gated** — **agreed** ([Seams](#seams-gigs-skills)); **no** overlap with external armor skills — **agreed**; **replace** has **cost**—removed unit **likely** becomes **scrap** (salvage / recovery loop) — **agreed** direction; fees, clinic fiction, exact yields — **open** | +| **Rigging (gear)** | Drones, harnesses, carry systems, tool mods, and **powered / systems** armor **Manufacture**: exo-style frames, actuator-linked hardshell, tactical mechatronic rigs—**Fab tech**-heavy lane for **wearable** systems that are **not** plain **Hardshell** / **Softshell** fab. | **Craft** with skill—**no** gig; **combat deploy** / **combat activation** **gig-restricted** — **agreed** ([Seams](#seams-gigs-skills)); **non-combat** **use** gated by **intended specialty skill** when applicable ([Seams](#seams-gigs-skills)); **hybrid** armor (rigid plate + powered frame—**Hardshell** × **Rigging**): **primary** skill per recipe / multi-step splits — **open** (see Make intro) | +| **Food synth** | Ration fab, street kitchens, synth-food **Make** from **Harvest** / **Bioprocess** / **Synth-chem** inputs where recipes need them. | **Kept** in roster — **agreed** | + +**Make → gigs (combat):** **Vast majority** of **non-consumable** **Make** products are **gig-gated** when brought into **combat** (**equip**, **wear**, **deploy**). **Crafting** stays **skill**/recipe-only—e.g. anyone with **Rigging** can **build** a drone; **deploying** it in a fight needs a **gig** whose kit supports that **deploy** (**data-defined**). See [Seams](#seams-gigs-skills) **Combat gear** and **Make → combat (non-consumables)**. + +#### Tech — systems, hacking, and cyber security (non-gig) + +**Skill** tech covers **prep**, **world interaction**, and **instance / downtime** work. **Combat** net attacks, debuffs, and **today’s gig kit** **ICE-breaking in a fight** stay **gig**-gated unless we deliberately duplicate (**open**). + +| Skill | What it covers | Open / merge | +|-------|----------------|--------------| +| **Intrusion** | Bypass locks and access control, pivot non-combat systems, **hack timers** / objectives. | e.g. [brainstorm/hack-bodyguard](brainstorm/hack-bodyguard-missions.md) | +| **Netsec / hardening** | Patch holes, segment networks, raise **defense** for sites, convoys, ally systems (downtime / prep). | — | +| **Counter-intrusion** | Trace hostile processes, sever sessions, quarantine malware—defensive counterpart to **Intrusion**. | — | +| **Exploit dev** | Build or tune **payloads** and tools for **Intrusion** (pen-tests, heists, corps). | Fold into **Intrusion** mastery? **open** | +| **Crypto & identity** | Break weak schemes; spoof or forge **credentials** where content allows. | Rep / legality hooks — **open** | +| **Electronics** | Repair boards, swap modules, bench diagnostics—physical layer next to netsec. | — | +| **Signal** | Scan, trace, tap—RF and traffic **out of combat** or in objectives. | **Combat** jamming: gig vs skill — **open** | + +**Cross-cutting notes** + +- **Production chain shape:** **Agreed**—(1) **Overlapping** paths: shared **inputs**, divergent **outputs** across **Process** / **Make**; (2) **Multi-stage** depth: **Gather → Process → Process → Make** (or longer), with **any** **Process** skill able to participate. Recipe UX and balance **open** (roster intro + **Process** subsection in [Skill roster](#skill-roster-draft-ideas-by-category)). +- **Agreed Process boundaries:** **Salvage** vs **Quarry**; **Refine** vs **Synth-chem prep** (physical materials vs bio/chem); **Refine** vs **Fab tech** (base material grades vs physical electromechanical fab); **Fab tech** vs **Data scrub** (physical components vs **data/firmware** on salvage). Further merge/split ideas — **open** as the roster evolves. +- **Next pass:** pick **prototype trio** (one Gather, one Process/Make, one Tech) for Epic 2/3 slices—written anchors for gather/craft legs: [gathering.md](gathering.md), [crafting.md](crafting.md); lock **`SkillDef` ids** in data with [E2.M1](../decomposition/modules/E2_M1_SkillDefinitionRegistry.md) when Slice 1 freezes. + +### XP, levels, curves + +- **Server-authoritative** XP and level resolution ([E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md)). +- **Primary source (agreed):** **do the activity**—gather, craft steps, skill-based mission objectives, etc. +- **Secondary sources (open):** quests, dailies, books, training dummies—tuned so they **assist** without **replacing** loops. +- **Structured grants:** skill id, amount, **source** (node id, recipe, quest key…) for telemetry and anti-exploit review. + +**Failure XP** (failed craft, failed hack attempt—not **death**): **not** deciding defaults here—stays **open** for **late-stage tuning** once activity mechanics and the wider progression picture exist ([Decisions log](#decisions-log), [Open questions](#open-questions-skills-only)). + +**Caps (agreed):** **soft** curve only—**each level needs more XP** than the last; **data-driven** per skill or policy. **Runaway** mitigation: steeper curves, context modifiers, diminishing returns on repeat actions—**open** per skill. + +**Pacing / catch-up** ([E2.M4](../decomposition/modules/E2_M4_ProgressionPacingControls.md)): global or cohort knobs for ops; **gig** pacing stays separate ([gigs.md](gigs.md)). + +### Gates, discovery, prerequisites + +**UnlockRequirement**-style gates ([E2.M1](../decomposition/modules/E2_M1_SkillDefinitionRegistry.md)) should **widen** what you can do, not mimic a class pick: + +- **Recipes** and **facilities** tied to skill tier or world state. +- **Faction rep** or **licenses** for restricted goods or zones. +- **Discovery:** find a schematic, rescue a teacher, complete a gig-agnostic storyline. + +**Open:** how much is **available at level 1** vs **gated**; how **alt-friendly** discovery is. + +### Mastery and perks (skills) + +Beyond raw level, **mastery tracks** and **perks** ([E2.M3](../decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md)) give **build texture** inside one skill (branch picks, efficiency, side effects). Same *idea* as gig expression, **different** system—no shared perk tree between gig and skill unless we deliberately link them (**open**). + +**Respec** for skill mastery—**not** locking rules (cost, partial reset, cadence) at this vision stage; **open** for **late-stage tuning** ([Decisions log](#decisions-log)). + +### Cross-skill synergies + +Explicit **bonuses** when skill A + B cross a threshold vs **pure fiction** (“you’re known as a rigger-smith”) with no math—**not** deciding formulas or mandatory links here; **open** until the **system** is better understood; avoid mandatory cross-grinds unless the loop proves fun ([Decisions log](#decisions-log)). + +### Where skills meet the rest of the game + +| Area | Tie-in | +|------|--------| +| [Epic 2 — Skills and Progression Framework](../decomposition/epics/epic_02_skills_and_progression.md) | Registry, XP engine, mastery, pacing | +| [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) | Gather and craft **award** skill XP; items and recipes | +| [Epic 7](../decomposition/epics/epic_07_quest_faction.md) | Quest rewards, rep gates, optional skill payouts | +| [gigs.md](gigs.md) | **Craft** combat gear with **skills**; **equip** with **gigs**—[Seams](#seams-gigs-skills) | +| [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) | **Skill** lane in a group instance (idea only) | + + + +### Open questions (skills-only) + +**Late-stage tuning (intentionally open):** **Failure XP**, **skill mastery respec**, and **cross-skill synergy** math are **not** commitments at this stage. They stay **open** until we understand **skills**, **gigs**, economy, and combat together—then we **fine-tune** in a later balance pass, not as immediate design blockers. See [Decisions log](#decisions-log) **Late-stage tuning**. + +| Topic | Status | +|-------|--------| +| Full launch **skill list** and names | **Draft** roster by category in [Skill roster](#skill-roster-draft-ideas-by-category) | +| **Failure XP**; **mastery respec**; **cross-skill synergy** | **Open**—deferred; **late-stage tuning** (paragraph above) | +| Combat **deploy** / **equip** for **Make** outputs vs **gig** | **Agreed**—see [Seams](#seams-gigs-skills) **Combat gear** and **Make → combat (non-consumables)** | + + + +## Seams (gigs ↔ skills) + +| Topic | Direction | +|--------|-----------| +| **Combat gear** | **Gig-restricted.** Weapons, armor (including **Hardshell**, **Softshell**, and **Rigging**-built powered frames when **worn** as loadout), **combat deployables** **Manufactured** by **Rigging** (e.g. drones **deployed** in a fight), and other **swap-friendly** or **field-deployed** combat pieces declare which **gig(s)** may **equip**, **wear**, **fully activate**, or **combat-deploy** them. After a **hub-only** [gig swap](gigs.md#hub-swap), the player **re-banks or re-equips** combat gear for the new gig (automation vs. manual loadout UX **open**). Non-combat tools (pickaxe, scanner, craft bench) stay **skill**-gated for **use**, not gig-gated, unless a piece is explicitly hybrid; **Rigging** **non-combat** outputs follow **Non-combat Rigging / utility Make**. **Does not** apply to **semi-permanent** **Cybernetics** augments—see **Cybernetics / implants** row. | +| **Cybernetics / implants** | **Not gig-gated.** Augments from **Cybernetics** (**Make**) are **body-integrated** and **semi-permanent**: they remain **in play** when you change **main gig**, **sub-gig**, or combat loadout (e.g. an **ocular** implant does not come off at hub swap). **Crafting** stays **skill**/recipe/rep—never gig level. **Changing** an installed augment has **cost** (credits, clinic, downtime—**open**); the **replaced** piece **likely** comes out as **scrap** or salvage-grade material (feeds **Gather**/**Salvage**/**Refine** loops) rather than a clean reusable item—**agreed** direction, exact tables **open**. **Not** the same rhythm as re-banking a rifle. **External** armor (**Hardshell**, **Softshell**, **Rigging**-built powered shells) and **Cybernetics** **do not overlap**: external armor is **swap-friendly** **Combat gear** (**gig-restricted**); **Cybernetics** is **not** that bucket. | +| **Crafting combat gear** | **No gig or gig level requirement.** Who can *build* it depends on **skills** (e.g. **Gunsmith**, **Edgesmith**, **Hardshell**, **Softshell**, **Rigging (gear)** for powered frames and **deployables**), recipes, rep, facilities—never on owning a gig or its level. A character can **craft combat gear they cannot equip or combat-deploy** (wrong gig, low gig level, etc.): valid for **trade**, **stock**, or **group play**. **Equip / wear / combat deploy / activation** stays **gig-restricted** as **Combat gear** above. | +| **Make → combat (non-consumables)** | **Agreed default:** **Most** **non-consumable** **Make** outputs are **gig-gated** when used in **combat**—weapons, armor, **Rigging** **combat deployables**, and similar—via **equip**, **wear**, or **combat deployment**. **Craft** is **always** **skill**/recipe/rep (plus world gates); **gig** gates **field use**, not the bench. **Exceptions:** **Cybernetics** (**not** gig-gated); **Consumables** (see row below—**carry/use** baseline not gig-gated); **purely non-combat** **Make** (e.g. **Food synth**, civilian tools)—**data-tagged** per item (**open** catalog); **utility** items with **no** combat role and **no** specialty **use** hook (e.g. **backpacks**)—see **Non-combat Rigging / utility Make** row. | +| **Non-combat Rigging / utility Make** | **Non-combat** outputs from **Rigging** (and similar **Make**)—survey drones, harnesses, carry frames—**craft** on **Rigging** (or recipe skill). **Operating** them or getting **full benefit** is **skill-gated** when the item has an **intended specialty**: tie **use** to the relevant skill (**Signal**, **Electronics**, **Intrusion** kit, **Gather** tools, etc.)—**data-defined** per item. **General** items **outside** any specialty or gig (e.g. **backpacks**, simple webbing) may have **no** skill **use** requirement—anyone can **wear** or **use** them; **craft** still follows the recipe (**Rigging** or another **Make** skill as designed). | +| **Consumables** | Unlike most **non-consumable** **Make** products, **carry and use** are not gig-gated by default—anyone can pop a stim or patch. **Passive** potency can scale with **gig** match: e.g. a **medic**-tagged bonus applies if **main *or* sub-gig** matches (see [gigs.md](gigs.md)). Others use a **baseline**. **Active** abilities from consumables (if any) follow their own rules—**open**. Other items may have **no** gig hook—data-driven per item. | +| **Rep / story** | **Hybrid.** **Faction / world reputation** stays **character-wide** where it fits (one person, one web of grudges). **Narrative** also includes **gig storylines** and **main-quest-style arcs** tied to a **gig**—mentor paths, employer chains, identity stories that assume you *are* that role for a chapter. State for those arcs is **per gig** (or per gig branch) on the same character; switching gigs does not erase character rep, but **gig plot progress** is its own track. | +| **Alts / multi-gig mastery** | One avatar still reduces **alt** pressure for economy and story. **Maining every gig** is **not** a design problem for now: **gig leveling is intentionally slow**, so fully progressing (or “maxing”) every gig is a **long-term time investment**, not something handed out quickly. Players who put in that time **may** legitimately be strong in every gig on one character. **Revisit** only if pacing, live balance, or PvP show harm. | + +## Player-facing readability + +- **Combat:** UI shows **main gig**, **sub-gig**, levels/tracks, combat abilities, and **combat gear** the main gig can use (mismatched gear disabled or greyed). **Deployables** (**Rigging**-built, etc.): show whether this gig may **combat-deploy** the item even if you **crafted** it with skills. Consumable tooltips for **passive** amps can show **baseline vs. boosted** when **main or sub** matches the item’s gig hook. +- **Cybernetics vs external armor:** **Hardshell**, **Softshell**, and **Rigging**-built powered pieces show on the **combat loadout** strip when equipped (swap-friendly, **gig-matched**). **Cybernetics** shows as **character** chrome—always relevant, **not** gig-disabled—**separate** UI lane ([Seams](#seams-gigs-skills) **Cybernetics / implants**). +- **Non-combat / crafting:** **skill** list, **category** filters, XP with **source** hints where helpful; **mastery** branches when E2.M3-style systems exist. Crafting combat-facing **Make** uses **skill**/recipe gates only—not gigs (optional hint if you can’t **equip** or **combat-deploy** the product on your current gig). **Rigging** civ gear: tooltip **intended skill** for **full** operation when the item has a specialty; **utility** pieces (e.g. **backpacks**) may show **no** skill **use** gate. +- **Story:** journal or quest UI can separate **character / faction** threads from **gig** threads so players see which arc belongs to which gig. +- Use **gig** / **skill** consistently in specs and tools; flavor text can vary. + + + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Vocabulary | **Gig** = combat role; **skill** = non-combat only | Agreed | +| Combat gear | **Gig-restricted** **equip** / **wear** / **combat deploy** / **activation**; includes **Rigging** **combat deployables**; non-combat tools **skill**-gated | Agreed | +| **Make** non-consumables + combat | **Default** **gig-gated** in combat; **craft** **skill**-only—**vast majority** of **Make** non-consumables | Agreed | +| **Rigging** deployables | **Anyone** with skill can **craft**; **combat deploy** **gig**-matched (e.g. drone gig kit) | Agreed | +| **Rigging** non-combat **use** | **Use** / **full benefit** gated by **intended specialty skill** when item defines one; **no** skill hook for general **utility** (e.g. **backpacks**) | Agreed | +| Cybernetics / implants | **Semi-permanent** augments—**character-wide**, **not gig-gated**; **replacement** costs and **likely** turns old unit into **scrap** / salvage feedstock | Agreed | +| **Hardshell** / **Softshell** / **Rigging** vs **Cybernetics** | **External** armor (**Hardshell**, **Softshell**, **Rigging** powered shells) = **swappable** **combat gear**, gig-restricted; **Cybernetics** = **body-integrated** implants—**no** overlap | Agreed | +| **Armor split + powered** | **Hardshell** = rigid; **Softshell** = flexible; **powered / systems** armor **Make** = **Rigging (gear)** | Agreed | +| Crafting combat gear | **Skill**/recipe/rep (etc.) only—**not** gig or gig level; craft-for-others OK | Agreed | +| Consumables | Baseline for all; **passive gig amp** from **main or sub** ([gigs.md](gigs.md)) | Agreed | +| Rep / story | Character-wide **rep**; **gig**-scoped **storylines** and **main quests** (per-gig progress on one avatar) | Agreed | +| Multi-gig mastery | **OK for now**; slow gig leveling makes “all gigs” a **time** goal, not a loophole | Agreed (revisit if balance/PvP needs) | +| Combat vs. non-combat | **Gigs** for combat; **skills** for gather/craft/etc. | Agreed | +| Professions (economy) | No separate profession system; economy identity from **skills** + rep | Agreed ([overview](overview.md)) | +| Primary skill XP | Do the activity | Agreed | +| **Late-stage tuning** | **Failure XP**, **skill mastery respec**, **cross-skill synergy** formulas—**not** decided at vision stage; **open** until the **system** (skills, gigs, economy, combat) is understood; **fine-tuning** pass | Open (deferred) | +| Skill caps | **Soft**; **progressively more XP** per level (data-driven curves) | Agreed | +| Gig swap rules | **Hub-only** (city / home base / designated site)—**not** in the field or mid-fight | Agreed | +| Sub-gig | **FFXI-style** slot **agreed**; sub abilities up to **~½ main gig level** (formula TBD); wide build space | Agreed | +| Combat progression | **Per gig**—separate level/XP (and mastery) per gig; no shared combat rank | Agreed | +| Social skills category | **No** dedicated **Social** skill family or tracked negotiation/fixer/fence skills—outcomes live in **rep**, **quests**, **economy**, and other systems if we need them | Agreed | +| **Refine** vs **Synth-chem prep** | **Refine** = physical materials (ore, glass, steel, scrap metals → usable grades); **Synth-chem prep** = bio/chem streams (precursors, reagents, lab-oriented outputs) | Agreed | +| **Refine** vs **Fab tech** | **Refine** = smelt/purify/grade **base** materials; **Fab tech** = fabricate **chips, PCBs, solenoids**, and similar **components**—may **consume** refined materials, does not **overlap** the refine loop | Agreed | +| **Fab tech** vs **Data scrub** | **Fab tech** = **physical** fab; **Data scrub** = **abstract** data—datasets, **firmware wipes**, logical reuse of salvaged parts—not the same skill fantasy | Agreed | +| **Tech** category roster | **Solid** for v0 (table under **Tech** in [Skill roster](#skill-roster-draft-ideas-by-category)); **skill** vs **gig kit** split as documented; per-row **open** notes stay until implementation | Agreed | +| Low-gig specialist | **Viable** to focus progression on **skills** (gather/craft/tech) with **low gig levels**; economy loops must not **hard-gate** on high gig rank | Agreed | +| Skill roster size | **Opening** v0 list is strong; **add skills** pre-launch as needed—**breadth** is a feature | Agreed | +| **Food synth** | **Make** skill **kept**—rations, street kitchens, food economy loops | Agreed | +| **Gunsmith** vs **Edgesmith** | **Gunsmith** = firearms / ballistics; **Edgesmith** = **non-gun** melee, thrown (non-ballistic), stun batons, monowire-style—same craft/equip **Seams** as other **combat gear** | Agreed | +| Gig XP award | **Main gig only**; **sub-gig** earns no XP—see [gigs.md](gigs.md) | Agreed | +| Mission reward skill XP | **Combat encounters** → **gig XP** only. **Skill XP** allowed when a **mission/contract** explicitly **rewards** it (hand-in, bonus)—**separate** payout from encounter **gig XP**, not “fighting levels a `SkillDef`” | Agreed | +| Epic 2 doc split | Align modules when gig data model is chosen | TBD | + +## Next artifacts + +- **[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.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). +- **[economy.md](economy.md)** — faucets/sinks, trade, **E3.M5**; mission vs loot ([progression.md](progression.md)) (written). +- **[death-loss-recovery.md](death-loss-recovery.md)** — death stakes, **E3.M4** / **E6.M3**, recovery (written). +- **[risk-security-bands.md](risk-security-bands.md)** — **E4.M4** tiers, **E6.M1**/**M2** PvP + consent (written). +- **[zones.md](zones.md)** — district **identity**, **E4.M1** graph, **hooks** for gather/missions (written). +- [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) — group **skill** (hack) + **gig** (bodyguard) instances (brainstorm). diff --git a/docs/game-design/zones.md b/docs/game-design/zones.md new file mode 100644 index 0000000..8f920ad --- /dev/null +++ b/docs/game-design/zones.md @@ -0,0 +1,74 @@ +# Zones (places & identity) + +Vision for **what a place is** in fiction and design: **tone**, **danger feel**, **faction** or **economic role**, and **content hooks**—paired with the **same** underlying **zone graph** as [risk-security-bands.md](risk-security-bands.md) (**security tiers**, **PvP** rules) but **not** duplicating **tier** or **eligibility** mechanics. + +**Topology & travel (runtime):** [E4.M1 — ZoneGraphAndTravelRules](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md) (`ZoneDef`, `ZoneEdge`, `TravelRule`)—**server-authoritative** **zone** **id** and **legal** **transitions** ([Epic 4 — Slice 1](../decomposition/epics/epic_04_world_topology.md#epic-4-slice-1)). **Travel** costs, **gates**, and **downtime** **fiction** → future **`travel.md`**; **TravelRule** already covers **gating** (level, quest, faction). + +**Ecology & density:** [E4.M2 — SpawnEcologyController](../decomposition/modules/E4_M2_SpawnEcologyController.md) drives **resource** and **NPC** **profiles** **per** **zone** ([gathering.md](gathering.md) **competition** **feel** ties here). + +**Handoffs:** [E4.M3 — SeamlessHandoffAndRegionState](../decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md) for **cross-region** **authority** (later scope). + +**Security overlay:** [E4.M4](../decomposition/modules/E4_M4_SecurityTierZoneFlags.md) attaches **`SecurityTier`** to **`ZoneDef`**—**one** **zone** **row** carries **both** **fiction** **tags** and **policy** **flags** in data (**open** how we split **design** **docs** vs **one** **`ZoneDef`** **sheet**). + +## Zone lenses (design-facing) + +Use these when briefing **writers**, **environment**, and **systems**; they **overlap** in data. + +| Lens | Questions | +|------|-----------| +| **Tone** | Noir, grime, hope, satire—how **hard** is life **here**? ([overview.md](overview.md) **presentation** band) | +| **Threat** | **Ambient** danger (mobs, cops, gangs) vs **opt-in** **combat**—distinct from **SecurityTier** **alone** | +| **Economy** | **Hub**, **industrial**, **black** **market**, **corporate** **enclave**—feeds **loot**, **vendors**, **gather** **node** **flavor** ([economy.md](economy.md)) | +| **Faction** | Who **owns** **the** **street**? **Rep** **gates**, **quests** ([skills.md](skills.md) **world** **gates**); detail → future **factions** doc | +| **Activity mix** | **PvE** **lanes**, **skill** **instances**, **social** **hubs**—what **players** **do** **here** | + +## Relationship to security tiers + +- **`SecurityTier`** answers **“what rules apply?”** ([risk-security-bands.md](risk-security-bands.md)). +- **Zone** **identity** answers **“what is this place **for** in the **fantasy**?”**—two **districts** can share a **tier** but **feel** **different** (**open** **content**). +- **TravelRule** can **reference** **rep**, **licenses**, **quests**—**fiction** **explains** **why** the **gate** **exists**. + +## Hubs, pockets, and edges + +Directional **shape** for **prototype** **districts** (names **TBD**—align with [Epic 4 — Slice 1](../decomposition/epics/epic_04_world_topology.md#epic-4-slice-1)): + +| Role | Intent | +|------|--------| +| **Hub** | **Services**, **vendors**, **social** **density**, **lower** **ambient** **PvE** **pressure** in **safe** **bands** | +| **Pocket** | **Focused** **PvE** or **skill** **content**—**instances** or **carved** **overworld** **chunks** | +| **Edge / frontier** | **Higher** **risk** **feel**, **richer** **gather** **or** **loot** **fantasy**, **clear** **warnings** on **entry** | + +## Module map (zone–fiction alignment) + +| Module | Role | Ties to this doc | +|--------|------|-------------------| +| [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md) | `ZoneDef`, edges, `TravelRule` | **Identity** **data** **home** | +| [E4.M4](../decomposition/modules/E4_M4_SecurityTierZoneFlags.md) | Tier, warnings | **Overlay** on **same** **zones** | +| [E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md) | Spawn **profiles** | **Feel** of **danger** / **resources** | +| [E4.M3](../decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md) | Region **handoff** | **Scale** **up** **later** | +| [E7.M4](../decomposition/modules/E7_M4_ContractMissionGenerator.md) | Contract **gen** | **Zone**-tagged **missions** (per E4.M1 **dependents**) | + +## Decisions log + +| Topic | Direction | Status | +|-------|-----------|--------| +| Fiction vs policy | **Same** **zone** **graph**; **tier** **is** **not** the **only** **identity** **axis** | Agreed | +| Server zone truth | **Current** **zone** **id** **authoritative**—no **client** **shortcuts** | Agreed ([E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md)) | +| Presentation band | **Grim** **ideas**, **restrained** **depiction**—[overview.md](overview.md) | Agreed | + +## Open questions + +- **Naming** **convention** for **player-facing** **district** **labels** vs **internal** **`ZoneDef` ids**. +- **Verticality** **and** **interiors** as **sub-zones** vs **one** **flat** **graph** **node**. +- **Dynamic** **zones** (lockdown, **riot**, **player** **corp** **capture**) vs **static** **data** **only**. + +## Where to read next + +| Topic | Document / module | +|--------|-------------------| +| Security tiers, PvP, warnings | [risk-security-bands.md](risk-security-bands.md) | +| Gather contest, nodes | [gathering.md](gathering.md) | +| Death / loss by context | [death-loss-recovery.md](death-loss-recovery.md) | +| Economy, trade hubs | [economy.md](economy.md) | +| Epic 4 overview | [Epic 4](../decomposition/epics/epic_04_world_topology.md) | +| Travel detail (stub) | [overview.md](overview.md) planned **Travel & connections** | diff --git a/docs/plans/internal-content-authoring.md b/docs/plans/internal-content-authoring.md index 5843f67..80dbb8f 100644 --- a/docs/plans/internal-content-authoring.md +++ b/docs/plans/internal-content-authoring.md @@ -54,10 +54,13 @@ Neon Sprawl is **data-driven** for skills, items, recipes, quests, and (eventual ## Phased roadmap (suggested) + + ### Phase 0 — Contracts and validation spine - Publish minimal **JSON Schemas** for `ItemDef`, `RecipeDef`, `QuestDef`, and zone graph payloads; align **one** canonical schema location with [contracts.md](../decomposition/modules/contracts.md) (`contracts/schemas/content/` vs co-located — pick once). - Wire **CI** so `content/**/*.json` cannot merge invalid (Node `ajv` / CLI or `dotnet` validator). +- **Done (partial):** `SkillDef` + `content/skills/*.json` — validated in **PR gate** via [`scripts/validate_content.py`](../../scripts/validate_content.py) + [`scripts/requirements-content.txt`](../../scripts/requirements-content.txt); see [CT.M1 — ContentValidationPipeline](../decomposition/modules/CT_M1_ContentValidationPipeline.md#ci-prototype). - Optional: **dotnet** test that **loads** all content (catches deserialization drift). ### Phase 1 — “Content Studio” MVP diff --git a/docs/reviews/2026-03-31-game-design-skills-coherence.md b/docs/reviews/2026-03-31-game-design-skills-coherence.md new file mode 100644 index 0000000..d2316a1 --- /dev/null +++ b/docs/reviews/2026-03-31-game-design-skills-coherence.md @@ -0,0 +1,60 @@ +# Game design docs coherence review — skills + links + +**Date:** 2026-03-31 +**Scope:** `docs/game-design/skills.md` and connected game-design + decomposition references (no PR diff; full-document pass). +**Base:** `docs/game-design/` vision set as of this date. + +## Verdict + +**Approve for vision / pre-implementation guidance** — the hybrid **gig + skill** model, **Seams**, and **v0 skill roster** are internally coherent and usable to steer E2/E3/E5 work. **Epic 2** **Slice 1** (non-combat `SkillDef` trio) and **Slice 3** (encounters → **gig XP**, gather/craft → **skill** XP, **mission rewards** may grant **skill** XP) are aligned with game-design. + +## Summary + +`skills.md` is the strongest single artifact: clear **vocabulary**, **domains vs categories**, **roster tables**, **production chains**, **Seams** (combat gear, cybernetics, crafting, deployables, utility Rigging), **decisions log**, and **deferred late-stage tuning** (failure XP, respec, synergy). Linked docs (`progression.md`, `overview.md`, `gigs.md`, `README.md`) and **Epic 2** slices **1** and **3** align with **skills = non-combat**, **combat encounters = gig XP only** (mission **reward** skill XP stays a **separate** payout). + +Remaining gaps are **expected** for vision docs: stable skill IDs, per-recipe data tags, and **gig ↔ item** deploy matrices are not yet specified — call those out for implementation plans rather than blocking the design read-through. + +## Documentation checked + +| Path | Match vs skills.md / hybrid model | +|------|-----------------------------------| +| `docs/game-design/skills.md` | **N/A** (source reviewed) | +| `docs/game-design/progression.md` | **Matches** after **Medtech fab** naming alignment | +| `docs/game-design/overview.md` | **Matches** — index, rating vision, artifact table | +| `docs/game-design/gigs.md` | **Matches** — sub-gig **Combat gear** bullet now links to `skills.md` **Seams** | +| `docs/game-design/README.md` | **Matches** | +| `docs/decomposition/epics/epic_02_skills_and_progression.md` | **Matches** — **Slice 3**: gather/craft → E2.M2 **skill** XP; **encounters** → **gig** XP; **mission rewards** may grant **skill** XP (no combat `SkillDef` from encounters) | +| `docs/decomposition/epics/epic_03_crafting_economy.md` | **Not re-read in full** — `skills.md` “Where skills meet” cites E3; no contradiction spotted from skills side | +| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | **Matches** — schema + `allowedXpSourceKinds`, categories `gather`/`process`/`make`/`tech`, Slice 1 acceptance criteria | + +## Blocking issues + +None for **using the docs as design guidance**. (No incorrect security or authority claims found.) + +## Suggestions + +1. ~~**gigs.md — Combat gear:**~~ **Done** — sub-gig section links to `skills.md#seams-gigs-skills`. +2. ~~**epic_02 — Slice 3:**~~ **Done** — **encounters** → **gig XP only**; gather/craft → E2.M2 **skill** XP; **mission rewards** may grant **skill** XP explicitly (`progression.md`, `epic_02` Slice 3). +3. ~~**overview.md artifact table:**~~ **Done** — `skills.md` row notes **Hardshell** / **Softshell** / **Edgesmith** / **Rigging** equip vs combat-deploy + link to **Seams**. +4. ~~**Stable IDs + XP sources:**~~ **Done** — [`content/schemas/skill-def.schema.json`](../../content/schemas/skill-def.schema.json), [`content/skills/prototype_skills.json`](../../content/skills/prototype_skills.json), [E2.M1](../decomposition/modules/E2_M1_SkillDefinitionRegistry.md) + [E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md); [`skills.md`](../game-design/skills.md) links. + +## Nits + +- ~~**Categories table (Tech):**~~ **Addressed** — row now includes exploit dev and crypto & identity. +- ~~**Anchor fragility:**~~ **Addressed** — `skills.md` uses explicit `` for **Skill roster**, **Open questions (skills-only)**, and **Decisions log** (same pattern as **Seams**). + +## Verification + +- Manually re-follow links from `skills.md` intro → `progression.md`, `gigs.md`, `overview.md`, `brainstorm/hack-bodyguard-missions.md`, E2/E3/E7 epics. +- After gig data model work: grep `docs/decomposition` for “combat skill” / “class” and align with hybrid vocabulary. + +## Follow-up (applied in this review pass) + +- `progression.md`: **medic fab** → **Medtech fab** (consistent with roster). +- `epic_02_skills_and_progression.md` **Slice 1** scope: **non-combat** trio aligned with `skills.md` / gigs hybrid (see commit). +- `skills.md`: **Tech** category row aligned with full Tech roster (exploit dev, crypto & identity). +- `gigs.md`: sub-gig **Combat gear** → link to `skills.md` **Seams**. +- `AGENTS.md`: **Docs review** agent row → `.cursor/rules/docs-review-agent.md`. +- **Combat XP rule:** `progression.md` + `epic_02` **Slice 3** — **encounters** → **gig XP only** (no combat `SkillDef`); **mission reward** skill XP is **separate**. +- `overview.md`: artifact table **skills.md** row — **Hardshell** / **Softshell** / **Edgesmith** / **Rigging** + **Seams** link. +- **SkillDef schema:** `content/schemas/skill-def.schema.json` + `prototype_skills.json`; E2.M1 / E2.M2 docs for **IDs** and **`allowedXpSourceKinds`**. diff --git a/docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md b/docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md new file mode 100644 index 0000000..b93ddc6 --- /dev/null +++ b/docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md @@ -0,0 +1,69 @@ +# Branch review — `chore/game-design-docs` vs `main` + +**Date:** 2026-04-03 +**Scope:** Full documentation and content-contract pass over all paths changed relative to `main` (`git diff main...HEAD`). Includes game-design vision set, decomposition updates (Epic 2 / E2.M1 / E2.M2), `content/` schema + prototype catalog, Cursor rules, and `AGENTS.md`. +**Base:** `main` at merge-base with this branch; branch tip includes prior commits on `chore/game-design-docs` plus coherence follow-ups. + +## Verdict + +**Approve with suggestions addressed in-repo for one epic line** — The branch delivers a **coherent hybrid progression story** (gigs + skills, Seams, gig XP vs skill XP, mission reward carve-out) and wires it into **Epic 2** slices and **SkillDef** JSON Schema. **Non-doc** changes (`.vscode/` launch/tasks) are fine but **out of scope** for design coherence; no conflict with docs. + +## Summary + +Compared to `main`, this branch adds the **`docs/game-design/`** corpus (`overview`, `progression`, `skills`, `gigs`, `README`, `brainstorm/`), extends **Epic 2** and **E2.M1/E2.M2** to match that vision, introduces **`content/schemas/skill-def.schema.json`** with **`allowedXpSourceKinds`**, replaces prototype skills with three **non-combat** rows, and adds the **docs review** agent plus an earlier coherence review file. Cross-links between game-design and decomposition are generally consistent. One **stale sentence** in **Epic 2 Objective** implied combat fed the same **skill-XP** pipeline as gather/craft; that line is **updated** during this review to match **`progression.md`** / **Slice 3**. + +## Documentation checked + +| Path | Role vs `main` | Match / notes | +|------|------------------|---------------| +| `docs/game-design/overview.md` | New | **Matches** hybrid index; artifact table + **Seams** pointer for `skills.md` | +| `docs/game-design/progression.md` | New | **Matches** vocabulary, mission vs encounter XP, implementation note | +| `docs/game-design/skills.md` | New | **Matches** roster, Seams, decisions log; explicit **`id`** anchors for fragile fragments | +| `docs/game-design/gigs.md` | New | **Matches** gig XP rules, link to **Seams**, combat vs skill boundary | +| `docs/game-design/README.md` | New | **Matches** entry to `overview` / `progression` / brainstorm | +| `docs/game-design/brainstorm/*` | New | **Matches** “ideas only”; links to `skills.md` resolve | +| `docs/decomposition/epics/epic_02_skills_and_progression.md` | Updated | **Matches** after **Objective** paragraph fix (hybrid model explicit); Slice 1/3/DoD align | +| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | Updated | **Matches** schema paths, categories, acceptance criteria | +| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | Updated | **Matches** `sourceKind` validation, gig vs skill callers | +| `content/schemas/skill-def.schema.json` | Updated | **Matches** game-design categories (`gather`/`process`/`make`/`tech`); no combat `SkillDef` | +| `content/skills/prototype_skills.json` | Updated | **Matches** Slice 1 non-combat trio + `allowedXpSourceKinds` | +| `content/README.md` | Updated | **Matches** pointers to schema + E2 docs | +| `.cursor/rules/docs-review-agent.md` | New | **Matches** repo conventions; `globs: docs/**/*` | +| `AGENTS.md` | Updated | **Matches** Docs review row | +| `docs/reviews/2026-03-31-game-design-skills-coherence.md` | New | Prior focused review; still consistent with branch after later edits | +| `docs/decomposition/epics/epic_03_crafting_economy.md` | Unchanged | **Spot-check:** gather/craft → skill XP via E2.M2 — **no contradiction** | +| `docs/decomposition/modules/client_server_authority.md` | Unchanged | **Nit:** combat path still says “`SkillDef`” in one line — likely **ability/stats** semantics, not non-combat skill catalog; clarify when combat data model is written | +| `neon_sprawl_vision.plan.md` | Updated later | Epic 2 / pillars align with **gigs + skills** hybrid (see current plan text) | +| `.vscode/launch.json`, `.vscode/tasks.json` | New | **N/A** (editor config, not design docs) | + +## Blocking issues + +None for **using the branch as design + schema guidance**. + +## Suggestions + +1. ~~**Epic 2 Objective** — “gathering, crafting, and combat all feed one coherent progression model.”~~ **Fixed in this review** — now states **skill** vs **gig** split and mission **skill** rewards. +2. ~~**E2.M1 “Module Breakdown” stub**~~ **Done** — `epic_02` **E2.M1** block matches long-form module + schema links. +3. ~~**CT.M1 / CI:**~~ **Done** — PR gate runs [`scripts/validate_content.py`](../../scripts/validate_content.py) for `content/skills/*.json` vs `skill-def.schema.json`; docs updated ([CT.M1](../decomposition/modules/CT_M1_ContentValidationPipeline.md#ci-prototype), [`internal-content-authoring` Phase 0](../plans/internal-content-authoring.md#phase-0-contracts-validation)). +4. ~~**Decomposition grep:**~~ **Done** — automated via [`scripts/check_decomposition_language.py`](../../scripts/check_decomposition_language.py) in **PR gate**; see [CT.M1 — CI (prototype)](../decomposition/modules/CT_M1_ContentValidationPipeline.md#ci-prototype). + +## Nits + +- ~~**Epic title vs filename:**~~ **Addressed** — epic file is **`epic_02_skills_and_progression.md`** with H1 **Skills and Progression Framework**; cross-links match. +- ~~**`module_dependency_register.md`:** E2.M1 **Contract Needed**~~ **Addressed** — includes **`allowedXpSourceKinds`**. +- **Two review files:** `2026-03-31-…` vs this `2026-04-03-…` — keep both; this one is **branch-wide vs main**, the other is **skills-focused**. + +## Verification + +- `git diff main...HEAD --stat` — 18 paths (docs + content + Cursor + VS Code + AGENTS). +- Re-follow `overview` → `progression` / `skills` / `gigs` / decomposition links. +- Validate sample data: `python3 -c "… jsonschema …"` against `skill-def.schema.json` (optional local check). + +## Follow-up (applied during this review pass) + +- `epic_02_skills_and_progression.md` **Objective**: hybrid **skill** vs **gig** wording + links to `progression.md` and E2.M2. +- `epic_02_skills_and_progression.md` **E2.M1** module stub: non-combat **`SkillDef`**, categories, **`allowedXpSourceKinds`**, links to E2.M1 module + JSON Schema. +- **Content CI:** `.github/workflows/pr-gate.yml` + `scripts/validate_content.py` + `scripts/requirements-content.txt`; CT.M1 / E2.M1 / `content/README` / internal-content-authoring updates. +- **Decomposition language CI:** `scripts/check_decomposition_language.py` + PR gate + CT.M1 / docs-review-agent notes. +- **Epic 2 naming:** Renamed epic doc + **Skills and Progression Framework** (dropped misleading “classless” now that **gigs** are combat roles). +- **module_dependency_register:** E2.M1 **Contract Needed** lists **`allowedXpSourceKinds`**. diff --git a/docs/reviews/2026-04-03-final-branch-docs-review.md b/docs/reviews/2026-04-03-final-branch-docs-review.md new file mode 100644 index 0000000..84b5994 --- /dev/null +++ b/docs/reviews/2026-04-03-final-branch-docs-review.md @@ -0,0 +1,64 @@ +# Final branch documentation review + +**Date:** 2026-04-03 +**Scope:** Full doc + content contract pass for branch **`chore/game-design-docs`** vs **`main`** (game-design vision set, Epic 2 rename and module updates, `content/` skill schema + CI, `docs-review-agent`, PR gate, root README, `.vscode` debug/tasks). +**Base:** `main` (diff as of review); HEAD sample `0dea48e` on `chore/game-design-docs` (verify at merge time). + +## Verdict + +**Approve with suggestions** — Vision and decomposition align on the hybrid **gig vs non-combat skill** model; `SkillDef` schema, prototype catalog, and CI checks are consistent with **E2.M1** / **E2.M2** module text. The **E2.M2** bullet **Note** in **`epic_02_skills_and_progression.md`** was corrected during this review so it no longer implies **E5.M1** calls **E2.M2**. + +## Summary + +The branch tightens the **skills** track around **`allowedXpSourceKinds`**, four **`SkillCategory`** values, and explicit rejection of **combat encounter → skill XP**. Game-design docs (`progression`, `gathering`, `crafting`, `abilities`, `gigs`, `skills`) and **`epic_02_skills_and_progression.md`** agree with **E2.M1** / **E2.M2**. **`zones.md`** and cross-links sit correctly beside **`risk-security-bands.md`** on the **E4.M1** graph. **`scripts/validate_content.py`** and **`scripts/check_decomposition_language.py`** both pass locally. **`neon_sprawl_vision.plan.md`** **E2.M2** **grant channel policy** was added after this review (**53fb1d6**). + +## Documentation checked + +| Path | Result | Notes | +|------|--------|--------| +| `docs/game-design/overview.md` | **Matches** | Artifact index + planned topics coherent; combat stub points to Epic 5 / abilities / items | +| `docs/game-design/progression.md` | **Matches** | Epic 2 Slice 3 = gather/craft → skill XP, combat → gig XP, mission rewards explicit | +| `docs/game-design/skills.md` | **Matches** | Seams anchor `#seams-gigs-skills` present; categories align with schema enum | +| `docs/game-design/gigs.md` | **Matches** | Epic 2 / Epic 5 anchors; PvP open indefinite called out | +| `docs/game-design/gathering.md`, `crafting.md`, `abilities.md` | **Matches** | Epic 2 links use `epic_02_skills_and_progression.md` | +| `docs/game-design/zones.md` | **Matches** | Same graph as tiers; E4.M1 / E7.M4 map | +| `docs/game-design/risk-security-bands.md` | **Matches** | Points to `zones.md` for place fiction | +| `docs/decomposition/epics/epic_02_skills_and_progression.md` | **Matches** | Objective + Slice 1/3/DoD correct; **E2.M2** **Note** updated: E3 callers vs E5 gig path (same session as this review) | +| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | **Matches** | Schema table, `allowedXpSourceKinds`, CI pointer | +| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | **Matches** | `sourceKind` validation; E5.M1 → gig XP | +| `docs/decomposition/modules/E2_M3_*.md`, `E2_M4_*.md` | **Matches** | Epic link updated | +| `docs/decomposition/README.md` | **Matches** | Epic 2 row → new filename | +| `docs/decomposition/modules/CT_M1_ContentValidationPipeline.md` | **Matches** | PR gate + scripts described | +| `neon_sprawl_vision.plan.md` | **Matches** | Epic 2 title, E2.M1, E2.M2 **grant channel policy** bullet (**53fb1d6**) | +| `content/schemas/skill-def.schema.json` | **Matches** | Required fields + enum align with **E2.M1** | +| `content/skills/prototype_skills.json` | **Matches** | Three rows, distinct categories | +| `content/README.md` | **Matches** | Local validate instructions | +| `.cursor/rules/docs-review-agent.md` | **Matches** | Hybrid ground truth includes `zones.md` | +| `AGENTS.md` | **Matches** | Docs review agent row | +| `README.md` (root) | **Matches** | Gigs + skills one-liner | +| `.github/workflows/pr-gate.yml` | **N/A** (workflow) | Validates content + decomposition language | +| `.vscode/launch.json`, `tasks.json` | **N/A** | Launch targets `server/NeonSprawl.Server.Tests` + `NeonSprawl.sln` at repo root — paths exist | + +## Blocking issues + +None for **merge** from a **documentation correctness** standpoint. + +## Suggestions + +1. ~~**`neon_sprawl_vision.plan.md`** — Optional one-line under **E2.M2**: reject **XP** grants whose **`sourceKind`** is not in the target skill’s **`allowedXpSourceKinds`** (mirrors module + schema descriptions).~~ **Done** (**53fb1d6**): **Grant channel policy** bullet under **E2.M2**. + +## Nits + +- **`docs/reviews/2026-04-03-game-design-branch-docs-review.md`** verification bullet still mentions grepping **`epic_02_classless_progression`**; repo docs no longer use that path (harmless historical note). +- **`.vscode/launch.json`** retains default .NET template comments — fine for a first drop; team may want a Neon Sprawl–specific label later. + +## Verification + +```bash +pip install -r scripts/requirements-content.txt +python scripts/validate_content.py +python scripts/check_decomposition_language.py +rg 'epic_02_classless_progression' docs/ content/ --glob '*.md' +``` + +Expect **no** hits under `docs/` (except optional old **reviews** text). Spot-check **GitHub** rendering for `docs/game-design/overview.md` and `epic_02_skills_and_progression.md` links after merge. diff --git a/docs/reviews/2026-04-03-game-design-branch-docs-review.md b/docs/reviews/2026-04-03-game-design-branch-docs-review.md new file mode 100644 index 0000000..2adf993 --- /dev/null +++ b/docs/reviews/2026-04-03-game-design-branch-docs-review.md @@ -0,0 +1,61 @@ +# Docs review — game-design branch (`chore/game-design-docs` vs `main`) + +**Date:** 2026-04-03 +**Scope:** Documentation and content-contract coherence for paths changed on the branch relative to `main`: `docs/game-design/**`, linked `docs/decomposition/**` updates, `content/schemas` + prototype skills, `.cursor/rules/docs-review-agent.md`, `AGENTS.md`, PR gate scripts, and related cross-links. **Out of scope for verdict:** `.vscode/launch.json` and `.vscode/tasks.json` (editor convenience; no doc contradiction). +**Base:** `main` (review reflects branch state as of this file). +**Follow-up:** Suggestions in **Suggestions** below were implemented in commit `6b9f4e8` (same day). + +## Verdict + +**Approve** — Hybrid **gig vs non-combat skill** vocabulary is consistent across vision docs, **Epic 2** / **E2.M1** / **E2.M2**, and **CI** (`validate_content.py`, `check_decomposition_language.py` both **OK** locally). No blocking factual errors found in sampled cross-links. Prior **polish** suggestions (overview placeholder row, `skills.md` next-pass, `abilities.md` framing) are **done** — see strikethrough list below. + +## Summary + +The branch ships a **complete spine** for progression design: `progression.md`, `gigs.md`, `skills.md` (Seams), `abilities.md`, `items.md`, `gathering.md`, `crafting.md`, plus `overview.md` index and combat-pillars stub. Decomposition renames **Epic 2** to **Skills and Progression Framework** and aligns **Slice 1** / **Slice 3** with **no combat `SkillDef` XP** from encounters. **Content** enforces **`allowedXpSourceKinds`** and **category** enum (`gather` / `process` / `make` / `tech`) consistent with `skills.md`. The **docs-review-agent** ground truth correctly lists the new vision artifacts. + +## Documentation checked + +| Path | Assessment | +|------|------------| +| `docs/game-design/overview.md` | **Matches** — index, combat pillars stub, links to all core artifacts. ~~Placeholder artifact row~~ **Removed** in follow-up (`6b9f4e8`). | +| `docs/game-design/progression.md` | **Matches** — vocabulary, Epic 2 Slice 3 note, where-to-read includes items / gathering / crafting. | +| `docs/game-design/skills.md` | **Matches** — roster, production chains, Seams, decisions log, links to Epic 2/3/7 and content schema. ~~“Next pass” without gather/craft anchors~~ **Updated** — now cites `gathering.md`, `crafting.md`, E2.M1 (`6b9f4e8`). | +| `docs/game-design/gigs.md` | **Matches** — roster, hub/sub-gig, XP rules, next-artifact links. | +| `docs/game-design/abilities.md` | **Matches** — gig kit vs skill interaction vs item channel; Epic 2 Slice 3 cite. **N/A** for full combat pillar doc (still stubbed in overview). ~~Framing without gather/craft spine~~ **Updated** — `gathering.md` / `crafting.md` in framing (`6b9f4e8`). | +| `docs/game-design/items.md` | **Matches** — buckets, Seams, Epic 3 module map, open questions, cross-links to gathering/crafting. | +| `docs/game-design/gathering.md` | **Matches** — E3.M1/E4.M2/E2.M2 hooks, skill-not-gig XP, pipeline handoff to `crafting.md`. | +| `docs/game-design/crafting.md` | **Matches** — E3.M2 contracts, bench vs gig, module map including E7.M1 / E6.M4. | +| `docs/game-design/README.md` | **Matches** — pointers to overview + progression + new artifacts. | +| `docs/game-design/brainstorm/*` | **Matches** — relative links to parent `skills.md` / `gigs.md` / `overview.md` resolve. | +| `docs/decomposition/epics/epic_02_skills_and_progression.md` | **Matches** — objective and slices align with `progression.md` (gather/craft → skill XP; combat → gig XP; mission skill rewards explicit). | +| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | **Matches** — schema + `allowedXpSourceKinds` table aligns with `content/schemas/skill-def.schema.json`. | +| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | **Matches** — rejects skill grants outside allowed sources; combat → gig XP. | +| `docs/decomposition/README.md` | **Matches** — Epic 2 filename updated. | +| `docs/decomposition/modules/module_dependency_register.md` | **Matches** — Epic 2 heading + E2.M1 contract row. | +| `docs/decomposition/modules/CT_M1_ContentValidationPipeline.md` | **Matches** — documents PR gate validation. | +| `content/README.md` + `skill-def.schema.json` + `prototype_skills.json` | **Matches** — categories and XP source kinds align with game-design and E2.M1. | +| `.cursor/rules/docs-review-agent.md` | **Matches** — hybrid ground truth includes `gathering.md` and `crafting.md`. | +| `AGENTS.md` | **Matches** — docs-review agent row present. | +| `README.md` (repo root) | **Matches** — gigs + skills product line; consistent with hybrid docs. | +| `neon_sprawl_vision.plan.md` | **Matches** (spot-check via grep) — Epic 2 naming consistent with branch. | + +## Blocking issues + +None identified. + +## Suggestions + +1. ~~**`docs/game-design/overview.md`** — Remove or shrink the `*(add rows as files land)*` artifact row once you treat the core economy/combat vision set as “indexed.”~~ **Done** — placeholder row removed (`6b9f4e8`). +2. ~~**`docs/game-design/skills.md`** — Under **Cross-cutting notes**, refresh **Next pass** to reference **`gathering.md`** and **`crafting.md`** as the written anchors for the gather/craft legs of the prototype trio (still **TBD** which three `SkillDef` ids ship first in data).~~ **Done** — next-pass bullet cites `gathering.md`, `crafting.md`, and E2.M1 slice freeze (`6b9f4e8`). +3. ~~**`docs/game-design/abilities.md`** (optional) — In the opening **Framing** paragraph, add one line pointing to **`gathering.md`** / **`crafting.md`** so combat-adjacent readers find the economy spine without going through `items.md` only.~~ **Done** — **Gather → craft economy spine** line in framing (`6b9f4e8`). + +## Nits + +- ~~Epic 3 slice references in `gathering.md` / `crafting.md` use *italic* slice titles next to the epic link rather than `#` anchors—**intentionally robust** vs GitHub slug drift; keep as-is unless you add explicit HTML ids in the epic doc.~~ **Done** — `epic_03_crafting_economy.md` now has `` / ``; `gathering.md` / `crafting.md` deep-link with stable anchors. +- `skills.md` **Next artifacts** lists **gigs** first — **intentional** (folder reading order); no change. + +## Verification + +- Re-run locally: `pip install -r scripts/requirements-content.txt && python scripts/validate_content.py && python scripts/check_decomposition_language.py` +- If **`pip install`** fails with **PEP 668** (externally managed environment), use a venv (e.g. `python3 -m venv .venv-content`, then `.venv-content/bin/pip install -r scripts/requirements-content.txt` — `.venv-content/` is gitignored) or rely on the **PR gate** workflow for the same checks. +- Before merge: grep for **`epic_02_classless_progression`** (should be **zero**); quick click-test of `docs/game-design/overview.md` links in the GitHub preview for the PR. diff --git a/neon_sprawl_vision.plan.md b/neon_sprawl_vision.plan.md index b3c718a..0a461a3 100644 --- a/neon_sprawl_vision.plan.md +++ b/neon_sprawl_vision.plan.md @@ -1,6 +1,6 @@ --- name: Neon Sprawl Vision -overview: Create a 50,000-foot planning document for Neon Sprawl, a sci-fi/cyberpunk MMORPG inspired by RuneScape, focused on classless progression and deep crafting, with optional PvP and questing. +overview: Create a 50,000-foot planning document for Neon Sprawl, a sci-fi/cyberpunk MMORPG inspired by RuneScape, focused on hybrid progression (combat **gigs** and open non-combat **skills**) and deep crafting, with optional PvP and questing. isProject: false --- @@ -17,7 +17,7 @@ isProject: false ### Experience Pillars -- **Classless mastery:** Every character can learn and level every skill over time; identity comes from choices, gear, economy role, and mastery paths. +- **Open skill training:** Every character can learn and level every **non-combat** **skill** over time; **combat** identity uses **gigs** (swappable roles). Identity also comes from choices, gear, economy role, and mastery paths. - **Crafting-first economy:** Crafting and gathering are central progression loops, not side systems; player-made goods should matter at every stage. - **Persistent social world:** Shared hubs, guilds/corps, trading, and cooperative activities should be core to retention. - **Meaningful progression:** Long-term goals, visible advancement, and layered progression loops (short, mid, long horizons). @@ -298,11 +298,11 @@ Transform the validated prototype into a scalable production-ready development m - **Scope:** Isometric camera runtime, character movement, interaction framework, input/ability scaffolding, moment-to-moment game feel. - **Success criteria:** Stable 3D isometric control loop feels responsive and readable across supported hardware tiers. -### Epic 2 - Classless Skill and Progression Framework +### Epic 2 - Skills and Progression Framework - **Ownership focus:** Systems Design + Gameplay Engineering -- **Scope:** Skill definitions, XP curves, unlock logic, mastery/perk unlocks, progression pacing controls. -- **Success criteria:** Any character can train all skills, and progression remains long-term without dead-end grinds. +- **Scope:** **Non-combat** `SkillDef` catalog, **skill** XP and level curves, unlock logic, mastery/perk unlocks, progression pacing controls. **Combat role** progression (**gigs**) is separate—see Epic 5 and game-design `gigs.md`. +- **Success criteria:** Any character can train all **non-combat** **skills** tracked as `SkillDef`, with long-term **skill** progression and no dead-end grinds; **gig** combat roles remain swappable combat identity. ### Epic 3 - Crafting, Gathering, and Itemization Economy @@ -385,20 +385,21 @@ Module template: - Dependencies: E1.M3, E5.M1. - Stage target: Prototype. -### Epic 2 Modules - Classless Skill and Progression +### Epic 2 Modules - Skills and Progression Framework - **E2.M1 SkillDefinitionRegistry** - - Responsibility: Central catalog for skill metadata, category tags, unlock prerequisites. + - Responsibility: Central catalog for **non-combat** `SkillDef` metadata, category tags, unlock prerequisites (and **`allowedXpSourceKinds`** in prototype schema). - Key contracts: `SkillDef`, `SkillCategory`, `UnlockRequirement`. - Dependencies: None. - Stage target: Prototype. - **E2.M2 XpAwardAndLevelEngine** - Responsibility: XP award rules, level thresholds, level-up event generation. + - Grant channel policy: Reject **`XpGrantEvent`** when **`sourceKind`** is not listed on the target **`SkillDef.allowedXpSourceKinds`** (E2.M1 catalog + [`content/schemas/skill-def.schema.json`](content/schemas/skill-def.schema.json)). - Key contracts: `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`. - Dependencies: E2.M1. - Stage target: Prototype. - **E2.M3 MasteryAndPerkUnlocks** - - Responsibility: Mastery tracks and perk unlock state for non-class build expression. + - Responsibility: Mastery tracks and perk unlock state for **skill** build expression beyond raw levels. - Key contracts: `MasteryTrack`, `PerkUnlockEvent`, `PerkState`. - Dependencies: E2.M2. - Stage target: Pre-production. @@ -644,7 +645,7 @@ flowchart TD ```mermaid flowchart TD - E1[CorePlayerRuntime] --> E2[ClasslessProgression] + E1[CorePlayerRuntime] --> E2[SkillsProgression] E1 --> E5[PvECombatEncounters] E4[WorldTopologyZones] --> E5 E4 --> E6[PvPSecurityZones] @@ -767,7 +768,7 @@ flowchart TD flowchart TD Vision[ProductVision] --> Pillars[ExperiencePillars] Pillars --> Systems[CoreSystems] - Systems --> Progression[ClasslessSkillProgression] + Systems --> Progression[SkillXpAndMastery] Systems --> Crafting[CraftingAndEconomy] Systems --> Questing[QuestAndFactionContent] Systems --> Combat[CombatAndEncounters] diff --git a/scripts/check_decomposition_language.py b/scripts/check_decomposition_language.py new file mode 100644 index 0000000..5a2f09c --- /dev/null +++ b/scripts/check_decomposition_language.py @@ -0,0 +1,75 @@ +#!/usr/bin/env python3 +"""Fail if decomposition docs regress hybrid vocabulary (gig vs non-combat skill). + +Catches phrases like "one combat skill" or bare "combat skill" that imply a combat +SkillDef. Allows "non-combat skill(s)" and "anti-combat …" when the hyphen prefix +is immediately before ``combat``. + +Run in CI (PR gate) and locally after editing ``docs/decomposition/**``. +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +DECOMP_ROOT = REPO_ROOT / "docs/decomposition" + +# Standalone phrases that almost always indicate a doc bug vs game-design hybrid model. +LITERAL_BANS = [ + "one combat skill", + "one combat skills", +] + +# Match "combat skill" / "combat skills" unless prefixed by "non-" or "anti-" (hyphenated). +COMBAT_SKILL = re.compile(r"\bcombat skills?\b", re.IGNORECASE) + + +def line_has_bad_combat_skill(line: str) -> bool: + for m in COMBAT_SKILL.finditer(line): + start = m.start() + if start >= 4 and line[start - 4 : start].lower() == "non-": + continue + if start >= 5 and line[start - 5 : start].lower() == "anti-": + continue + return True + return False + + +def check_file(path: Path) -> list[str]: + errors: list[str] = [] + text = path.read_text(encoding="utf-8") + lower = text.lower() + for banned in LITERAL_BANS: + if banned in lower: + errors.append(f"{path.relative_to(REPO_ROOT)}: contains forbidden phrase {banned!r}") + + for i, line in enumerate(text.splitlines(), start=1): + if line_has_bad_combat_skill(line): + errors.append(f"{path.relative_to(REPO_ROOT)}:{i}: suspicious 'combat skill' (use gig or 'non-combat skill'): {line.strip()[:200]}") + return errors + + +def main() -> int: + if not DECOMP_ROOT.is_dir(): + print(f"error: missing {DECOMP_ROOT}", file=sys.stderr) + return 1 + + all_errors: list[str] = [] + for path in sorted(DECOMP_ROOT.rglob("*.md")): + all_errors.extend(check_file(path)) + + if all_errors: + for msg in all_errors: + print(msg, file=sys.stderr) + print(f"decomposition language check failed ({len(all_errors)} issue(s))", file=sys.stderr) + return 1 + + print("decomposition language OK: hybrid vocabulary (no stray combat SkillDef phrasing)") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/requirements-content.txt b/scripts/requirements-content.txt new file mode 100644 index 0000000..0e4776b --- /dev/null +++ b/scripts/requirements-content.txt @@ -0,0 +1,2 @@ +# Used by scripts/validate_content.py and PR gate CI (SkillDef + future catalogs). +jsonschema>=4.22.0,<5 diff --git a/scripts/validate_content.py b/scripts/validate_content.py new file mode 100644 index 0000000..798f87a --- /dev/null +++ b/scripts/validate_content.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +"""Validate content catalogs against JSON Schema (CI + local). + +Today: each object in content/skills/*.json top-level ``skills`` array vs +content/schemas/skill-def.schema.json. Extend this script as new catalogs land. +""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path + +from jsonschema import Draft202012Validator + +REPO_ROOT = Path(__file__).resolve().parent.parent +SKILL_SCHEMA = REPO_ROOT / "content/schemas/skill-def.schema.json" +SKILLS_DIR = REPO_ROOT / "content/skills" + + +def main() -> int: + if not SKILL_SCHEMA.is_file(): + print(f"error: missing schema {SKILL_SCHEMA}", file=sys.stderr) + return 1 + + schema = json.loads(SKILL_SCHEMA.read_text(encoding="utf-8")) + validator = Draft202012Validator(schema) + + if not SKILLS_DIR.is_dir(): + print(f"error: missing directory {SKILLS_DIR}", file=sys.stderr) + return 1 + + json_files = sorted(SKILLS_DIR.glob("*.json")) + if not json_files: + print(f"error: no JSON files under {SKILLS_DIR}", file=sys.stderr) + return 1 + + seen_ids: dict[str, str] = {} + errors = 0 + + for path in json_files: + data = json.loads(path.read_text(encoding="utf-8")) + skills = data.get("skills") + if not isinstance(skills, list): + print(f"error: {path.relative_to(REPO_ROOT)}: expected top-level 'skills' array", file=sys.stderr) + errors += 1 + continue + for i, row in enumerate(skills): + if not isinstance(row, dict): + print(f"error: {path.relative_to(REPO_ROOT)}: skills[{i}] must be an object", file=sys.stderr) + errors += 1 + continue + for err in sorted(validator.iter_errors(row), key=lambda e: e.path): + loc = ".".join(str(p) for p in err.path) or "(root)" + print( + f"error: {path.relative_to(REPO_ROOT)} skills[{i}] {loc}: {err.message}", + file=sys.stderr, + ) + errors += 1 + sid = row.get("id") + if isinstance(sid, str): + prev = seen_ids.get(sid) + if prev: + print( + f"error: duplicate skill id {sid!r} in {prev} and {path.relative_to(REPO_ROOT)}", + file=sys.stderr, + ) + errors += 1 + else: + seen_ids[sid] = str(path.relative_to(REPO_ROOT)) + + if errors: + print(f"content validation failed with {errors} error(s)", file=sys.stderr) + return 1 + + print(f"content OK: {len(json_files)} skill catalog file(s), {len(seen_ids)} unique skill id(s)") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())