diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8aa6685 --- /dev/null +++ b/.gitignore @@ -0,0 +1,24 @@ +# .NET +bin/ +obj/ +out/ +*.user +*.suo +*.userosscache +.vs/ + +# Godot 4 +.import/ +export_presets.cfg +*.translation +# Mono build artifacts if you enable C# on the client later +client/.godot/ + +# OS / editor +.DS_Store +*.swp +.idea/ + +# Local secrets +.env +.env.*.local diff --git a/NeonSprawl.sln b/NeonSprawl.sln new file mode 100644 index 0000000..1ae92d7 --- /dev/null +++ b/NeonSprawl.sln @@ -0,0 +1,27 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 17 +VisualStudioVersion = 17.0.31903.59 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "server", "server", "{8683E7E4-B4D9-4001-8E99-DA987A03A73D}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NeonSprawl.Server", "server/NeonSprawl.Server/NeonSprawl.Server.csproj", "{098FCB1C-4A31-4E36-8D9C-1F1CEECDFF50}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {098FCB1C-4A31-4E36-8D9C-1F1CEECDFF50}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {098FCB1C-4A31-4E36-8D9C-1F1CEECDFF50}.Debug|Any CPU.Build.0 = Debug|Any CPU + {098FCB1C-4A31-4E36-8D9C-1F1CEECDFF50}.Release|Any CPU.ActiveCfg = Release|Any CPU + {098FCB1C-4A31-4E36-8D9C-1F1CEECDFF50}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(NestedProjects) = postSolution + {098FCB1C-4A31-4E36-8D9C-1F1CEECDFF50} = {8683E7E4-B4D9-4001-8E99-DA987A03A73D} + EndGlobalSection +EndGlobal diff --git a/README.md b/README.md index 1cfb03b..46c3cac 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Untitled Cyberpunk MMO +# Neon Sprawl -Planning and vision for a classless, crafting-focused cyberpunk MMORPG (solo-dev scope). See [`cyberpunk_mmo_vision_86a57ef3.plan.md`](cyberpunk_mmo_vision_86a57ef3.plan.md). +**Neon Sprawl** is the working title for a classless, crafting-focused sci-fi / cyberpunk MMORPG (solo-dev scope). Product intent and phase gates: [`neon_sprawl_vision.plan.md`](neon_sprawl_vision.plan.md). ## Tech stack (locked) @@ -15,3 +15,33 @@ Full rationale and constraints: [`docs/architecture/tech_stack.md`](docs/archite ## Decomposition Epic-level breakdown: [`docs/decomposition/README.md`](docs/decomposition/README.md). + +## Repository layout (prototype scaffold) + +| Path | Purpose | +|------|---------| +| [`NeonSprawl.sln`](NeonSprawl.sln) | .NET solution | +| [`server/NeonSprawl.Server/`](server/NeonSprawl.Server/) | ASP.NET Core game server | +| [`client/`](client/) | Godot 4.x project (import `project.godot`) | +| [`content/`](content/) | JSON data + JSON Schema (`skills/`, `schemas/`) | +| [`docker-compose.yml`](docker-compose.yml) | Local **PostgreSQL** (`docker compose up -d`) | + +### Run the server + +```bash +cd server/NeonSprawl.Server && dotnet run +``` + +Then open `http://localhost:5253/health` (port from `launchSettings.json`). + +### Run Postgres locally + +```bash +docker compose up -d +``` + +Connection (dev): host `localhost`, port `5432`, database `neon_sprawl`, user `neon_sprawl`, password `neon_sprawl_dev`. + +### Run the client + +Open the [`client/`](client/) folder in **Godot 4.2+** and run the main scene (see [`client/README.md`](client/README.md)). diff --git a/client/README.md b/client/README.md new file mode 100644 index 0000000..4e8e4a5 --- /dev/null +++ b/client/README.md @@ -0,0 +1,12 @@ +# Neon Sprawl — Godot client + +Open this **`client/`** directory as a project in **Godot 4.2+** (4.x recommended). + +- Main scene: `scenes/main.tscn` (bootstrap `scripts/main.gd`). +- Networking will use **WebSocket** or **TCP** to the C# server; authoritative logic stays on the server per [`docs/architecture/tech_stack.md`](../docs/architecture/tech_stack.md). + +## First run + +1. Install [Godot 4.x](https://godotengine.org/download). +2. In the project manager, **Import** and select `client/project.godot`. +3. Press **F5** to run the main scene. diff --git a/client/icon.svg b/client/icon.svg new file mode 100644 index 0000000..da3561f --- /dev/null +++ b/client/icon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/client/project.godot b/client/project.godot new file mode 100644 index 0000000..7d439a8 --- /dev/null +++ b/client/project.godot @@ -0,0 +1,20 @@ +; Godot 4.x project — import this folder in the Godot project manager. + +config_version=5 + +[application] + +config/name="Neon Sprawl" +config/description="Neon Sprawl — prototype client (isometric MMO; planning docs in repo root)." +run/main_scene="res://scenes/main.tscn" +config/features=PackedStringArray("4.2", "Forward Plus") +config/icon="res://icon.svg" + +[display] + +window/size/viewport_width=1280 +window/size/viewport_height=720 + +[rendering] + +textures/canvas_textures/default_texture_filter=0 diff --git a/client/scenes/main.tscn b/client/scenes/main.tscn new file mode 100644 index 0000000..39b869a --- /dev/null +++ b/client/scenes/main.tscn @@ -0,0 +1,6 @@ +[gd_scene load_steps=2 format=3 uid="uid://cyberpunkmmo_main"] + +[ext_resource type="Script" path="res://scripts/main.gd" id="1_main"] + +[node name="Main" type="Node3D"] +script = ExtResource("1_main") diff --git a/client/scripts/main.gd b/client/scripts/main.gd new file mode 100644 index 0000000..e45a4d4 --- /dev/null +++ b/client/scripts/main.gd @@ -0,0 +1,4 @@ +extends Node3D + +func _ready() -> void: + print("Neon Sprawl client bootstrap (Godot). Connect to game server TBD.") diff --git a/content/README.md b/content/README.md new file mode 100644 index 0000000..a16b047 --- /dev/null +++ b/content/README.md @@ -0,0 +1,10 @@ +# Content data + +Data-driven definitions (skills, items, recipes, quests) validated in CI with **JSON Schema**. + +| Path | Purpose | +|------|---------| +| [`schemas/`](schemas/) | JSON Schema files (`*.schema.json`) | +| [`skills/`](skills/) | Skill catalogs and related tables | + +Server load path and hot-reload policy are TBD; keep files versioned here as the source of truth. diff --git a/content/schemas/skill-def.schema.json b/content/schemas/skill-def.schema.json new file mode 100644 index 0000000..9a21a8d --- /dev/null +++ b/content/schemas/skill-def.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://neon-sprawl.local/schemas/skill-def.json", + "title": "SkillDef", + "type": "object", + "additionalProperties": false, + "required": ["id", "category", "displayName"], + "properties": { + "id": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]*$" + }, + "category": { + "type": "string", + "enum": ["gathering", "crafting", "combat", "exploration", "utility", "social"] + }, + "displayName": { "type": "string", "minLength": 1 } + } +} diff --git a/content/skills/prototype_skills.json b/content/skills/prototype_skills.json new file mode 100644 index 0000000..bf55cbc --- /dev/null +++ b/content/skills/prototype_skills.json @@ -0,0 +1,20 @@ +{ + "schemaVersion": 1, + "skills": [ + { + "id": "gathering_scrap", + "category": "gathering", + "displayName": "Scrap Salvaging" + }, + { + "id": "crafting_engineering", + "category": "crafting", + "displayName": "Street Engineering" + }, + { + "id": "combat_ballistics", + "category": "combat", + "displayName": "Ballistics" + } + ] +} diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..d060f15 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,21 @@ +# Local PostgreSQL for prototype / dev. Start: docker compose up -d +services: + postgres: + image: postgres:16-alpine + container_name: neon-sprawl-postgres + environment: + POSTGRES_USER: neon_sprawl + POSTGRES_PASSWORD: neon_sprawl_dev + POSTGRES_DB: neon_sprawl + ports: + - "5432:5432" + volumes: + - neon_sprawl_pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U neon_sprawl -d neon_sprawl"] + interval: 5s + timeout: 5s + retries: 5 + +volumes: + neon_sprawl_pgdata: diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index fd5a0e7..3507571 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -105,5 +105,5 @@ Revisit this document if: ## Related docs -- [`cyberpunk_mmo_vision_86a57ef3.plan.md`](../cyberpunk_mmo_vision_86a57ef3.plan.md) — product locks and phase gates +- [`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 diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index f0af86d..612574b 100644 --- a/docs/decomposition/README.md +++ b/docs/decomposition/README.md @@ -2,7 +2,7 @@ This workspace contains detailed planning artifacts derived from the finalized master plan: -- Source of truth: `cyberpunk_mmo_vision_86a57ef3.plan.md` +- Source of truth: [`neon_sprawl_vision.plan.md`](../neon_sprawl_vision.plan.md) - Tech stack baseline: [`docs/architecture/tech_stack.md`](../architecture/tech_stack.md) - Scope here: executable decomposition (epics, modules, milestones) diff --git a/docs/decomposition/epics/_epic_template.md b/docs/decomposition/epics/_epic_template.md index 889497f..d8f0f3a 100644 --- a/docs/decomposition/epics/_epic_template.md +++ b/docs/decomposition/epics/_epic_template.md @@ -2,7 +2,7 @@ ## Source Anchors -- Master epic reference: `cyberpunk_mmo_vision_86a57ef3.plan.md` +- Master epic reference: `neon_sprawl_vision.plan.md` - Related modules: `` ## Objective diff --git a/neon_sprawl_vision.plan.md b/neon_sprawl_vision.plan.md new file mode 100644 index 0000000..9a8e8c8 --- /dev/null +++ b/neon_sprawl_vision.plan.md @@ -0,0 +1,789 @@ +--- +name: Neon Sprawl Vision +overview: Create a 50,000-foot planning document for Neon Sprawl, a sci-fi/cyberpunk MMORPG inspired by RuneScape, focused on classless progression and deep crafting, with optional PvP and questing. +todos: + - id: lock-critical-decisions + content: Combat model and world topology are locked; remaining decision is progression pace. + status: completed + - id: define-core-epics + content: Split the vision into 6-10 product epics with ownership and success criteria. + status: completed + - id: prototype-core-loop + content: Design and scope a prototype proving movement, combat, skill gain, crafting, and quest loops. + status: completed + - id: plan-preproduction + content: Define pre-production deliverables for architecture, tools, and vertical slice quality bar. + status: completed + - id: establish-metrics + content: Set top-level KPIs and telemetry requirements for testing and live operations. + status: completed +isProject: 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. + +## 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 + +- **Classless mastery:** Every character can learn and level every skill over time; identity 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`](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 8** (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 (Todo 3 Output) + +### 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 (Todo 4 Output) + +### 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 - Classless Skill and Progression Framework + +- **Ownership focus:** Systems Design + Gameplay Engineering +- **Scope:** Skill definitions, XP curves, unlock logic, mastery/perk unlocks, progression pacing controls. +- **Success criteria:** Any character can train all skills, and progression remains long-term without dead-end grinds. + +### 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. + +## 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 - Classless Skill and Progression + +- **E2.M1 SkillDefinitionRegistry** + - Responsibility: Central catalog for skill metadata, category tags, unlock prerequisites. + - Key contracts: `SkillDef`, `SkillCategory`, `UnlockRequirement`. + - Dependencies: None. + - Stage target: Prototype. +- **E2.M2 XpAwardAndLevelEngine** + - Responsibility: XP award rules, level thresholds, level-up event generation. + - Key contracts: `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`. + - Dependencies: E2.M1. + - Stage target: Prototype. +- **E2.M3 MasteryAndPerkUnlocks** + - Responsibility: Mastery tracks and perk unlock state for non-class build expression. + - Key contracts: `MasteryTrack`, `PerkUnlockEvent`, `PerkState`. + - Dependencies: E2.M2. + - Stage target: Pre-production. +- **E2.M4 ProgressionPacingControls** + - Responsibility: Tuning knobs for progression velocity and catch-up policy enforcement. + - Key contracts: `XpModifierProfile`, `CatchUpRule`, `PacingPolicy`. + - Dependencies: E2.M2, E9.M2. + - Stage target: Pre-production. + +### 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. + +## Module Dependency Flow (Level 2) + +```mermaid +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 + +```mermaid +flowchart TD + E1[CorePlayerRuntime] --> E2[ClasslessProgression] + 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 (Todo 5 Output) + +### 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 + +```mermaid +flowchart TD + Vision[ProductVision] --> Pillars[ExperiencePillars] + Pillars --> Systems[CoreSystems] + Systems --> Progression[ClasslessSkillProgression] + 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/`. + diff --git a/server/NeonSprawl.Server/NeonSprawl.Server.csproj b/server/NeonSprawl.Server/NeonSprawl.Server.csproj new file mode 100644 index 0000000..87441a4 --- /dev/null +++ b/server/NeonSprawl.Server/NeonSprawl.Server.csproj @@ -0,0 +1,11 @@ + + + + net8.0 + enable + enable + NeonSprawl.Server + NeonSprawl.Server + + + diff --git a/server/NeonSprawl.Server/Program.cs b/server/NeonSprawl.Server/Program.cs new file mode 100644 index 0000000..ddbd094 --- /dev/null +++ b/server/NeonSprawl.Server/Program.cs @@ -0,0 +1,14 @@ +var builder = WebApplication.CreateBuilder(args); +var app = builder.Build(); + +app.MapGet("/", () => Results.Text( + "Neon Sprawl game server — GET /health for JSON status.", + "text/plain")); + +app.MapGet("/health", () => Results.Json(new +{ + status = "ok", + service = "NeonSprawl.Server", +})); + +app.Run(); diff --git a/server/README.md b/server/README.md new file mode 100644 index 0000000..8a756ac --- /dev/null +++ b/server/README.md @@ -0,0 +1,17 @@ +# Game server (`NeonSprawl.Server`) + +ASP.NET Core **.NET 8** host for authoritative simulation (prototype: HTTP + health only). + +## Run + +```bash +cd server/NeonSprawl.Server +dotnet run +``` + +- Default URL is printed by Kestrel (see `Properties/launchSettings.json`, typically `http://localhost:5253`). +- Check `GET /health` for a JSON heartbeat. + +## Solution + +From repo root: `dotnet build NeonSprawl.sln`