diff --git a/.cursor/rules/code-review-agent.md b/.cursor/rules/code-review-agent.md index c42b2eb..8380f32 100644 --- a/.cursor/rules/code-review-agent.md +++ b/.cursor/rules/code-review-agent.md @@ -25,7 +25,18 @@ Align recommendations with repo rules and docs, including: - [jira-git-naming](jira-git-naming.md) — branch/commit prefixes when the work is ticketed. - [git-workflow](git-workflow.md) — branch vs `main`, story-scoped plans. -If the change contradicts an adopted plan under `docs/plans/`, call that out. +### Plan and decomposition documentation (required to reference) + +For every review, **identify and cite** the documentation that defines intent for the change, then **check the implementation against it** (not only style and correctness). + +1. **Story / implementation plans** — If the work maps to a ticket or plan under `docs/plans/` (e.g. `NS-*-implementation-plan.md`), treat that document as acceptance criteria. If the diff diverges without an updated plan or an explicit “out of scope” note, call it out (blocking or non-blocking by severity). +2. **Module docs** — Map the change to one or more modules in [`docs/decomposition/modules/module_dependency_register.md`](../../docs/decomposition/modules/module_dependency_register.md) and the corresponding `docs/decomposition/modules/E*_*.md` pages. Verify behavior matches **Purpose**, **Responsibilities**, **Key contracts**, and **Authority** / linked policy sections where relevant. +3. **Cross-cutting policies** — When applicable, align with `docs/decomposition/modules/` policy docs (e.g. [`contracts.md`](../../docs/decomposition/modules/contracts.md), [`client_server_authority.md`](../../docs/decomposition/modules/client_server_authority.md), [`pvp_combat_integration.md`](../../docs/decomposition/modules/pvp_combat_integration.md), [`data_and_ops_policy.md`](../../docs/decomposition/modules/data_and_ops_policy.md)). +4. **Implementation status** — If the register or [`documentation_and_implementation_alignment.md`](../../docs/decomposition/modules/documentation_and_implementation_alignment.md) tracks the module, note whether **Status** / the implementation tracking table should be updated after this merge. + +In the **saved review document**, include a subsection **Documentation checked**: bullet list of paths consulted and whether the diff **matches**, **partially matches**, or **conflicts** with them. If no decomposition doc applies (e.g. pure tooling), state that explicitly. + +If the change contradicts an adopted plan under `docs/plans/` or documented module/policy intent without justification, treat that as at least a **should fix** (or **blocking** if it breaks contracts or authority). ## Review checklist @@ -38,6 +49,7 @@ Work through what applies to the diff (skip irrelevant sections briefly). 5. **Tests** — Happy path, failure modes, integration boundaries per [testing-expectations](testing-expectations.md); note gaps. 6. **Observability** — Logging/metrics where failures would be hard to diagnose (server/runtime code). 7. **Docs** — README or plan updates when behavior or run instructions change. +8. **Plan & decomposition alignment** — Per **Plan and decomposition documentation** above: relevant `docs/plans/` and module/policy docs cited; implementation checked against them; **Documentation checked** section in the saved review file. ## Code review document (required) @@ -60,10 +72,11 @@ Use this structure in **both** the saved document and (abbreviated if you want) 1. **Verdict** — One line: `Approve` / `Approve with nits` / `Request changes`. 2. **Summary** — 2–5 sentences on what the change does and overall risk. -3. **Blocking issues** — Numbered list; empty section if none. -4. **Suggestions** — Non-blocking improvements. -5. **Nits** — Optional; prefix with “Nit:”. -6. **Verification** — Commands or manual steps the author should run before merge (e.g. `dotnet test`, Godot scenario). +3. **Documentation checked** — Paths under `docs/plans/` and `docs/decomposition/modules/` (and related) consulted; **matches** / **partially matches** / **conflicts** / **N/A** per item; note if register/tracking table updates are needed. +4. **Blocking issues** — Numbered list; empty section if none. +5. **Suggestions** — Non-blocking improvements. +6. **Nits** — Optional; prefix with “Nit:”. +7. **Verification** — Commands or manual steps the author should run before merge (e.g. `dotnet test`, Godot scenario). In **chat only**, you may use Cursor line-number **code citations** when referencing existing code. For hypothetical fixes, use normal fenced code blocks everywhere. diff --git a/AGENTS.md b/AGENTS.md index 1838faf..9c5804d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,6 @@ 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` plus a short chat pointer | +| **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 | Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index bdc24c4..b91a7cb 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -85,7 +85,7 @@ The [`client/`](../../client/) Godot project targets **4.6** (`config/features` ## Observability - **Serilog** and/or **OpenTelemetry** for .NET from early prototype. -- Align event names with `E9.M1 TelemetryEventSchema` in the vision doc; client batches to server or OTLP endpoint as capacity allows. +- Align event names with `E9.M1 TelemetryEventSchema` in the vision doc; client batches to server or OTLP endpoint as capacity allows. **PII, sampling, retention, reload:** [`docs/decomposition/modules/data_and_ops_policy.md`](../decomposition/modules/data_and_ops_policy.md). ## Security (proportionate to phase) @@ -111,3 +111,9 @@ Revisit this document if: - [`neon_sprawl_vision.plan.md`](../neon_sprawl_vision.plan.md) — product locks and phase gates - [`docs/decomposition/README.md`](../decomposition/README.md) — epic/module decomposition +- [`docs/decomposition/modules/contracts.md`](../decomposition/modules/contracts.md) — contract kinds (wire, content, telemetry), repo layout, versioning vs. register “Contract needed” +- [`docs/decomposition/modules/client_server_authority.md`](../decomposition/modules/client_server_authority.md) — intents vs authoritative state; movement, camera, combat, economy ownership +- [`docs/decomposition/modules/pvp_combat_integration.md`](../decomposition/modules/pvp_combat_integration.md) — E5.M1 combat engine × E6.M1 PvP eligibility (single pipeline, deny reasons) +- [`docs/decomposition/modules/quest_scope_and_party.md`](../decomposition/modules/quest_scope_and_party.md) — quest state per character, party credit, turn-in, instance deferral +- [`docs/decomposition/modules/data_and_ops_policy.md`](../decomposition/modules/data_and_ops_policy.md) — content boot load vs dev reload, telemetry PII/sampling/retention, baseline events vs vision plan +- [`docs/decomposition/modules/documentation_and_implementation_alignment.md`](../decomposition/modules/documentation_and_implementation_alignment.md) — module register Status vs code, implementation tracking table diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 612574b..e142cf0 100644 --- a/docs/decomposition/README.md +++ b/docs/decomposition/README.md @@ -9,7 +9,7 @@ This workspace contains detailed planning artifacts derived from the finalized m ## Folder Layout - `epics/` - One file per epic with implementation slices. -- `modules/` - Cross-epic contracts, dependency register, and interface notes. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. - `milestones/` - Phase-gated implementation tracks and pass/fail checklists. ## Working Rules diff --git a/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md new file mode 100644 index 0000000..f1e6b43 --- /dev/null +++ b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md @@ -0,0 +1,61 @@ +# E1.M1 — InputAndMovementRuntime + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M1 | +| **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | +| **Stage target** | Prototype | +| **Status** | In Progress (see [dependency register](module_dependency_register.md); [implementation snapshot](#implementation-snapshot)) | + +## Purpose + +**Authority:** [Client vs server](client_server_authority.md#e1m1-inputandmovementruntime) — server owns `PositionState`; client sends move intent and may predict; reconcile to server. + +Provides the foundational client/runtime path for character locomotion and world interaction: click-to-move or path-follow baseline, interaction trigger range checks, and the authoritative reconciliation surface for where the player is in the world. Other epics attach gameplay (gathering, combat, quests) on top of stable position and movement contracts. + +## Responsibilities + +- Character locomotion and movement command handling. +- Interaction trigger range checks using a single source of truth for distance. +- Emitting or consuming movement-related state suitable for server reconciliation in multiplayer tests. + +## Key contracts + +| Contract | Role | +|----------|------| +| `MoveCommand` | Client or input layer requests movement; server (or sim) validates and applies. | +| `PositionState` | Current authoritative (or reconciled) position for the avatar. | +| `InteractionRequest` | Optional path for interaction attempts; pairs with range checks. | + +Contract readiness is tracked in the [module dependency register](module_dependency_register.md). + +## Implementation snapshot + +- **Done (spike):** Server-side authoritative **read** API for `PositionState` (JSON over HTTP, versioned payload); in-memory store. See [NS-15 implementation plan](../../plans/NS-15-implementation-plan.md), `server/NeonSprawl.Server/Game/PositionState/`, and [server README — Position state](../../../server/README.md#position-state-ns-15). +- **Not yet:** `MoveCommand` ingestion, client sync, persistence, full movement loop per Epic 1 Slice 1. +- **Alignment:** [Documentation and implementation alignment](documentation_and_implementation_alignment.md). + +## Module dependencies + +- **None** — root of the player runtime stack. + +## Dependents (by design) + +- **E1.M2** — [IsometricCameraController](E1_M2_IsometricCameraController.md): stable player anchor / position. +- **E1.M3** — [InteractionAndTargetingLayer](E1_M3_InteractionAndTargetingLayer.md): interaction and targeting on movement/position. +- **Downstream epics** — Gathering (E3.M1), zone transitions (E4.M1), and others consume position implicitly via higher layers. + +## Related implementation slices + +See Epic 1 **Slice 1 — Movement and position sync**: server-authoritative or client-predicted baseline with `MoveCommand` / `PositionState` reconciliation; interaction range single source of truth; telemetry hooks such as `session_start`, lightweight position samples, and `interaction_attempt` failures. + +## Risks and telemetry + +- Desync between client prediction and server authority: mitigate with one reconciliation ruleset and log desync via [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md) when schema exists. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E1_M2_IsometricCameraController.md b/docs/decomposition/modules/E1_M2_IsometricCameraController.md new file mode 100644 index 0000000..61a4719 --- /dev/null +++ b/docs/decomposition/modules/E1_M2_IsometricCameraController.md @@ -0,0 +1,52 @@ +# E1.M2 — IsometricCameraController + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M2 | +| **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +**Authority:** [Client vs server](client_server_authority.md#e1m2-isometriccameracontroller) — camera is client-local for prototype; server does not use camera pose for gameplay checks. + +Delivers a locked isometric camera that keeps the player readable during motion: follow behavior, discrete zoom bands, occlusion handling, and explicit **no rotation** so combat telegraphs and UI remain consistent with the vision for fixed isometric presentation. + +## Responsibilities + +- Locked isometric follow (camera does not freely orbit). +- Zoom bands and configuration-driven limits. +- Occlusion policy so critical gameplay elements remain visible where possible. +- Enforcement of no-rotation rules for the prototype camera model. + +## Key contracts + +| Contract | Role | +|----------|------| +| `CameraState` | Current follow target, zoom level, and policy flags for consumers (e.g. risk UX). | +| `ZoomBandConfig` | Data-driven min/max or discrete zoom steps. | +| `OcclusionPolicy` | Rules for fading, dithering, or offset when geometry blocks the view. | + +## Module dependencies + +- **E1.M1** — InputAndMovementRuntime: camera follows the player anchor derived from movement/position. + +## Dependents (by design) + +- **E6.M2** — Consent and risk UX may use camera-adjacent presentation; epic lists E1.M2 as a dependency for in-zone risk signaling and readability. + +## Related implementation slices + +See Epic 1 **Slice 2 — Locked isometric camera**: follow-center, zoom bands, occlusion policy, no rotation; optional telemetry such as throttled `camera_zoom_changed` and perf stress markers for occluders. + +## Risks and telemetry + +- Occlusion hiding telegraphs: tune policy early and include readability checklist in prototype gates. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md b/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md new file mode 100644 index 0000000..331e823 --- /dev/null +++ b/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md @@ -0,0 +1,47 @@ +# E1.M3 — InteractionAndTargetingLayer + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M3 | +| **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +World object selection, target lock, focus swap rules, and hover/highlight feedback. Bridges movement/position ([E1.M1](E1_M1_InputAndMovementRuntime.md)) into combat, gathering, and ability activation ([E1.M4](E1_M4_AbilityInputScaffold.md), [E5.M1](E5_M1_CombatRulesEngine.md)). + +## Responsibilities + +- Resolve `TargetState` for tab-target and interaction flows. +- Describe interactables via `InteractableDescriptor` and emit `SelectionEvent` for UI and systems. + +## Key contracts + +| Contract | Role | +|----------|------| +| `TargetState` | Current locked target, validity, and swap rules. | +| `InteractableDescriptor` | What can be selected or used in range. | +| `SelectionEvent` | Selection changes for feedback and downstream consumers. | + +## Module dependencies + +- **E1.M1** — InputAndMovementRuntime: range and position source of truth. + +## Dependents (by design) + +- **E1.M4** — AbilityInputScaffold. +- **E3.M1** — ResourceNodeAndGatherLoop. +- **E5.M1** — CombatRulesEngine. +- **E8.M1** — PartyAndMatchAssembly (player/party context hooks per epic). + +## Related implementation slices + +Epic 1 **Slice 3** — interaction, targeting, and ability input wiring with [E5.M1](E5_M1_CombatRulesEngine.md). + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md b/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md new file mode 100644 index 0000000..006314a --- /dev/null +++ b/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md @@ -0,0 +1,45 @@ +# E1.M4 — AbilityInputScaffold + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M4 | +| **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Hotbar bindings, cooldown slot UI hooks, and the client/input path that issues `AbilityCastRequest` into [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md), using targeting from [E1.M3](E1_M3_InteractionAndTargetingLayer.md). + +## Responsibilities + +- Map hotbar slots to abilities and emit `AbilityCastRequest` with validation hints. +- Surface `HotbarLoadout` and `CooldownSnapshot` for UI sync. + +## Key contracts + +| Contract | Role | +|----------|------| +| `AbilityCastRequest` | Intent sent to combat resolution. | +| `HotbarLoadout` | Bound abilities per slot. | +| `CooldownSnapshot` | Client/server-visible cooldown state for UI. | + +## Module dependencies + +- **E1.M3** — InteractionAndTargetingLayer: target lock and cast validity. +- **E5.M1** — CombatRulesEngine: authoritative accept/deny of casts. + +## Dependents (by design) + +- Consumed by UX and telemetry; combat engine remains the authority. + +## Related implementation slices + +Epic 1 **Slice 3** — `ability_cast_requested`, `ability_cast_denied` with reason codes. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md b/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md new file mode 100644 index 0000000..b492124 --- /dev/null +++ b/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md @@ -0,0 +1,43 @@ +# E2.M1 — SkillDefinitionRegistry + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M1 | +| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_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. + +## Responsibilities + +- Load and validate `SkillDef` from data; expose `SkillCategory` and `UnlockRequirement` for gating. + +## Key contracts + +| Contract | Role | +|----------|------| +| `SkillDef` | Per-skill metadata and references. | +| `SkillCategory` | Grouping for UX and balance. | +| `UnlockRequirement` | Prerequisites before XP or use counts apply. | + +## Module dependencies + +- **None** + +## Dependents (by design) + +- **E2.M2** — XpAwardAndLevelEngine (primary). + +## Related implementation slices + +Epic 2 **Slice 1** — skill registry and prototype skills; invalid references fail at load or in CI. + +## Source anchors + +- 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 new file mode 100644 index 0000000..a75d636 --- /dev/null +++ b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md @@ -0,0 +1,55 @@ +# E2.M2 — XpAwardAndLevelEngine + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M2 | +| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_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). + +## Responsibilities + +- Apply `XpGrantEvent` (or equivalent) per skill with validated skill references from [E2.M1](E2_M1_SkillDefinitionRegistry.md). +- 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). + +## Key contracts + +| Contract | Role | +|----------|------| +| `XpGrantEvent` | Structured XP award (skill id, amount, source, 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. + +## Dependents (by design) + +- **E5.M1** — CombatRulesEngine: combat awards XP via integration (Epic 5 / Epic 2 slices). +- **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). + +## 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. + +## Risks and telemetry + +- Runaway leveling in one skill: diminishing returns per slice; monitor distribution via E9.M2 when available. +- Telemetry: `xp_grant`, `level_up`, time-to-first-level-up once real activity fires. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 2. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md b/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md new file mode 100644 index 0000000..1dd4db8 --- /dev/null +++ b/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md @@ -0,0 +1,43 @@ +# E2.M3 — MasteryAndPerkUnlocks + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M3 | +| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_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. + +## Responsibilities + +- Progress `MasteryTrack` data; emit `PerkUnlockEvent` and persist `PerkState`. + +## Key contracts + +| Contract | Role | +|----------|------| +| `MasteryTrack` | Branch progress per design. | +| `PerkUnlockEvent` | Unlocks for UI and combat/craft hooks. | +| `PerkState` | Current unlocked perks per character. | + +## Module dependencies + +- **E2.M2** — XpAwardAndLevelEngine. + +## Dependents (by design) + +- Gameplay systems that gate abilities or recipes on perks (integration per content). + +## Related implementation slices + +Epic 2 **Slice 4** — at least one mastery path unlocks a perk without blocking other skills. + +## Source anchors + +- 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_M4_ProgressionPacingControls.md b/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md new file mode 100644 index 0000000..f5bcd06 --- /dev/null +++ b/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md @@ -0,0 +1,44 @@ +# E2.M4 — ProgressionPacingControls + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M4 | +| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Tuning knobs for progression velocity and catch-up policy, informed by KPIs from [E9.M2](E9_M2_KpiDashboardsAndAlerting.md). + +## Responsibilities + +- Apply `XpModifierProfile`, `CatchUpRule`, and `PacingPolicy` without breaking skill-ID integrity from [E2.M1](E2_M1_SkillDefinitionRegistry.md) / [E2.M2](E2_M2_XpAwardAndLevelEngine.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `XpModifierProfile` | Multipliers or bands per cohort. | +| `CatchUpRule` | Acceleration for lapsed or new players. | +| `PacingPolicy` | Named policy bundles for ops toggles. | + +## Module dependencies + +- **E2.M2** — XpAwardAndLevelEngine. +- **E9.M2** — KpiDashboardsAndAlerting. + +## Dependents (by design) + +- **E9.M3** — LiveBalanceControlPlane (remote tuning). + +## Related implementation slices + +Epic 2 **Slice 4** — pacing policy toggles for test cohorts where possible without full redeploy. + +## Source anchors + +- 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/E3_M1_ResourceNodeAndGatherLoop.md b/docs/decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md new file mode 100644 index 0000000..77e1e4a --- /dev/null +++ b/docs/decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md @@ -0,0 +1,45 @@ +# E3.M1 — ResourceNodeAndGatherLoop + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M1 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +World resource nodes, gather interactions, and yield outputs feeding inventory ([E3.M3](E3_M3_ItemizationAndInventorySchema.md)) and XP ([E2.M2](E2_M2_XpAwardAndLevelEngine.md)). + +## Responsibilities + +- Spawn/manage nodes per `ResourceNodeDef`; resolve `GatherResult` via `ResourceYieldTable`; integrate interaction range via [E1.M3](E1_M3_InteractionAndTargetingLayer.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `ResourceNodeDef` | Node type, capacity, regen. | +| `GatherResult` | Items and depletion state. | +| `ResourceYieldTable` | Probabilities or fixed yields. | + +## Module dependencies + +- **E1.M3** — InteractionAndTargetingLayer. +- **E2.M2** — XpAwardAndLevelEngine. + +## Dependents (by design) + +- **E3.M2** — RefinementAndRecipeExecution (inputs). +- **E4.M2** — SpawnEcologyController. + +## Related implementation slices + +Epic 3 **Slice 2** — 4–6 node types; `resource_gathered`, `gather_node_depleted`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md b/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md new file mode 100644 index 0000000..3645271 --- /dev/null +++ b/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md @@ -0,0 +1,53 @@ +# E3.M2 — RefinementAndRecipeExecution + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M2 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Implements the processing and crafting pipeline: raw-to-refined flows and recipe execution with server-authoritative inventory mutations. Bridges gathered materials ([E3.M1](E3_M1_ResourceNodeAndGatherLoop.md)) and item definitions ([E3.M3](E3_M3_ItemizationAndInventorySchema.md)) into usable outputs for combat, quests, and economy loops. + +## Responsibilities + +- Validate `CraftRequest` against `RecipeDef`, costs, and player inventory state. +- Produce `CraftResult` (success/failure, outputs, failures with reason codes). +- Support prototype recipe set (e.g. 8–12 starter recipes per epic slice minimums). + +## Key contracts + +| Contract | Role | +|----------|------| +| `RecipeDef` | Inputs, outputs, skill gates, station requirements (as scoped for prototype). | +| `CraftRequest` | Actor, recipe, quantities, optional targeting for UI/server sync. | +| `CraftResult` | Deterministic outcome for inventory and telemetry. | + +## Module dependencies + +- **E3.M1** — [ResourceNodeAndGatherLoop](E3_M1_ResourceNodeAndGatherLoop.md): refined materials from gather outputs into crafting inputs. +- **E3.M3** — [ItemizationAndInventorySchema](E3_M3_ItemizationAndInventorySchema.md): `ItemDef`, `ItemInstance`, inventory slots for costs and outputs. + +## Dependents (by design) + +- **E7.M1** — [QuestStateMachine](E7_M1_QuestStateMachine.md): quest steps may require crafted items or craft completion. +- **E6.M4** — [RewardParityEnforcer](E6_M4_RewardParityEnforcer.md): PvP ↔ PvE/crafting equivalents involving craft outputs. +- **Epic 2 integration** — Callers award crafting XP via [E2.M2](E2_M2_XpAwardAndLevelEngine.md) at activity sites. + +## Related implementation slices + +See Epic 3 **Slice 3 — Recipes and crafting pipeline**: gather → refine → item used in combat or quest; telemetry `item_crafted`, `craft_failed`, time-to-first-craft. + +## Risks and telemetry + +- Duplication or negative stacks: server-authoritative craft and inventory; integrity signals via E9.M4 when live. +- Quest/economy parity: lint reward bundles against E6.M4 and E3.M5 policies in later phases. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M3_ItemizationAndInventorySchema.md b/docs/decomposition/modules/E3_M3_ItemizationAndInventorySchema.md new file mode 100644 index 0000000..198dcec --- /dev/null +++ b/docs/decomposition/modules/E3_M3_ItemizationAndInventorySchema.md @@ -0,0 +1,43 @@ +# E3.M3 — ItemizationAndInventorySchema + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M3 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Item definitions, rarity/quality, stackability, and equipment metadata plus `InventorySlot` representation. Foundation for craft outputs, quest rewards, combat loot, and trade. + +## Responsibilities + +- Version `ItemDef` / `ItemInstance` schema; enforce stack and slot rules server-side. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ItemDef` | Static template data. | +| `ItemInstance` | Per-item state (stack, durability hook, binds). | +| `InventorySlot` | Container model for players and exchanges. | + +## Module dependencies + +- **None** + +## Dependents (by design) + +- **E3.M2**, **E3.M4**, **E5.M3**, **E7.M2**, **E8.M3**, and any system moving items. + +## Related implementation slices + +Epic 3 **Slice 1** — MVP inventory; `item_created`, transfer failures. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md b/docs/decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md new file mode 100644 index 0000000..80d10c5 --- /dev/null +++ b/docs/decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md @@ -0,0 +1,44 @@ +# E3.M4 — SinkAndDurabilityLifecycle + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M4 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Item decay, consumption, repair, and other sinks that sustain demand; may integrate with market/trade flows from [E8.M3](E8_M3_PlayerTradeAndMarketplace.md). + +## Responsibilities + +- Track `DurabilityState`; emit `ItemSinkEvent`; apply `RepairCostRule` server-authoritatively. + +## Key contracts + +| Contract | Role | +|----------|------| +| `DurabilityState` | Wear and breakage. | +| `ItemSinkEvent` | Destruction/consumption audit trail. | +| `RepairCostRule` | Currency and material costs. | + +## Module dependencies + +- **E3.M3** — ItemizationAndInventorySchema. +- **E8.M3** — PlayerTradeAndMarketplace (epic dependency for settlement-related sinks). + +## Dependents (by design) + +- **E3.M5** — EconomyBalancePolicy. + +## Related implementation slices + +Epic 3 **Slice 4** — `item_sink`, `repair_performed`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M5_EconomyBalancePolicy.md b/docs/decomposition/modules/E3_M5_EconomyBalancePolicy.md new file mode 100644 index 0000000..389df91 --- /dev/null +++ b/docs/decomposition/modules/E3_M5_EconomyBalancePolicy.md @@ -0,0 +1,45 @@ +# E3.M5 — EconomyBalancePolicy + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M5 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Faucet/sink parameter sets and guardrails for inflation/deflation; feeds alerts via [E9.M2](E9_M2_KpiDashboardsAndAlerting.md). + +## Responsibilities + +- Encode `EconomyPolicy`, `PriceBandRule`, `FaucetSinkRatio` thresholds; integrate with [E3.M4](E3_M4_SinkAndDurabilityLifecycle.md) sinks. + +## Key contracts + +| Contract | Role | +|----------|------| +| `EconomyPolicy` | Named tunable bundles. | +| `PriceBandRule` | Listing/fee bands for [E8.M3](E8_M3_PlayerTradeAndMarketplace.md). | +| `FaucetSinkRatio` | KPI targets and breach signals. | + +## Module dependencies + +- **E3.M4** — SinkAndDurabilityLifecycle. +- **E9.M2** — KpiDashboardsAndAlerting. + +## Dependents (by design) + +- **E8.M3** — marketplace fees and validation. +- **E9.M3** — LiveBalanceControlPlane. + +## Related implementation slices + +Epic 3 **Slice 4** — policy alerts on ratio breaches. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md b/docs/decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md new file mode 100644 index 0000000..645cc5b --- /dev/null +++ b/docs/decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md @@ -0,0 +1,44 @@ +# E4.M1 — ZoneGraphAndTravelRules + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M1 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Regional zone graph, transition links, and travel constraints. Server and client agree on current zone id; illegal shortcuts are blocked. + +## Responsibilities + +- Author `ZoneDef` and `ZoneEdge`; evaluate `TravelRule` on transitions. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ZoneDef` | Identity, bounds or graph membership. | +| `ZoneEdge` | Valid transitions. | +| `TravelRule` | Gating (level, quest, faction). | + +## Module dependencies + +- **None** + +## Dependents (by design) + +- **E4.M2**, **E4.M3**, **E4.M4** — SecurityTierZoneFlags and world layers. +- **E7.M4** — ContractMissionGenerator. + +## Related implementation slices + +Epic 4 **Slice 1** — `zone_enter`, `zone_exit`, invalid transition attempts. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 4. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M2_SpawnEcologyController.md b/docs/decomposition/modules/E4_M2_SpawnEcologyController.md new file mode 100644 index 0000000..73bdaad --- /dev/null +++ b/docs/decomposition/modules/E4_M2_SpawnEcologyController.md @@ -0,0 +1,45 @@ +# E4.M2 — SpawnEcologyController + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M2 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Resource and NPC spawn profiles per zone, respawn pacing, and depletion/recovery so densities stay within design bounds. + +## Responsibilities + +- Drive `SpawnProfile` / `RespawnRule`; maintain `ZoneEcologyState`; coordinate with [E3.M1](E3_M1_ResourceNodeAndGatherLoop.md) and [E5.M2](E5_M2_NpcAiAndBehaviorProfiles.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `SpawnProfile` | What spawns where and how often. | +| `RespawnRule` | Timers and caps. | +| `ZoneEcologyState` | Current density/depletion snapshot. | + +## Module dependencies + +- **E4.M1** — ZoneGraphAndTravelRules. +- **E3.M1** — ResourceNodeAndGatherLoop. +- **E5.M2** — NpcAiAndBehaviorProfiles. + +## Dependents (by design) + +- Content and live ops tuning; telemetry for spawn waves and recovery. + +## Related implementation slices + +Epic 4 **Slice 3** — `spawn_wave`, depletion/recovery markers. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 4. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md b/docs/decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md new file mode 100644 index 0000000..c7f98b7 --- /dev/null +++ b/docs/decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md @@ -0,0 +1,45 @@ +# E4.M3 — SeamlessHandoffAndRegionState + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M3 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Cross-region handoff behavior and region authority boundaries. Minimal spike: two regions with authority transfer and no duplicate entities. + +**Epic note:** Depends on **backend world services** in addition to E4.M1; those integrations are out-of-repo contracts until defined. + +## Responsibilities + +- Orchestrate `RegionHandoffEvent`; model `RegionAuthority` and `TransferState` during handoff. + +## Key contracts + +| Contract | Role | +|----------|------| +| `RegionHandoffEvent` | Start/complete/fail lifecycle. | +| `RegionAuthority` | Which service owns simulation for an entity. | +| `TransferState` | Serializable handoff payload. | + +## Module dependencies + +- **E4.M1** — ZoneGraphAndTravelRules. + +## Dependents (by design) + +- World/shard services (external); client runtime for loading/streaming. + +## Related implementation slices + +Epic 4 **Slice 4** — `region_handoff_start`, `region_handoff_complete`, rollback path documented. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 4. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md b/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md new file mode 100644 index 0000000..9a84980 --- /dev/null +++ b/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md @@ -0,0 +1,51 @@ +# E4.M4 — SecurityTierZoneFlags + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M4 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Layer on top of the zone graph that tags each zone with security tier (e.g. high / low / contested) and exposes **server-authoritative** policy state and entry-warning payloads. Enables PvP eligibility ([E6.M1](E6_M1_PvPEligibilityAndFlagState.md)) and risk UX without circular dependencies: Epic 6 consumes this data; E4.M4 does not depend on Epic 6. + +## Responsibilities + +- Assign and persist `SecurityTier` per zone (from data on [E4.M1](E4_M1_ZoneGraphAndTravelRules.md)). +- Publish `ZonePolicyState` for server and client display alignment. +- Emit or serve `ZoneEntryWarning` when players transition into higher-risk zones. + +## Key contracts + +| Contract | Role | +|----------|------| +| `SecurityTier` | Discrete tier driving PvP and risk rules. | +| `ZonePolicyState` | Authoritative flags for what is allowed in-zone. | +| `ZoneEntryWarning` | Structured warning for consent flows and UI copy. | + +## Module dependencies + +- **E4.M1** — [ZoneGraphAndTravelRules](E4_M1_ZoneGraphAndTravelRules.md): `ZoneDef`, edges, and travel context for tier attachment. + +## Dependents (by design) + +- **E6.M1** — [PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md): who may engage in PvP where. +- **E6.M2** — [ConsentAndRiskUxSignals](E6_M2_ConsentAndRiskUxSignals.md): risk UI from tier and warnings. + +## Related implementation slices + +See Epic 4 **Slice 2 — Security tier tagging and UI hooks**: server and client agree on tier at transitions; entry-warning contract stable for Epic 6; telemetry `security_zone_enter`, `security_zone_exit` aligned with PvP events. + +## Risks and telemetry + +- Client/server mismatch: server is source of truth; client prediction display-only. +- Coordinate with Epic 6 prototype gates for optionality and clarity. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 4. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E5_M1_CombatRulesEngine.md b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md new file mode 100644 index 0000000..722e3d4 --- /dev/null +++ b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md @@ -0,0 +1,60 @@ +# E5.M1 — CombatRulesEngine + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M1 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +**Authority:** [Client vs server](client_server_authority.md#e5m1-combatrulesengine) — server validates intents and computes all outcomes; never trust client damage/healing/crit/death. + +Core tab-target combat resolution: valid actions against a locked target, hit resolution, cooldown and resource timing, and threat state as needed for prototype encounters. Presents readable outcomes in fixed isometric view and feeds XP awards through [E2.M2](E2_M2_XpAwardAndLevelEngine.md). + +**PvP:** Single engine for PvE and PvP; player-target hostility **gates** on [E6.M1](E6_M1_PvPEligibilityAndFlagState.md). See [PvP and the combat engine](pvp_combat_integration.md). + +## Responsibilities + +- Combat state machine for tab-target flow (attacks, abilities per prototype scope). +- Validate and apply `CombatAction`; produce `CombatResolution` for UI and logs (include **PvP deny reasons** when player targets are blocked; see [pvp_combat_integration.md](pvp_combat_integration.md)). +- Integrate with targeting/interaction from **E1.M3** (target lock, valid target checks). +- Award combat XP via E2.M2 integration where specified in slices. + +## Key contracts + +| Contract | Role | +|----------|------| +| `CombatAction` | Attack, ability, or other combat intent from client/input scaffold. | +| `CombatResolution` | Hits, misses, damage, denies with reason codes (no silent failures). | +| `ThreatState` | Aggro/threat for NPC and encounter coordination (as scoped). | + +## Module dependencies + +- **E1.M3** — [InteractionAndTargetingLayer](E1_M3_InteractionAndTargetingLayer.md): `TargetState`, selection, and alignment with **E1.M4** ([AbilityInputScaffold](E1_M4_AbilityInputScaffold.md)) for `AbilityCastRequest` wiring. +- **E2.M2** — [XpAwardAndLevelEngine](E2_M2_XpAwardAndLevelEngine.md): combat XP grants. + +## Dependents (by design) + +- **E5.M2** — NpcAiAndBehaviorProfiles. +- **E5.M3** — EncounterAndRewardTables. +- **E1.M4** — AbilityInputScaffold sends `AbilityCastRequest` to combat. +- **E7.M1** — QuestStateMachine for combat-related quest steps. +- **E2.M2** — Invoked as integration caller for XP (not a structural child). + +## Related implementation slices + +See Epic 5 **Slice 1 — Combat rules MVP**: target lock, basic attacks, 4–6 abilities, cooldowns/resources; telemetry `encounter_start`, `ability_used`, `player_death`, `enemy_defeat`. + +## Risks and telemetry + +- Sluggish or opaque tab-target: prototype readability gate; instrument time-in-combat and deny reasons. +- Desync logging via E9.M1 taxonomy when available. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md b/docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md new file mode 100644 index 0000000..ba4aae3 --- /dev/null +++ b/docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md @@ -0,0 +1,44 @@ +# E5.M2 — NpcAiAndBehaviorProfiles + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M2 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Enemy archetype behavior loops, aggro logic, and telegraph scheduling on top of [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md). + +## Responsibilities + +- Run `NpcBehaviorDef`; emit `TelegraphEvent`; apply `AggroRule` / threat integration with combat state. + +## Key contracts + +| Contract | Role | +|----------|------| +| `NpcBehaviorDef` | Archetype scripts or state machines. | +| `TelegraphEvent` | Telegraph timing for UI and dodge windows. | +| `AggroRule` | Target selection and leash behavior. | + +## Module dependencies + +- **E5.M1** — CombatRulesEngine. + +## Dependents (by design) + +- **E4.M2** — SpawnEcologyController. +- **E5.M3** — EncounterAndRewardTables. + +## Related implementation slices + +Epic 5 **Slice 2** — three archetypes; `telegraph_fired`, `npc_state_transition`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md b/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md new file mode 100644 index 0000000..5a84ba9 --- /dev/null +++ b/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md @@ -0,0 +1,47 @@ +# E5.M3 — EncounterAndRewardTables + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M3 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Encounter templates, completion criteria, and reward drop routing into items ([E3.M3](E3_M3_ItemizationAndInventorySchema.md)) and quest credit via [E7.M2 — RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md). + +## Responsibilities + +- Instantiate `EncounterDef`; roll `RewardTable`; emit `EncounterCompleteEvent` for downstream routers and parity checks. + +## Key contracts + +| Contract | Role | +|----------|------| +| `EncounterDef` | Spawns, objectives, completion rules. | +| `RewardTable` | Loot and currency references validated against item schema. | +| `EncounterCompleteEvent` | Completion signal for quests and telemetry. | + +## Module dependencies + +- **E5.M1** — CombatRulesEngine. +- **E3.M3** — ItemizationAndInventorySchema. +- **E7.M2** — RewardAndUnlockRouter. + +## Dependents (by design) + +- **E5.M4** — GroupCombatScaling. +- **E6.M4** — RewardParityEnforcer. +- **E7.M4** — ContractMissionGenerator. + +## Related implementation slices + +Epic 5 **Slice 3** — `encounter_complete`, reward attribution once. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E5_M4_GroupCombatScaling.md b/docs/decomposition/modules/E5_M4_GroupCombatScaling.md new file mode 100644 index 0000000..de35722 --- /dev/null +++ b/docs/decomposition/modules/E5_M4_GroupCombatScaling.md @@ -0,0 +1,44 @@ +# E5.M4 — GroupCombatScaling + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M4 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Duo/squad scaling and anti-trivialization hooks using party context from [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md). + +## Responsibilities + +- Apply `ScalingProfile`, `PartySizeModifier`, and `CombatDifficultyBand` when resolving encounters ([E5.M3](E5_M3_EncounterAndRewardTables.md)). + +## Key contracts + +| Contract | Role | +|----------|------| +| `ScalingProfile` | HP/damage modifiers per party size. | +| `PartySizeModifier` | Discrete steps or curves. | +| `CombatDifficultyBand` | Named difficulty for tuning. | + +## Module dependencies + +- **E5.M3** — EncounterAndRewardTables. +- **E8.M1** — PartyAndMatchAssembly. + +## Dependents (by design) + +- Encounter runtime and telemetry `party_combat_scaling_applied`. + +## Related implementation slices + +Epic 5 **Slice 4** — duo fairness metrics. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md b/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md new file mode 100644 index 0000000..4d27b0c --- /dev/null +++ b/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md @@ -0,0 +1,57 @@ +# E6.M1 — PvPEligibilityAndFlagState + +## Summary + + +| Field | Value | +| ---------------- | ------------------------------------------------------------------ | +| **Module ID** | E6.M1 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + + +## Purpose + +Server-enforced rules for whether player-versus-player combat is allowed: driven by [E4.M4](E4_M4_SecurityTierZoneFlags.md) security tiers and explicit opt-in context. Ensures PvP is never client-only toggles; eligibility is authoritative and auditable. + +## Responsibilities + +- Evaluate `EligibilityRule` against current zone policy and player PvP flag / consent context. +- Maintain and transition `PvPFlagState` (or equivalent) with clear semantics for combat engine gating. +- Emit `PvPStateChanged` (or equivalent) for UI, telemetry, and downstream systems. + +## Key contracts + + +| Contract | Role | +| ----------------- | -------------------------------------------------------------------- | +| `PvPFlagState` | Current opt-in and effective PvP capability for an actor in context. | +| `EligibilityRule` | Policy mapping from tier + context to allow/deny. | +| `PvPStateChanged` | Event for subscribers (UX, analytics, combat deny reasons). | + + +## Module dependencies + +- **E4.M4** — SecurityTierZoneFlags: `SecurityTier`, `ZonePolicyState`, `ZoneEntryWarning` inputs. + +## Dependents (by design) + +- **E6.M2** — ConsentAndRiskUxSignals: prompts and HUD indicators. +- **E6.M3** — LossPenaltyAndAntiGriefRules: builds on eligibility and zone context. +- **Combat resolution** — [E5.M1](E5_M1_CombatRulesEngine.md) consults E6.M1 **in the same pipeline** before applying player-target hostility; see [PvP and the combat engine](pvp_combat_integration.md). + +## Related implementation slices + +See Epic 6 **Slice 1 — Zone-based PvP flag core**: high-sec blocks player combat; server-enforced eligibility; telemetry `pvp_state_changed`, `pvp_zone_enter`, `pvp_zone_exit`. + +## Risks and telemetry + +- PvP feeling mandatory: pair with E6.M4 reward parity and design gates from master plan. +- Griefing: high-sec safe hubs; fast iteration using telemetry and E9 integrity paths when live. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 6. +- [Module dependency register](module_dependency_register.md) + diff --git a/docs/decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md b/docs/decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md new file mode 100644 index 0000000..db18d13 --- /dev/null +++ b/docs/decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md @@ -0,0 +1,44 @@ +# E6.M2 — ConsentAndRiskUxSignals + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E6.M2 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Entry warnings, in-zone risk UI, and clear PvP state communication using eligibility from [E6.M1](E6_M1_PvPEligibilityAndFlagState.md) and camera/readability context from [E1.M2](E1_M2_IsometricCameraController.md). + +## Responsibilities + +- Show `RiskPrompt` on low-sec entry; drive `ZoneRiskState` / `PvPIndicatorState` in HUD. + +## Key contracts + +| Contract | Role | +|----------|------| +| `RiskPrompt` | Consent dialog payload and outcomes. | +| `ZoneRiskState` | Display model for current zone risk. | +| `PvPIndicatorState` | Persistent indicator semantics. | + +## Module dependencies + +- **E6.M1** — PvPEligibilityAndFlagState. +- **E1.M2** — IsometricCameraController. + +## Dependents (by design) + +- Client UX only; server remains authoritative via E6.M1 / E4.M4. + +## Related implementation slices + +Epic 6 **Slice 2** — `risk_prompt_shown`, accepted/declined. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 6. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md b/docs/decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md new file mode 100644 index 0000000..fc49bb6 --- /dev/null +++ b/docs/decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md @@ -0,0 +1,44 @@ +# E6.M3 — LossPenaltyAndAntiGriefRules + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E6.M3 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Death/loss rules in PvP contexts, spawn protection, and abuse mitigation with escalation hooks to [E9.M4 — IntegrityAndAbuseResponse](E9_M4_IntegrityAndAbuseResponse.md). + +## Responsibilities + +- Encode `PvPLossRule`; track `SpawnProtectionState`; raise `GriefingStrike` signals for ops review. + +## Key contracts + +| Contract | Role | +|----------|------| +| `PvPLossRule` | Drop, durability, or flag penalties. | +| `SpawnProtectionState` | Timers and invuln windows. | +| `GriefingStrike` | Escalation input to integrity pipeline. | + +## Module dependencies + +- **E6.M1** — PvPEligibilityAndFlagState. +- **E9.M4** — IntegrityAndAbuseResponse. + +## Dependents (by design) + +- Combat resolution and spawn systems when in PvP context. + +## Related implementation slices + +Epic 6 **Slice 4** — `pvp_death`, `spawn_protection_applied`, `grief_flag_raised`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 6. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E6_M4_RewardParityEnforcer.md b/docs/decomposition/modules/E6_M4_RewardParityEnforcer.md new file mode 100644 index 0000000..eb3e9fb --- /dev/null +++ b/docs/decomposition/modules/E6_M4_RewardParityEnforcer.md @@ -0,0 +1,45 @@ +# E6.M4 — RewardParityEnforcer + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E6.M4 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Ensure functional equivalents for PvP rewards through PvE/crafting paths; blocks ship when mapping incomplete per policy. + +## Responsibilities + +- Maintain `RewardParityMap` and `EquivalentPowerBand`; emit `ParityViolationAlert` for CI or live checks across [E3.M2](E3_M2_RefinementAndRecipeExecution.md), [E5.M3](E5_M3_EncounterAndRewardTables.md), [E7.M2](E7_M2_RewardAndUnlockRouter.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `RewardParityMap` | PvP-only reward → equivalent path. | +| `EquivalentPowerBand` | Acceptable power band comparison. | +| `ParityViolationAlert` | Blocking or warning signal. | + +## Module dependencies + +- **E3.M2** — RefinementAndRecipeExecution. +- **E5.M3** — EncounterAndRewardTables. +- **E7.M2** — RewardAndUnlockRouter. + +## Dependents (by design) + +- Release/content gates; telemetry `parity_violation`, `parity_grant_path_completed`. + +## Related implementation slices + +Epic 6 **Slice 3** — prototype sidegrade example validated. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 6. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E7_M1_QuestStateMachine.md b/docs/decomposition/modules/E7_M1_QuestStateMachine.md new file mode 100644 index 0000000..5b9f225 --- /dev/null +++ b/docs/decomposition/modules/E7_M1_QuestStateMachine.md @@ -0,0 +1,56 @@ +# E7.M1 — QuestStateMachine + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M1 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Data-driven quest lifecycle: start, step progression, branching, failure/reset, and completion with durable persistence. Integrates crafting and combat outcomes so guided content ties together gather–craft–combat loops without duplicate rewards. + +**Scope / party:** [Per-character state by default](quest_scope_and_party.md#persistence-per-character-by-default); optional [party credit and turn-in rules](quest_scope_and_party.md#quest-modes-content-driven) via `QuestDef` and [E8.M1](E8_M1_PartyAndMatchAssembly.md). + +## Responsibilities + +- Load and interpret `QuestDef`; track `QuestStepState` **per character**; synchronize party-credit advances per [quest_scope_and_party.md](quest_scope_and_party.md). +- Apply `QuestStateTransition` rules for advance, abandon, fail, and complete. +- Invoke or subscribe to [E3.M2](E3_M2_RefinementAndRecipeExecution.md) and [E5.M1](E5_M1_CombatRulesEngine.md) (or their events) for step completion predicates. + +## Key contracts + +| Contract | Role | +|----------|------| +| `QuestDef` | Steps, prerequisites, objectives, and branching metadata. | +| `QuestStepState` | Current step progress and internal flags. | +| `QuestStateTransition` | Valid transitions and side effects (before E7.M2 reward routing). | + +## Module dependencies + +- **E3.M2** — RefinementAndRecipeExecution: craft completion, item hand-ins, refine steps. +- **E5.M1** — CombatRulesEngine: defeat objectives, encounter-linked steps. + +## Dependents (by design) + +- **E7.M2** — [RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md): idempotent delivery after completion. +- **E7.M3** — [FactionReputationLedger](E7_M3_FactionReputationLedger.md): reputation-gated content (pre-production). +- **E5.M3** — [EncounterAndRewardTables](E5_M3_EncounterAndRewardTables.md): encounter completion and quest credit. +- **E6.M4** — [RewardParityEnforcer](E6_M4_RewardParityEnforcer.md): quest/PvP reward alignment. + +## Related implementation slices + +See Epic 7 **Slice 1 — Quest core and persistence**: 3–5 onboarding quests plus one chain across gather/craft/combat; telemetry `quest_start`, `quest_step_complete`, `quest_complete`, funnel times. + +## Risks and telemetry + +- Scripting weight: keep `QuestDef` data-first; templates in decomposition/tooling path per epic. +- Double-claim: design for idempotency before E7.M2; lint bundles vs E6.M4 / E3.M5. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md b/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md new file mode 100644 index 0000000..38cde7c --- /dev/null +++ b/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md @@ -0,0 +1,46 @@ +# E7.M2 — RewardAndUnlockRouter + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M2 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Route quest and encounter outputs to XP, items, unlocks, and flags with **idempotent** delivery ([E7.M1](E7_M1_QuestStateMachine.md) completion, [E2.M2](E2_M2_XpAwardAndLevelEngine.md), [E3.M3](E3_M3_ItemizationAndInventorySchema.md)). **Party:** [Per-character idempotent grants](quest_scope_and_party.md#rewards-e7m2) when party credit completes multiple characters. + +## Responsibilities + +- Apply `QuestRewardBundle`; grant `UnlockGrant`; emit `RewardDeliveryEvent` for audit. + +## Key contracts + +| Contract | Role | +|----------|------| +| `QuestRewardBundle` | Composite rewards for a step or completion. | +| `UnlockGrant` | Blueprints, gates, cosmetics. | +| `RewardDeliveryEvent` | Idempotency key and outcome. | + +## Module dependencies + +- **E2.M2** — XpAwardAndLevelEngine. +- **E3.M3** — ItemizationAndInventorySchema. +- **E7.M1** — QuestStateMachine. + +## Dependents (by design) + +- **E5.M3** — EncounterAndRewardTables. +- **E6.M4** — RewardParityEnforcer. + +## Related implementation slices + +Epic 7 **Slice 2** — `reward_delivery`, `unlock_granted`; no double-claim on replay. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E7_M3_FactionReputationLedger.md b/docs/decomposition/modules/E7_M3_FactionReputationLedger.md new file mode 100644 index 0000000..7a1bf29 --- /dev/null +++ b/docs/decomposition/modules/E7_M3_FactionReputationLedger.md @@ -0,0 +1,44 @@ +# E7.M3 — FactionReputationLedger + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M3 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Faction standing, reputation deltas, and `FactionGateRule` evaluation for content and contracts. + +## Responsibilities + +- Persist auditable `FactionStanding`; apply `ReputationDelta`; fail closed on tamper for gates. + +## Key contracts + +| Contract | Role | +|----------|------| +| `FactionStanding` | Current rep per faction. | +| `ReputationDelta` | Change events with source attribution. | +| `FactionGateRule` | Unlock conditions for content. | + +## Module dependencies + +- **E7.M1** — QuestStateMachine. + +## Dependents (by design) + +- **E7.M4** — ContractMissionGenerator. +- **E8.M2** — GuildCorpProgressionState. + +## Related implementation slices + +Epic 7 **Slice 3** — `reputation_delta`, `faction_gate_blocked`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E7_M4_ContractMissionGenerator.md b/docs/decomposition/modules/E7_M4_ContractMissionGenerator.md new file mode 100644 index 0000000..a11e87b --- /dev/null +++ b/docs/decomposition/modules/E7_M4_ContractMissionGenerator.md @@ -0,0 +1,45 @@ +# E7.M4 — ContractMissionGenerator + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M4 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Semi-procedural repeatable contracts from templates, keyed by zone difficulty ([E4.M1](E4_M1_ZoneGraphAndTravelRules.md)), encounter templates ([E5.M3](E5_M3_EncounterAndRewardTables.md)), and faction state ([E7.M3](E7_M3_FactionReputationLedger.md)). + +## Responsibilities + +- Emit validated `ContractTemplate` instances from `ContractSeed`; record `ContractOutcome`. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ContractTemplate` | Parameterized mission skeleton. | +| `ContractSeed` | RNG or daily seed inputs. | +| `ContractOutcome` | Completion and reward linkage. | + +## Module dependencies + +- **E4.M1** — ZoneGraphAndTravelRules. +- **E5.M3** — EncounterAndRewardTables. +- **E7.M3** — FactionReputationLedger. + +## Dependents (by design) + +- Live ops and content pipelines; validate against economy/parity rules per epic. + +## Related implementation slices + +Epic 7 **Slice 4** — `contract_issued`, `contract_complete`, reward anomalies. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md b/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md new file mode 100644 index 0000000..ef50c14 --- /dev/null +++ b/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md @@ -0,0 +1,45 @@ +# E8.M1 — PartyAndMatchAssembly + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M1 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Party creation, invites, ready-state, and party-scoped hooks for cooperative activities, anchored on player identity/selection from [E1.M3](E1_M3_InteractionAndTargetingLayer.md). + +## Responsibilities + +- Server-authoritative `PartyState`; `InviteEvent` lifecycle; optional `RolePreference` for matchmaking. + +## Key contracts + +| Contract | Role | +|----------|------| +| `PartyState` | Members, leader, ready flags. | +| `InviteEvent` | Invite, accept, decline, timeout. | +| `RolePreference` | Role or build hints for assembly. | + +## Module dependencies + +- **E1.M3** — InteractionAndTargetingLayer. + +## Dependents (by design) + +- **E5.M4** — GroupCombatScaling. +- **E8.M2** — GuildCorpProgressionState. +- **E7.M1** — [QuestStateMachine](E7_M1_QuestStateMachine.md) when `QuestDef` uses party credit or leader-only turn-in ([quest scope](quest_scope_and_party.md)). + +## Related implementation slices + +Epic 8 **Slice 1** — `party_formed`, `party_disbanded`, invite failures. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M2_GuildCorpProgressionState.md b/docs/decomposition/modules/E8_M2_GuildCorpProgressionState.md new file mode 100644 index 0000000..9f8b554 --- /dev/null +++ b/docs/decomposition/modules/E8_M2_GuildCorpProgressionState.md @@ -0,0 +1,44 @@ +# E8.M2 — GuildCorpProgressionState + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M2 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Guild/corp membership, rank permissions, and shared progression tied to faction/social goals via [E7.M3](E7_M3_FactionReputationLedger.md). + +## Responsibilities + +- Maintain `GuildState` and `GuildRolePolicy`; emit `GuildProgressionEvent`; prevent permission bypass griefing. + +## Key contracts + +| Contract | Role | +|----------|------| +| `GuildState` | Org roster, level, shared unlocks. | +| `GuildRolePolicy` | Permission matrix. | +| `GuildProgressionEvent` | Shared milestones. | + +## Module dependencies + +- **E8.M1** — PartyAndMatchAssembly. +- **E7.M3** — FactionReputationLedger. + +## Dependents (by design) + +- Social UI, contracts, and telemetry `guild_progression_event`. + +## Related implementation slices + +Epic 8 **Slice 4** — corp progress not griefable by solo permission bypass. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md b/docs/decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md new file mode 100644 index 0000000..1c73b77 --- /dev/null +++ b/docs/decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md @@ -0,0 +1,45 @@ +# E8.M3 — PlayerTradeAndMarketplace + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M3 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Listings, direct trade, purchases, and **atomic server settlement** for player economy, grounded in [E3.M3](E3_M3_ItemizationAndInventorySchema.md) and policy from [E3.M5](E3_M5_EconomyBalancePolicy.md). + +## Responsibilities + +- `MarketListing` / `TradeOffer` validation; `SettlementEvent` with duplication and cancel-edge coverage. + +## Key contracts + +| Contract | Role | +|----------|------| +| `MarketListing` | Seller, item, price, fees. | +| `TradeOffer` | Bilateral trade window state. | +| `SettlementEvent` | Completed exchange audit. | + +## Module dependencies + +- **E3.M3** — ItemizationAndInventorySchema. +- **E3.M5** — EconomyBalancePolicy. + +## Dependents (by design) + +- **E3.M4** — SinkAndDurabilityLifecycle (epic coupling). +- Integrity and fraud telemetry. + +## Related implementation slices + +Epic 8 **Slice 2** — `trade_completed`, `listing_created`, `purchase_completed`, fraud flags. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M4_ChatModerationAndReporting.md b/docs/decomposition/modules/E8_M4_ChatModerationAndReporting.md new file mode 100644 index 0000000..96768f9 --- /dev/null +++ b/docs/decomposition/modules/E8_M4_ChatModerationAndReporting.md @@ -0,0 +1,43 @@ +# E8.M4 — ChatModerationAndReporting + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M4 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Channel chat with rate limits, player reports, and moderation action logs escalated to [E9.M4 — IntegrityAndAbuseResponse](E9_M4_IntegrityAndAbuseResponse.md). + +## Responsibilities + +- Emit `ChatMessageEvent` with stable ids; accept `PlayerReport`; record `ModerationAction` for audit export. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ChatMessageEvent` | Message payload + channel + ids. | +| `PlayerReport` | Reason codes and context. | +| `ModerationAction` | Mute/ban/warn with actor and timestamp. | + +## Module dependencies + +- **E9.M4** — IntegrityAndAbuseResponse. + +## Dependents (by design) + +- Moderator tooling and compliance exports. + +## Related implementation slices + +Epic 8 **Slice 3** — trace message id to action history in test; `chat_message_sent`, `moderation_action`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md new file mode 100644 index 0000000..34fc30a --- /dev/null +++ b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md @@ -0,0 +1,54 @@ +# E9.M1 — TelemetryEventSchema + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M1 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Artifact policy for telemetry (envelope, field naming, versioning) aligns with [contracts.md — contract kinds](contracts.md#contract-kinds) and **Telemetry** row. **PII, sampling, retention, baseline list:** [Data reload and telemetry operations policy](data_and_ops_policy.md). + +Canonical taxonomy and versioning for gameplay and operations events: session, progression, economy, combat, PvP, movement desync, and integrity-adjacent signals. Provides the shared **envelope** so every epic can instrument consistently and breaking changes are explicit. + +## Responsibilities + +- Define `TelemetryEvent` shapes (or schema IDs) and required context fields. +- Govern `EventSchemaVersion` and migration rules for ingest pipelines. +- Specify `ClientEventEnvelope` (batching, privacy guardrails, delivery semantics) for prototype SDK. + +## Key contracts + +| Contract | Role | +|----------|------| +| `TelemetryEvent` | Named event with versioned payload; single registry or catalog. | +| `EventSchemaVersion` | Bump policy when fields or semantics change. | +| `ClientEventEnvelope` | Transport wrapper: timestamps, session, sampling, PII policy hooks. | + +## Module dependencies + +- **None** — horizontal capability; other modules depend on E9.M1 for event names and fields. + +## Dependents (by design) + +- **E9.M2** — KpiDashboardsAndAlerting: aggregates and gates. +- **E9.M4** — IntegrityAndAbuseResponse: correlates signals to incidents. +- **All epics** — Slices reference concrete events (e.g. `xp_grant`, `zone_enter`, `pvp_state_changed`) once schema exists. + +## Related implementation slices + +See Epic 9 **Slice 1 — Baseline event SDK and schema versioning**: prototype funnel events match master plan baseline; breaking changes versioned; telemetry for `schema_version_mismatch` and ingest errors. + +## Risks and telemetry + +- Noise drowning signals: decision-driven instrumentation, sampling strategy from master plan. +- Privacy: guardrails in envelope and field catalog before wide client shipment. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 9. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md b/docs/decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md new file mode 100644 index 0000000..c2d9e3d --- /dev/null +++ b/docs/decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md @@ -0,0 +1,45 @@ +# E9.M2 — KpiDashboardsAndAlerting + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M2 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +KPI aggregation, dashboards, trend alerts, and milestone gate signals built on [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md). + +## Responsibilities + +- Define `KpiDefinition` and `AlertThreshold`; emit `MilestoneGateSignal` for phase checklists. + +## Key contracts + +| Contract | Role | +|----------|------| +| `KpiDefinition` | Query + visualization binding. | +| `AlertThreshold` | Breach conditions. | +| `MilestoneGateSignal` | Pass/fail inputs for milestones. | + +## Module dependencies + +- **E9.M1** — TelemetryEventSchema. + +## Dependents (by design) + +- **E2.M4** — ProgressionPacingControls. +- **E3.M5** — EconomyBalancePolicy. +- **E9.M3** — LiveBalanceControlPlane. + +## Related implementation slices + +Epic 9 **Slice 2** — each prototype gate has at least one chart or query. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 9. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M3_LiveBalanceControlPlane.md b/docs/decomposition/modules/E9_M3_LiveBalanceControlPlane.md new file mode 100644 index 0000000..55d7e5d --- /dev/null +++ b/docs/decomposition/modules/E9_M3_LiveBalanceControlPlane.md @@ -0,0 +1,46 @@ +# E9.M3 — LiveBalanceControlPlane + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M3 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Runtime-safe application of signed `BalancePatch` bundles to combat, progression, and economy knobs with `RolloutState` and rollback story. + +## Responsibilities + +- Version `ConfigVersion` per patch; stage `RolloutState`; integrate with [E9.M2](E9_M2_KpiDashboardsAndAlerting.md), [E5.M1](E5_M1_CombatRulesEngine.md), [E2.M4](E2_M4_ProgressionPacingControls.md), [E3.M5](E3_M5_EconomyBalancePolicy.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `BalancePatch` | Signed tunable diff bundle. | +| `ConfigVersion` | Client/server hash visibility. | +| `RolloutState` | Canary, full, rollback. | + +## Module dependencies + +- **E9.M2** — KpiDashboardsAndAlerting. +- **E5.M1** — CombatRulesEngine. +- **E2.M4** — ProgressionPacingControls. +- **E3.M5** — EconomyBalancePolicy. + +## Dependents (by design) + +- Operations UI and automated rollback SLOs. + +## Related implementation slices + +Epic 9 **Slice 4** — `balance_patch_applied`, client config hash; rollback within agreed SLO. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 9. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md b/docs/decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md new file mode 100644 index 0000000..f0c8054 --- /dev/null +++ b/docs/decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md @@ -0,0 +1,44 @@ +# E9.M4 — IntegrityAndAbuseResponse + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M4 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Correlate exploit/bot signals from [E9.M1](E9_M1_TelemetryEventSchema.md) to `IncidentTicket` and `EnforcementAction` with audit trail. + +## Responsibilities + +- Ingest `IntegritySignal`; open/close incidents; log `EnforcementAction` for moderation and economy response. + +## Key contracts + +| Contract | Role | +|----------|------| +| `IntegritySignal` | Detection pipeline output. | +| `IncidentTicket` | Triage record. | +| `EnforcementAction` | Ban, rollback, warning with actor. | + +## Module dependencies + +- **E9.M1** — TelemetryEventSchema. + +## Dependents (by design) + +- **E6.M3** — LossPenaltyAndAntiGriefRules. +- **E8.M4** — ChatModerationAndReporting. + +## Related implementation slices + +Epic 9 **Slice 3** — known exploit replay produces ticket + action log; `integrity_signal`, `incident_open`, `enforcement_action`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 9. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/client_server_authority.md b/docs/decomposition/modules/client_server_authority.md new file mode 100644 index 0000000..325a591 --- /dev/null +++ b/docs/decomposition/modules/client_server_authority.md @@ -0,0 +1,84 @@ +# Client vs server authority (Neon Sprawl) + +This doc answers **who owns truth** for gameplay-relevant state and what the client may assume or predict. It complements [contracts.md](contracts.md) (what shapes cross the wire) and [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) (stack locks). + +--- + +## Default rule + +- **Server** is authoritative for anything that affects **persistence**, **other players**, **economy**, **progression**, **security / PvP policy**, or **anti-cheat**. +- **Client** owns **input**, **presentation**, **UI**, **camera framing**, and **optional local prediction** that must **reconcile** to the server without changing committed outcomes. + +Matches tech stack: client sends **intents**; server emits **state** (deltas or snapshots). Authoritative logic stays in **ASP.NET Core**, not Godot multiplayer templates. + +--- + +## Intents vs authoritative state + +| Direction | Content | Rule | +|-----------|---------|------| +| Client → server | **Intents** (move path, ability use, craft request, interact, chat, …) | Server validates every intent against rules, content, and current sim state. | +| Server → client | **Authoritative state** (`PositionState`, inventory, combat resolution, quest flags, zone tier, PvP eligibility, …) | Client displays and may predict; server wins on conflict. | + +Naming on the wire may use `*Command` or `*Intent` for client→server and `*State` / `*Resolution` / snapshots for server→client; the **role** (intent vs truth) matters more than the suffix. + +--- + +## By module (prototype defaults) + +### E1.M1: InputAndMovementRuntime + +- **Authoritative:** `PositionState` (and any rule derived from it: interaction range, zone presence) is owned by the **server** simulation. +- **Client:** Sends movement **intent** (e.g. destination, path id, or tick-aligned input—exact wire shape in Protobuf later). May **predict** the local avatar for responsiveness. +- **Reconciliation:** One documented ruleset: on server snapshot or correction, the client **must** converge to server truth (snap or blend—implementation choice; server outcome is final). Log material desync via [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md) when schema exists. +- **Deferred (not fixed here):** Sim tick rate, snapshot cadence, delta vs full snapshot protocol, and prediction smoothing curves—pick when networking MVP is scoped. + +### E1.M2: IsometricCameraController + +- **Authoritative:** **None** for prototype gameplay. Camera follow, zoom band, and occlusion are **client-local**; the server does **not** need `CameraState` for combat, zones, or PvP unless a future feature (e.g. replay) explicitly requires it. +- **Server:** Must not use client-reported camera pose for **gameplay checks** (targeting, line of sight, etc.); those use **world geometry + server-known positions**, not “what the player saw.” + +### E1.M3: InteractionAndTargetingLayer + +- **Authoritative:** Valid **target** and **interactable** eligibility (range, faction, phase, alive/dead) are decided on the **server**. Client sends selection or use **intent**; server responds with accepted `TargetState` or denial. +- **Client:** Hover, highlights, and tentative selection are presentation; may be wrong until server confirms. + +### E1.M4: AbilityInputScaffold + +- **Client:** Emits ability **intent** (`AbilityCastRequest` / equivalent) with ability id, target id, optional aim data as designed. +- **Server:** [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md) (and related systems) validate cooldowns, resources, range, facing/LOS rules, and [E6.M1](E6_M1_PvPEligibilityAndFlagState.md) where relevant; emits **CombatResolution** (or denies with reason). + +### E5.M1: CombatRulesEngine + +- **Never trust** client-supplied **damage**, **healing**, **crit rolls**, or **death** outcomes as source of truth. +- **Trust** only what the client can **observe** as intent: which action, which target, timing within tolerance—then **recompute** everything server-side from `SkillDef`, stats, and combat state. +- **Player targets:** Before applying hostile effects to another player, consult [E6.M1](E6_M1_PvPEligibilityAndFlagState.md) in-process; one combat engine for PvE and PvP — [details](pvp_combat_integration.md). + +### Economy, crafting, inventory, quests, zones, PvP + +- **E3.\*, E7.\*, E4.\*, E6.\*:** Commit state and validate requests **only** on the server; client UI is a **view** over server-driven data. Already assumed in epics; this doc makes the split explicit for implementers. + +--- + +## Telemetry and debugging + +- **Authority violations** (client assumed an outcome the server denied) should be **visible**: denied intents with reason codes, optional lightweight desync counters—not silent fixes in production without logging. + +--- + +## What this doc does not fix yet + +- Exact **network update rate** and **interest management** (who receives which entity updates). +- **Lag compensation** model for tab-target combat (if any)—decide with combat design and E5.M1 implementation. +- **Rollback** vs **hard snap** reconciliation for movement—engineering choice after first multiplayer vertical slice. + +Revisit when the first **Protobuf** game channel and a **multiplayer** milestone are defined. + +--- + +## Related docs + +- [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) — server-authoritative critical paths, intents vs state +- [contracts.md](contracts.md) — wire vs content artifacts +- [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 × E6.M1 integration shape +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md new file mode 100644 index 0000000..5aaa499 --- /dev/null +++ b/docs/decomposition/modules/contracts.md @@ -0,0 +1,89 @@ +# What a “contract” is (Neon Sprawl) + +Decomposition modules and the [dependency register](module_dependency_register.md) use **contract** as the name for a **stable boundary**: something two systems (client and server, two server subsystems, or server and content pipeline) can depend on without sharing an undocumented struct. + +This doc fixes **artifact types**, **ownership**, and **versioning** so “Contract needed” in the register is actionable. + +**Baseline stack alignment:** [tech stack](../../architecture/tech_stack.md) — authoritative server in C#; client in Godot/GDScript; **Protobuf** for versioned client–server messages (JSON acceptable only for the earliest spike); **JSON/YAML + JSON Schema** for content tables. **Who owns truth** for movement, camera, and combat: [client vs server authority](client_server_authority.md). + +--- + +## Contract kinds + + +| Kind | Use for | Authoritative form | Typical consumers | +| ------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| **Wire** | Player intents, state snapshots, RPC payloads crossing the network | **Protocol Buffer** `.proto` definitions; generated C# on server; mirrored types or codegen path in GDScript client | Client runtime, server host | +| **Server-internal** | Shapes used only inside the ASP.NET process (persistence DTOs, internal queues) until promoted | **C#** records/types in the server solution; behavior covered by tests | Server modules only | +| **Content** | Data-driven defs (`SkillDef`, `RecipeDef`, `QuestDef`, …) | **JSON or YAML** files + **JSON Schema** (or **CUE** later) validated in CI | Server load; tools; optional client bundles | +| **Telemetry** | Analytics and ops events ([E9.M1](E9_M1_TelemetryEventSchema.md)) | Versioned **event catalog** (JSON Schema or equivalent) + transport envelope; align names with OpenTelemetry where practical | Client emitters, ingest, dashboards | +| **HTTP (optional)** | Health, admin, or tooling — not the primary game sim path | **OpenAPI** if exposed; keep game loop on Protobuf per tech stack | Ops, CI, external tools | + + +A single logical name (e.g. `MoveCommand`) might appear as a **protobuf message** on the wire and a **different** internal server type that maps to/from it; the **wire schema** is what client and server must agree on. Until Protobuf exists for a message, a spike may use JSON with an explicit **throwaway** note in PRs and a tracked issue to migrate. + +--- + +## Mapping module “Key contracts” to kinds + +Rough default (exceptions per module): + +- **Intents and state sync** (`MoveCommand`, `PositionState`, `CombatAction`, `CombatResolution`, …) → **Wire** (protobuf). +- **Catalog / defs** (`RecipeDef`, `QuestDef`, `ItemDef`, `SkillDef`, …) → **Content** (files + JSON Schema). +- **Pure server resolution** (e.g. internal threat tables, idempotency keys not sent to client) → **Server-internal** until a client or tool needs them; then promote to wire or document as admin-only HTTP. + +When unsure, default to **wire protobuf** for anything the **Godot client** must send or interpret; default to **content + schema** for anything authored as **bulk data**. + +--- + +## Repository layout (convention) + +Paths are **conventions** until the first codegen lands; adjust in one doc PR when you add the first artifact. + + +| Artifact | Planned location | Notes | +| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `.proto` files | `contracts/proto/` (repo root) | Keeps schemas visible to both server and client tooling; generate C# into `server/` and client bindings per chosen Godot/protobuf workflow | +| JSON Schema for content | `contracts/schemas/content/` (or co-located `schema.json` next to data) | Validate in CI before server boot in strict modes | +| Telemetry catalog | `contracts/schemas/telemetry/` or under `docs/` until ingest exists | Must carry **schema / semver** for [E9.M1](E9_M1_TelemetryEventSchema.md) | + + +Server-only helpers stay next to features (e.g. `NeonSprawl.Server/Game/...`) until extracted to a shared assembly if multiple hosts need them. + +--- + +## Naming + +- Register and epics use **PascalCase** names (`CraftRequest`, `LevelUpEvent`). **Protobuf messages** use the same PascalCase style; **protobuf field names** follow `snake_case` in `.proto` if you adopt common style guides (generated C# still maps to idiomatic names). +- **JSON Schema** `$id` and file names should include a **version** or folder (`v1/`) when breaking changes ship. + +--- + +## Versioning and “Ready” + +- **Wire:** additive changes via new fields and reserved numbers; breaking changes require a **new message** or a negotiated major bump and client rollout strategy. +- **Content:** schema version in CI; server rejects or migrates unknown versions per policy. +- **Telemetry:** bump **EventSchemaVersion** (E9.M1); document in changelog for dashboards. + +A module’s register **Status** can move to **Ready** when the contracts it **exports** are published in the agreed form (proto checked in, or schema in CI, plus a minimal consumer test or stub). + +--- + +## What this doc does not decide + +- **Exact** Protobuf package layout and service vs unary choices — decide when the first real RPC is added. +- **Godot** protobuf library choice — tooling decision; still must consume the same `.proto` truth as the server. + +--- + +## Related docs + +- [tech stack](../../architecture/tech_stack.md) — Protobuf vs JSON spike, content validation, client/server split +- [Client vs server authority](client_server_authority.md) — intents vs state, E1/E5 defaults, deferred networking choices +- [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 gating with E6.M1, deny reasons +- [Quest scope and party rules](quest_scope_and_party.md) — per-character quest state, party credit, turn-in +- [Data reload and telemetry operations policy](data_and_ops_policy.md) — content reload, PII, sampling, retention, baseline events +- [Documentation and implementation alignment](documentation_and_implementation_alignment.md) — register Status vs repo, tracking table +- [Module dependency register](module_dependency_register.md) +- [Decomposition README](../README.md) + diff --git a/docs/decomposition/modules/data_and_ops_policy.md b/docs/decomposition/modules/data_and_ops_policy.md new file mode 100644 index 0000000..bae1976 --- /dev/null +++ b/docs/decomposition/modules/data_and_ops_policy.md @@ -0,0 +1,61 @@ +# Data reload and telemetry operations policy + +Prototype-through–early-pre-production rules for **how gameplay data is loaded and refreshed** (including progression curves and content tables) and **how telemetry is collected** (PII, sampling, retention, baseline events). Aligns with [contracts.md](contracts.md), [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md), and [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md). + +--- + +## Content and gameplay data reload + +Applies to **JSON/YAML** (or equivalent) loaded by the server: [E2.M1](E2_M1_SkillDefinitionRegistry.md) / [E2.M2](E2_M2_XpAwardAndLevelEngine.md) `LevelCurve` and skill data, items, recipes, quests, zones, etc. + + +| Environment / phase | Policy | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Prototype default** | Load at **process start** after **CI validation** (JSON Schema or agreed validators). No requirement for hot reload in the first milestone. | +| **Development** | Optional **file-watcher reload** or **developer-only** admin endpoint to re-read tables; must be **disabled or authenticated** in any shared/staging/prod-like deploy. Document the switch in server config. | +| **Tuning without redeploy** | Prefer **[E9.M3 — LiveBalanceControlPlane](E9_M3_LiveBalanceControlPlane.md)** and **[E2.M4](E2_M4_ProgressionPacingControls.md)** when those exist—not ad-hoc editing production disk files. | + + +**E2.M2:** Replace vague “reload policy TBD” with: **boot load** for prototype; optional dev reload as above; production path goes through gated balance patches per tech stack. + +--- + +## Telemetry: privacy and payload rules + +- **Identifiers:** Use **opaque** account/session/character ids in telemetry. Do not send email addresses, real names, billing identifiers, or unhashed hardware fingerprints in the default `ClientEventEnvelope` / event catalog. +- **User-generated content:** **No** free-form chat, player names, or report narrative in high-volume analytics streams unless a **separate**, access-controlled pipeline exists with stricter retention (integrity / moderation workflows may use different storage—see [E9.M4](E9_M4_IntegrityAndAbuseResponse.md), [E8.M4](E8_M4_ChatModerationAndReporting.md)). +- **Geo / device:** Collect only what is needed for stability and fraud signals; document any addition in the event catalog with purpose. +- **Envelope:** `ClientEventEnvelope` (or successor) carries **schema version**, **sampling** metadata, and a **privacy review flag** for events that need explicit approval before shipping to general ingest. + +--- + +## Sampling and volume + +- Follow vision plan **decision-driven instrumentation**: high-frequency signals (e.g. movement samples) are **sampled or bucketed**, not logged raw at full tick rate, unless a short-lived debug cohort is enabled. +- Each **high-volume** event class gets an explicit **default sample rate** in the E9.M1 catalog when defined; ops may raise/lower within agreed bounds. +- **Noise:** Prefer fewer, well-named events over many redundant ones; use `schema_version_mismatch` / ingest errors to catch client drift (see [Epic 9](../epics/epic_09_liveops_integrity.md) Slice 1). + +--- + +## Retention and storage + +- **Retention buckets** (raw vs aggregate, per-region legal requirements) are chosen when **ingest and storage** are provisioned—not fixed in this doc. Record the chosen values in runbooks or infra config. +- **Principle:** Raw events shorter retention; rolled-up KPIs longer. Integrity / incident artifacts may follow a **separate** retention policy under E9.M4. + +--- + +## Baseline event taxonomy: source of truth + +**Product baseline (categories and examples):** [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — section **“Event Instrumentation Baseline”** (session lifecycle, progression, economy, combat, PvP, system health), plus **“KPI and Telemetry Framework”** for what decisions the events must support. + +**Machine-readable schemas:** When implemented, the versioned catalog under the repo layout in [contracts.md](contracts.md) (e.g. `contracts/schemas/telemetry/`) is the **field-level** source of truth for implementers; the vision plan remains the **intent** check. If the two disagree, **fix the catalog** and note the vision update if product meaning changed. + +--- + +## Related docs + +- [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md) +- [E2.M2 — XpAwardAndLevelEngine](E2_M2_XpAwardAndLevelEngine.md) +- [contracts.md](contracts.md) +- [Module dependency register — cross-cutting: data reload and telemetry](module_dependency_register.md#cross-cutting-data-reload-and-telemetry) +- [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) diff --git a/docs/decomposition/modules/documentation_and_implementation_alignment.md b/docs/decomposition/modules/documentation_and_implementation_alignment.md new file mode 100644 index 0000000..7a24879 --- /dev/null +++ b/docs/decomposition/modules/documentation_and_implementation_alignment.md @@ -0,0 +1,55 @@ +# Documentation and implementation alignment + +The [module dependency register](module_dependency_register.md) **Status** column and each module’s summary table should **not silently disagree** with the repo. This doc defines how to keep decomposition docs truthful and where to record **partial** work. + +--- + +## Roles + +| Source | Role | +|--------|------| +| **Register + module markdown** | Intent, dependencies, contracts, policies (authority, PvP, quests, ops). | +| **Code + tests** | What actually runs; paths under `server/`, `client/`, etc. | +| **Plans** | `docs/plans/` (e.g. NS-* implementation plans) tie stories to acceptance criteria. | +| **This doc’s tracking table** | Quick **inventory** of modules that have started implementation; expand as work lands. | + +--- + +## Status column (register) + +| Status | Meaning | +|--------|---------| +| **Planned** | No meaningful implementation toward this module yet, or only unrelated spikes. | +| **In Progress** | At least one tracked story or code path exists toward the module; contracts may be partial. | +| **Ready** | Exported contracts meet [contracts.md](contracts.md) “Ready” guidance and dependents may integrate. | +| **Blocked** | Upstream module or external dependency prevents progress. | + +**Rule:** When a story merges that implements part of a module (API, store, schema), move that row from **Planned** to **In Progress** (or **Ready** when appropriate) in the same PR or a follow-up doc PR. + +**Partial modules** stay **In Progress** until the **prototype slice** for that module is satisfied or contracts are explicitly frozen for dependents. + +--- + +## Per-module docs + +Optional **`## Implementation snapshot`** (or a short bullet under Summary) on a module page: one paragraph + links to `docs/plans/…`, server paths, and [server README](../../../server/README.md) sections—avoid duplicating the full tracking table on every page. + +The **Summary** table **Status** field should match the register row for that module. + +--- + +## Implementation tracking table + +Rows appear when work starts; default for unlisted modules is **Planned** / not started. + + +| Module | Register status | Snapshot | Plans / pointers | +|--------|-----------------|----------|-------------------| +| E1.M1 | In Progress | Authoritative **read** `PositionState` over HTTP (JSON spike); in-memory store; no `MoveCommand` / client sync yet. | [NS-15 plan](../../plans/NS-15-implementation-plan.md); code: `server/NeonSprawl.Server/Game/PositionState/`; [server README — Position state](../../../server/README.md#position-state-ns-15) | + +--- + +## Related docs + +- [Module dependency register](module_dependency_register.md) +- [contracts.md](contracts.md) — versioning and Ready criteria diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index e0da946..3d4745e 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -1,24 +1,156 @@ # Module Dependency Register -Tracks cross-epic dependencies and contract readiness. +Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). + +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. **Data reload × telemetry ops:** **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. **Docs vs code:** **[Documentation and implementation alignment](documentation_and_implementation_alignment.md)**. + +Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). ## Dependency Table +### Epic 1 — Core Player Runtime + | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | |---|---|---|---|---|---| -| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState | Prototype | Planned | -| E1.M2 | IsometricCameraController | E1.M1 | CameraState, ZoomBandConfig | Prototype | Planned | -| E2.M2 | XpAwardAndLevelEngine | E2.M1 | XpGrantEvent, LevelUpEvent | Prototype | Planned | -| E3.M2 | RefinementAndRecipeExecution | E3.M1, E3.M3 | CraftRequest, CraftResult | Prototype | Planned | -| E5.M1 | CombatRulesEngine | E1.M3, E2.M2 | CombatAction, CombatResolution | Prototype | Planned | +| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState, InteractionRequest | Prototype | In Progress | +| E1.M2 | IsometricCameraController | E1.M1 | CameraState, ZoomBandConfig, OcclusionPolicy | Prototype | Planned | +| 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 + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E2.M1 | SkillDefinitionRegistry | None | SkillDef, SkillCategory, UnlockRequirement | 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 | + +### Epic 3 — Crafting Economy + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E3.M1 | ResourceNodeAndGatherLoop | E1.M3, E2.M2 | ResourceNodeDef, GatherResult, ResourceYieldTable | Prototype | Planned | +| E3.M2 | RefinementAndRecipeExecution | E3.M1, E3.M3 | RecipeDef, CraftRequest, CraftResult | Prototype | Planned | +| E3.M3 | ItemizationAndInventorySchema | None | ItemDef, ItemInstance, InventorySlot | Prototype | Planned | +| E3.M4 | SinkAndDurabilityLifecycle | E3.M3, E8.M3 | DurabilityState, ItemSinkEvent, RepairCostRule | Pre-production | Planned | +| E3.M5 | EconomyBalancePolicy | E3.M4, E9.M2 | EconomyPolicy, PriceBandRule, FaucetSinkRatio | Pre-production | Planned | + +### Epic 4 — World Topology + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E4.M1 | ZoneGraphAndTravelRules | None | ZoneDef, ZoneEdge, TravelRule | Prototype | Planned | +| E4.M2 | SpawnEcologyController | E4.M1, E3.M1, E5.M2 | SpawnProfile, RespawnRule, ZoneEcologyState | Pre-production | Planned | +| E4.M3 | SeamlessHandoffAndRegionState | E4.M1 | RegionHandoffEvent, RegionAuthority, TransferState | Pre-production | Planned | | E4.M4 | SecurityTierZoneFlags | E4.M1 | SecurityTier, ZonePolicyState, ZoneEntryWarning | Prototype | Planned | -| E6.M1 | PvPEligibilityAndFlagState | E4.M4 | PvPFlagState, EligibilityRule | Prototype | Planned | -| E7.M1 | QuestStateMachine | E3.M2, E5.M1 | QuestStateTransition | Prototype | Planned | -| E9.M1 | TelemetryEventSchema | None | TelemetryEvent envelope | Prototype | Planned | + +**E4.M3:** Epic also references backend world services for region authority; treat as external integration alongside E4.M1 contracts. + +### Epic 5 — PvE Combat + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E5.M1 | CombatRulesEngine | E1.M3, E2.M2 | CombatAction, CombatResolution, ThreatState | Prototype | Planned | +| E5.M2 | NpcAiAndBehaviorProfiles | E5.M1 | NpcBehaviorDef, TelegraphEvent, AggroRule | Prototype | Planned | +| E5.M3 | EncounterAndRewardTables | E5.M1, E3.M3, E7.M2 | EncounterDef, RewardTable, EncounterCompleteEvent | Prototype | Planned | +| E5.M4 | GroupCombatScaling | E5.M3, E8.M1 | ScalingProfile, PartySizeModifier, CombatDifficultyBand | Pre-production | Planned | + +### Epic 6 — PvP Security + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E6.M1 | PvPEligibilityAndFlagState | E4.M4 | PvPFlagState, EligibilityRule, PvPStateChanged | Prototype | Planned | +| E6.M2 | ConsentAndRiskUxSignals | E6.M1, E1.M2 | RiskPrompt, ZoneRiskState, PvPIndicatorState | Prototype | Planned | +| E6.M3 | LossPenaltyAndAntiGriefRules | E6.M1, E9.M4 | PvPLossRule, SpawnProtectionState, GriefingStrike | Pre-production | Planned | +| E6.M4 | RewardParityEnforcer | E3.M2, E5.M3, E7.M2 | RewardParityMap, EquivalentPowerBand, ParityViolationAlert | Prototype | Planned | + +### Cross-cutting: combat and PvP eligibility + +When hostile actions can target **players**, [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md) **must** consult [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) in the same server handling path before applying effects. **PvE-only** milestones may use a **stub** that denies all player-target hostility until PvP is enabled. Shape and deny reasons: **[PvP and the combat engine](pvp_combat_integration.md)**. + +### Cross-cutting: quests and party + +Quest state is **per-character** by default; **party credit** and **leader-only turn-in** use [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md) when enabled in `QuestDef`. Solo milestones need no party service. Details: **[Quest scope and party rules](quest_scope_and_party.md)**. + +### Cross-cutting: data reload and telemetry + +Gameplay **content and curves** default to **boot load** with optional **dev-only** reload; live tuning defers to **E9.M3 / E2.M4** when available. **Telemetry:** PII rules, sampling, retention principles, and **baseline event taxonomy** (vision plan + future catalog). See **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. + +### Epic 7 — Quest / Faction + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E7.M1 | QuestStateMachine | E3.M2, E5.M1 | QuestDef, QuestStepState, QuestStateTransition | Prototype | Planned | +| E7.M2 | RewardAndUnlockRouter | E2.M2, E3.M3, E7.M1 | QuestRewardBundle, UnlockGrant, RewardDeliveryEvent | Prototype | Planned | +| E7.M3 | FactionReputationLedger | E7.M1 | FactionStanding, ReputationDelta, FactionGateRule | Pre-production | Planned | +| E7.M4 | ContractMissionGenerator | E4.M1, E5.M3, E7.M3 | ContractTemplate, ContractSeed, ContractOutcome | Pre-production | Planned | + +### Epic 8 — Social / Guild + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E8.M1 | PartyAndMatchAssembly | E1.M3 | PartyState, InviteEvent, RolePreference | Pre-production | Planned | +| E8.M2 | GuildCorpProgressionState | E8.M1, E7.M3 | GuildState, GuildRolePolicy, GuildProgressionEvent | Production | Planned | +| E8.M3 | PlayerTradeAndMarketplace | E3.M3, E3.M5 | MarketListing, TradeOffer, SettlementEvent | Pre-production | Planned | +| E8.M4 | ChatModerationAndReporting | E9.M4 | ChatMessageEvent, PlayerReport, ModerationAction | Pre-production | Planned | + +### Epic 9 — LiveOps / Integrity + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E9.M1 | TelemetryEventSchema | None | TelemetryEvent, EventSchemaVersion, ClientEventEnvelope | Prototype | Planned | +| E9.M2 | KpiDashboardsAndAlerting | E9.M1 | KpiDefinition, AlertThreshold, MilestoneGateSignal | Pre-production | Planned | +| E9.M3 | LiveBalanceControlPlane | E9.M2, E5.M1, E2.M4, E3.M5 | BalancePatch, ConfigVersion, RolloutState | Production | Planned | +| E9.M4 | IntegrityAndAbuseResponse | E9.M1 | IntegritySignal, IncidentTicket, EnforcementAction | Pre-production | Planned | + +## Per-module documentation + +| Module ID | Document | +|-----------|----------| +| E1.M1 | [E1_M1_InputAndMovementRuntime.md](E1_M1_InputAndMovementRuntime.md) | +| E1.M2 | [E1_M2_IsometricCameraController.md](E1_M2_IsometricCameraController.md) | +| E1.M3 | [E1_M3_InteractionAndTargetingLayer.md](E1_M3_InteractionAndTargetingLayer.md) | +| E1.M4 | [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md) | +| E2.M1 | [E2_M1_SkillDefinitionRegistry.md](E2_M1_SkillDefinitionRegistry.md) | +| E2.M2 | [E2_M2_XpAwardAndLevelEngine.md](E2_M2_XpAwardAndLevelEngine.md) | +| E2.M3 | [E2_M3_MasteryAndPerkUnlocks.md](E2_M3_MasteryAndPerkUnlocks.md) | +| E2.M4 | [E2_M4_ProgressionPacingControls.md](E2_M4_ProgressionPacingControls.md) | +| E3.M1 | [E3_M1_ResourceNodeAndGatherLoop.md](E3_M1_ResourceNodeAndGatherLoop.md) | +| E3.M2 | [E3_M2_RefinementAndRecipeExecution.md](E3_M2_RefinementAndRecipeExecution.md) | +| E3.M3 | [E3_M3_ItemizationAndInventorySchema.md](E3_M3_ItemizationAndInventorySchema.md) | +| E3.M4 | [E3_M4_SinkAndDurabilityLifecycle.md](E3_M4_SinkAndDurabilityLifecycle.md) | +| E3.M5 | [E3_M5_EconomyBalancePolicy.md](E3_M5_EconomyBalancePolicy.md) | +| E4.M1 | [E4_M1_ZoneGraphAndTravelRules.md](E4_M1_ZoneGraphAndTravelRules.md) | +| E4.M2 | [E4_M2_SpawnEcologyController.md](E4_M2_SpawnEcologyController.md) | +| E4.M3 | [E4_M3_SeamlessHandoffAndRegionState.md](E4_M3_SeamlessHandoffAndRegionState.md) | +| E4.M4 | [E4_M4_SecurityTierZoneFlags.md](E4_M4_SecurityTierZoneFlags.md) | +| E5.M1 | [E5_M1_CombatRulesEngine.md](E5_M1_CombatRulesEngine.md) | +| E5.M2 | [E5_M2_NpcAiAndBehaviorProfiles.md](E5_M2_NpcAiAndBehaviorProfiles.md) | +| E5.M3 | [E5_M3_EncounterAndRewardTables.md](E5_M3_EncounterAndRewardTables.md) | +| E5.M4 | [E5_M4_GroupCombatScaling.md](E5_M4_GroupCombatScaling.md) | +| E6.M1 | [E6_M1_PvPEligibilityAndFlagState.md](E6_M1_PvPEligibilityAndFlagState.md) | +| E6.M2 | [E6_M2_ConsentAndRiskUxSignals.md](E6_M2_ConsentAndRiskUxSignals.md) | +| E6.M3 | [E6_M3_LossPenaltyAndAntiGriefRules.md](E6_M3_LossPenaltyAndAntiGriefRules.md) | +| E6.M4 | [E6_M4_RewardParityEnforcer.md](E6_M4_RewardParityEnforcer.md) | +| E7.M1 | [E7_M1_QuestStateMachine.md](E7_M1_QuestStateMachine.md) | +| E7.M2 | [E7_M2_RewardAndUnlockRouter.md](E7_M2_RewardAndUnlockRouter.md) | +| E7.M3 | [E7_M3_FactionReputationLedger.md](E7_M3_FactionReputationLedger.md) | +| E7.M4 | [E7_M4_ContractMissionGenerator.md](E7_M4_ContractMissionGenerator.md) | +| E8.M1 | [E8_M1_PartyAndMatchAssembly.md](E8_M1_PartyAndMatchAssembly.md) | +| E8.M2 | [E8_M2_GuildCorpProgressionState.md](E8_M2_GuildCorpProgressionState.md) | +| E8.M3 | [E8_M3_PlayerTradeAndMarketplace.md](E8_M3_PlayerTradeAndMarketplace.md) | +| E8.M4 | [E8_M4_ChatModerationAndReporting.md](E8_M4_ChatModerationAndReporting.md) | +| E9.M1 | [E9_M1_TelemetryEventSchema.md](E9_M1_TelemetryEventSchema.md) | +| E9.M2 | [E9_M2_KpiDashboardsAndAlerting.md](E9_M2_KpiDashboardsAndAlerting.md) | +| E9.M3 | [E9_M3_LiveBalanceControlPlane.md](E9_M3_LiveBalanceControlPlane.md) | +| E9.M4 | [E9_M4_IntegrityAndAbuseResponse.md](E9_M4_IntegrityAndAbuseResponse.md) | ## Status Legend -- Planned: identified but not implemented -- In Progress: currently being implemented -- Ready: contract stable and usable by dependents -- Blocked: dependency missing or unstable +- **Planned:** No meaningful implementation toward this module yet (see [documentation and implementation alignment](documentation_and_implementation_alignment.md)). +- **In Progress:** Partial implementation or active stories; contracts may be incomplete. +- **Ready:** Contract stable and usable by dependents ([contracts.md](contracts.md)). +- **Blocked:** Dependency missing or unstable. + +**Tracking table** (modules with code or plans in flight): [documentation_and_implementation_alignment.md — Implementation tracking table](documentation_and_implementation_alignment.md#implementation-tracking-table). diff --git a/docs/decomposition/modules/pvp_combat_integration.md b/docs/decomposition/modules/pvp_combat_integration.md new file mode 100644 index 0000000..e831782 --- /dev/null +++ b/docs/decomposition/modules/pvp_combat_integration.md @@ -0,0 +1,51 @@ +# PvP and the combat engine + +This doc fixes **how** [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) connects to [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md): one pipeline vs a forked “PvP combat” module, and how denials surface on the wire. + +Complements [client_server_authority.md](client_server_authority.md) (authority) and [contracts.md](contracts.md) (artifact types). + +--- + +## Decision: single combat rules engine + +**Default for Neon Sprawl:** **E5.M1** is the **only** combat resolution engine for tab-target play. **Player vs player** uses the **same** code path as **player vs NPC** for formulas that should stay aligned (hit checks, cooldowns, resources, ability application), with **extra gating** when the target (or victims in an AoE) include **players**. + +**Do not** introduce a separate “PvP combat engine” for the prototype unless design later proves **irreconcilable** rule divergence. If that happens, prefer a **shared resolution kernel** (pure functions / shared module) plus **policy profiles** (PvE vs PvP) rather than two divergent engines. + +**Rationale:** One engine reduces duplicate bugs, keeps `CombatAction` / `CombatResolution` as a single wire story, and matches optional-PvP product goals (PvP is policy on top of the same abilities, not a different game). + +--- + +## Where E6.M1 plugs in + +- **When:** During **validation** of a `CombatAction` (or internal equivalent) **before** applying damage, debuffs, displacement, or other hostile effects to another **player** character. +- **Who calls whom:** **E5.M1** calls into **E6.M1** (or an abstraction it owns, implemented by E6.M1) — e.g. `CanApplyHostility(attacker, target, actionContext) → Allow | Deny(reason)`. +- **Consistency:** Use **current server** eligibility and zone policy for that tick/request; avoid stale client-only flags. If eligibility is cached per session, invalidate on zone transition and on `PvPStateChanged`. + +**NPC targets:** No E6.M1 check for ordinary PvE (unless a future rule ties NPC combat to zone policy — then call out explicitly). + +**Register note:** Epic 5 lists E5.M1 dependencies as E1.M3 and E2.M2 only. **Enabling player-target hostility** adds a **logical** dependency on E6.M1; PvE-only milestones may ship with a **stub** implementation that denies all player-target hostility until Epic 6 wiring lands. See [cross-cutting note in the dependency register](module_dependency_register.md#cross-cutting-combat-and-pvp-eligibility). + +--- + +## Deny reasons and telemetry + +PvP blocks must be **first-class** in combat outcomes, not silent failures: + +- Extend the combat deny / `CombatResolution` reason set (or parallel field) with stable codes such as: `pvp_forbidden_in_zone`, `attacker_pvp_not_eligible`, `target_pvp_not_eligible`, `pvp_consent_required`, `pvp_flag_mismatch` (exact names to be frozen when Protobuf enums are defined). +- Align high-signal events with [E9.M1](E9_M1_TelemetryEventSchema.md) (e.g. ability denied with reason) and Epic 6 hooks (`pvp_state_changed`, zone enter/exit) without double-counting. + +--- + +## E6.M3 and beyond + +**E6.M3** (loss, spawn protection, grief strikes) applies **after** hostility is **allowed** by E6.M1 and **resolved** by E5.M1 (e.g. on death in PvP context). Order: **eligibility → combat resolution → loss/anti-grief rules**. + +--- + +## Related docs + +- [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md) +- [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) +- [Client vs server authority](client_server_authority.md) +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/quest_scope_and_party.md b/docs/decomposition/modules/quest_scope_and_party.md new file mode 100644 index 0000000..eb6e04e --- /dev/null +++ b/docs/decomposition/modules/quest_scope_and_party.md @@ -0,0 +1,69 @@ +# Quest scope and party rules + +This doc fixes **solo vs party** quest behavior: where `QuestStepState` lives, who gets credit, who can turn in, and how open-world vs instanced scope is handled. It complements [E7.M1 — QuestStateMachine](E7_M1_QuestStateMachine.md), [E7.M2 — RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md), and [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md). + +--- + +## Persistence: per-character by default + +- **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. + +--- + +## Quest modes (content-driven) + +Express in **`QuestDef`** (or equivalent content) — exact field names are for the content schema when added: + +| Mode | Behavior | +|------|----------| +| **Solo (default)** | Objectives and completion use **only** the acting character. No read of [E8.M1](E8_M1_PartyAndMatchAssembly.md) `PartyState`. | +| **Party credit** | When an objective completes, the server evaluates **eligible party members** and advances **each** eligible character’s `QuestStepState` **idem**potently (same step transition, no double-apply). Eligibility rules are data-driven, e.g. in zone, within distance of completer, alive, was in party when step started—minimum set TBD per quest in content. | +| **Leader-only turn-in (optional)** | If set, only the **party leader** (per authoritative `PartyState`) may trigger the final hand-in / complete interaction; otherwise **any** character in completable state may turn in. | + +**Starting / accepting:** Each character **accepts** the quest individually unless content defines a rare “party accepts as one” flow (defer unless needed); prototype can require all intended recipients to accept the same quest id. + +--- + +## Party dependency + +- **Party credit** and **leader-only turn-in** require server-authoritative **party membership** from [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md). +- **Milestone ordering:** Solo quests ship without E8.M1. **Party-credit** quests are **gated** until E8.M1 (or a minimal stub that returns “solo only”) exists; document in slice plans. + +--- + +## Rewards: E7.M2 + +- After completion, **rewards are granted per character** with **idempotent** keys (e.g. `(character_id, quest_id, completion_epoch_or_counter)`). +- If **party credit** advanced multiple characters to completion in one logical event, **each** receives their bundle per `QuestRewardBundle` rules (same bundle vs per-role bundles—content choice). + +--- + +## Open world vs instances (prototype) + +- **Prototype default:** Objectives live in **shared zones** ([E4.M1](E4_M1_ZoneGraphAndTravelRules.md)); no separate quest instance id required. +- **Instanced steps (later):** When dungeon / private instance exists, bind objectives to an **`instance_id`** (or shard key) so credit does not leak across instances. Wire when instance module and E4 handoff slices define the authoritative instance handle. + +--- + +## Edge cases (explicit) + +- **Member leaves party mid-quest:** Per-character state **freezes** at last server-advanced step unless `QuestDef` defines abandon-on-leave. No implicit merge of two solo runs into one party run. +- **Disband:** Same as leave for remaining members; leader-only turn-in re-evaluates on next `PartyState` update. + +--- + +## Telemetry + +- Emit `quest_step_complete` / `quest_complete` **per character** credited; optional correlation id linking party-synchronized advances for funnel debugging. + +--- + +## Related docs + +- [E7.M1 — QuestStateMachine](E7_M1_QuestStateMachine.md) +- [E7.M2 — RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md) +- [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md) +- [Module dependency register — cross-cutting: quests and party](module_dependency_register.md#cross-cutting-quests-and-party)