Restructure into pnpm monorepo with game shell, docs, and SpacetimeDB backend
- Restructure flat static prototype into pnpm workspace monorepo - apps/game: playable shell with R3F 3D scene, HUD, SpacetimeDB connection - apps/docs: design docs and prototypes - apps/site: landing page - packages/ui: shared Button and Panel primitives - services/spacetimedb: backend module (9 tables, 11 reducers) - Archive legacy static files to archive/legacy-static/ - Game loop: connect, undock, target, approach, dock, mine, sell - Add pnpm-workspace.yaml, tsconfig.base.json, spacetime.json
This commit is contained in:
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 309 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 273 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 246 KiB |
305
apps/docs/public/docs/gap-analysis.md
Normal file
305
apps/docs/public/docs/gap-analysis.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Gap Analysis — EVE-Inspired Multiplayer Prototype GDD
|
||||
|
||||
**Date:** 2026-05-24
|
||||
**Last Updated:** 2026-05-25 (Session 7)
|
||||
**Scope:** Full cross-reference of design documentation vs. interactive demos vs. roadmap readiness
|
||||
|
||||
---
|
||||
|
||||
## Session 7 Progress (2026-05-25)
|
||||
|
||||
Comprehensive fresh gap analysis identified 20 missing specs. The 3 critical blockers for Phase 0 have been addressed:
|
||||
|
||||
| Gap | Resolution |
|
||||
|---|---|
|
||||
| **Galaxy Generation Spec** (Critical #1) | Added "Galaxy Generation" sub-tab to Backend → Galaxy Simulation. Concrete parameters: 4 regions, ~50 systems (MVP), Poisson disk placement, MST + random edges stargate topology, starter system template, faction territory seeding, station/belt placement rules, full pseudocode. Deterministic seeded RNG. |
|
||||
| **Ship Acquisition Flow** (Critical #2) | Added "🚀 Acquisition" tab to Ships page. Free Rookie Frigate on spawn and death respawn. 5 acquisition methods (free grant, NPC market, player market, manufacturing, LP store). NPC ship pricing table. Ship switching flow (dock → hangar → select → activate). Hangar storage model. Backend schema changes (storage_location, is_rookie, switch_ship reducer). |
|
||||
| **Warp & Travel Mechanics** (Critical #3) | Added "🚀 Travel & Warp" tab to Gameplay page. 3 travel modes (sub-warp, warp, gate jump) with speeds. Warp sequence (align → accelerate → cruise → exit). Warp speeds by ship class (3.0–6.0 AU/s). Stargate mechanics (2.5km activation, 5s jump cooldown, 30s gate cloak). Gate guns by security level. Docking/undocking with invulnerability. Autopilot vs manual piloting. Warp disruption. Backend state columns (travel_mode, gate_cloak_until, weapons_timer_until, etc.). |
|
||||
|
||||
### Remaining 17 Gaps (from 20-item analysis)
|
||||
|
||||
| Priority | Gap | Status |
|
||||
|---|---|---|
|
||||
| 🟠 Important | Mining Mechanics Detail (cycle time, yield, depletion) | Not started |
|
||||
| 🟠 Important | Module Activation & Cycle System | Not started |
|
||||
| 🟠 Important | Damage Types & Resistances | Not started |
|
||||
| 🟠 Important | Stargate Mechanics | **Resolved** — covered in Travel & Warp tab |
|
||||
| 🟠 Important | Multiplayer Combat (Phase 13) | Not started |
|
||||
| 🟠 Important | Scanning / Exploration System | Not started |
|
||||
| 🟠 Important | Fleet System | Not started |
|
||||
| 🟡 Nice-to-have | Contract system | Not started |
|
||||
| 🟡 Nice-to-have | Cloaking/stealth | Not started |
|
||||
| 🟡 Nice-to-have | Server admin/GM tools | Not started |
|
||||
| 🟡 Nice-to-have | Settings/preferences panel | Not started |
|
||||
| 🟡 Nice-to-have | Performance targets | Not started |
|
||||
| 🟡 Nice-to-have | Galaxy Generation demo | **Resolved** — Interactive Galaxy Generation demo created. Validates seeded RNG, region/constellation/system placement, MST stargate topology, station/belt seeding, security distribution, connectivity check, route finding. 12th demo. |
|
||||
| 🟡 Nice-to-have | Direct player-to-player trade | Not started |
|
||||
| 🟡 Nice-to-have | Death/respawn full UX flow | Partially addressed (respawn mechanism defined in Ship Acquisition) |
|
||||
| 🟡 Nice-to-have | Corp backend tables missing from master list | Not started |
|
||||
| 🟡 Nice-to-have | Progression demo XP curve mismatch | Not started |
|
||||
|
||||
---
|
||||
|
||||
## Session 6 Progress (2026-05-24)
|
||||
|
||||
All remaining gap analysis items have been addressed:
|
||||
|
||||
| Gap | Resolution |
|
||||
|---|---|
|
||||
| **Era 1 System Map demo** | Added to demo gallery as a known-needed demo. Listed in demo gallery header note. Implementation is Phase 1 scope (after movement model is built). |
|
||||
| **Missing backend tables (factions, regions, constellations)** | Added `regions`, `constellations`, and `factions` to Backend → Tables tab with full field descriptions. `systems` table now has `constellation_id` FK. |
|
||||
| **Debug Panel spec** | Expanded from 4 bullet points to 8 items in Gameplay → Screen Specifications. Added: SpacetimeDB table row counts, Agent tick scheduler status, Force-spawn controls (dev mode), Game time display. |
|
||||
| **Tutorial / Onboarding spec** | Already resolved in Session 5 (OV-05). 5-mission guided sequence, tutorial principles, Zora as guide, skip mechanics, stuck-player detection. |
|
||||
| **Error handling / Reconnection spec** | Added to Architecture → ARCH-4. 7 disconnection scenarios, reconnection flow with exponential backoff, anti-exploit (combat logging) rules. |
|
||||
| **Session persistence / Save-Load spec** | Added to Architecture → ARCH-5. No save button, no localStorage. SpacetimeDB is continuous persistence. Full table-by-table persistence guarantee. |
|
||||
| **Sound / Audio design spec** | Added to Architecture → ARCH-6. 6 audio categories, 6 volume sliders, spatial audio rules, Phase 7 scope. |
|
||||
| **Localization / i18n decision** | Added to Architecture → ARCH-7. MVP English-only with day-one i18n architecture (string keys, Intl formatters, RTL-ready CSS). |
|
||||
| **Accessibility spec** | Added to Architecture → ARCH-8. 8 accessibility areas with requirements and implementation details. Gate 4 acceptance tests. |
|
||||
| **Corporations & Territory spec** | Added as new tab to Social page (SOC-CORP). Full spec: corp lifecycle, 5 roles, wallet/tax system, territory & sovereignty (3 structure tiers), 6 new backend tables, 11 new reducers. Phase 14 scope. |
|
||||
|
||||
---
|
||||
|
||||
## Session 5 Progress (2026-05-24)
|
||||
|
||||
The following gaps have been addressed based on a full 15-point critique review:
|
||||
|
||||
| Gap | Resolution |
|
||||
|---|---|
|
||||
| **Economy first-30-minutes walkthrough** | Added "First 30 Minutes" tab to Economy page (ECON-30). 14-step walkthrough from spawn to loop-set, emphasizing price discovery as the aha moment. |
|
||||
| **Power allocation failure modes** | Added GP-FAIL section to Gameplay → Core Loop tab. Per-subsystem failure table (Weapons→no firing, Shields→no recharge, Engines→immobile, Aux→no specials). Reroute timing (1.5–3s). |
|
||||
| **Flight Mode HUD cognitive load** | Added Red Alert mode to GP-FAIL. When shields <25% and taking armor damage, non-essential HUD elements collapse. Combat HUD expands. Cannot be disabled. |
|
||||
| **Roadmap integration gates** | Added 6 integration gates to Roadmap page (Gate 1–6). Each gate covers a phase group and defines a focused playtest. |
|
||||
| **Gap analysis partial resolutions** | (a) Bounty is now sector-specific (petty=system-local, standard=regional, dangerous+=galaxy-wide). (b) AI module examples added to both fitting examples in Ships page. (c) Onboarding/tutorial section added to Overview → OV-05 with 5-mission guided sequence. |
|
||||
| **Zora phased delivery** | Added phased delivery milestones table to Ship AI → Implementation Tiers section. Maps Zora features to roadmap phases (Phase 0 stub → Phase 7 Tier 0 complete → Phase 12 Tier 1 → Phase 15+ Tier 2). Full design kept intact. |
|
||||
| **Faucet/sink untestable in Era 1** | Added Balancing Agent system (new tab: Gameplay → Balancing Agent). Monitors 5 metrics (ISK velocity, price index, death rate, faucet/sink ratio, engagement). Controls 4 levers (NPC spawn rate, difficulty tier, ISK faucet multiplier, world event frequency). New tables: balance_metrics, balance_levers, balance_audit. |
|
||||
| **ER diagram** | Added ER Diagram tab to Backend page. 5 clusters (Player, Economy, World, Social, Ship AI) with all 50+ tables, PKs, FKs, and cross-cluster flow descriptions. |
|
||||
| **Chinese characters** | Fixed: "PvP主力" → "PvP main combat ships" in Insurance table. |
|
||||
| **Currency naming** | Added ISK temporary placeholder note to Economy → Flow Overview tab. All ISK references are subject to renaming. |
|
||||
| **Security level 0.0 gap** | Fixed: Security 0.0 is explicitly null-sec. Added clarification to Gameplay → Security Levels intro text. |
|
||||
| **Architecture page localStorage** | Fixed: Architecture overview now states "There is no localStorage — persistence is always through SpacetimeDB, even in single-player Era 1." |
|
||||
| **No respec mentioned** | Added respec mechanics to Social → Progression tab (SOC-RESPEC). 20% XP penalty, 7-day cooldown, full or single-skill respec, requires Neural Remapping facility. |
|
||||
| **Roadmap localStorage** | Fixed: Phase 0 goal now mentions "local SpacetimeDB instance". Phase 7 doneWhen says "SpacetimeDB persists all state — no localStorage". Era 1 subtitle reflects SpacetimeDB-from-day-1. |
|
||||
| **World events missing lightweight Era 1 version** | Phase 7 doneWhen now includes "Lightweight exploration events spawn in visited systems." Integration Gate 4 validates exploration events as part of Era 1 completion. |
|
||||
|
||||
---
|
||||
|
||||
## Session 4 Progress (2026-05-24)
|
||||
|
||||
The following gaps have been addressed:
|
||||
|
||||
| Gap | Resolution |
|
||||
|---|---|
|
||||
| **HUD ambiguity resolved** | Decision documented in Overview → OV-04 "HUD & View Mode Architecture": game uses two view modes — Flight Mode (diegetic overlays on 3D viewport when undocked) and Station Mode (traditional panel UI when docked). Map Mode is shared. Demo gallery updated: gamehud now labeled "Game HUD (Flight Mode)", starmap labeled "Star Map (Era 2 Galaxy Map)". Transition rules specified (undock, dock, open map, combat ambush). |
|
||||
| **Starmap demo labeled correctly** | Demo gallery entry renamed from "Star Map" to "Star Map (Era 2 Galaxy Map)" with explicit validates/limitations noting it covers the Era 2 Galaxy Map, NOT the Era 1 System Map. Era 1 System Map still needs a separate demo. |
|
||||
| **Mission system spec** | Full spec added to Gameplay → Missions tab: 6 mission types (Kill/Courier/Mining/Survey/Escort/Trade), NPC agent interaction flow (6 steps), standing mechanics (6 tiers from Hostile to Inner Circle), reward scaling table (4 levels), Loyalty Points secondary currency, 6 new backend tables (npc_agents, mission_templates, active_missions, player_standing, player_loyalty_points, mission_offers), mission-related reducers. |
|
||||
| **World event UX spec** | Full spec added to Gameplay → World Events UX tab: 3 notification tiers (Critical/Nearby/Background) with Flight Mode and Station Mode behavior, Event Detail Panel layout (7 sections), event map integration (System Map Era 1 + Galaxy Map Era 2), contribution tracking with anti-AFK, 3 reward tiers (Bronze/Silver/Gold), Galaxy Story Log with search/export. |
|
||||
| **Economy spec brought to Market demo level** | New "Market Surface" section added to Economy → Flow Overview tab: order book & depth with bid/ask spread, candlestick price history charts, contract specifications, margin accounts & long/short positions (Era 2), commodity ticker, station-filtered view. Acknowledges the Market demo implements all of these. |
|
||||
| **Manufacturing depth expanded** | Manufacturing tab expanded from 2 cards to 4 sections: Full Production Chain (5-tier chain: Ore → Mineral → Component → Module → Ship), Blueprint Research with ME/TE levels and cost/time curves, Production Queues with concurrent job limits by skill, Station Facility tiers, BPC copies, and Invention (post-MVP T2). |
|
||||
| **Backend tables for missions** | Added 6 new mission-related tables to Backend → Tables tab: npc_agents, mission_templates, active_missions, player_standing, player_loyalty_points, mission_offers. Total tables now 44. |
|
||||
|
||||
---
|
||||
|
||||
## Session 3 Progress (2026-05-24)
|
||||
|
||||
The following gaps have been addressed:
|
||||
|
||||
| Gap | Resolution |
|
||||
|---|---|
|
||||
| **NPC price adjustment algorithm** | Full spec added to Economy → NPC Pricing tab: demand pressure algorithm with EMA, price formula (base × regional × demand × station type), worked tick-by-tick example, regional price seed table with 6 regions, anti-arbitrage safeguards, 3 new backend tables (`station_commodity_demand`, `commodity_price_params`, `regional_price_seeds`), `market_price_adjust` agent updated. |
|
||||
| **Chat/comms prototype** | New interactive demo (`js/demos/chat.js`): 4 channels (Local/Trade/Private/Fleet), light-speed delay simulation with formula `2 × √(jumps)`, pre-seeded message corpus, pilot proximity sidebar with delay map, NPC auto-responses in local channel. Registered in sidebar, loader, app, and demo gallery. |
|
||||
| **Zora Tier 0 demo** | New interactive demo (`js/demos/zora.js`): deterministic template engine with 15 event triggers × 5 soul depths, module gating logic (6 modules), personality axes sliders, response history. Validates the soul depth progression from raw status codes to full personality. Registered in sidebar, loader, app, and demo gallery. |
|
||||
| **Backend tables for NPC pricing** | Added `station_commodity_demand`, `commodity_price_params`, `regional_price_seeds` to Backend → Tables tab. |
|
||||
| **Agent updated for NPC pricing** | Updated `market_price_adjust` agent interval from 900s to 300s, added cross-reference to Economy → NPC Pricing tab. |
|
||||
|
||||
---
|
||||
|
||||
## Session 2 Progress (2026-05-24)
|
||||
|
||||
The following gaps from the original analysis have been addressed:
|
||||
|
||||
| Gap | Resolution |
|
||||
|---|---|
|
||||
| **Currency naming** | Standardized to "ISK" with symbol `₢`. Removed all "credits" references. Updated overview, ships, roadmap. |
|
||||
| **Chat scope ambiguity** | Core loop Step 8 now explicitly states "Requires multiplayer — ships in Phase 11 (Era 2)." Summary paragraph clarified Steps 1–7 as Era 1. |
|
||||
| **Security level system** | Full spec added to Gameplay → Security Levels tab: 4 security bands (+1.0 to −1.0), player security status (−10 to +5), CONCORD response tiers, PvP rules per band, backend schema changes. |
|
||||
| **NPC pirate AI behavior** | Full spec added to Gameplay → NPC Pirates tab: spawning rules, location-based triggers, difficulty tiers by security band, 4 behavior templates (orbit kiter, brawler, shield tank, EWAR support), state machine (idle→aggro→combat→flee→dead), new backend tables + agents. |
|
||||
| **CONCORD response model** | Full spec added to Gameplay → CONCORD tab: response time by system sec (3s–15s), CONCORD force scaling, 6-step response pipeline, anti-exploit rules, suspect vs. criminal flag system, weapons timer. |
|
||||
| **Insurance system** | Full spec added to Gameplay → Insurance tab: 4 coverage tiers (None/Basic/Standard/Platinum), premium/payout structure, ISK faucet/sink analysis, anti-abuse rules, new backend tables + reducers. |
|
||||
| **Missing backend tables** | Added 13 new tables to Backend → Tables tab: `ship_types`, `modules_catalog`, `ship_fittings`, `npc_entities`, `npc_class_templates`, `loot_tables`, `blueprints`, `manufacturing_jobs`, `skills_catalog`, `chat_channels`, `insurance_policies`, `ship_type_base_values`. |
|
||||
| **Missing agents** | Added `pirate_spawn`, `pirate_combat_tick`, `pirate_loot_drop`, `concord_response`, `security_status_tick` agents to catalog. |
|
||||
| **AI Crew vs Zora confusion** | Added clarifying callout to Ships → AI Crew tab explaining the two systems are separate. |
|
||||
| **Economy faucet/sink completeness** | Added Insurance Payout as explicit faucet and Insurance Premiums as explicit sink with cross-reference to the new spec. |
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The GDD is remarkably thorough — 12 design pages, 9 interactive demos, a 16-phase roadmap, and a detailed backend schema. The documentation quality is high and internally consistent. However, several substantive gaps exist between **what is specified**, **what is prototyped**, and **what is ready for Phase 0 implementation**. These gaps fall into four categories:
|
||||
|
||||
1. **Specified but not prototyped** — features with design detail but no interactive demo
|
||||
2. **Prototyped but not fully specified** — demos that go beyond or diverge from the spec
|
||||
3. **Cross-reference inconsistencies** — details that conflict between pages
|
||||
4. **Missing specifications** — systems implied by the roadmap but not yet designed
|
||||
|
||||
---
|
||||
|
||||
## 1. Specified but Not Prototyped
|
||||
|
||||
These features have meaningful design documentation but no interactive demo to validate UX feel.
|
||||
|
||||
| Feature | Spec Location | Gap Description | Risk |
|
||||
|---|---|---|---|
|
||||
| **Chat & Comms** | Social → Chat & Comms | ~~No chat demo exists.~~ Range-based propagation, light-speed delay, local/system channels are all specified but untested for UX feel. | **Resolved** — Chat & Comms demo created. Validates delay mechanics, channel switching, and pilot proximity. |
|
||||
| **Galaxy Map** | Overview → Era 2 Screens | ~~The starmap demo shows a *system* map (single system scale). The *galaxy* map (region/constellation/system hierarchy with faction overlay, world event icons, migration routes) has no demo.~~ **Resolved:** Demo gallery now labels starmap as Era 2 Galaxy Map. The remaining gap is a separate Era 1 System Map demo. | **Partially Resolved** — Era 1 System Map still needs a demo. |
|
||||
| **World Events** | Gameplay → Dynamic Galaxy / World Events UX | ~~No demo for world event spawning, propagation, participation, or the story log.~~ Full player-facing UX spec added to Gameplay → World Events UX tab: notification tiers, event detail panel, map integration, contribution tracking, reward tiers, story log. No interactive demo yet. | **Spec Resolved** — UX fully designed. Demo is nice-to-have, not blocking. |
|
||||
| **NPC Economy Sim** | Economy → NPC Pricing | ~~The market demo shows a contract exchange with fixed seed data.~~ NPC pricing algorithm now fully specified with demand pressure model, regional seeds, and anti-arbitrage safeguards. No demo for full NPC supply/demand simulation over time yet. | **Spec Resolved** — Algorithm documented. Demo for full multi-station simulation is nice-to-have, not blocking. |
|
||||
| **Manufacturing** | Economy → Manufacturing | ~~The refining demo covers ore → mineral but stops there. No demo for manufacturing jobs, blueprint research, production queues, or the mineral → module → ship chain.~~ Manufacturing tab expanded with full production chain (5 tiers), ME/TE research with cost curves, production queues, station facility levels, BPC copies, and invention. No demo yet. | **Spec Resolved** — Full manufacturing chain specified. Demo is Phase 5 scope. |
|
||||
| **Ship AI (Zora)** | Ship AI (entire page) | ~~No demo at all.~~ Zora Tier 0 demo created validating deterministic template engine. Tier 1 (LLM-assisted) and Tier 2 (full agent) still unvalidated. | **Partially Resolved** — Tier 0 demo validates soul depth + module gating + personality axes. Higher tiers are post-MVP. |
|
||||
| **Corporations & Territory** | ~~Mentioned in roadmap but zero design detail anywhere.~~ **Resolved:** Full spec added to Social → Corporations tab. Corp lifecycle, roles, wallet/tax, territory & sovereignty, 6 new backend tables, 11 new reducers. Phase 14 scope. |
|
||||
| **Debug Panel** | ~~Listed as an Era 1 screen with minimal spec.~~ **Resolved:** Expanded to 8 items including SpacetimeDB row counts, agent scheduler status, force-spawn controls, game time display. Utility panel — no demo needed. |
|
||||
| **Waypoints & Bookmarks** | Fully specified with backend tables, but no demo. The starmap demo doesn't integrate waypoint creation or route planning. | **Medium** — Navigation UX demo deferred to Phase 1 when System Map is built. Spec is complete. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Prototyped but Not Fully Specified (Demo Divergences)
|
||||
|
||||
These demos contain features or behaviors not reflected in the design docs.
|
||||
|
||||
| Demo | Divergence | Impact |
|
||||
|---|---|---|
|
||||
| **Market** | ~~The market demo implements a full *contract/commodities exchange* with bid/ask spread, price history charts, long/short positions, and margin accounts. The Economy page describes a simpler "order book, price per unit, place sell order from inventory" model. The demo is significantly more ambitious than the spec.~~ **Resolved:** Economy → Flow Overview tab now has a full "Market Surface" section covering order book depth, candlestick charts, contract specs, margin accounts, commodity ticker, and station-filtered view. Spec now matches the demo. | **Resolved** — Economy spec updated to match Market demo's feature set. |
|
||||
| **Market** | Uses `₢` symbol for ISK in some places. The Overview page uses "ISK" and "credits" interchangeably. No canonical symbol defined. | **Inconsistency** — minor but should be standardized. |
|
||||
| **Combat** | The combat demo implements 3D projectile rendering with beam/bolt types, subsystem damage, and multiple damage types (EM, thermal, kinetic, explosive). The spec mentions "generic damage" as a demo limitation but the actual demo goes further. | **Positive divergence** — spec should acknowledge what the demo actually validates. |
|
||||
| **Combat** | Demo uses 4 power subsystems (Weapons/Shields/Engines/Aux). The spec consistently uses the same 4. This is consistent — no gap. | ✓ Aligned |
|
||||
| **Game HUD** | ~~The gamehud demo renders a full 3D space scene with diegetic HUD overlays. This is more immersive than the "UI panels" model described in the Overview. The spec should clarify whether the final game uses diegetic overlays or traditional panel layout.~~ **Resolved:** Overview → OV-04 "HUD & View Mode Architecture" documents the decision: Flight Mode uses diegetic overlays (gamehud demo), Station Mode uses traditional panels (market/fitting/refining demos). Hybrid approach. | **Resolved** — HUD ambiguity resolved with two-view-mode architecture. |
|
||||
| **Progression** | The progression demo uses a flat XP curve, but the Social page specifies an exponential curve (100 → 500 → 2,000 → 8,000 → 32,000). The demo's "limitations" callout acknowledges this but it means the demo doesn't validate the actual intended feel. | **Known limitation** — should be tracked for Phase 7. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Cross-Reference Inconsistencies
|
||||
|
||||
Details that conflict or are unclear across pages.
|
||||
|
||||
| Area | Inconsistency | Pages Involved | Resolution Needed |
|
||||
|---|---|---|---|
|
||||
| **Currency name** | ~~"ISK", "credits", and `₢` used interchangeably~~ | Overview, Economy, Market Demo | ✅ **Resolved:** Standardized to "ISK" with symbol `₢`. All "credits" references replaced. |
|
||||
| **Ship AI module slot type** | The Ships page says "AI module slot type added to fitting schema" in Phase 4 done-when. The Ship AI page says AI modules occupy "medium or low, depending on the module." The Ships page doesn't have a dedicated AI slot column in the ship classes table. | Ships, Ship AI, Roadmap | The slot allocation model is clear in Ship AI (medium for comms/tactical/nav, low for economic/memory). The Ships page should reflect this in the fitting section or acknowledge the overlap. |
|
||||
| **Ship AI Tier 0 timeline** | The Roadmap says "Tier 0 Zora" ships in Phase 7. The Ship AI page says Tier 0 = deterministic, no LLM. But Phase 7 also says "bare-bones soul state vector in SpacetimeDB." The Ship AI page's implementation tiers section says Tier 0 is "MVP launch." These are consistent but the overlap between Phase 7 and "MVP" should be explicit. | Roadmap, Ship AI | Clarify: is Phase 7 the Tier 0 launch, or does Tier 0 come later? The current text is consistent but could be more explicit. |
|
||||
| **Galaxy map vs star system map** | ~~The Overview distinguishes between "3D Star-System Map" (Era 1, single system) and "Galaxy Map" (Era 2, multi-system). The starmap demo renders a multi-system galaxy view with warp routes. This is the Era 2 galaxy map, not the Era 1 system map.~~ **Resolved:** Demo gallery now labels starmap as "Star Map (Era 2 Galaxy Map)". Overview → OV-04 explicitly notes Era 1 System Map as needed. | **Partially Resolved** — Labeling fixed. Era 1 System Map demo still needed. |
|
||||
| **Fitting affects combat** | The Ships page says "Fitting affects combat and mining stats" as Phase 4 done-when. The combat demo and fitting demo are independent — fitting changes don't carry over to combat. | Ships, Demo Gallery | Expected for demos; flagged for implementation planning. |
|
||||
| **Information diffusion model** | The Economy page has a detailed diffusion model with specific propagation times (2 min adjacent, 5 min hub, 15 min region, 30 min galaxy). The Backend page's `propagate_market_data` reducer mentions "1 system per 2 minutes per jump" which is consistent. No gap, but the propagation pipeline has no demo. | Economy, Backend | Not a gap per se, but the diffusion pipeline is complex and unvalidated. |
|
||||
| **Era 2 screens vs social features** | ~~Chat listed as core loop step but is Phase 11 (Era 2)~~ | Overview, Roadmap, Gameplay | ✅ **Resolved:** Gameplay page now explicitly states Steps 1–7 are Era 1, Step 8 requires multiplayer. |
|
||||
| **Kill feed visibility** | Social page says "galaxy-wide feed." Bounty tiers have visibility ranges (system-local, regional, galaxy-wide). The kill feed demo shows all events everywhere. | Social, Bounty Demo | Kill feed should probably follow the same visibility tiering as bounties, or be explicitly always-galaxy-wide. |
|
||||
| **AI crew vs Ship AI (Zora)** | ~~Two different AI systems with confusing shared terminology~~ | Ships → Crew, Ship AI | ✅ **Resolved:** Added clarifying callout to Ships → AI Crew tab explaining the two systems are separate. Future expansion may connect them post-MVP. |
|
||||
| **NPC pirate spawning** | ~~No spec for pirate spawning, AI behavior, difficulty curves~~ | Gameplay, Agents, Combat Demo | ✅ **Resolved:** Full spec added to Gameplay → NPC Pirates tab. New agents added: `pirate_spawn`, `pirate_combat_tick`, `pirate_loot_drop`. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Missing Specifications
|
||||
|
||||
Systems implied by the roadmap or cross-referenced but not yet designed.
|
||||
|
||||
| Missing Spec | Referenced By | Impact |
|
||||
|---|---|---|
|
||||
| **Pirate / NPC AI behavior model** | ~~Gameplay (PvE Content), Roadmap Phase 3~~ | ✅ **Resolved:** Full spec added to Gameplay → NPC Pirates tab. |
|
||||
| **Security level system** | ~~Gameplay (high-sec/low-sec/null-sec mentioned), Ships (security status mentioned), Social (high-sec attacks trigger CONCORD)~~ | ✅ **Resolved:** Full spec added to Gameplay → Security Levels tab. |
|
||||
| **CONCORD / law enforcement** | ~~Social (piracy lowers security status), Gameplay (high-sec attacks trigger CONCORD response)~~ | ✅ **Resolved:** Full spec added to Gameplay → CONCORD tab. |
|
||||
| **Insurance system** | ~~Economy (faucet: insurance payout), Ships (ship destruction section), Social (insurance premium sink)~~ | ✅ **Resolved:** Full spec added to Gameplay → Insurance tab. |
|
||||
| **Mission system** | ~~Economy (faucet: mission rewards), Agents (npc_mission_refresh agent)~~ | ✅ **Resolved:** Full spec added to Gameplay → Missions tab. 6 mission types, agent interaction, standing, rewards, LP, backend tables. |
|
||||
| **Tutorial / onboarding** | ~~Roadmap Phase 15, Overview OV-05~~ | ✅ **Resolved:** Full 5-mission tutorial spec in Overview → OV-05. Zora as guide. Skip allowed. Stuck detection. |
|
||||
| **Error handling / reconnection** | ~~Roadmap Phase 15~~ | ✅ **Resolved:** Architecture → ARCH-4. 7 disconnection scenarios, reconnection flow with exponential backoff, anti-exploit rules. |
|
||||
| **Session persistence / save-load** | ~~Roadmap Phase 7~~ | ✅ **Resolved:** Architecture → ARCH-5. No save button, no localStorage. SpacetimeDB is continuous persistence. Full table-by-table persistence guarantee. |
|
||||
| **Sound / audio design** | ~~Ship AI Voice Synthesizer only~~ | ✅ **Resolved:** Architecture → ARCH-6. 6 audio categories, 6 volume sliders, spatial audio rules. |
|
||||
| **Localization / i18n** | ~~Not mentioned~~ | ✅ **Resolved:** Architecture → ARCH-7. MVP English-only with day-one i18n architecture. |
|
||||
| **Accessibility** | ~~Not mentioned~~ | ✅ **Resolved:** Architecture → ARCH-8. 8 accessibility areas, Gate 4 acceptance tests. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Backend Schema Gaps
|
||||
|
||||
The Backend page lists 44 tables. Cross-referencing with the design docs reveals:
|
||||
|
||||
| Missing Table | Referenced By | Note |
|
||||
|---|---|---|
|
||||
| `blueprints` | ~~Economy (Manufacturing)~~ | ✅ **Added** to Backend → Tables tab. |
|
||||
| `manufacturing_jobs` | ~~Economy (Manufacturing), Agents (`production_cycle`)~~ | ✅ **Added** to Backend → Tables tab. |
|
||||
| `ship_fittings` | ~~Ships (Fitting System)~~ | ✅ **Added** to Backend → Tables tab. |
|
||||
| `modules_catalog` | ~~Ships (Fitting System)~~ | ✅ **Added** to Backend → Tables tab. |
|
||||
| `ship_types` | ~~Ships (Ship Classes)~~ | ✅ **Added** to Backend → Tables tab. |
|
||||
| `factions` | ~~Backend (Galaxy Simulation) lists it, not in Tables tab~~ | ✅ **Added** to Backend → Tables tab with full field descriptions. |
|
||||
| `skills_catalog` | ~~Social (XP & Skills)~~ | ✅ **Added** to Backend → Tables tab. |
|
||||
| `npc_entities` | ~~Gameplay (PvE), Agents (enemy_regen, aggro_scan)~~ | ✅ **Added** to Backend → Tables tab + NPC Pirates spec. |
|
||||
| `loot_tables` | ~~Gameplay (combat drops)~~ | ✅ **Added** to Backend → Tables tab + NPC Pirates spec. |
|
||||
| `regions` / `constellations` | ~~Backend (Galaxy Simulation) lists them, not in Tables tab~~ | ✅ **Added** to Backend → Tables tab. `systems` now has `constellation_id` FK. |
|
||||
| `corporations` | ~~Roadmap Phase 14 — not designed~~ | ✅ **Specified** in Social → Corporations tab. 6 new tables added. Phase 14 scope. |
|
||||
| `chat_channels` | ~~Social (Chat)~~ | ✅ **Added** to Backend → Tables tab. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Roadmap Readiness Assessment
|
||||
|
||||
Assessing whether each Phase has enough specification to begin implementation.
|
||||
|
||||
| Phase | Title | Spec Readiness | Blockers |
|
||||
|---|---|---|---|
|
||||
| **0** | Local Skeleton | ✅ Ready | None. Tech stack is specified. File structure is defined. |
|
||||
| **1** | Movement & Commands | ✅ Ready | Movement model is fully specified in Backend → Movement Model. |
|
||||
| **2** | Mining & Inventory | ✅ Ready | Mining cycle, inventory panel, and fake-backend data models exist. |
|
||||
| **3** | Combat — FTL Power Allocation | ✅ Ready | ~~NPC pirate AI behavior was missing.~~ **Resolved:** NPC Pirates, Security Levels, CONCORD, and Insurance specs added to Gameplay page. |
|
||||
| **4** | Ship Fitting | ✅ Ready | ~~`ship_types`, `modules_catalog`, and `ship_fittings` tables were missing.~~ **Resolved:** All three added to Backend → Tables tab. |
|
||||
| **5** | Refining & Manufacturing | ✅ Ready | ~~Refining is well-specified. Manufacturing is described but `blueprints` and `manufacturing_jobs` tables were missing.~~ **Resolved:** Both tables added to Backend → Tables tab. |
|
||||
| **6** | NPC Economy Sim | ✅ Ready | ~~Economy philosophy is clear, but NPC price adjustment logic, regional price seeding, and the full diffusion pipeline lack implementation detail beyond pseudocode.~~ **Resolved:** NPC pricing algorithm fully specified. Regional price seeds documented. Demand pressure model defined. Backend tables added. |
|
||||
| **7** | Single-Player Polish | ✅ Ready | Tutorial/onboarding (OV-05), error handling (ARCH-4), persistence (ARCH-5), audio (ARCH-6), accessibility (ARCH-8) all fully specified. Tier 0 Zora demo exists. Mission system fully specified. |
|
||||
| **8–15** | Era 2 | ✅ Ready | Era 2 depends on SpacetimeDB integration. Chat demo exists. World event UX fully specified. Corporations and territory fully specified (SOC-CORP). Multiplayer combat needs spec work (Phase 13 scope). |
|
||||
|
||||
---
|
||||
|
||||
## 7. Priority Recommendations
|
||||
|
||||
### Immediate (before starting Phase 0)
|
||||
|
||||
1. ~~**Standardize currency naming**~~ ✅ **Done.** ISK + ₢ symbol.
|
||||
2. ~~**Clarify core loop scope**~~ ✅ **Done.** Steps 1–7 = Era 1, Step 8 = Era 2.
|
||||
3. ~~**Create `ship_types` and `modules_catalog` table specs**~~ ✅ **Done.** Added to Backend → Tables tab.
|
||||
|
||||
### Before Phase 3 (Combat)
|
||||
|
||||
4. ~~**Specify NPC pirate AI behavior**~~ ✅ **Done.** Gameplay → NPC Pirates tab.
|
||||
5. ~~**Define security level system**~~ ✅ **Done.** Gameplay → Security Levels tab.
|
||||
6. ~~**Specify CONCORD response model**~~ ✅ **Done.** Gameplay → CONCORD tab.
|
||||
|
||||
### Before Phase 6 (Economy)
|
||||
|
||||
7. ~~**Detail NPC price adjustment algorithm**~~ ✅ **Done.** Economy → NPC Pricing tab with full algorithm, regional seeds, anti-arbitrage safeguards, backend tables.
|
||||
8. ~~**Create a chat prototype**~~ ✅ **Done.** Chat & Comms demo validates range-based propagation, light-speed delay, channel switching.
|
||||
|
||||
### Before Era 2
|
||||
|
||||
9. ~~**Design the Galaxy Map**~~ ✅ **Done.** Era 2 Galaxy Map demo exists. Era 1 System Map is Phase 1 implementation scope.
|
||||
10. ~~**World event UX prototype**~~ ✅ **Done.** Full UX spec added to Gameplay → World Events UX tab.
|
||||
11. ~~**Clarify AI Crew vs Zora relationship**~~ ✅ **Done.** Added clarifying callout to Ships → AI Crew tab.
|
||||
12. ~~**Corporations & Territory spec**~~ ✅ **Done.** Full spec added to Social → Corporations tab. 6 new tables, 11 new reducers, 3 structure tiers, sovereignty mechanics. Phase 14 scope.
|
||||
|
||||
### Ongoing
|
||||
|
||||
12. ~~**Add missing backend tables**~~ ✅ **Done.** All tables added to Backend → Tables tab including regions, constellations, factions.
|
||||
13. ~~**Create a Zora Tier 0 demo**~~ ✅ **Done.** Deterministic template engine with 15 events × 5 soul depths, module gating, personality axes. Validates soul depth progression and module tradeoffs.
|
||||
14. ~~**Error handling & reconnection spec**~~ ✅ **Done.** Architecture → ARCH-4.
|
||||
15. ~~**Session persistence spec**~~ ✅ **Done.** Architecture → ARCH-5.
|
||||
16. ~~**Audio design spec**~~ ✅ **Done.** Architecture → ARCH-6.
|
||||
17. ~~**Localization decision**~~ ✅ **Done.** Architecture → ARCH-7.
|
||||
18. ~~**Accessibility spec**~~ ✅ **Done.** Architecture → ARCH-8.
|
||||
|
||||
---
|
||||
|
||||
## 8. What's Working Well
|
||||
|
||||
The gaps above should not overshadow what this GDD does exceptionally well:
|
||||
|
||||
- **Consistent vision**: The "spreadsheet simulator" design pillar is maintained across all pages. No page accidentally designs a flight sim.
|
||||
- **Roadmap is honest**: Phase 0 is marked "in progress" and every subsequent phase has a concrete done-when condition.
|
||||
- **Ship AI design is exceptional**: The soul/module/agent architecture is one of the most detailed and original companion AI designs I've seen in a game design document. The three implementation tiers (deterministic → LLM-assisted → full agent) show practical engineering thinking.
|
||||
- **Backend schema is unusually detailed for a GDD**: 56+ tables with field descriptions is ahead of most game prototypes at this stage.
|
||||
- **Demo coverage**: 11 interactive demos for a pre-Phase-0 GDD is impressive. Each demo honestly states its limitations.
|
||||
- **Agent lifecycle system**: The scheduled_agents model with uniform lifecycle, three scheduling strategies, and kill-switch is production-quality thinking.
|
||||
- **Information diffusion model**: The economy's info-asymmetry design is well-thought-through and explicitly tied to gameplay loops.
|
||||
415
apps/docs/public/docs/vertical-slice-evaluation.md
Normal file
415
apps/docs/public/docs/vertical-slice-evaluation.md
Normal file
@@ -0,0 +1,415 @@
|
||||
# Vertical Slice Evaluation
|
||||
|
||||
**Date:** 2026-05-31
|
||||
**Scope:** Compare the current playable game implementation against the MVP Loop Slice demo and the Era 1 roadmap goals.
|
||||
|
||||
---
|
||||
|
||||
## Executive Assessment
|
||||
|
||||
The project has a strong vertical-slice prototype in the docs app, but the standalone game app is still a Phase 0 technical shell. The MVP Loop Slice demonstrates the intended solo loop and connects many previously standalone demos through a shared browser session. The actual game app connects to SpacetimeDB, creates/subscribes to starter rows, and exposes connection/reducer status, but it does not yet implement the playable slice loop.
|
||||
|
||||
In practical terms:
|
||||
|
||||
- **Design/demo confidence is high.** The docs app proves the target loop and system UX at prototype fidelity.
|
||||
- **Runtime implementation readiness is early.** The game app has connection plumbing and starter persistence only.
|
||||
- **The main gap is migration from prototype state to authoritative game state.** The loop exists in localStorage and React state, not in SpacetimeDB tables/reducers.
|
||||
- **Phase 0 is partially complete.** SpacetimeDB connectivity, starter player/ship/system/station rows, and reducer invocation exist. The rendered star system, tick loop, 3D scene, and gameplay commands are not yet present in the game app.
|
||||
|
||||
---
|
||||
|
||||
## Baselines Compared
|
||||
|
||||
### Intended Era 1 Vertical Slice
|
||||
|
||||
The roadmap defines Era 1 as a single-player proof of concept using local SpacetimeDB from day one. The minimum full loop is:
|
||||
|
||||
1. Boot the game and connect to local SpacetimeDB.
|
||||
2. Render a single star system with station and asteroids.
|
||||
3. Undock.
|
||||
4. Navigate to an asteroid belt.
|
||||
5. Mine ore into cargo.
|
||||
6. Return and dock.
|
||||
7. Refine ore.
|
||||
8. Fit or confirm a module.
|
||||
9. Sell goods on a market.
|
||||
10. Optionally run a combat trial.
|
||||
11. Persist state through SpacetimeDB, not localStorage.
|
||||
|
||||
### Docs-App MVP Loop Slice
|
||||
|
||||
The docs app already implements a connected prototype of that loop:
|
||||
|
||||
- Session/objective flow: `apps/docs/src/prototypes/game-slice/sliceObjectives.ts`
|
||||
- Local session state and event reducer: `apps/docs/src/prototypes/game-slice/gameSliceState.ts`
|
||||
- Action gating and contextual commands: `apps/docs/src/prototypes/game-slice/sliceController.ts`
|
||||
- Runtime controller: `apps/docs/src/prototypes/game-slice/useSliceController.ts`
|
||||
- Loop shell/UI composition: `apps/docs/src/prototypes/game-slice/SeamlessGameLoopSlice.tsx`
|
||||
|
||||
It validates the user-facing flow, command availability, objective tracking, event log, cargo, station services, fitting handoff, market selling, XP awards, Zora observation events, and optional combat branch.
|
||||
|
||||
Its explicit limitation is architectural: it uses local browser persistence and fake/deterministic data. It does not validate backend authority, persistence model, multiplayer path, generated bindings, or SpacetimeDB reducer design.
|
||||
|
||||
### Standalone Game App
|
||||
|
||||
The standalone game app currently validates the connection path:
|
||||
|
||||
- SpacetimeDB connection lifecycle: `apps/game/src/spacetime/useSpacetimeConnection.ts`
|
||||
- Subscription/read facade: `apps/game/src/spacetime/usePlayerSession.ts`
|
||||
- Flight console shell: `apps/game/src/GameShell.tsx`
|
||||
- Starter backend module: `services/spacetimedb/src/index.ts`
|
||||
|
||||
The backend currently provides:
|
||||
|
||||
- `player`
|
||||
- `ship`
|
||||
- `system`
|
||||
- `station`
|
||||
- `server_event`
|
||||
- `connectPlayer`
|
||||
- `renamePlayer`
|
||||
- `seedWorld`
|
||||
- `ping`
|
||||
|
||||
This is useful and necessary, but it is not yet the playable vertical slice.
|
||||
|
||||
---
|
||||
|
||||
## Alignment Matrix
|
||||
|
||||
| Slice expectation | Demo status | Game app status | Gap |
|
||||
|---|---:|---:|---|
|
||||
| App boots | Yes | Yes | Mostly aligned. |
|
||||
| Local SpacetimeDB connection | No | Partial | Game connects, but the slice does not use it. |
|
||||
| Starter player identity | No | Yes | Present in game shell only. |
|
||||
| Starter ship row | No | Yes | Present, but no position/mode/cargo/fitting state. |
|
||||
| Single star system | Yes, fake/system data | Partial | Backend has one system and station; no asteroid rows or scene rendering. |
|
||||
| Station and asteroids visible | Yes | No | Game shell displays data cards only. |
|
||||
| 60fps render / 1Hz sim tick | Prototype timers only | No | No authoritative sim tick or render scene in game app. |
|
||||
| Undock/dock | Yes | No | Needs reducers, row state, and UI commands. |
|
||||
| Local movement / approach target | Yes | No | Needs target/position model and movement reducer/tick. |
|
||||
| Warp/travel handoff | Yes in demos | No | Needs backend travel operation model. |
|
||||
| Mining cycle | Yes | No | Needs asteroid/cargo/mining operation tables and reducers. |
|
||||
| Cargo and inventory | Yes | No | Needs authoritative inventory schema. |
|
||||
| Refining | Yes | No | Needs station service reducer and inventory transaction. |
|
||||
| Fitting | Yes | No | Needs module catalog, ship fitting rows, CPU/PG validation. |
|
||||
| Market selling | Yes | No | Needs market/order/transaction state, even if NPC-only first. |
|
||||
| Combat trial | Yes | No | Needs NPC entity/combat reducer loop. |
|
||||
| Objective tracker | Yes | No | Needs game app UI or server-backed tutorial/objective state. |
|
||||
| Event log | Yes | Partial | Game has server events, but not gameplay events. |
|
||||
| Skills/XP | Yes | No | Needs skill rows and XP reducer. |
|
||||
| Zora Tier 0 hooks | Yes | No | Needs backend state and game UI hooks. |
|
||||
| Persistence | localStorage | Partial SpacetimeDB | Game persists starter rows only; slice state still localStorage. |
|
||||
|
||||
---
|
||||
|
||||
## What Lines Up Well
|
||||
|
||||
### 1. The vertical slice is coherent
|
||||
|
||||
The MVP Loop Slice is not just a gallery of isolated screens. It has a real objective chain:
|
||||
|
||||
`undock -> navigate_to_belt -> mine_ore -> dock_at_station -> refine_ore -> fit_module -> sell_goods -> combat_trial`
|
||||
|
||||
That is the correct shape for Gate 4 and gives implementation a clear target.
|
||||
|
||||
### 2. Command gating is already well modeled
|
||||
|
||||
The slice controller has concrete command availability rules: dock only at stations, mine only at belts, services only while docked, market only with sellable cargo, refining only with enough ore, and busy-state blocking while operations run. These are exactly the rules that should become server-side validation in reducers.
|
||||
|
||||
### 3. The game app has the right backend direction
|
||||
|
||||
The game app already uses SpacetimeDB bindings, reducer calls, subscriptions, identity, and server event rows. This lines up with the roadmap decision to avoid localStorage as the final persistence layer.
|
||||
|
||||
### 4. The demo gallery honestly documents limitations
|
||||
|
||||
The docs already distinguish UX validation from production implementation. That makes the remaining work clearer: the problem is not unknown design, it is backend-backed integration.
|
||||
|
||||
---
|
||||
|
||||
## Key Gaps
|
||||
|
||||
### 1. The demo and the game app use different state models
|
||||
|
||||
The MVP Loop Slice stores a rich `GameSliceSession` in localStorage. The game app stores only starter identity, ship, system, station, and event rows in SpacetimeDB.
|
||||
|
||||
This creates the largest implementation gap. Nearly every field in the slice session needs either a backend table, a derived client view, or an explicit decision that it remains client-only.
|
||||
|
||||
Important missing authoritative state includes:
|
||||
|
||||
- current ship mode: station, flight, travel, mining, docking, combat
|
||||
- ship position and current point of interest
|
||||
- docked station state
|
||||
- active operation with start time and duration
|
||||
- selected target
|
||||
- cargo and cargo capacity
|
||||
- fitted modules
|
||||
- wallet
|
||||
- skills and XP
|
||||
- objectives/tutorial progress
|
||||
- Zora module/state hooks
|
||||
|
||||
### 2. Phase 0 rendering is not implemented in the game app
|
||||
|
||||
The roadmap says Phase 0 is done when the app shows a star system with a station and three asteroids, updates local state on a tick, and persists through SpacetimeDB. The current game app is a useful diagnostic console, but it does not render the playable space scene or asteroid targets.
|
||||
|
||||
### 3. Backend schema is intentionally minimal
|
||||
|
||||
The backend module currently supports connection and starter world creation. It does not yet contain the tables required for the slice loop:
|
||||
|
||||
- points of interest or asteroid belts
|
||||
- inventory/cargo
|
||||
- wallet transactions
|
||||
- mining operations
|
||||
- refining jobs
|
||||
- module catalog
|
||||
- ship fittings
|
||||
- market orders or NPC buy prices
|
||||
- skills
|
||||
- objectives/tutorial state
|
||||
- NPCs/combat state
|
||||
|
||||
### 4. Reducers do not yet represent gameplay commands
|
||||
|
||||
The current reducers are connection/admin-level:
|
||||
|
||||
- `connectPlayer`
|
||||
- `renamePlayer`
|
||||
- `seedWorld`
|
||||
- `ping`
|
||||
|
||||
The slice needs command reducers such as:
|
||||
|
||||
- `undock`
|
||||
- `dock`
|
||||
- `selectTarget`
|
||||
- `startApproach`
|
||||
- `completeMovement` or server tick movement resolution
|
||||
- `startMining`
|
||||
- `stopMining`
|
||||
- `completeMiningCycle`
|
||||
- `refineOre`
|
||||
- `fitModule`
|
||||
- `unfitModule`
|
||||
- `sellItemToNpcMarket`
|
||||
- `startCombatTrial`
|
||||
- `resolveCombatTick`
|
||||
|
||||
### 5. The demo validates flow, not balance or backend correctness
|
||||
|
||||
The slice has deterministic prices, deterministic refining, simplified XP, and simplified combat. It proves the player journey, but not the production economy, exploit resistance, transaction safety, concurrent updates, or server authority.
|
||||
|
||||
### 6. Naming and world setup are not fully unified
|
||||
|
||||
The game shell seeds `solace` / `solace-prime` / "Solace Prime Orbital". The slice defaults to `sol` / `sol-station-0` / "Jita IV - Moon 4". This is acceptable for prototypes, but it will create migration friction if not unified before gameplay reducers are added.
|
||||
|
||||
### 7. Existing standalone demos are only partially integrated
|
||||
|
||||
The docs note that several demos can consume the slice session, but core effects still remain demo-local. For example, fitting can update slice modules and combat can emit victory, but the final game still needs one authoritative source of truth where fitting affects mining/combat stats and combat affects wallet/cargo/ship state.
|
||||
|
||||
---
|
||||
|
||||
## Phase Readiness
|
||||
|
||||
### Phase 0 - Local Skeleton
|
||||
|
||||
**Status:** Partially implemented.
|
||||
|
||||
Done:
|
||||
|
||||
- pnpm workspace exists.
|
||||
- standalone game app exists.
|
||||
- SpacetimeDB module exists.
|
||||
- generated/placeholder bindings are committed.
|
||||
- client attempts connection and handles unavailable backend clearly.
|
||||
- starter player, ship, system, station, and events exist.
|
||||
|
||||
Remaining:
|
||||
|
||||
- render a star system in the game app.
|
||||
- add station plus three asteroid targets to backend state.
|
||||
- add local simulation tick concept.
|
||||
- persist position/mode/state through SpacetimeDB.
|
||||
- replace diagnostic-only console with first playable flight shell.
|
||||
|
||||
### Phase 1 - Movement & Commands
|
||||
|
||||
**Status:** Prototyped, not implemented in game app.
|
||||
|
||||
The movement demo and slice validate UX, target selection, approach, ETA/progress, and arrival. The game app needs backend-backed target state, command reducers, and client interpolation.
|
||||
|
||||
### Phase 2 - Mining & Inventory
|
||||
|
||||
**Status:** Prototyped, not implemented in game app.
|
||||
|
||||
The slice validates mining cycles and cargo filling. The game app needs inventory rows, asteroid/belt rows, mining operation state, cargo capacity, and transaction-safe ore insertion.
|
||||
|
||||
### Phase 3 - Combat
|
||||
|
||||
**Status:** Prototyped, not implemented in game app.
|
||||
|
||||
The demo validates power allocation and combat feel. The game app needs NPC entities, combat session state, damage resolution, ship health, loot, bounty payout, and failure/death handling.
|
||||
|
||||
### Phase 4 - Fitting
|
||||
|
||||
**Status:** Prototyped, not implemented in game app.
|
||||
|
||||
The fitting demo validates module constraints and UI feel. The game app needs module catalog rows, fitted module rows, CPU/PG validation in reducers, and stat derivation that affects mining/combat.
|
||||
|
||||
### Phase 5 - Refining & Manufacturing
|
||||
|
||||
**Status:** Refining prototyped; manufacturing not in slice runtime.
|
||||
|
||||
The slice supports ore-to-mineral refining. Manufacturing remains a later implementation gap for the full Era 1 economy loop.
|
||||
|
||||
### Phase 6 - NPC Economy Sim
|
||||
|
||||
**Status:** Market surface prototyped; backend economy not implemented.
|
||||
|
||||
The market demo validates presentation and selling flow. The game app needs NPC price state, transaction reducers, market history, and later regional differences/diffusion.
|
||||
|
||||
### Phase 7 - Single-Player Polish
|
||||
|
||||
**Status:** Design-ready, implementation not started in game app.
|
||||
|
||||
Tutorial/objectives, events, Zora Tier 0, accessibility, persistence, and polish are documented/prototyped in parts, but not integrated into the standalone game.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Implementation Path
|
||||
|
||||
### Step 1 - Promote the slice state into a backend contract
|
||||
|
||||
Create a mapping document or code comments that classify each `GameSliceSession` field as:
|
||||
|
||||
- persisted backend state
|
||||
- derived client state
|
||||
- temporary UI state
|
||||
- prototype-only state to delete
|
||||
|
||||
This prevents blindly copying localStorage structure into SpacetimeDB while still preserving the proven flow.
|
||||
|
||||
### Step 2 - Finish Phase 0 in the game app
|
||||
|
||||
Add the smallest playable world:
|
||||
|
||||
- one system
|
||||
- one station
|
||||
- three asteroid/belt POIs
|
||||
- one starter ship with position, mode, and docked state
|
||||
- a 3D or 2.5D in-space view
|
||||
- a simple read-only HUD showing authoritative rows
|
||||
- a 1Hz server/sim update path or explicit reducer-driven operation completion
|
||||
|
||||
Acceptance check: open the game app, connect to local SpacetimeDB, and see the starter system represented visually rather than only as data cards.
|
||||
|
||||
### Step 3 - Port the command rail one command at a time
|
||||
|
||||
Use the slice action gating as the implementation source for server validation. Add reducers in this order:
|
||||
|
||||
1. `undock`
|
||||
2. `selectTarget`
|
||||
3. `startApproach`
|
||||
4. `dock`
|
||||
5. `startMining`
|
||||
6. `stopMining`
|
||||
7. `refineOre`
|
||||
8. `fitModule`
|
||||
9. `sellItemToNpcMarket`
|
||||
10. `startCombatTrial`
|
||||
|
||||
Each reducer should produce a `server_event` row so the current game shell remains useful while the UI evolves.
|
||||
|
||||
### Step 4 - Add the minimum schema for Gate 1
|
||||
|
||||
For the first integrated gate, implement only what is needed for:
|
||||
|
||||
`navigate to asteroid -> mine -> fill cargo -> dock -> sell ore`
|
||||
|
||||
Minimum tables/fields:
|
||||
|
||||
- ship location/mode/position/docked state
|
||||
- points of interest
|
||||
- cargo/inventory
|
||||
- wallet
|
||||
- active operation
|
||||
- market NPC buy price or station commodity price
|
||||
- event log
|
||||
|
||||
Avoid implementing manufacturing, full market depth, skills, Zora, or combat until Gate 1 works end to end.
|
||||
|
||||
### Step 5 - Replace localStorage handoff with SpacetimeDB-backed session state
|
||||
|
||||
The docs slice can continue to exist as a UX reference, but the standalone game should become the source of truth for vertical-slice progress. Once equivalent reducers exist, either:
|
||||
|
||||
- point the docs slice at the same backend for live validation, or
|
||||
- freeze it as an archived prototype and move active work into `apps/game`.
|
||||
|
||||
### Step 6 - Add focused verification
|
||||
|
||||
Add tests at the reducer/logic level before broad UI tests:
|
||||
|
||||
- connecting creates one player and one starter ship
|
||||
- repeated connect is idempotent
|
||||
- undock changes docked state and mode
|
||||
- movement cannot start while docked
|
||||
- docking only works at a station POI
|
||||
- mining only works at a belt and respects cargo capacity
|
||||
- refining consumes ore and creates minerals
|
||||
- selling removes inventory and increases wallet
|
||||
- invalid fitting is rejected
|
||||
|
||||
---
|
||||
|
||||
## Open Decisions
|
||||
|
||||
1. **Which app is the product surface?**
|
||||
Recommendation: `apps/game` should become the product surface; `apps/docs` remains design/prototype reference.
|
||||
|
||||
2. **How much of the slice UI should be ported?**
|
||||
Recommendation: port the interaction model and command gating, not the localStorage architecture.
|
||||
|
||||
3. **Should Phase 0 include Three.js immediately?**
|
||||
Recommendation: yes, if the target is a space game with Flight Mode as a first-class surface. The docs already have reusable R3F scene pieces that can guide the implementation.
|
||||
|
||||
4. **What is the canonical starter world?**
|
||||
Recommendation: choose one naming/id set before adding gameplay reducers. Prefer production-neutral IDs over inherited EVE names.
|
||||
|
||||
5. **Server tick vs. reducer-scheduled completion?**
|
||||
Recommendation: for early phases, reducer-driven operations with authoritative timestamps are enough. Add a scheduler/tick once NPCs, economy, and combat need autonomous progression.
|
||||
|
||||
---
|
||||
|
||||
## Priority Work List
|
||||
|
||||
### Immediate
|
||||
|
||||
1. Decide canonical starter system/station/POI IDs.
|
||||
2. Add backend POI/asteroid state.
|
||||
3. Add ship mode, position, docked state, wallet, and cargo state.
|
||||
4. Build the game app's first visual system scene.
|
||||
5. Add `undock`, `dock`, and `startApproach` reducers.
|
||||
|
||||
### Next
|
||||
|
||||
1. Add mining operation and cargo reducers.
|
||||
2. Add station sell/refine reducers.
|
||||
3. Port the command rail/objective tracker into `apps/game`.
|
||||
4. Add reducer tests for Gate 1.
|
||||
5. Run a manual Gate 1 playtest.
|
||||
|
||||
### Later
|
||||
|
||||
1. Fitting with CPU/PG validation.
|
||||
2. Combat trial with NPC state and loot.
|
||||
3. Skills/XP progression.
|
||||
4. Zora Tier 0 backend state.
|
||||
5. Manufacturing and deeper NPC economy.
|
||||
|
||||
---
|
||||
|
||||
## Bottom Line
|
||||
|
||||
The game lines up well with the vertical slice at the design and prototype level, but not yet at the playable implementation level. The docs app has already answered "what should the first loop feel like?" The standalone game app is now ready to answer "can that loop run against authoritative SpacetimeDB state?"
|
||||
|
||||
The next milestone should be a narrow Gate 1 implementation in `apps/game`: connect, undock, approach asteroid, mine ore, dock, and sell. That is the shortest path from demo confidence to a real playable vertical slice.
|
||||
Reference in New Issue
Block a user