don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/neon_sprawl_vision.plan.md

46 KiB
Raw Blame History

name overview isProject
Neon Sprawl Vision Create a 50,000-foot planning document for Neon Sprawl, a sci-fi/cyberpunk MMORPG inspired by RuneScape, focused on hybrid progression (combat **gigs** and open non-combat **skills**) and deep crafting, with optional PvP and questing. false

Neon Sprawl — 50,000-Foot Plan

Vision and Product Intent

Neon Sprawl is a long-lived online world that captures the freedom and progression depth of RuneScape while delivering a distinct sci-fi/cyberpunk identity. The core player fantasy is to start as a low-tier citizen of a mega-city ecosystem and grow into a high-impact operator through any combination of skills, professions, social play, and questlines.

Design axioms (governing)

These two principles override narrower preferences when they conflict:

  1. It must be fun — Engagement and player experience are the filter for scope, pacing, and systems: if it is not enjoyable to play, it is not succeeding regardless of architectural elegance.
  2. It must be distinctly cyberpunk in theme — Fiction, tone, and presentation should read as cyberpunk (mega-city decay, corp power, street tech, body and identity under pressure), not interchangeable sci-fi or fantasy with surface chrome. Other constraints (e.g. presentation and rating targets in game-design docs) still apply; the axiom means bias toward recognizable cyberpunk identity when choosing between otherwise viable options.

Delivery Model Constraint (Locked)

  • Team model (locked): Solo developer with AI assistant support; all roadmap, scope, and technical decisions must be feasible for one human operator.
  • Execution principle: Prefer smallest shippable slices, heavy reuse of data-driven systems, and ruthless deferral of non-core features.

Experience Pillars

  • Open skill training: Every character can learn and level every non-combat skill over time; combat identity uses gigs (swappable roles). Identity also comes from choices, gear, economy role, and mastery paths.
  • Crafting-first economy: Crafting and gathering are central progression loops, not side systems; player-made goods should matter at every stage.
  • Persistent social world: Shared hubs, guilds/corps, trading, and cooperative activities should be core to retention.
  • Meaningful progression: Long-term goals, visible advancement, and layered progression loops (short, mid, long horizons).
  • Quest-driven worldbuilding: Narrative arcs reveal factions, districts, corporate politics, and world-state tensions.
  • Readable tactical presentation: 3D world rendered through a fixed, character-centered isometric camera for clarity and consistency.
  • PvE-first with optional PvP: PvP exists as opt-in content in designated security zones, never as a mandatory progression gate.

Big Product Scope (What Must Exist)

  • World foundation: Persistent zones, cities, wilderness/industrial sectors, instanced content where needed.
  • Core MMO loops: Movement, interaction, combat (PvE mandatory; PvP optional), loot, death/penalty rules.
  • Skill system: Multi-skill progression covering gathering, processing, crafting, combat, exploration, utility/social.
  • Crafting ecosystem: Resource acquisition, recipes/blueprints, quality tiers, item sinks, repair/decay, specialization edges.
  • Economy and trade: Currency strategy, NPC sinks/faucets, player marketplace/trading, anti-inflation tools.
  • Questing framework: Main arcs, faction missions, repeatable jobs, dynamic contracts, tutorial onboarding quests.
  • Social systems: Chat, groups, guild/corp structures, friends, cooperative content.
  • Live operations: Events, seasonal arcs, balancing cadence, telemetry, moderation, support workflows.
  • Camera and controls model: Locked isometric 3D view, zoom support, no camera rotation, and continuous character-centering.
  • Security-zone ruleset: Clear high/medium/low-security area rules that define where PvP is allowed, restricted, or disallowed.

Design Decisions to Lock Early (Critical Unknowns)

These decisions heavily affect architecture and content pipelines and should be resolved before deep production:

  • Camera model (locked): 3D fixed isometric view, zoom in/out enabled, no rotation, camera always centered on the player character.
  • Combat model (locked): Tab-target tactical combat (RuneScape-like readability and pacing) with clear telegraphs and ability timing.
  • PvP policy (locked): PvE-first, opt-in PvP via security-level zones; no player is required to PvP for core progression.
  • World topology (locked): Mostly seamless open world with regional zoning and minimal/surgical instancing where strictly needed.
  • Economy strictness: Player-driven with limited NPC intervention vs more curated economy.
  • Progression velocity: Slow-burn old-school pacing vs modernized pacing with catch-up systems.
  • Death and loss model: Cosmetic penalties, durability loss, resource drop, or gear risk.

Gameplay Architecture (Macro)

1) Player Progression Architecture

  • Horizontal + vertical progression: Skills level up; mastery unlocks efficiency, recipes, perks, and advanced content access.
  • Soft identity without classes: Loadouts, implants, cyberware, weapon proficiencies, and crafted gear create build expression.
  • Progression safeguards: Diminishing returns, training bottlenecks, and sink systems to preserve long-term goals.

2) Crafting and Economy Architecture

  • Resource ladder: Raw materials -> refined components -> advanced modules -> high-end gear/consumables.
  • Crafting depth: Quality rolls, optional minigames/process control, blueprint rarity, experimental modifiers.
  • Market health controls: Crafting demand via item decay/upkeep, consumable usage, quest contracts, upgrade loops.
  • Role interdependence: No single skill line should be fully self-sufficient at endgame efficiency.

3) Quest and Content Architecture

  • Narrative layers: Main storyline, faction arcs, district stories, profession questlines.
  • Systemic contracts: Procedural or semi-procedural missions to supply endless midgame activities.
  • Progression-linked content: Quests unlock areas, facilities, blueprints, and social reputation paths.

4) Combat and Encounter Architecture

  • PvE baseline: Solo, duo/squad, and group-scale activities with variable challenge and rewards.
  • Tab-target foundation: Readable targeting, cooldown/resource management, and positioning decisions over twitch-heavy execution.
  • Boss/raid-lite loops: Repeatable high-value encounters feeding economy and social engagement.
  • PvP zone architecture: PvP enabled only in defined low-security spaces and specific opt-in contexts.
  • Progression parity rule: PvP-exclusive rewards must have a PvE and/or crafting path to equivalent or near-equivalent power.
  • Horizontal PvP rewards: PvP can grant unique cosmetics, variants, sidegrades, titles, and utility flavor without hard power lockout.
  • Isometric combat readability: Telegraphs, hit feedback, verticality handling, and target visibility designed for fixed-angle play.

6) PvP Governance and Fairness Architecture

  • Security levels: High-security (no PvP), contested/security-transition zones (limited PvP conditions), low-security (open PvP rules).
  • Consent clarity: Strong UI/state signaling when entering PvP-enabled areas and clear loss/risk expectations.
  • Non-mandatory progression: Main questing, skill advancement, and key gear tiers remain fully obtainable via PvE/crafting.
  • Reward equivalency policy: If PvP has an exclusive item archetype, provide PvE/crafting alternatives with comparable functional value.
  • Abuse controls: Anti-griefing protections, spawn safety, and guardrails for low-level/new-player experiences.

5) Social and Community Architecture

  • Guild/Corp systems: Shared progression goals, facilities, contracts, and territory/economic objectives.
  • Community retention: Events, cooperative milestones, social rewards, mentorship/new-player integration.
  • Trust/safety: Anti-toxicity systems, moderation workflows, reporting, and escalation.

Technical and Production Architecture (Macro)

Tech stack (baseline — prototype / early pre-production)

Decision record: docs/architecture/tech_stack.md

  • Client: Godot 4.x — isometric 3D presentation, intents to server, no client-authoritative economy or combat outcomes.
  • Game server: C# / .NET 10 (ASP.NET Core)—authoritative simulation, PostgreSQL, Protobuf (JSON acceptable for earliest spike). Locked: operator primary language for backend.
  • Content: JSON/YAML + schema validation in CI; shared definitions drive skills, items, recipes, quests.
  • Plan B: Unity client if the art pipeline warrants it; server remains C# for continuity.

Platform and Engine (constraints)

  • Networking and toolchain must stay feasible for solo operation; prefer boring, debuggable server tech.
  • Prioritize deterministic-ish server authority and robust backend observability from day one.
  • Ensure rendering/input/camera stack supports fixed isometric projection, zoom tiers, occlusion handling, and always-centered follow behavior.

Backend/Core Services

  • Account and identity
  • Character and progression state
  • Inventory and itemization
  • Economy/marketplace
  • Quest/state machines
  • Social/guild/chat
  • Analytics and live-ops controls
  • World streaming and shard orchestration (support large persistent regions with controlled handoffs)

Content Pipeline

  • Data-driven systems for skills, items, recipes, quests, NPCs, and encounter tuning.
  • Authoring tools for designers/writers to ship safely without deep engineering dependency.
  • Validation and balancing pipeline to catch broken recipes/economy exploits before release.

Security and Integrity

  • Server-authoritative critical actions (progression, trades, combat outcomes).
  • Anti-cheat, anti-bot, fraud detection, and exploit response processes.

Development Roadmap at 50,000 Feet

Phase 0 - Vision Alignment and Risk Burn-down

  • Lock pillars, target audience, and design constraints.
  • Resolve remaining critical unknown (progression velocity), with camera/PvP/combat/topology fixed.
  • Build paper economy and progression models.
  • Define success metrics for prototype and pre-production.

Phase 1 - Prototype (Prove the Core Fun)

  • Deliver a playable vertical prototype proving:
    • Movement + interaction in shared space
    • Locked isometric camera behavior (center-follow, zoom ranges, no rotation)
    • Security-zone PvP rules (high-sec safe zone vs low-sec opt-in combat zone)
    • Basic combat loop
    • Skill gain loop
    • Gather -> craft -> use/sell loop
    • Minimal quest loop
  • Run small closed tests focused on “is this actually fun and sticky?”.

Prototype Scope Definition

Prototype Objective

Prove that the core gameplay loop is fun, readable, and repeatable in a controlled slice before broad world/content expansion.

Prototype Build Target

  • Single contained test region: One compact district with a safe hub, nearby PvE combat pocket, and a low-security edge zone.
  • Playable session length: 30-60 minute loop where players can complete a full gather -> craft -> combat -> reward cycle.
  • Concurrent users target: Small-scale multiplayer validation (e.g., internal team and invited external cohort), not production load.

In-Scope Features (Must Have)

  • Movement and camera: Locked isometric camera, follow-center behavior, zoom bands, and occlusion handling.
  • Combat MVP (tab-target): Target selection, basic auto/basic attack flow, 4-6 starter abilities, cooldown/resource model, enemy telegraphs.
  • Skill gain loop: At least 3 skills represented (one gathering, one crafting, one combat) with visible XP gain and level-up feedback.
  • Crafting loop: Gather node -> refine component -> craft usable item (weapon, armor piece, or consumable) with material costs.
  • Quest loop: 3-5 onboarding quests plus one chain quest that requires gathering/crafting/combat in sequence.
  • PvP rules MVP: High-security no-PvP hub and low-security opt-in zone with clear UI signaling and no progression-gated rewards.
  • Reward parity example: One PvP-oriented sidegrade with a PvE or crafting equivalent of similar functional power.

Out-of-Scope Features (Explicitly Deferred)

  • Full zone streaming across multiple regions.
  • Advanced guild systems, player housing, large-scale market depth, and endgame raids.
  • Full narrative arc breadth and extensive faction branching.
  • Launch-grade anti-cheat and complete live-ops tooling depth.

Prototype Content Minimums

  • Enemies: 3 archetypes (melee pressure, ranged control, elite mini-boss).
  • Resources: 4-6 node types with tiered outputs.
  • Recipes: 8-12 starter recipes across gear and consumables.
  • Quests: 5-8 total quests, including one integrated multi-system questline.

Pass/Fail Gates (Go/No-Go)

  • Core fun gate: Majority of test players complete at least two full loop cycles voluntarily in one session.
  • Readability gate: Players understand combat telegraphs, target state, and zone PvP status without external coaching.
  • Progression gate: Players clearly perceive skill advancement and short-term goals within first 15 minutes.
  • Crafting relevance gate: Crafted items are used in combat or quest completion at meaningful rates.
  • PvP optionality gate: Non-PvP participants can complete all prototype progression goals with no material disadvantage.

Validation Metrics for Prototype

  • Session length and loop completions per player.
  • Time-to-first-combat, time-to-first-craft, and time-to-first-level-up.
  • Quest completion funnel and early churn points.
  • PvP zone entry rate, opt-out behavior, and parity satisfaction sentiment.

Exit Criteria to Pre-Production

  • Prototype passes at least 4 of 5 go/no-go gates across two consecutive test rounds.
  • Highest-impact usability/combat/crafting issues triaged with clear follow-up owners.
  • Confirmed recommendation on progression pace direction (remaining unresolved decision).

Phase 2 - Pre-Production (Build the Machine)

  • Establish final technical architecture, tools, and standards.
  • Implement foundational backend services and data schemas.
  • Build scalable content pipelines for quests, items, and skills.
  • Produce a polished vertical slice with representative quality.

Pre-Production Deliverables

Objective

Transform the validated prototype into a scalable production-ready development machine across engineering, design, content, and operations.

Workstreams and Deliverables

1) Engineering Architecture and Platform

  • Engine/runtime baseline: Frozen engine version, performance budgets, networking model constraints, and build targets.
  • Service architecture: Character/progression, inventory/itemization, economy, quest state, social/chat, telemetry services with interface contracts.
  • World services: Regional zoning, handoff strategy, shard policy, and failover/recovery behavior definitions.
  • Dev infrastructure: CI pipelines, automated build verification, environment promotion flow (dev/stage/test), and release branch policy.

2) Gameplay Systems and Data Contracts

  • Combat specs: Final tab-target rules, stat formulas, ability schema, threat/aggro model, and encounter tuning framework.
  • Progression specs: Skill XP curves, unlock dependencies, pacing knobs, catch-up policy stance, and level band definitions.
  • Economy specs: Currency faucets/sinks, crafting input/output ratios, durability/consumption sinks, and parity constraints (PvP vs PvE/crafting).
  • PvP zone specs: Security tier rules, opt-in boundaries, penalties/loss model, anti-griefing safeguards, and reward-sidegrade policy.

3) Content Pipeline and Authoring Tools

  • Schema standards: Versioned data schemas for items, skills, recipes, quests, NPCs, and loot tables.
  • Authoring workflow: Designer-facing tools/templates for quest scripting, encounter setup, item/recipe creation, and validation.
  • Quality gates: Lint/validation for broken references, invalid progression locks, economy outliers, and reward parity violations.
  • Content throughput targets: Expected per-sprint output capacity for quests, recipes, and encounters to sustain production velocity.

4) Vertical Slice Quality Bar

  • Slice composition: One district-quality slice with representative art style, final-ish UX standards, quest chain, combat encounters, and crafting progression.
  • Performance bar: Stable frame-rate target and acceptable latency envelope under expected slice concurrency.
  • User experience bar: Readable combat, understandable progression, clear PvP zone signaling, and smooth onboarding.
  • Polish bar: Audio/UI feedback baseline, bug severity thresholds, and crash stability criteria.

5) Team Process and Governance

  • Solo ownership model: Single owner across design/engineering/content with AI-assisted implementation and documentation workflows.
  • Milestone cadence: Lightweight weekly planning/review loop, monthly milestone gate, and explicit WIP limits to prevent context fragmentation.
  • Change control: Strict backlog triage, decision log, and rule that new scope replaces existing scope (no additive expansion without cuts).
  • Automation-first workflow: CI checks, test templates, codegen/helpers, and repeatable scripts to reduce manual operational load.

Stage Gates (Pre-Production Pass/Fail)

  • Gate A - Architecture Readiness: Core services/interfaces documented, reviewed, and implementation-ready.
  • Gate B - Pipeline Readiness: Content tools and schema validation enable non-engineers to ship safe data changes.
  • Gate C - Vertical Slice Readiness: Slice meets quality/performance/readability targets with no blocker-class issues.
  • Gate D - Production Readiness: Solo-capacity plan, backlog structure, delivery cadence, and risk controls support sustained production.

Pre-Production Exit Criteria

  • All four stage gates pass in sequence with documented sign-off owners.
  • Top 10 technical and design risks have mitigation plans and target dates.
  • Production roadmap is decomposed into epic/module backlogs with solo-capacity assumptions.
  • KPI instrumentation plan is approved and embedded in core systems before production scale-up.

Phase 3 - Production (Build the World)

  • Expand zones, skills, crafting tree, factions, and questlines.
  • Iterate economy and progression with telemetry-driven tuning.
  • Implement social systems, events, and endgame loops.
  • Start staged external testing (alpha/beta cohorts).

Phase 4 - Launch Readiness and Live Ops

  • Harden infrastructure and operations runbooks.
  • Finalize onboarding/new-player funnels.
  • Complete monetization and trust/safety implementation.
  • Launch with a clear 6-12 month live content roadmap.

Core Epic Map (Level 1)

Epic 1 - Core Player Runtime (Client Controls + Character Loop)

  • Ownership focus: Gameplay Engineering + Technical Design
  • Scope: Isometric camera runtime, character movement, interaction framework, input/ability scaffolding, moment-to-moment game feel.
  • Success criteria: Stable 3D isometric control loop feels responsive and readable across supported hardware tiers.

Epic 2 - Skills and Progression Framework

  • Ownership focus: Systems Design + Gameplay Engineering
  • Scope: Non-combat SkillDef catalog, skill XP and level curves, unlock logic, mastery/perk unlocks, progression pacing controls. Combat role progression (gigs) is separate—see Epic 5 and game-design gigs.md.
  • Success criteria: Any character can train all non-combat skills tracked as SkillDef, with long-term skill progression and no dead-end grinds; gig combat roles remain swappable combat identity.

Epic 3 - Crafting, Gathering, and Itemization Economy

  • Ownership focus: Economy Design + Content Engineering
  • Scope: Resource nodes, refinement chains, recipes/blueprints, quality tiers, crafting sinks, item lifecycle.
  • Success criteria: Crafting is a primary progression lane with healthy supply-demand loops and consistent item relevance.

Epic 4 - World Topology and Zone Infrastructure

  • Ownership focus: Online/Backend Engineering + World Design
  • Scope: Seamless regional world structure, travel and handoff logic, selective instancing strategy, spawn/ecology systems.
  • Success criteria: Mostly seamless open world runs reliably with predictable transitions and low-disruption handoffs.

Epic 5 - PvE Combat and Encounter Content

  • Ownership focus: Combat Design + Encounter Design
  • Scope: Tab-target combat rules, enemy AI patterns, dungeons/events, boss loops, reward hooks.
  • Success criteria: PvE combat delivers tactical depth, clear readability, and repeatable fun for solo and group play.

Epic 6 - PvP Security Zones and Fairness Rules

  • Ownership focus: Systems Design + Online Engineering + Trust/Safety
  • Scope: High/contested/low-security rulesets, consent signaling, loss/risk models, anti-griefing systems.
  • Success criteria: PvP is compelling for participants while remaining fully optional and non-blocking for progression.

Epic 7 - Questing, Narrative, and Faction Reputation

  • Ownership focus: Narrative Design + Quest Design + Tools
  • Scope: Main arc, faction questlines, repeatable contracts, reputation states, unlock dependencies.
  • Success criteria: Quest content provides clear progression direction, worldbuilding depth, and durable midgame engagement.

Epic 8 - Social, Guild/Corp, and Cooperative Features

  • Ownership focus: Social Systems + Online Services
  • Scope: Party/group tools, guild/corp systems, chat and moderation hooks, cooperative objective systems.
  • Success criteria: Players can easily form long-term social bonds and group structures that improve retention.

Epic 9 - LiveOps, Telemetry, and Game Integrity

  • Ownership focus: Live Operations + Data/Analytics + Security
  • Scope: Metrics pipeline, tuning controls, event tooling, anti-cheat/anti-bot workflows, incident runbooks.
  • Success criteria: Team can operate, balance, and protect the game continuously post-launch with fast feedback loops.

Tooling epic — Internal authoring and content pipeline (CT)

Type: Operator- and build-focused tooling epic, parallel to the numbered E1–E9 player/product epics above. It does not extend the sequence to “Epic 10”; modules use the CT.M# prefix. Full program doc (slices, risks, DoD): docs/decomposition/tooling/internal_authoring.md.

  • Ownership focus: Content Engineering + Tools + Build/CI
  • Scope: JSON (or YAML) schemas for catalogs, CI and local validation (including cross-table reference checks), optional internal authoring UI (TypeScript-friendly per tech stack), reference/rename workflows, optional content bundles; consumes contract shapes from E2 / E3 / E4 / E7 as those stabilize.
  • Success criteria: Zones, items, recipes, and quests can be authored as file-backed, versioned data with merge gates that prevent broken references; no separate authoring database as source of truth.

System Modules by Epic (Level 2)

Module template:

  • Responsibility: What this module owns.
  • Key contracts: Core data/events/interfaces exposed.
  • Dependencies: Upstream modules required before this module is effective.
  • Stage target: Minimum phase where the module must exist.

Epic 1 Modules - Core Player Runtime

  • E1.M1 InputAndMovementRuntime
    • Responsibility: Character locomotion, click-to-move/path-follow baseline, interaction trigger range checks.
    • Key contracts: MoveCommand, PositionState, InteractionRequest.
    • Dependencies: None.
    • Stage target: Prototype.
  • E1.M2 IsometricCameraController
    • Responsibility: Locked isometric camera follow, zoom bands, occlusion handling, no-rotation enforcement.
    • Key contracts: CameraState, ZoomBandConfig, OcclusionPolicy.
    • Dependencies: E1.M1.
    • Stage target: Prototype.
  • E1.M3 InteractionAndTargetingLayer
    • Responsibility: World object selection, target lock, focus swap rules, hover/highlight feedback.
    • Key contracts: TargetState, InteractableDescriptor, SelectionEvent.
    • Dependencies: E1.M1.
    • Stage target: Prototype.
  • E1.M4 AbilityInputScaffold
    • Responsibility: Hotbar bindings, cooldown slot UI hooks, ability activation request path to combat systems.
    • Key contracts: AbilityCastRequest, HotbarLoadout, CooldownSnapshot.
    • Dependencies: E1.M3, E5.M1.
    • Stage target: Prototype.

Epic 2 Modules - Skills and Progression Framework

  • E2.M1 SkillDefinitionRegistry
    • Responsibility: Central catalog for non-combat SkillDef metadata, category tags, unlock prerequisites (and allowedXpSourceKinds in prototype schema).
    • Key contracts: SkillDef, SkillCategory, UnlockRequirement.
    • Dependencies: None.
    • Stage target: Prototype.
  • E2.M2 XpAwardAndLevelEngine
    • Responsibility: XP award rules, level thresholds, level-up event generation.
    • Grant channel policy: Reject XpGrantEvent when sourceKind is not listed on the target SkillDef.allowedXpSourceKinds (E2.M1 catalog + content/schemas/skill-def.schema.json).
    • Key contracts: XpGrantEvent, LevelCurve, LevelUpEvent.
    • Dependencies: E2.M1.
    • Stage target: Prototype.
  • E2.M3 MasteryAndPerkUnlocks
    • Responsibility: Mastery tracks and perk unlock state for skill build expression beyond raw levels.
    • Key contracts: MasteryTrack, PerkUnlockEvent, PerkState.
    • Dependencies: E2.M2.
    • Stage target: Pre-production.
  • E2.M4 ProgressionPacingControls
    • Responsibility: Tuning knobs for progression velocity and catch-up policy enforcement.
    • Key contracts: XpModifierProfile, CatchUpRule, PacingPolicy.
    • Dependencies: E2.M2, E9.M2.
    • Stage target: Pre-production.

Epic 3 Modules - Crafting, Gathering, and Itemization Economy

  • E3.M1 ResourceNodeAndGatherLoop
    • Responsibility: Node spawning, gather interaction, resource output events.
    • Key contracts: ResourceNodeDef, GatherResult, ResourceYieldTable.
    • Dependencies: E1.M3, E2.M2.
    • Stage target: Prototype.
  • E3.M2 RefinementAndRecipeExecution
    • Responsibility: Raw-to-refined processing and recipe crafting execution pipeline.
    • Key contracts: RecipeDef, CraftRequest, CraftResult.
    • Dependencies: E3.M1, E3.M3.
    • Stage target: Prototype.
  • E3.M3 ItemizationAndInventorySchema
    • Responsibility: Item definitions, rarity/quality fields, stackability and equipment metadata.
    • Key contracts: ItemDef, ItemInstance, InventorySlot.
    • Dependencies: None.
    • Stage target: Prototype.
  • E3.M4 SinkAndDurabilityLifecycle
    • Responsibility: Item decay/consumption/repair sinks that sustain market demand.
    • Key contracts: DurabilityState, ItemSinkEvent, RepairCostRule.
    • Dependencies: E3.M3, E8.M3.
    • Stage target: Pre-production.
  • E3.M5 EconomyBalancePolicy
    • Responsibility: Faucet/sink parameter set and guardrails for inflation/deflation.
    • Key contracts: EconomyPolicy, PriceBandRule, FaucetSinkRatio.
    • Dependencies: E3.M4, E9.M2.
    • Stage target: Pre-production.

Epic 4 Modules - World Topology and Zone Infrastructure

  • E4.M1 ZoneGraphAndTravelRules
    • Responsibility: Regional zone graph, transition links, movement and travel constraints.
    • Key contracts: ZoneDef, ZoneEdge, TravelRule.
    • Dependencies: None.
    • Stage target: Prototype.
  • E4.M2 SpawnEcologyController
    • Responsibility: Resource and NPC spawn profiles per zone, respawn pacing, depletion recovery.
    • Key contracts: SpawnProfile, RespawnRule, ZoneEcologyState.
    • Dependencies: E4.M1, E3.M1, E5.M2.
    • Stage target: Pre-production.
  • E4.M3 SeamlessHandoffAndRegionState
    • Responsibility: Cross-region handoff behavior and region authority ownership boundaries.
    • Key contracts: RegionHandoffEvent, RegionAuthority, TransferState.
    • Dependencies: E4.M1, backend world services.
    • Stage target: Pre-production.
  • E4.M4 SecurityTierZoneFlags
    • Responsibility: High/contested/low-security tagging and client/server zone risk signaling. E6.M1 reads SecurityTier and ZonePolicyState from here; Epic 4 does not depend on Epic 6 modules.
    • Key contracts: SecurityTier, ZonePolicyState, ZoneEntryWarning.
    • Dependencies: E4.M1.
    • Stage target: Prototype.

Epic 5 Modules - PvE Combat and Encounter Content

  • E5.M1 CombatRulesEngine
    • Responsibility: Tab-target combat state machine, hit resolution, cooldown/resource timing.
    • Key contracts: CombatAction, CombatResolution, ThreatState.
    • Dependencies: E1.M3, E2.M2.
    • Stage target: Prototype.
  • E5.M2 NpcAiAndBehaviorProfiles
    • Responsibility: Enemy archetype behavior loops, aggro logic, telegraph scheduling.
    • Key contracts: NpcBehaviorDef, TelegraphEvent, AggroRule.
    • Dependencies: E5.M1.
    • Stage target: Prototype.
  • E5.M3 EncounterAndRewardTables
    • Responsibility: Encounter setup templates, completion criteria, reward drop routing.
    • Key contracts: EncounterDef, RewardTable, EncounterCompleteEvent.
    • Dependencies: E5.M1, E3.M3, E7.M2.
    • Stage target: Prototype.
  • E5.M4 GroupCombatScaling
    • Responsibility: Duo/squad scaling logic and anti-trivialization balancing hooks.
    • Key contracts: ScalingProfile, PartySizeModifier, CombatDifficultyBand.
    • Dependencies: E5.M3, E8.M1.
    • Stage target: Pre-production.

Epic 6 Modules - PvP Security Zones and Fairness

  • E6.M1 PvPEligibilityAndFlagState
    • Responsibility: PvP enablement logic by zone state and explicit opt-in context.
    • Key contracts: PvPFlagState, EligibilityRule, PvPStateChanged.
    • Dependencies: E4.M4.
    • Stage target: Prototype.
  • E6.M2 ConsentAndRiskUxSignals
    • Responsibility: Entry warnings, in-zone risk UI, and clear state communication for PvP status.
    • Key contracts: RiskPrompt, ZoneRiskState, PvPIndicatorState.
    • Dependencies: E6.M1, E1.M2.
    • Stage target: Prototype.
  • E6.M3 LossPenaltyAndAntiGriefRules
    • Responsibility: Death/loss rules in PvP contexts plus spawn protection and abuse mitigation.
    • Key contracts: PvPLossRule, SpawnProtectionState, GriefingStrike.
    • Dependencies: E6.M1, E9.M4.
    • Stage target: Pre-production.
  • E6.M4 RewardParityEnforcer
    • Responsibility: Guarantee functional equivalents for PvP rewards through PvE/crafting paths.
    • Key contracts: RewardParityMap, EquivalentPowerBand, ParityViolationAlert.
    • Dependencies: E3.M2, E5.M3, E7.M2.
    • Stage target: Prototype.

Epic 7 Modules - Questing, Narrative, and Faction Reputation

  • E7.M1 QuestStateMachine
    • Responsibility: Quest start/step/complete state transitions and persistence.
    • Key contracts: QuestDef, QuestStepState, QuestStateTransition.
    • Dependencies: E3.M2, E5.M1.
    • Stage target: Prototype.
  • E7.M2 RewardAndUnlockRouter
    • Responsibility: Route quest outputs to XP, items, unlocks, and reputation.
    • Key contracts: QuestRewardBundle, UnlockGrant, RewardDeliveryEvent.
    • Dependencies: E2.M2, E3.M3, E7.M1.
    • Stage target: Prototype.
  • E7.M3 FactionReputationLedger
    • Responsibility: Track faction standing and gate faction-specific contracts/content.
    • Key contracts: FactionStanding, ReputationDelta, FactionGateRule.
    • Dependencies: E7.M1.
    • Stage target: Pre-production.
  • E7.M4 ContractMissionGenerator
    • Responsibility: Semi-procedural repeatable contract generation with difficulty/reward bands.
    • Key contracts: ContractTemplate, ContractSeed, ContractOutcome.
    • Dependencies: E4.M1, E5.M3, E7.M3.
    • Stage target: Pre-production.

Epic 8 Modules - Social, Guild/Corp, and Cooperative Features

  • E8.M1 PartyAndMatchAssembly
    • Responsibility: Party creation/invite/ready-state flow for cooperative activities.
    • Key contracts: PartyState, InviteEvent, RolePreference.
    • Dependencies: E1.M3.
    • Stage target: Pre-production.
  • E8.M2 GuildCorpProgressionState
    • Responsibility: Guild/corp membership, rank permissions, and shared progression tracks.
    • Key contracts: GuildState, GuildRolePolicy, GuildProgressionEvent.
    • Dependencies: E8.M1, E7.M3.
    • Stage target: Production.
  • E8.M3 PlayerTradeAndMarketplace
    • Responsibility: Listing, trade, purchase, and settlement flows for player economy.
    • Key contracts: MarketListing, TradeOffer, SettlementEvent.
    • Dependencies: E3.M3, E3.M5.
    • Stage target: Pre-production.
  • E8.M4 ChatModerationAndReporting
    • Responsibility: Channel chat, report pipeline, moderation action logs and escalation hooks.
    • Key contracts: ChatMessageEvent, PlayerReport, ModerationAction.
    • Dependencies: E9.M4.
    • Stage target: Pre-production.

Epic 9 Modules - LiveOps, Telemetry, and Integrity

  • E9.M1 TelemetryEventSchema
    • Responsibility: Canonical event taxonomy covering session, progression, economy, combat, and PvP events.
    • Key contracts: TelemetryEvent, EventSchemaVersion, ClientEventEnvelope.
    • Dependencies: None.
    • Stage target: Prototype.
  • E9.M2 KpiDashboardsAndAlerting
    • Responsibility: KPI aggregation, dashboard surfaces, trend alerts, and milestone gate signals.
    • Key contracts: KpiDefinition, AlertThreshold, MilestoneGateSignal.
    • Dependencies: E9.M1.
    • Stage target: Pre-production.
  • E9.M3 LiveBalanceControlPlane
    • Responsibility: Runtime-safe tuning of combat, progression, and economy parameters.
    • Key contracts: BalancePatch, ConfigVersion, RolloutState.
    • Dependencies: E9.M2, E5.M1, E2.M4, E3.M5.
    • Stage target: Production.
  • E9.M4 IntegrityAndAbuseResponse
    • Responsibility: Bot/exploit detection signals, incident triage, and response workflows.
    • Key contracts: IntegritySignal, IncidentTicket, EnforcementAction.
    • Dependencies: E9.M1.
    • Stage target: Pre-production.

Content tooling modules (CT) — Internal authoring

Tooling track (not E1–E9). Depends softly on catalog shapes from E2.M1, E3.M2–M3, E4.M1, E7.M1; see docs/decomposition/tooling/internal_authoring.md.

  • CT.M1 ContentValidationPipeline
    • Responsibility: Canonical schemas for content files; CI and local validation; optional server/test smoke load of catalogs.
    • Key contracts: JSON Schema bundle, validation CLI, stable error format for editors.
    • Dependencies: Soft alignment with E2/E3/E4/E7 content contracts; can start with minimal schemas.
    • Stage target: Prototype.
  • CT.M2 AuthoringStudioApplication
    • Responsibility: Internal authoring app (e.g. Vite + React) for content/**, forms and ID pickers, zone graph editing aligned with E4.M1 payloads.
    • Key contracts: Repo read/write paths; optional local API for dev browser; invokes CT.M1 rules.
    • Dependencies: CT.M1.
    • Stage target: Prototype.
  • CT.M3 ContentReferenceAndBundleWorkflows
    • Responsibility: Project-wide reference index, safer renames, schema-version warnings; optional bundle manifest for client/server parity.
    • Key contracts: ContentBundleManifest (optional), reference graph for CI/review.
    • Dependencies: CT.M1; CT.M2 recommended for integrated UX.
    • Stage target: Pre-production.

Module Dependency Flow (Level 2)

flowchart TD
  E1M1[InputAndMovementRuntime] --> E1M2[IsometricCameraController]
  E1M1 --> E1M3[InteractionAndTargetingLayer]
  E1M3 --> E5M1[CombatRulesEngine]
  E1M3 --> E1M4[AbilityInputScaffold]
  E5M1 --> E1M4
  E2M1[SkillDefinitionRegistry] --> E2M2[XpAwardAndLevelEngine]
  E2M2 --> E3M1[ResourceNodeAndGatherLoop]
  E3M1 --> E3M2[RefinementAndRecipeExecution]
  E3M3[ItemizationAndInventorySchema] --> E3M2
  E4M1[ZoneGraphAndTravelRules] --> E4M4[SecurityTierZoneFlags]
  E4M4 --> E6M1[PvPEligibilityAndFlagState]
  E6M1 --> E6M2[ConsentAndRiskUxSignals]
  E5M1 --> E5M2[NpcAiAndBehaviorProfiles]
  E5M2 --> E5M3[EncounterAndRewardTables]
  E7M1[QuestStateMachine] --> E7M2[RewardAndUnlockRouter]
  E5M1 --> E7M1
  E3M2 --> E7M1
  E3M2 --> E6M4[RewardParityEnforcer]
  E5M3 --> E6M4
  E9M1[TelemetryEventSchema] --> E9M2[KpiDashboardsAndAlerting]
  E9M1 --> E9M4[IntegrityAndAbuseResponse]
  E2M4[ProgressionPacingControls] --> E9M3[LiveBalanceControlPlane]
  E3M5[EconomyBalancePolicy] --> E9M3
  E5M1 --> E9M3

Critical Path Modules by Phase

  • Prototype critical path: E1.M1, E1.M2, E1.M3, E2.M1, E2.M2, E3.M1, E3.M2, E3.M3, E4.M1, E4.M4, E5.M1, E1.M4, E5.M2, E5.M3, E6.M1, E6.M2, E6.M4, E7.M1, E7.M2, E9.M1.
  • Pre-production critical path additions: E2.M3, E2.M4, E3.M4, E3.M5, E4.M2, E4.M3, E5.M4, E6.M3, E7.M3, E7.M4, E8.M1, E8.M3, E8.M4, E9.M2, E9.M4.

Solo-Dev Build Order (First Executable Roadmap Cut)

  1. Foundation runtime: E1.M1 -> E1.M2 -> E1.M3 to guarantee movement, camera lock, and interactions.
  2. Progression scaffold: E2.M1 -> E2.M2 for visible XP progression in first session.
  3. Inventory and crafting core: E3.M3 -> E3.M1 -> E3.M2 to enable gather -> craft loop.
  4. Combat baseline: E5.M1 -> E5.M2 -> E5.M3 with starter encounters and reward hooks; add E1.M4 after E5.M1 so hotbar and AbilityCastRequest wiring matches prototype combat MVP.
  5. Quest integration: E7.M1 -> E7.M2 to chain gather/craft/combat into guided progression.
  6. Zone policy and optional PvP: E4.M1 -> E4.M4 -> E6.M1 -> E6.M2 -> E6.M4 for clear opt-in PvP parity.
  7. Telemetry minimum: E9.M1 events wired into prototype pass/fail gates.
  8. Pre-production hardening wave: Add E2.M3/E2.M4, E3.M4/E3.M5, E4.M2/E4.M3, E8.M1/E8.M3/E8.M4, E9.M2/E9.M4 before large content expansion.

Epic Dependency Flow

flowchart TD
  E1[CorePlayerRuntime] --> E2[SkillsProgression]
  E1 --> E5[PvECombatEncounters]
  E4[WorldTopologyZones] --> E5
  E4 --> E6[PvPSecurityZones]
  E2 --> E3[CraftingEconomy]
  E3 --> E7[QuestFactionReputation]
  E5 --> E7
  E7 --> E8[SocialGuildCorp]
  E2 --> E9[LiveOpsTelemetryIntegrity]
  E3 --> E9
  E5 --> E9
  E6 --> E9
  E8 --> E9

Business and Sustainability Frame

  • Monetization guardrails: Avoid pay-to-win; prioritize cosmetics, convenience with constraints, optional subscriptions/battle pass patterns as appropriate.
  • Content economics: Ensure live team can produce sustainable updates without unsustainable bespoke content burden.
  • Community strategy: Transparent communication cadence, test realms, creator/community partnerships.

Success Metrics (Top-Level)

  • Retention: D1/D7/D30, returning weekly users, average session depth.
  • Progression health: Skill distribution, completion rates, midgame drop-off points.
  • Economy health: Inflation/deflation, item velocity, crafting participation, market concentration risk.
  • Social health: Guild participation, group activity rates, toxicity/report trends.
  • Operational health: Server stability, incident frequency, exploit response time.
  • PvP policy health: PvP participation rate, opt-in churn impact, kill/death concentration, and parity satisfaction across PvE/PvP reward paths.

KPI and Telemetry Framework

Measurement Principles (Solo-Friendly)

  • Decision-driven instrumentation: Track only metrics that change roadmap decisions.
  • Tiered telemetry depth: Start with lightweight event coverage and expand only where blind spots block progress.
  • Automate collection first: Prefer dashboards/reports generated from stable event schemas over manual analysis.
  • One owner model: All KPI definitions, thresholds, and review cadence are maintained by the solo developer.

KPI Categories and Core Signals

1) Player Retention and Engagement

  • Core KPIs: D1/D7/D30 retention, weekly active users, average session duration, sessions per active user.
  • Early warning signals: Rising first-session abandonment, declining return rate after first craft or first quest chain.

2) Progression and Onboarding Health

  • Core KPIs: Time-to-first-level-up, time-to-first-craft, first-hour quest completion rate, skill progression distribution.
  • Early warning signals: Concentrated drop-off before first meaningful unlock, one skill line dominating due to imbalance.

3) Crafting and Economy Health

  • Core KPIs: Gather-to-craft conversion rate, crafted item usage rate, item sink velocity, median material price trend.
  • Early warning signals: Persistent oversupply without sinks, crafting bypassed by drops/vendors, inflation spikes.

4) Combat and Content Health

  • Core KPIs: Encounter completion rates by tier, death/failure rates, average combat duration, repeat participation rate.
  • Early warning signals: Frequent wipe/frustration clusters, trivialized encounters, low replay of intended repeatable loops.

5) PvP Policy and Parity Health

  • Core KPIs: PvP participation opt-in rate, non-PvP progression completion rate, reward parity sentiment, zone exit-after-death behavior.
  • Early warning signals: PvE players feeling forced into PvP, abnormal churn among players who enter low-security zones once.

6) Technical and Operational Health

  • Core KPIs: Crash-free session rate, server uptime, p95 latency, disconnect frequency, severe bug incidence.
  • Early warning signals: Regressions after releases, latency hotspots tied to specific zones/features, repeated rollback needs.

Event Instrumentation Baseline

  • Session lifecycle events: Login, logout, session start/end, reconnect, crash marker.
  • Progression events: Skill XP gain, level-up, unlock acquisition, quest start/step complete/quest complete.
  • Economy events: Resource gathered, item crafted, item consumed/destroyed, trade/listing/purchase.
  • Combat events: Encounter start/end, ability used, player death, enemy defeat, boss completion.
  • PvP events: Zone enter/exit by security level, PvP flag state, PvP defeat, PvP reward claimed.
  • System health events: Error class counts, server tick/perf counters, network latency buckets.

Phase-Based KPI Maturity

  • Prototype phase: Focus on onboarding funnel, core loop completion, readability, and optional PvP validation.
  • Pre-production phase: Add economy stability, content throughput metrics, and performance/latency trend tracking.
  • Production phase: Full KPI suite with release-over-release regression checks and automated anomaly alerts.
  • Live operations phase: Cohort tracking, long-horizon progression health, monetization guardrail checks, and seasonal event impact.

Review Cadence and Decision Gates

  • Weekly review: Check core KPI dashboard and identify one to three highest-impact interventions.
  • Monthly gate: Validate whether KPI trends justify continuing current roadmap priorities.
  • Milestone gate rule: No phase advancement if two or more red-status KPIs remain unresolved.

KPI Status Threshold Model

  • Green: Metric within target band for at least two consecutive review cycles.
  • Yellow: Metric drifting from target; requires hypothesis and owner-assigned corrective action.
  • Red: Metric outside acceptable bounds; triggers scope freeze on non-critical features until addressed.

Minimal Dashboard Set (Solo Operator)

  • Dashboard A - New Player Funnel: Session start -> first quest -> first craft -> first level-up -> return session.
  • Dashboard B - Core Loop Health: Gather/craft/combat loop completion rates and average loop duration.
  • Dashboard C - Economy Pulse: Resource inflow/outflow, crafted item velocity, sink effectiveness.
  • Dashboard D - Stability and Performance: Crash rates, latency percentiles, disconnects, severe defect counts.
  • Dashboard E - PvP Optionality and Parity: Zone participation, opt-out churn, and parity pathway completion.

Program Risks and Mitigations

  • Scope overload: Use staged gates and strict definition-of-done for each phase.
  • Solo bandwidth saturation: Cap concurrent initiatives, prioritize automation, and aggressively cut non-core feature requests.
  • Content bottlenecks: Invest early in data-driven pipelines and reusable encounter templates.
  • Economy collapse: Simulate and monitor continuously; maintain tunable sinks/faucets.
  • Technical debt in networking/backends: Build observability and load-testing into milestones.
  • Identity drift (too derivative): Enforce cyberpunk differentiators in art, narrative, systems, and social structures.
  • PvP griefing harms PvE-first vision: Enforce security zones, consent clarity, and progression parity policies with telemetry audits.

High-Level System Map

flowchart TD
  Vision[ProductVision] --> Pillars[ExperiencePillars]
  Pillars --> Systems[CoreSystems]
  Systems --> Progression[SkillXpAndMastery]
  Systems --> Crafting[CraftingAndEconomy]
  Systems --> Questing[QuestAndFactionContent]
  Systems --> Combat[CombatAndEncounters]
  Systems --> Social[SocialAndGuildSystems]
  Systems --> Tech[BackendAndLiveOps]
  Tech --> Launch[LaunchAndOperations]
  Launch --> Growth[PostLaunchGrowth]

Document Finalization Status

  • Status: Finalized baseline vision document (v1).
  • Purpose: This file is now the canonical 50,000-foot reference for product intent, architecture, and phase gates.
  • Change policy: Keep this file stable; place detailed decomposition work in dedicated files under docs/decomposition.

Decomposition Workspace (Next Artifacts)

  • Index: docs/decomposition/README.md
  • Epic files: docs/decomposition/epics/ (one file per epic)
  • Module mapping files: docs/decomposition/modules/ (cross-epic module contracts and dependency references)
  • Milestone files: docs/decomposition/milestones/ (phase-gated implementation tracks)

Immediate Next Step (Execution)

  1. Create one decomposition file per epic in docs/decomposition/epics/.
  2. Expand each epic into backlog-ready slices (system, content, tooling, telemetry, acceptance).
  3. Capture cross-epic dependencies in docs/decomposition/modules/module_dependency_register.md.
  4. Convert phase gates into actionable milestone checklists in docs/decomposition/milestones/.