Skip to content

WPF MVP Kickoff

Purpose

This document defines the first real implementation pass for the EchoSpire WPF MVP client.

It exists to answer five practical questions:

  • what we should build first
  • why WPF is the current MVP choice
  • what WPF should own versus what must stay in Core
  • how the first paid-preview slice should be structured
  • how to keep a later Unity migration cheap if the product is proven

Current Repo Reality

The repository already contains the backend, runtime, and contract foundations needed for a Windows-first client shell:

  • auth endpoints
  • game-data endpoints
  • hero CRUD endpoints
  • tutorial data endpoints
  • a shared Core runtime with UX abstraction boundaries

The strongest practical reason to use WPF for the MVP is current implementation speed.

The product needs a real player-facing client sooner than it needs advanced engine-specific presentation. A Windows-first WPF shell is the fastest route to a paid preview on Steam while preserving the option to migrate the presentation layer later.

Product Decision

The current direction is:

  • target the first paid preview as Windows-first
  • use WPF for the MVP presentation client
  • keep gameplay-rule truth in EchoSpire.Core
  • treat Unity as a later presentation upgrade only if the product proves itself and the upgrade is justified

This is a product-speed decision, not a statement that WPF is the ideal forever game client.

Why WPF Is The Right MVP Choice Now

WPF is the right current choice because:

  • implementation familiarity is stronger right now than Unity familiarity
  • the early product risk is proving retention, clarity, and willingness to pay, not maximizing rendering sophistication
  • the current architecture already supports multiple presentation clients as long as rule ownership stays in Core
  • Steam can distribute a Windows desktop executable without caring whether the client was built in WPF or Unity

The cost of this decision is that a later Unity migration would still require a presentation rewrite.

That cost is acceptable only if the WPF client stays disciplined and does not become the owner of gameplay logic.

Non-Negotiable Boundaries

WPF should own:

  • application startup
  • windowing and layout
  • screen flow and local UX state
  • settings, local cache, and packaging behavior
  • API orchestration for auth, heroes, tutorials, run bootstrap, and save-resume surfaces
  • visual styling, templates, and interaction polish appropriate for the MVP

WPF must not own:

  • combat rules
  • map-generation rules
  • reward logic
  • save-schema truth
  • deterministic sequencing rules
  • duplicated effect execution behavior

If a choice would make a later Unity migration rewrite gameplay logic instead of presentation, it is the wrong choice.

The first WPF milestone should be a thin but real client shell with this flow:

  1. boot directly into a branded command-deck shell
  2. bootstrap the configured preview player session automatically inside the client
  3. fetch factions and eligible classes without exposing transport setup in the UI
  4. list existing heroes for the active player account
  5. create a new hero with appearance metadata stub support
  6. fetch tutorial and run-start data needed for the next screen transition

This milestone is valuable because it validates:

  • backend connectivity from the real desktop client
  • account and hero ownership flow
  • real player-facing layout and pacing decisions
  • the minimum paid-preview shell needed to move beyond the console client
  • the state-management seam that later combat and map screens will reuse

MVP Architecture Direction

The WPF client should be structured around five layers:

1. Bootstrap And Host Layer

  • app startup
  • configuration loading
  • dependency injection
  • HTTP client registration
  • local settings and cache wiring

2. Transport And API Layer

  • auth client
  • game-data client
  • hero client
  • run client
  • DTO translation and token handling

3. Application Layer

  • screen routing
  • session state
  • run bootstrap orchestration
  • save-resume decisions
  • error handling and recovery

4. Presentation Layer

  • XAML views
  • view-models or presenters
  • styling, templates, and asset references
  • user input and command bindings

5. Core Integration Seam

  • explicit translation from Core-owned gameplay or run events into UI-facing state
  • no WPF types crossing inward into gameplay code
  • no gameplay code depending on XAML, bindings, or window state

Suggested Project Structure

The first WPF project should be organized like this:

  • App.xaml and app startup wiring
  • Configuration/ for client options and local settings models
  • Services/ for API clients and session services
  • ViewModels/ for screen state and command handlers
  • Views/ or root window XAML for shell composition
  • Presentation/ for styling resources and later control templates
  • Infrastructure/ for command and observable-object helpers

Immediate Build Order

  1. scaffold the WPF app shell and configuration model
  2. wire dependency injection, HTTP client setup, and preview-session bootstrap
  3. implement faction, class, and hero-list loading behind the shell
  4. implement hero creation with appearance stub payload support
  5. turn the run-ready surface into a real start, resume, or abandon handoff
  6. add combat, map, rewards, and save-resume screens without moving gameplay-rule truth out of Core
  7. keep account and session work integrated into actual product screens rather than as standalone setup widgets

The first paid preview should include:

  • command deck and integrated account state flow
  • hero selection and hero creation
  • tutorial and run bootstrap flow
  • combat presentation
  • map presentation
  • rewards, shop, event, and rest flow
  • save, load, resume, and abandon behavior
  • settings and crash-safe recovery messaging

It does not need final animation, advanced VFX, or a maximal controller-first presentation layer.

Migration Rules For Future Unity

If the product is proven and a Unity upgrade becomes worth funding, the migration should replace presentation, not rules.

To preserve that option:

  • keep view-model state separate from gameplay state
  • keep transport DTOs and UX event payloads portable
  • keep save-schema and run-state ownership outside WPF-specific code
  • do not let code-behind evolve into the real game loop
  • prefer explicit adapters over hidden UI-driven orchestration

Success Criteria

The WPF MVP kickoff pass is successful when:

  • the new client boots cleanly on Windows
  • it can bootstrap the configured preview player session without visible setup controls
  • the client can load factions and heroes from the API
  • the repo has a stable WPF client shell for iterating toward paid-preview scope
  • the shell has a documented screen flow and stub surfaces for the next screens
  • the Unity migration seam is still clear and bounded