Skip to content

Unity Client Kickoff

Current Status

This document is no longer the immediate MVP client plan.

The current product direction is to use a Windows-first WPF client for the MVP and first paid preview, then revisit Unity as a later presentation migration target if the product is proven and richer presentation investment is justified.

That means this document should now be read as a preserved later-phase migration target rather than the current first implementation pass.

Purpose

This document defines the later-phase implementation pass for a Unity presentation client after the MVP is proven.

It exists to answer four practical questions:

  • what we should build first
  • what can be done in code versus in the Unity editor
  • what technical constraint currently blocks direct reuse of the shared runtime
  • what visual assets we need for the first playable slice

Current Repo Reality

The repository already contains a Unity 6 project with a 2D/URP-oriented package set and a sample scene.

The repository also already has the backend and runtime foundations needed for a client shell:

  • auth endpoints
  • game-data endpoints
  • hero CRUD endpoints
  • tutorial data endpoints

The main current constraint is that the shared runtime projects target net10.0, while Unity cannot safely consume those assemblies directly as-is.

That means the first Unity milestone should not be a forced direct EchoSpire.Core integration.

The first milestone should instead be a Unity client shell that talks to the API, proves the player-facing flow, and keeps gameplay-rule truth in Core while we prepare a Unity-safe contract split.

Chosen Kickoff Direction

The current kickoff direction is:

  • presentation style: 2D
  • first product slice: hero selection and new run flow
  • workflow preference: minimize manual editor work when possible

This is the fastest route to a real player-facing client without pretending the full combat runtime can already drop into Unity untouched.

What Can Be Done In Code Versus In The Unity Editor

Copilot Can Do Directly In The Repo

  • create Unity-side C# scripts, folders, and assembly definitions
  • define API client classes and DTOs for auth, factions, classes, heroes, and tutorials
  • create editor scripts that reduce repetitive scene setup work
  • define UI architecture, screen flow, and state-management conventions
  • write canonical docs, onboarding notes, and checklists
  • write and preserve Ludo asset prompts in versioned docs
  • scaffold placeholder data models until the shared contract split is ready

Still Better Done In The Unity Editor

  • scene composition and layout tuning
  • prefab creation and visual hierarchy checks
  • assigning references in inspectors unless automated by editor scripts
  • font, sprite, slice, atlas, and import tuning
  • animation timeline and transition authoring
  • camera framing, sorting layers, and 2D lighting tweaks

The goal should be to keep editor-only work focused on visual judgment rather than repetitive setup.

The first Unity milestone should be a thin client shell with this flow:

  1. boot the app into a title screen
  2. authenticate against the API with a player account
  3. fetch factions and eligible classes
  4. list existing heroes for the signed-in 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 Unity
  • account and hero ownership flow
  • real player-facing UI composition
  • the first cosmetic payload path for future portraits and faction styling
  • the screen-state architecture that later combat and map screens will reuse

Current Implemented Shell

The repository now contains the first Unity-side implementation of this milestone as a code-driven bootstrap shell.

That shell currently provides:

  • runtime auto-bootstrap without hand-editing the scene first
  • a Unity-safe shared contract package for auth, faction, class, hero, and tutorial startup DTOs
  • a runtime-built uGUI shell instead of IMGUI bootstrap rendering
  • API login against the existing auth endpoint
  • faction loading and eligible-class discovery
  • hero list loading
  • hero creation with a stub appearance payload
  • tutorial discovery after hero selection or creation
  • run bootstrap metadata via shared run-start and active-run contracts

This is intentionally an implementation scaffold, not final presentation.

The current goal is to validate client flow and contracts before investing in final prefabs, animation, and scene composition.

Required Technical Decision

Before Unity can become the real shipping client for the full runtime loop, the shared runtime contract needs to be split into Unity-safe layers.

The current direction should be:

  • keep gameplay rule truth inside EchoSpire.Core
  • do not duplicate combat logic in Unity
  • avoid direct Unity dependency on the current net10.0 Core assembly
  • extract or mirror Unity-safe DTO and contract layers for shared models that the client must read
  • keep the first Unity slice API-first until that contract work is done

The near-term contract options were:

  1. introduce a Unity-compatible shared contract library for DTOs and UX event payloads
  2. generate API client contracts for Unity from the HTTP surface
  3. temporarily mirror a narrow DTO subset inside Unity for auth, hero, and snapshot flows, then replace it once the shared contract package exists

The repository now has the first version of option 1 in place for startup-flow transport types.

That means the current direction is now:

  • keep startup transport DTOs in a Unity-safe shared package used by both Unity and the API
  • let Unity continue consuming the current API surface while deserializing only the narrow contract subset it needs
  • extend the shared package from startup and run-bootstrap metadata into save payload metadata and UX event payloads instead of jumping straight to full runtime reuse

Initial Unity Client Structure

The intended Unity-side structure for the first pass is:

  • Assets/Scripts/Bootstrap: app startup, configuration loading, and service wiring
  • Assets/Scripts/Api: auth client, hero client, game-data client, DTOs
  • Assets/Scripts/Application: screen-state orchestration and navigation
  • Assets/Scripts/UI: title, login, faction selection, class selection, hero list, hero creation
  • Assets/Scripts/Presentation: faction colors, sprite references, appearance mapping, UI theme helpers
  • Assets/Scripts/Editor: scene/bootstrap helpers that reduce inspector-heavy setup

The important rule is that these scripts should remain presentation and transport code, not gameplay-rule ownership.

Minimal Editor Checklist

The first editor pass should stay small:

  1. open the project in Unity 6.2
  2. confirm package resolution completes successfully
  3. create or rename the first real boot scene
  4. import placeholder visual assets once the first prompt batch is generated
  5. verify a Canvas, EventSystem, and camera setup exist for the boot scene
  6. connect the boot scene to the script-driven app root

Anything repetitive beyond that should be scripted rather than hand-built repeatedly.

First Asset Batch

The first asset batch should support the hero-selection-first slice, not the full game.

That means the first Ludo batch should focus on:

  • title screen background
  • faction crests for the five tutorial factions
  • class-selection card art frames or panels
  • hero portrait placeholder system
  • UI panel, button, and icon kit for a cathedral sci-fi 2D interface

Use Ludo Asset Prompts as the source of truth for those prompts.

Immediate Build Order

  1. create the Unity boot, config, and API shell
  2. implement login and token persistence flow
  3. implement faction, class, and hero list screens
  4. implement hero creation with appearance stub payload support
  5. wire a transition from hero selection into the next run-oriented screen
  6. extend the shared startup and run-bootstrap contract package toward save metadata, combat-bootstrap, and map integration payloads

Non-Goals For This First Pass

The first pass should not try to do all of the following at once:

  • full combat presentation
  • map rendering
  • full animation pipeline
  • final VFX stack
  • final save/resume UX
  • a direct drop-in GameRunner integration from the current net10.0 runtime assembly

Trying to do that immediately would hide the real dependency problem instead of solving it.

Success Criteria

The first Unity kickoff pass is successful when:

  • the project opens cleanly in Unity 6
  • the app boots into a real EchoSpire-branded screen
  • a player can authenticate
  • the client can fetch factions, classes, and heroes from the API
  • a player can create or select a hero
  • the repo has a stable prompt library for the first visual asset batch
  • the next shared-contract extraction task is clearly defined