Skip to content

EchoSpire — Development Status & Walkthrough

Body last written: March 5, 2026 · Counts re-verified: 2026-08-27

STATUS: PARTIALLY STALE — verify before citing. The system-by-system walkthrough below was written in March 2026 and has not had a full pass since. The test counts and the WPF section were corrected on 2026-08-27; the rest is March-era and known to understate what exists. Treat a "not started" claim here as unverified, not as fact.

Two known understatements found on 2026-08-27: all five faction mini-games are implemented (see MiniGames.md), and the package-model builders exist (see PackageModel.md).

This document walks through every major system, explains what's built, what's working, what's stubbed out, and what's not started yet. Think of it as a guided tour of the codebase in its current state.

Overall Health

  • ~693 test methods as of 2026-08-27 (~443 Core, ~208 API, ~22 ConsoleGame, ~15 WPF, ~5 Simulation). The March figure of 410 was accurate then; the suite has grown ~70% since, and a EchoSpire.Wpf.Tests project has been added that the March breakdown predates.
  • Zero compiler warnings (clean build on .NET 10)
  • API runs locally on port 5221 against SQL Server (Azure SQL)
  • Console game plays the full tutorial loop for all 5 factions
  • Simulation engine runs headless batches
  • Admin portal has pages for all entity types

System-by-System Status

1. Combat System — FULLY BUILT

Status: Complete and thoroughly tested. This is the most mature system.

What works: - Full turn cycle: player card play → enemy phase → cleanup → new turn - Card resolver pipeline with energy management, Unplayable/Exhaust/Retain/Overload keywords - Damage calculation with Block, STRENGTH, BREACH (1.25x multiplier), ECHO_BURN_BONUS - Event pipeline with 20+ event types (BeforeDamageDealt, AfterCardPlayed, TurnStarting, etc.) - All 5 class mechanics as handlers: - Density (Anchor): Block retention scaling, Grav-Lock penalty at max stacks - Echo-Lock (Drifter): 5-stack burst trigger with block-piercing damage - Overload (Conduit): Energy debt that deals self-damage on next turn - Construct (Machinist): 3-slot construct grid with auto-firing abilities and Overclock - Mutation (Catalyst): Card transformation into Anomaly variants - All 5 faction passives as handlers: - Stasis Lock (Valerii): Conditional block gain - Calibration Protocol (Axiom): Draw pile manipulation - Gilded Syphon (Syndicate): Self-damage for damage amplification - Temporal Echo (Censors): Discard pile retrieval - Scrap Protocol (Salvari): Energy from Exhaust - Protection Rift encounters (defend a VIP entity for N turns with data-driven scar cards on failure) - Status effects (Stasis, Breach, Strength, Structural Fracture, etc.) - Relic handler (triggers on combat events) - Enemy intent patterns with multiple targeting policies (Player, RandomConstruct, WeakestConstruct, RandomProtectable, WeakestProtectable, Adaptive)

Test coverage: CombatTests.cs, CombatPipelineTests.cs, CardResolverAndLifecycleTests.cs, BossMechanicsTests.cs, FactionPassiveTests.cs, MechanicsTests.cs

What to think about: The combat system is designed for composition — adding a new keyword, status effect, or mechanic means writing a new handler and registering it. No existing code needs to change. This is working well.

2. Effect System — FULLY BUILT

Status: Complete with 15+ effect implementations.

What works: - EffectRegistry with assembly scanning (auto-discovers IEffect implementations) - Data-driven card effects: cards store effect IDs + JSON parameters, not code - Full effect pipeline with EffectContext providing combat state, source, target, pipeline access

Implemented effects: DEAL_DAMAGE, GAIN_BLOCK, APPLY_STASIS, APPLY_STATUS, APPLY_ECHO_LOCK, GAIN_DENSITY, GAIN_ENERGY, DRAW_CARDS, HEAL, DEPLOY_CONSTRUCT, OVERCLOCK_CONSTRUCT, ECHO_BURN, ECHO_RECALL, LOGIC_STREAM, MUTATE_CARD

Test coverage: EffectTests.cs, AdditionalEffectTests.cs

What to think about: New card ideas just need to compose existing effects with different parameters. If a truly new mechanic is needed, it's one new IEffect implementation. The pattern is well-established and consistent.

3. Map Generation — FULLY BUILT

Status: Complete with deterministic seeded generation.

What works: - Procedural DAG generation with configurable row counts, branching factors, and node type weights - 10 node types: Combat, Elite, Shop, Event, Rest, Boss, Anchor, Treasure, Protection, Sanctuary - Fog of War (reveal on visit, Anchor reveals all) - Guaranteed shop in penultimate row - Edge connections with transit interrupt chances (anomaly encounters) - All parameters database-driven via MapGenParams

What to think about: Map generation is feature-complete for the tutorial and early campaign. Multi-realm runs (where you traverse 3+ realms with escalating difficulty) will need realm-to-realm progression logic in GameRunner, but the map generator itself already supports arbitrary realm indices.

4. RNG System — FULLY BUILT

Status: Complete and well-tested.

What works: - 64-bit seeded RNG with namespace forking (combat RNG independent of map RNG) - Full determinism guarantee: same seed + same decisions = identical outcome - Utility methods: NextInt(), NextDouble(), NextBool(), Shuffle(), WeightedChoice() - Seeds display as Base-36 alphanumeric strings

Test coverage: SeededRNGTests.cs, RandomPolicyTests.cs

5. Economy System — FULLY BUILT

Status: Complete with configurable parameters.

What works: - Gold rewards by encounter type (15/30/75) - Card reward counts - Shop pricing by rarity (buy and sell) - Card removal cost - Rest healing (30% of max HP) - Splice (card upgrade) system: Retain, Exhaust, DamageBoost upgrades with pricing - All values from EconomyConfig (database-driven)

Test coverage: EconomyManagerTests.cs

What to think about: Economy values are currently the tutorial defaults. Real campaign balance will need tuning once there's enough gameplay data from simulations.

6. Tutorial System — FULLY BUILT

Status: Complete for all 5 factions. Recently upgraded with template variable system.

What works: - 5 faction tutorials, each with: - 8-node scripted rift map - Fixed enemy encounters with faction-thematic enemies - Story beats with trigger conditions and template variable resolution - Protection Rift encounter (unique per faction: turn count, protectable entity, scar card, failure penalty) - Boss fight with faction-specific mechanics - Narrative intro and outro - Faction passive unlock on victory - Template system: {SurviveTurns}, {FailurePenalty} etc. resolved from encounter data - Data-driven protection rifts: each faction has its own turn count, VIP entity, HP, penalty, scar card, and messages - Tutorial data defined as static C# (compile-time reliable, no database dependency)

Factions and their tutorials:

Faction Tutorial Boss Protectable Survive Turns Scar Card
Valerii The Iron Oath The Siege Echo Barricade Generator (40 HP) 6 Failed Watch
Axiom The Calibration Sequence The Null Arbiter Logic Array (35 HP) 5 Data Corruption
Syndicate The Gilded Crucible The Crucible Incarnate Distillation Vat (30 HP) 4 Bad Investment
Censors The First Record The Temporal Parasite Memory Codex (35 HP) 5 False Memory
Salvari The Chore List The Corroded Engine-Heart Gravity Regulator (40 HP) 4 Structural Guilt

Test coverage: TutorialDataTests.cs (57 tests covering all factions' data integrity, template vars, scar cards)

7. Telemetry System — FULLY BUILT

Status: Complete with dual-write capability.

What works: - GameTelemetrySession records 15+ event types with monotonic sequencing - Events: RunStarted/Ended, PhaseStarted/Ended, CombatStarted/Ended, TurnEnded, CardPlayed, EnemyAction, GoldChanged, DeckChanged, RelicAcquired, NodeEntered, EventChoice, ErrorOccurred - KustoTelemetryWriter → Azure Data Explorer (production analytics) - JsonFileTelemetryWriter → local NDJSON files in %LOCALAPPDATA%\EchoSpire\telemetry\ - CompositeTelemetryWriter → both simultaneously - NullTelemetryWriter → testing - API exposes POST /api/v1/telemetry/query for raw KQL

Test coverage: TelemetryTests.cs, KustoIntegrationTests.cs

What to think about: The telemetry pipeline is production-ready. What's missing is analysis — dashboards, automated balance reports, anomaly detection. The data is being captured; the insights layer isn't built yet.

8. API — FULLY BUILT

Status: Complete with all CRUD endpoints, auth, and infrastructure.

What works: - JWT authentication (login, refresh, register) with role-based authorization - Game data CRUD: cards, enemies, classes, factions, relics, economy params, map params, random events, quest templates, tutorials - Hero management: list, create (with class/faction restriction validation), update appearance - Run management: start, save state, load state, complete - Health endpoint - Data snapshots (publish/rollback versioning) - Audit logging - Graceful provider fallbacks (Redis → in-memory, Kusto → file, AI → hardcoded names) - SQL Server with stored procedures and migrations - Swagger in development mode

Endpoints: 40+ across 8 controllers (Auth, GameData, Heroes, Runs, Admin, Telemetry, Meta, Simulation, Health)

Test coverage: ApiIntegrationTests.cs (full end-to-end flows using WebApplicationFactory + SQLite in-memory)

9. Hero System — FULLY BUILT

Status: Complete end to end.

What works: - Create hero with faction + class + name - Class/faction restriction validation (some classes aren't available to some factions) - AI-generated name suggestions (Anthropic/OpenAI/Ollama with offline fallback) - Hero list filtered by authenticated user - Hero persistence in SQL Server

Test coverage: API integration tests cover full hero CRUD flows

10. Save/Restore — INFRASTRUCTURE BUILT, PARTIALLY INTEGRATED

Status: The API endpoints exist and work. The serialization works. The Console Game has save-at-sanctuary points. Full resume-from-save needs more integration testing.

What works: - RunState serializes to JSON (all fields including deck, relics, map state, mechanic counters) - PUT /api/v1/runs/state saves state, GET /api/v1/runs/state/{id} loads it - SavedRun table with JSON StateJson column - RNG reconstruction from seed on load - Sanctuary nodes auto-save

What's incomplete: - Resume flow in GameRunner needs more testing for edge cases (mid-combat resume, mid-event resume) - No "save and quit" from arbitrary points — only auto-save at sanctuaries

11. Admin Portal — PAGES BUILT, NEEDS POLISH

Status: All entity pages exist. Basic CRUD works. UX is functional but not polished.

What works: - React app (src/admin-react) with pages for: Cards, Classes, Enemies, Factions, Relics, EconomyParams, MapParams, RandomEvents, QuestTemplates, Tutorials, Effects, Simulation. (This section described the Blazor admin until 2026-08-27; that project has been removed.) - Auto-authenticates as SuperAdmin - Publish/rollback versioned snapshots - Queue simulation batches

What's incomplete: - No validation UX (error messages for invalid data) - No bulk import/export - No relationship visualization (which cards belong to which class/faction) - No preview of how changes affect game balance

12. Console Game — FULLY BUILT

Status: Complete as a development and testing client.

What works: - Full game loop: auth → load data → hero selection/creation → tutorial → run - ConsoleGameUI implements all IGameUI methods - ConsoleRenderer handles all terminal rendering (map, combat, shop, events, rest, narrative) - Arrow key navigation, card selection, target selection - Connects to API for data and persistence

What to think about: The Console Game is a development tool, not the shipping product. It exercises every system and proves the architecture works. The shipping client is WPF, which sits on the same Core. Unity is a later presentation upgrade, not the release target.

13. Simulation Engine — PARTIALLY BUILT

Status: Core loop works. Analytics pipeline is stubbed.

What works: - BatchRunner executes N runs with configurable seed, policy, difficulty - RandomPolicy plays games automatically (random card plays, random paths) - Results recorded to telemetry store - CLI arg parsing for batch configuration

What's incomplete: - GET /api/v1/simulation/results — TODO - GET /api/v1/simulation/analytics — TODO - GET /api/v1/simulation/outliers — TODO - Smarter AI policies (greedy, heuristic) not yet implemented - No automated balance reports from simulation data

14. Meta Progression — STUBBED

Status: Endpoints exist with TODO implementations.

What exists: - GET /api/v1/meta/currency → returns { balance: 0 } - GET /api/v1/meta/unlocks → returns { unlocks: [] } - POST /api/v1/meta/unlocks/{itemId} → TODO - GET /api/v1/meta/progression → returns { level: 1, xp: 0 }

What's needed: Meta-currency earned from runs (victory/death/per-realm), persistent unlocks (new cards, cosmetics), cross-run progression tracking.

15. Unity Client — NOT STARTED

Status: Project structure exists (EchoSpire.Unity/EchoSpire_Project/), no implementation.

What's ready for it: The IGameUI interface is fully defined and battle-tested by the Console Game. Unity just needs to implement that interface. All game logic runs in EchoSpire.Core which has no framework dependencies.

Known Issues and Design Gaps

From the GDD consistency audit (now archived at _archive/docs-official/Issues-gdd-consistency-audit.txt) and discovered during development. Note: that audit was written against the GDD, which is itself now archived — several of the naming conflicts below were settled by the 2026-07-03 canon ratification in story/bible/canon-decisions.md. Check there before acting on any of them.

Naming Inconsistencies

  • "Praetors" vs "Valerii" — used interchangeably in some GDD sections
  • "Great Saturation" — term undefined (should be "Reality Bleed", "Schism", or "Prime Deviation")
  • "Grav-Lock" — used as both an ability name AND a debuff name
  • Alden's title — "Chief of Diagnostics" in some places, "Head of Maintenance" in others

Design Holes

  • Anchor/Axiom class-faction synergy not defined (all other combos have documented synergies)
  • Catalyst only available to 2 factions (Syndicate, Salvari) → lowest class variety
  • Echo-Lock "exactly 5 stacks" edge case: what happens if a card tries to apply stack 6?
  • Density block retention: does "without taking Life damage" count damage fully absorbed by Block?
  • Construct targeting AI rules not fully specified
  • Stasis on Player has no counterplay mechanic defined

Content Gaps

  • Card pool is tutorial-only — no full campaign card set designed yet
  • Enemy scaling formulas across difficulty tiers undefined
  • Relic pool is minimal
  • Random event variety is limited
  • Difficulty tier definitions not specified (what changes between tiers?)

What To Work On Next (Suggested Priority)

Near-Term (Foundation)

  1. Full campaign card pool — The tutorial has 8-9 cards per faction. A real run needs 30-50 per faction with rarity distribution
  2. Enemy scaling — Define how enemy HP/damage/abilities scale across realms and difficulty tiers
  3. Save/restore hardening — Test mid-combat and mid-event resume paths
  4. Simulation analytics — Build the results/analytics/outliers endpoints so simulation data becomes actionable

Medium-Term (Content)

  1. Campaign structure — Multi-realm runs (3+ realms with realm-to-realm transitions, escalating difficulty)
  2. Relic pool expansion — Design relics that interact with each mechanic
  3. Random event variety — More events with meaningful choices
  4. Meta progression — Currency, unlocks, cross-run persistence

Long-Term (Platform)

  1. Unity client — Implement IGameUI with 3D visuals
  2. Smarter AI policies — Greedy/heuristic policies for meaningful simulation data
  3. Balance dashboard — Automated reports from telemetry data
  4. Multiplayer/leaderboards — Seeded daily runs, competitive mode

How Systems Connect — The Full Data Flow

┌─────────────────────────────────────────────────┐
│                 SQL Server                        │
│  cards, enemies, factions, classes, relics,      │
│  heroes, saved_runs, economy_params, map_params  │
└──────────────────────┬──────────────────────────┘
                       │ Stored Procedures
                       ▼
┌──────────────────────────────────────────────────┐
│              EchoSpire.API                        │
│  Controllers → Repositories → DbContext           │
│  JWT Auth, Telemetry, Cache (Redis/InMemory)      │
└──────┬───────────┬───────────┬───────────────────┘
       │ HTTP      │ HTTP      │ HTTP
       ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Console  │ │  Admin   │ │Simulation│
│  Game    │ │ Portal   │ │ Engine   │
└────┬─────┘ └──────────┘ └────┬─────┘
     │                         │
     ▼                         ▼
┌──────────────────────────────────────────────────┐
│              EchoSpire.Core                       │
│                                                   │
│  GameRunner / TutorialRunner (orchestration)      │
│       │                                           │
│       ├── MapGenerator (procedural maps)          │
│       ├── CombatStateMachine (turn execution)     │
│       │      ├── CardResolver (card pipeline)     │
│       │      ├── EffectRegistry (effect lookup)   │
│       │      ├── CombatHandlerPipeline (events)   │
│       │      │      ├── Class handlers            │
│       │      │      ├── Faction handlers          │
│       │      │      └── Relic handlers            │
│       │      └── EnemyCombatState (intent AI)     │
│       ├── EconomyManager (gold/shop/rewards)      │
│       ├── SeededRNG (deterministic randomness)    │
│       ├── GameTelemetrySession (event recording)  │
│       └── RunState (serializable game state)      │
│                                                   │
│  IGameUI ←── ConsoleGameUI (dev)                  │
│          ←── WPF client (shipping)                │
│          ←── UnityGameUI (later upgrade)          │
│          ←── NullGameUI (simulation)              │
└──────────────────────────────────────────────────┘

File Quick Reference

What Where
Combat state machine src/EchoSpire.Core/Combat/CombatStateMachine.cs
Card resolver src/EchoSpire.Core/Combat/CardResolver.cs
Handler pipeline src/EchoSpire.Core/Combat/CombatHandlerPipeline.cs
Handler factory src/EchoSpire.Core/Combat/CombatHandlerFactory.cs
All class/faction handlers src/EchoSpire.Core/Combat/Handlers/
Effect registry src/EchoSpire.Core/Effects/EffectRegistry.cs
All effect implementations src/EchoSpire.Core/Effects/Implementations/
Map generator src/EchoSpire.Core/Map/MapGenerator.cs
Run state src/EchoSpire.Core/State/RunState.cs
Combat state src/EchoSpire.Core/State/CombatState.cs
Seeded RNG src/EchoSpire.Core/RNG/SeededRNG.cs
Economy manager src/EchoSpire.Core/Economy/EconomyManager.cs
Game runner src/EchoSpire.Core/Orchestration/GameRunner.cs
Tutorial runner src/EchoSpire.Core/Orchestration/TutorialRunner.cs
UI interface src/EchoSpire.Core/UI/IGameUI.cs
All enums src/EchoSpire.Core/Enums/
All models src/EchoSpire.Core/Models/
Telemetry session src/EchoSpire.Core/Telemetry/GameTelemetrySession.cs
Telemetry events src/EchoSpire.Core/Telemetry/Events/GameTelemetryEvents.cs
API startup src/EchoSpire.API/Program.cs
DB context src/EchoSpire.API/Data/EchoSpireDbContext.cs
All controllers src/EchoSpire.API/Controllers/
Auth setup src/EchoSpire.API/Auth/
Console game entry src/EchoSpire.ConsoleGame/Program.cs
Console renderer src/EchoSpire.ConsoleGame/ConsoleRenderer.cs
Simulation runner src/EchoSpire.Simulation/Runner/BatchRunner.cs
Tutorial data (per faction) src/EchoSpire.Core/Models/*TutorialData.cs
Faction narrative docs FactionTutorials/*.md
Story canon story/bible/
Game design doc (superseded) _archive/gdd/
Tech requirements (superseded, 2026-02-27) _archive/docs-official/TechRequirements-v1-2026-02-27.txt — specifies ClickHouse; the system runs Kusto. Archived 2026-08-27
GDD consistency audit (superseded) _archive/docs-official/Issues-gdd-consistency-audit.txt — audits GDD.txt, a file that no longer exists