From 25c0dd37e2c6ff6da77b08b13ca3786765d1786d Mon Sep 17 00:00:00 2001 From: don Date: Sun, 29 Mar 2026 17:04:37 -0400 Subject: [PATCH] Document tech stack, README, and align prototype critical path with modules. Add locked C# / .NET 8 + Godot baseline in docs/architecture/tech_stack.md and README; link stack from vision plan and decomposition index. Fix vision plan module graph and lists: include E1.M4 (AbilityInputScaffold) after E5.M1 and E2.M3 in pre-production additions; update Solo-Dev build order accordingly. Made-with: Cursor --- README.md | 17 ++++ cyberpunk_mmo_vision_86a57ef3.plan.md | 23 ++++-- docs/architecture/tech_stack.md | 109 ++++++++++++++++++++++++++ docs/decomposition/README.md | 1 + 4 files changed, 144 insertions(+), 6 deletions(-) create mode 100644 README.md create mode 100644 docs/architecture/tech_stack.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1cfb03b --- /dev/null +++ b/README.md @@ -0,0 +1,17 @@ +# Untitled Cyberpunk MMO + +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). + +## Tech stack (locked) + +| Area | Choice | +|------|--------| +| Client | **Godot 4.x** | +| Game server | **C# / .NET 8** (ASP.NET Core), **PostgreSQL**, **Protobuf** (JSON OK for earliest spike) | +| Content | **JSON/YAML** + **JSON Schema** in CI | + +Full rationale and constraints: [`docs/architecture/tech_stack.md`](docs/architecture/tech_stack.md). + +## Decomposition + +Epic-level breakdown: [`docs/decomposition/README.md`](docs/decomposition/README.md). diff --git a/cyberpunk_mmo_vision_86a57ef3.plan.md b/cyberpunk_mmo_vision_86a57ef3.plan.md index 499253a..bd753a8 100644 --- a/cyberpunk_mmo_vision_86a57ef3.plan.md +++ b/cyberpunk_mmo_vision_86a57ef3.plan.md @@ -113,9 +113,18 @@ These decisions heavily affect architecture and content pipelines and should be ## Technical and Production Architecture (Macro) -### Platform and Engine +### Tech stack (baseline — prototype / early pre-production) -- Select engine stack based on MMO networking needs, toolchain maturity, hiring reality, and content velocity. +**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. @@ -580,6 +589,8 @@ 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] @@ -603,19 +614,19 @@ flowchart TD ### 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, E5.M2, E5.M3, E6.M1, E6.M2, E6.M4, E7.M1, E7.M2, E9.M1. -- **Pre-production critical path additions:** 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. +- **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. +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.M4, E3.M4/E3.M5, E4.M2/E4.M3, E8.M1/E8.M3/E8.M4, E9.M2/E9.M4 before large content expansion. +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 diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md new file mode 100644 index 0000000..fd5a0e7 --- /dev/null +++ b/docs/architecture/tech_stack.md @@ -0,0 +1,109 @@ +# Tech stack (baseline decision) + +**Status:** Baseline for **prototype through early pre-production**. Revisit before vertical-slice freeze if tooling or hiring assumptions change. + +**Constraints from product vision:** Solo operator, server-authoritative critical paths, fixed isometric 3D client, tab-target combat, data-driven skills/items/recipes/quests, optional PvP zones, eventual scale-out (not day one). + +**Server runtime (locked):** **C# / .NET 8** — primary author has ~10 years C# experience; authoritative game logic, persistence, and ops stay in this stack. + +**Other operator skills:** **JavaScript** and **TypeScript** remain useful for content tooling, client-side scripting in Godot (GDScript on client for fast iteration), and one-off scripts—**not** the authoritative server. + +## Summary + +| Layer | Choice | Role | +|--------|--------|------| +| Game client | **Godot 4.x** | Rendering, input, camera, local prediction (if any), UI, telemetry emit | +| Game server | **C# / .NET 8** (ASP.NET Core) | Authoritative simulation, zones, combat/crafting resolution, persistence boundaries | +| RPC / messages | **Protobuf** (or **JSON** for earliest spike only) | Versioned contracts between client and server | +| Primary database | **PostgreSQL** | Characters, inventory, progression, economy ledger, idempotent transactions | +| Cache / presence (when needed) | **Redis** | Sessions, rate limits, hot read models—**defer** until second scaling pain | +| Content data | **JSON or YAML + JSON Schema** (or **CUE** later) | Skills, items, recipes, quests; validated in CI (can use Node or `dotnet` validators) | +| Repo / CI | **Git** + **GitHub Actions** or **Gitea Actions** | `dotnet build`, schema validation, optional Godot export | + +## Client: Godot 4 + +**Why** + +- Strong fit for solo iteration: fast reload, small install, no revenue cap. +- 3D isometric camera (orthographic or perspective), zoom, and **no rotation** are straightforward in a single-camera rig. +- **GDScript** for rapid client prototyping; **Godot C#** available if you want client/server language alignment in hot paths. +- Networking: treat **WebSocket** or **TCP** as transport only; **authoritative logic stays on the ASP.NET Core server**, not in Godot’s high-level multiplayer templates, to avoid fighting engine assumptions. + +**Prototype discipline** + +- One contained district; no multi-region streaming in engine until pre-production handoff slice. +- Client sends intents (`MoveIntent`, `UseAbilityIntent`, …); server emits state deltas or snapshots. + +**Plan B** + +- **Unity** (6000 LTS track) if the art pipeline shifts; **server stays C#**—reuse patterns and types where practical. + +**Defer** + +- **Unreal** for this phase unless art direction *requires* it. + +## Server: C# (.NET 8) + +**Why** + +- **ASP.NET Core** (minimal APIs or controllers) + **Kestrel**; WebSockets, gRPC, or raw TCP alongside HTTP health/metrics. +- **PostgreSQL** via **Npgsql**; **EF Core** (migrations) or **Dapper** + **FluentMigrator** / **DbUp**—pick ORM vs hand-written SQL and stay consistent. +- **Protobuf:** **Grpc.Net** or **protobuf-net**; JSON is acceptable for the first spike only. +- **Prototype shape:** single `GameHost` (or named) process—in-memory zone state + PostgreSQL for durable character/inventory; split processes only when metrics demand it. + +**Pre-production** + +- Optional read replicas or separate presence service; job queues only when needed. + +## Server alternative (not default) + +**TypeScript / Node** remains viable for tools-only or a secondary BFF; avoid splitting authoritative state across two runtimes unless there is a clear boundary (e.g. web shop vs simulation). + +## Other server languages (optional later) + +| If you… | Consider | +|---------|----------| +| Want a tiny deploy binary for a worker | **Go** — isolated sidecar, not replacing the main C# sim without a decision doc | +| Experiment | **Rust** — only for proven hot paths | + +## Data and persistence + +- **PostgreSQL** as source of truth for anything that must survive restarts or be audit-able (inventory, trades, progression). +- Migrations: **EF Core** or **FluentMigrator** / **DbUp** with **Npgsql**; keep migrations in-repo. +- **Avoid** client-trust for economy: craft outcomes, loot grants, and trades commit only after server validation + DB transaction where required. + +## Content pipeline + +- Author in **JSON/YAML**; validate with **JSON Schema** in CI (Node-based **ajv**/CLI, **dotnet**-based validators, or **CUE** later). +- Server loads tables at boot or hot-reloads in dev; client may receive **bundles** or hash-versioned blobs to avoid drift. +- Epic 3/7 decomposition modules (`RecipeDef`, `QuestDef`, …) map directly to these files. + +## Observability + +- **Serilog** and/or **OpenTelemetry** for .NET from early prototype. +- Align event names with `E9.M1 TelemetryEventSchema` in the vision doc; client batches to server or OTLP endpoint as capacity allows. + +## Security (proportionate to phase) + +- **Prototype:** TLS on public endpoints if exposed; auth token or session secret; minimal PII handling. +- **Pre-production:** Rate limits, input validation on all RPCs, admin tools behind separate auth. + +## Explicit non-goals for stack selection + +- Choosing a commercial “MMO middleware” that locks data formats or hosting. +- Client-authoritative combat or inventory. +- Full anti-cheat and bot defense before core loop fun is proven (track with E9.M4 workflows later). + +## Revision triggers + +Revisit this document if: + +- Target platforms add **console** or **mobile** with hard certification constraints. +- Art pipeline commits to an engine not listed above. +- Co-op session model forces **P2P** or large physics sync (unlikely for tab-target isometric). +- Simulation CPU bottlenecks justify a **Go/Rust worker** for isolated workloads—document the split; **keep C# as orchestration** unless you rewrite the decision. + +## Related docs + +- [`cyberpunk_mmo_vision_86a57ef3.plan.md`](../cyberpunk_mmo_vision_86a57ef3.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 0d17b28..f0af86d 100644 --- a/docs/decomposition/README.md +++ b/docs/decomposition/README.md @@ -3,6 +3,7 @@ This workspace contains detailed planning artifacts derived from the finalized master plan: - Source of truth: `cyberpunk_mmo_vision_86a57ef3.plan.md` +- Tech stack baseline: [`docs/architecture/tech_stack.md`](../architecture/tech_stack.md) - Scope here: executable decomposition (epics, modules, milestones) ## Folder Layout -- 2.40.1