Aether-Engine/GDD.md

# Aether Engine — Game Design Document
> **Version:** 0.4 · **Status:** Pre-Production / Prototype  
> **Engine:** Unity 6 (URP) · **Platform:** iOS 17+ (primary), iPadOS  
> **Hardware:** Concept2 PM5 (full experience) · Apple Watch (enhanced) · iPhone only (free tier)

---

## Table of Contents
1. [Concept Evaluation — Honest 7/10 → 10/10 Analysis](#1-concept-evaluation)
2. [Commercial Potential](#2-commercial-potential)
3. [The Pitch — Refined](#3-the-pitch--refined)
4. [The "First 60 Seconds" Experience](#4-the-first-60-seconds-experience)
5. [Narrative & World](#5-narrative--world)
6. [Core Design Pillars](#6-core-design-pillars)
7. [Hardware Tiers — Removing the Floor](#7-hardware-tiers--removing-the-floor)
8. [Game Modes (Biomes)](#8-game-modes-biomes)
9. [The "Secret Sauce" — Diegetic Feedback Systems](#9-the-secret-sauce--diegetic-feedback-systems)
10. [Multiplayer & B2B — The Shared World](#10-multiplayer--b2b--the-shared-world)
11. [The Viral Engine](#11-the-viral-engine)
12. [Progression & Retention](#12-progression--retention)
13. [Technical Architecture](#13-technical-architecture)
14. [Current Implementation Progress](#14-current-implementation-progress)
15. [Risk & Feasibility Assessment](#15-risk--feasibility-assessment)
16. [Monetisation](#16-monetisation)
17. [Roadmap](#17-roadmap)

---

## 1. Concept Evaluation

### Original Score: 7/10 → Target: 10/10

The original concept is exceptionally well-reasoned for its hardware category. The Diegetic UI insight, the biome-as-workout-selector framing, and the force-curve-to-audio idea are genuinely novel. No shipping product does this. The gap between 7 and 10 is not about the ideas — it is about **distribution strategy, the first-run experience, and two missing loops** (viral + social).

| Gap | Root Cause | Fix |
|---|---|---|
| **Hardware floor** | "You need a $900 erg" excludes 99.9% of App Store | Free Simulated tier — iPhone only (see §7) |
| **No viral loop** | Solo fitness apps die quietly | Strava integration + auto-generated world-state share cards |
| **No social/multiplayer** | One of the strongest retention mechanisms in fitness is community | Shared World Mode for gyms (see §10) |
| **No first-run experience** | "Select a Biome" is still a menu | The world must speak before any UI appears (see §4) |
| **No narrative mystery** | Lore that answers all questions up front has no retention value | The Silence is a mystery. Rowing earns the truth. |

### What Is Already Excellent ✅

- **Biome = Workout Selector** — The best UX reframe in fitness gaming. Not "HIIT" — *a place.*
- **Diegetic UI** — Explicit rejection of numeric HUD is the single highest taste-level decision in the document.
- **Force Curve → Engine Quality** — This is the feature rowers will talk about. No competitor is near it.
- **Head Tracking for steering** — Creative, non-fatiguing, solves monotony without wrecking form.
- **Three distinct audiences** — Each mode can be marketed independently. Zone 2 ad targets runners. Canyon ad targets CrossFit. Giant ad targets competitive masters rowers.

---

## 2. Commercial Potential

### Addressable Market (Stacked by Phase)

| Phase | Audience | Estimated Size | Revenue Model |
|---|---|---|---|
| **1 — PM5 Direct** | Concept2 home & commercial users, iOS | ~250,000 reachable | $7.99 purchase |
| **2 — Multi-Erg** | WaterRower, RP3, Hydrow (adding BLE interfaces) | +300,000 | Same |
| **3 — Watch-Only** | Any rower with Apple Watch (stroke cadence via accelerometer) | +2,000,000 | Freemium → upgrade |
| **B2B — Gyms** | Boutique rowing studios (CityRow, Row House), CrossFit boxes, uni rowing clubs | 5,000–15,000 sites globally | $199–399/year site licence |

### Revenue Scenarios (Conservative / Mid / Optimistic)

| Scenario | B2C Downloads | B2B Sites | Annual Revenue |
|---|---|---|---|
| Conservative | 3,000 @ $7.99 | 50 @ $199 | ~$34k |
| Mid | 12,000 @ $7.99 | 250 @ $299 | ~$171k |
| Optimistic | 40,000 @ $7.99 | 800 @ $299 | ~$559k |
| **With Concept2 Partner listing + phase 2 erg expansion** | 60,000 | 1,500 | ~**$1M+** |

### The Path to $1M
1. **Concept2 Partner Programme** listing → warm leads from exact target audience at zero cost.
2. **Strava App Gallery listing** → rowers already on Strava, already using connected apps.
3. **Phase 2 WaterRower BLE** → 3× TAM with minimal additional engine work (BLE interface is abstract).
4. **50 gym site licences in year 1** → baseline ARR that covers development costs.
5. **Solo developer, low overhead** — $300k net in year 2 is a life-changing outcome that does not require a unicorn exit.

### Competitive Moat
There is no direct competitor. ErgZone and Dark Horse Rowing are data dashboards with race tracks. Hydrow's games are basic. The closest analogue is Zwift for cycling — which reached $450M valuation. Aether Engine does not need 1% of Zwift's market to be a business. It needs 0.01%.

---

## 3. The Pitch — Refined

### App Store Tagline
> *"Your rowing machine is the engine. The world is the gauge."*

### One-Liner
> *"Aether Engine turns your PM5 into a portal. Row steadily and nature blooms. Sprint and break walls of light. Pull with precision and a stone giant walks. Three worlds. Three workouts. Zero menus."*

### Elevator Pitch (30 sec)
You are the last pilot of the Aether Vessel — the engine keeping a dying world alive. Your rowing machine powers it. Row in Zone 2 and a ruined landscape blooms beneath you in real time. Sprint through a cyberpunk canyon charging energy walls with your stroke rate. Drive a mechanical giant through deep snow using only raw, precise pulls.
There is no HUD. Speed looks like wind. Power looks like light. Bad technique sounds like an engine knocking. Good technique sounds like a machine in harmony.
Free for anyone with an iPhone. Full experience for Concept2 owners.

### Why Rowing, Why Now?
- Concept2 sold its **one-millionth** rowing machine in 2023. The community is large and product-loyal.
- Apple Watch Series 9+ detects rowing stroke cadence natively. The hardware ecosystem is ready.
- The post-COVID home fitness wave left a permanent install base of premium home erg owners with **no engaging software**.
- Boutique rowing studios are the fastest-growing fitness category in the US (IBISWorld, 2024). They need differentiating technology.

---

## 4. The "First 60 Seconds" Experience

> *This is the most important design section in the document. The first 60 seconds determine whether the user rows again tomorrow.*

### The First-Run Sequence (No Tutorial, No Menu)

**0s:** App opens. A single scene: a grey, silent, crumbling landscape. Dust falls upward — wrong. Rivers are still. The audio is absence.

**5s:** The Vessel appears at the top of the screen, descending slowly. Its engine is dark. No UI. No prompt.

**10s:** A single ambient text fades in, letterbox cinematic bars framing the image:
> *"Give it something."*
The text fades. No button. No arrow.

**15s:** The first stroke happens — whether on the erg, or a tap on the free tier. The engine flickers. One patch of ground, 50 metres below, shifts from grey to pale green. Just a patch. The audio emits a single breath — like something waking.

**30s:** The user is rowing. They don't know the rules yet. The world is responding. This is the hook.

**60s:** The FOV has widened slightly. Three patches of green. The music — a single piano note — has entered. The engine hum is steady. The user understands without being told: *I am doing this.*

**At session end (first time only):** A split-screen: the grey world on the left, what it looks like now on the right. Text:
> *"You gave it 3.2 minutes. It will remember."*

No mode selection. No Watts. No instructions. The first session is the tutorial and the hook. Mode selection appears as a *return* choice — "Where will you go next?"

---

## 5. Narrative & World

### The World — Aethon
A world once powered by **living kinetic energy** — the motion of rivers, tectonic drift, creature breath. A slow extinction called **The Silence** has been draining it for three centuries. Rivers stopped. Forests calcified mid-growth. A stone giant froze mid-stride in a mountain pass.

The Silence does not attack. It removes momentum. It is the absence of effort.

### The Vessel and the Pilot
You are not a hero. You are a **caretaker with an engine**. The Aether Vessel harvests kinetic energy from physical movement — specifically, rowing. Not because rowing is magical, but because the Vessel was built for a rower. It was built for *you.*

### The Mystery (Earned, Not Given)
The lore is not delivered in opening cutscenes. It is earned by rowing.

| Distance Milestone | Lore Fragment Unlocked |
|---|---|
| 5 km | *An old log speaks of the Silence arriving slowly — no event, no cause found.* |
| 20 km | *The stone giants didn't freeze from cold. They stopped themselves. Why?* |
| 50 km | *The neon canyon was not built. It grew, from the residue of a civilisation that tried to outrun the Silence at full speed.* |
| 100 km | *The Silence is not malevolent. Archive entry 7: "It is exhausted. It wants to stop but something is feeding it."* |
| 200 km | *The Vessel was not made for a pilot. It was made for the Silence. You were never supposed to find it.* |

**The 100km revelation** — The Silence is not the enemy. The Silence is a victim. Something else is the cause. The user who reaches 100km lifetime distance now has a question that cannot be answered without rowing more. This is the long-loop retention mechanic that no cosmetic unlock can replicate.

### Narrative Moments (World Events)
| Trigger | World Event |
|---|---|
| First session complete | One permanent flora element appears at your session start location. |
| HR spike > 30s in Zone 2 | Storm front gathers. Bloom reverses locally. Pull back or the recovery costs double. |
| First successful Neon Canyon wall break | Canyon depth extends. A new track section generates — permanently. |
| 1:2 drive/recovery ratio held for full session | Stone Giant speaks one sentence. No voice acting — carved text appears on its chest plate. |
| First 100km total | World achieves 40% restoration state. The Vessel changes shape slightly — evidence of something growing in the engine. |
| Shared World session completed (Gym Mode) | A pillar of light appears in the biome. Visible to all connected pilots. |

---

## 6. Core Design Pillars

1. **The Erg is the Controller.** Every game state is driveable by PM5 data alone. Tilt and head tracking are enhancements.
2. **Sub-100ms Perceived Feedback.** The latency between a stroke and its world response must be imperceptible. Shader displacement is per-frame, not per-second.
3. **The Game Teaches Without Instructing.** Bad technique degrades the experience visibly, audibly, and legibly. The user corrects because the game feels wrong, not because a voice said so.
4. **Every Session Produces a Story.** A 20-minute Zone 2 row produces a before-and-after world state worth sharing. This is a design constraint, not an aspiration.
5. **One Biome Done Exceptionally > Three Biomes Done Adequately.** Celestial Stream ships first, at 95% quality. Modes 2 and 3 are DLC. This is the product strategy.

---

## 7. Hardware Tiers — Removing the Floor

The original concept's biggest commercial risk is requiring a $900 Concept2 erg. The fix is a hardware tier system that **expands the audience without diluting the experience for erg owners**.

### Tier 1 — iPhone Only (Free)
**How it works:** The user taps the screen rhythmically or uses the iPhone's accelerometer to simulate stroke cadence. Watts are estimated from tap timing and pressure (Haptic Engine feedback). No real power data.
**Experience:** A simplified version of Celestial Stream. Slower world response. No force curve audio. No technique feedback.
**Purpose:** Marketing funnel and community builder. Converts to Tier 2/3 over time.
**App Store pitch:** "Play free. Row real."

### Tier 2 — Apple Watch (Lite)
**How it works:** Apple Watch Series 4+ detects rowing stroke cadence via accelerometer patterns. Heart rate is real. SPM is real. Watts are estimated from HR + SPM using a simple power model.
**Experience:** Full Celestial Stream with HR colour grading. No force curve (no PM5). Neon Canyon playable at reduced fidelity. Stone Giant not available (requires true force data).
**Expanded TAM:** Any rowing machine (gym, home, water) + Apple Watch = Tier 2 accessible. This is a 10× TAM expansion.

### Tier 3 — PM5 Full (Premium Purchase)
**How it works:** Full CSAFE + UART connection. All data channels live.
**Experience:** Complete game. All modes. Force curve audio. Diegetic technique coaching. Stone Giant.
**This is the product as designed.** The tiers exist to bring users here.

### Tier 4 — Multi-Erg (Phase 2)
**WaterRower, RP3, Hydrow** — all expose BLE services. Abstracting the PM5 manager behind an `IRowingMonitor` interface makes this a 2-4 week addition per erg type.

---

## 8. Game Modes (Biomes)

### Mode 1 — The Celestial Stream *(Launch Biome)*
**Workout:** Zone 2 · 55–70% Max HR · Sustainable Watts, low SPM  
**Session Asset:** [`Zone2_Session.asset`](Assets/Zone2_Session.asset)  
**Ship Priority:** P0 — This is the hero product.

#### Fantasy
A sky-vessel drifts above a ruined continent. Below, nature wakes to your rhythm.

#### Core Mechanic — The Flow State
The system computes a **Cruising Band**: `[TargetWatts × 0.85, TargetWatts × 1.10]`. Target derived from 2-min calibration row or stored FTP.

| State | Visual | Audio | HR Grade |
|---|---|---|---|
| **In Band** | FOV +5°, vignette fades, bloom expands | Music adds melodic string layer | Cyan → soft green |
| **Above Band (spike)** | Heat distortion on engine, bloom reverses | Tension string enters mix | Amber vignette |
| **Below Band** | Glider loses altitude toward fog | Music thins, reverb increases | No change |
| **In Fog** | Zero visibility | Single low drone | — |

**Session End:** The Vessel descends to a landing sequence over the most-restored patch. A persistent flora element appears — visible next session.

**Head Tracking (ARKit):** Ring gates every 15–25 seconds. Lean left/right to steer. Cosmetic — missing a gate has no penalty. Present for immersion and monotony-breaking.

---

### Mode 2 — The Neon Canyon
**Workout:** HIIT · 5–8 sprint walls per session  
**Session Asset:** [`HIIT30_Session.asset`](Assets/HIIT30_Session.asset)  
**Ship Priority:** P1 — DLC / v1.1

#### Fantasy
A cyberpunk tunnel at terminal velocity. The canyon consumes electrical charge. Your sprints feed it.

#### Core Mechanic — The Surge
**Cruise Phase:** Low Watts, geometric dodge obstacles via head tilt.  
**Wall Phase:** A wall appears 15 seconds ahead. An energy ring *on the wall* counts down. SPM fuels the charge bar (visible on engine bell, not HUD).

| Outcome | Result |
|---|---|
| **Wall broken** | Shockwave displacement, colour blast, canyon depth increases permanently |
| **Wall missed** | 30s canyon-dims penalty, no session fail |
| **Personal best Watts** | Canyon generates a new permanent neon signature |

**Adaptive Difficulty:** Wall energy requirement scales with `MaxPowerOutput`. Session 1 = 60% max. Session 5+ = 85% max.

---

### Mode 3 — The Stone Giant
**Workout:** Strength/Power · SPM 16–22, Maximum Force  
**Session Asset:** `StoneGiant_Session.asset` *(to create)*  
**Ship Priority:** P2 — DLC / v1.2

#### Fantasy
You pilot an ancient mechanical titan walking toward a frozen monument. Every stroke is a step.

#### Core Mechanic — The Heavy Lift

**Drive:** Force peak above threshold → Giant's leg lifts and commits.  
**Recovery:** Giant vents steam. A **Rhythm Bar** (diegetic, carved into Giant's chest plate) swings as a pendulum at target 1:2 cadence.  
**Slide Rush:** [`LastStrokeRatio`](Assets/Scripts/Input/RowingInputManager.cs:41) < 0.45 → Giant stumbles. Ground shakes. One clean stroke to re-sync.  
**Peak Force Record:** Stroke exceeds `MaxPowerOutput` personal best → Giant emits a golden pulse. Permanent footprint in snow.

**The Terrain Goal:** The Giant walks toward a **frozen monument** — N steps per session. Progress is persistent. Fill the monument's Aether meter over multiple sessions to unlock a cosmetic.

---

## 9. The "Secret Sauce" — Diegetic Feedback Systems

### 9.1 Wattage → Vertex Displacement
PM5 Watts drives a global shader displacement parameter on terrain mesh. Each stroke peak produces a radial displacement kernel centred on the vessel's world position. Formula: `displacement = (Watts / MaxWatts) × biomeDisplacementScalar`. Scalar is tuned per biome — subtle in Stream, violent in Canyon.

### 9.2 HR → Colour Grade
| Zone | LUT | Effect |
|---|---|---|
| Zone 1 (< 60%) | Deep cyan/teal | Calm, slightly desaturated |
| Zone 2 (60–70%) | Soft green, warm sky | The "sweet spot" — most beautiful |
| Zone 3 (70–80%) | Golden hour, orange edge | Exciting but sustainable |
| Zone 4 (80–90%) | Red vignette creep | Warning without text |
| Zone 5 (> 90%) | Full red dominance, bloom flicker | Unambiguous distress |

Zone 2 is intentionally the **most beautiful colour state**. Correct effort should look better than incorrect effort. This is coaching through aesthetics.

### 9.3 Force Curve → Engine Audio
Per-stroke force curve (via Nordic UART, [`PerformanceMonitorManager.cs`](Assets/Scripts/PM5/PerformanceMonitorManager.cs)) normalised and mapped to audio synthesis:

| Curve Shape | Engine Sound |
|---|---|
| Smooth bell (excellent) | Clean harmonic hum |
| Double peak (catch lunge) | Knock layer increases in mix |
| Flat / low peak (weak pull) | Pitch drops, reverb tail |
| Jagged / erratic | Sputter effect, slight reverb |

*This is the feature most serious rowers will talk about. It is also the feature with the highest emotional ceiling — a perfect stroke should sound transcendent. Prioritise audio design here.*

### 9.4 SPM → Music Tempo
Music stems authored at a target BPM per biome. `Stats.SPM` from [`RowingInputManager`](Assets/Scripts/Input/RowingInputManager.cs) modulates tempo ±15%. At target SPM the music is perfect. Drifting below sounds sluggish. Drifting above sounds anxious.

### 9.5 Stroke Ratio → Footfall (Stone Giant)
[`LastStrokeRatio`](Assets/Scripts/Input/RowingInputManager.cs:41) (drive time / recovery time) maps directly to the Giant's stride timing. 1:2 ratio = perfect footfall sound sync. Rushing = audible stumble.

---

## 10. Multiplayer & B2B — The Shared World

> *This is the primary commercial differentiator. It converts a personal app into institutional infrastructure.*

### Shared World Mode (Gym / Studio)

**Setup:** One iPad or Apple TV display per studio. 2–8 Concept2 ergs each running the Aether Engine companion app. Each erg's Watts contributes to a **shared Aether pool** driving a single shared world on the main display.

**Mechanics:**
- Each rower pilots their own smaller vessel visible to others.
- Combined Watts drive the world displacement shader — the world responds to *everyone simultaneously*.
- World sectors are assigned per-rower (rower 1 lights the river, rower 2 grows the forest). Each person sees their specific zone respond to their effort.
- A shared HP bar: if any rower stops cold, their zone begins greying. Social pressure to keep rowing without a coach saying a word.

**Why This Works for Gyms:**
- Boutique studios compete on experience differentiation. A large-screen shared-world display during a class is a marketing asset.
- Instructors can trigger biome events (storm front, neon wall) from a simple instructor tablet app.
- The class "restores" a persistent world over the semester. Students can see the cumulative effect of months of work.

**B2B Site Licence:** $199–399/year per studio location. Includes instructor app, multi-device sync, session reporting.

---

## 11. The Viral Engine

### Auto-Generated Share Cards
At every session end, the system renders a **share card**: a high-quality composite showing world state before vs. after, key stats rendered *as environment elements* (distance = a journey arc, calories = a bloom radius), and a single line of narrative text from the world.

Auto-saved to camera roll. One-tap share to Instagram Stories, Twitter/X, or Strava.

**Critical:** The card contains no raw fitness numbers by default. It shows a *world.* People share beautiful things.

### Strava Integration
Post-session data pushes automatically to Strava if authorised:
- Activity type: Rowing / Indoor Rowing
- Standard metrics: distance, time, average watts, calories
- Strava description: auto-populated with session narrative line + world state image attached
- **Result:** Every Aether Engine session appears in the Strava feed of the user's followers — who are rowers.

The Strava App Gallery listing + organic activity feed appearances = the most cost-effective marketing channel available for this audience.

### World-State Reel
One-tap 15-second video: a timelapse of the session's world transformation, rendered in real-time using stored world-state snapshots taken every 2 minutes. Auto-optimised for vertical 9:16 (Instagram/TikTok) and horizontal 16:9 (YouTube).

This is the clip that gets posted by rowing influencers. The visual spectacle does the selling.

### The "Aether Index" — Community Metric, Not Leaderboard
A global community counter: **Total Aether Generated Across All Players This Week.** Visualised as a world map showing which regions of Aethon the community has restored.

Users are not racing each other. They are cooperating. This removes the intimidation of competing against elite rowers while creating genuine community investment. A weekly summary notification: *"This week, the Aether community rowed 2.4 million metres. The Eastern Pass is restored."*

### Concept2 Partner Programme
Submit to Concept2's developer partner programme. Being listed on Concept2's website and featured in their newsletter delivers warm leads from customers who already own the hardware. No ad spend required. This should be pursued in parallel with development, not post-launch.

---

## 12. Progression & Retention

### Short-Loop (Per-Session)
- **Restoration Score:** Watts consistency (zone compliance) + technique bonus (force curve quality) + HR zone compliance.
- Score feeds **Aether Points** advancing the biome's healing state.
- Persistent terrain changes visible from the first return session.
- Share card generated. Strava post queued.

### Mid-Loop (Weekly)
| Unlock Trigger | Reward |
|---|---|
| 10 km total | Gold-trimmed Vessel skin |
| 25 km total | Trail effect: cherry blossom wake |
| 3 consecutive sessions Zone 2 | New biome weather state: morning fog variant |
| First Neon Canyon wall break | Canyon depth increases. New music stem unlocked. |
| 20 sessions total | Stone Giant biome unlocks |

### Long-Loop (Persistent World + Lore)
- World healing is **permanently visible** — a 60-session world looks fundamentally different from a new player's.
- Lore fragments at distance milestones (see §5).
- **Seasonal events:** Every 8 weeks, a Silence event rolls back one biome partially. Community challenge to restore it within 2 weeks.

### Failure Ritual (Previously Missing)
When a user stops rowing mid-session:
1. The engine dims. A 10-second grace timer begins (idle strokes allowed).
2. If no stroke within 10s: the world enters a **Suspension State** — time appears to slow, the palette cools. Ambient audio: a held breath.
3. Return stroke: the world exhales. The engine rekindles. No penalty — only the visual acknowledgement that the world noticed.
4. Full stop: session ends. Share card still generates. The world records the session's achievement regardless of early exit. *There is no failure — only effort.*

---

## 13. Technical Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         INPUT LAYER                             │
│  PM5 BLE (CSAFE+UART)  →  PerformanceMonitorManager            │
│  Apple Watch HealthKit →  HR Zone, Stroke Cadence (Tier 2)     │
│  iPhone Tap / Accel    →  SimulatedInputProvider (Tier 1)      │
│  ARKit Face Tracking   →  HeadTrackingProvider                 │
│                         ↓                                       │
│  RowingInputManager  ←  [IRowingMonitor] abstraction           │
│  (LivePM5 | Recorded | Simulated)                               │
└────────────────────┬────────────────────────────────────────────┘
                     │ RowingStats, StrokeEvents, HRZone
┌────────────────────▼────────────────────────────────────────────┐
│                      GAME LOGIC LAYER                           │
│  BiomeController (abstract)                                     │
│  ├── CelestialStreamController  (Flow State machine)           │
│  ├── NeonCanyonController        (Surge + wall spawner)        │
│  └── StoneGiantController        (Ratio + footfall sync)       │
│                                                                  │
│  SessionManager  →  RowingSessionData (ScriptableObject)       │
│  WorldStateManager  →  Persistent terrain save/load            │
│  SharedWorldSync  →  Multipeer Connectivity (B2B mode)         │
└────────────────────┬────────────────────────────────────────────┘
                     │ BiomeParameters, WorldState, GameEvents
┌────────────────────▼────────────────────────────────────────────┐
│                    RENDERING LAYER (URP)                        │
│  Vertex Displacement Shader  ←  Watts peak                     │
│  Post-Process LUT Stack      ←  HR Zone                        │
│  Adaptive Music System       ←  SPM, Zone, StrokeQuality       │
│  Force Curve Audio           ←  OnForceCurveUpdated event      │
│  ARKit Camera Rig            ←  Head lean angle                │
│  Share Card Renderer         ←  Session end trigger            │
└─────────────────────────────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────────┐
│                   PLATFORM SERVICES                             │
│  Strava API      →  Activity post + world state image          │
│  CloudKit        →  Persistent world state sync across devices  │
│  Game Center     →  Aether Index leaderboard (non-competitive)  │
│  HealthKit       →  Workout session save (calories, HR)        │
└─────────────────────────────────────────────────────────────────┘
```

### Key Interface: `IRowingMonitor`
Abstracting [`PerformanceMonitorManager`](Assets/Scripts/PM5/PerformanceMonitorManager.cs) behind an interface is the single most important architectural decision for Phase 2. It enables WaterRower, RP3, and Watch-only tiers with zero changes to game logic.

```csharp
public interface IRowingMonitor
{
    RowingStats Stats { get; }
    event Action<RowingStats> OnStatsUpdated;
    event Action<List<float>> OnForceCurveUpdated;
    event Action<bool> OnConnectionStateChanged;
}
```

---

## 14. Current Implementation Progress

### ✅ Complete / Solid

| Component | File(s) | Notes |
|---|---|---|
| PM5 BLE full connection | [`PM5Connection.cs`](Assets/Shatalmic/PM5Connection.cs), [`PerformanceMonitorManager.cs`](Assets/Scripts/PM5/PerformanceMonitorManager.cs) | CSAFE + Nordic UART, 10Hz poll, activity watchdog |
| CSAFE protocol parsing | [`CSAFEProtocol.cs`](Assets/Scripts/PM5/CSAFEProtocol.cs) | Watts, SPM, Distance, Cals, HR, Stroke State decoded |
| Force curve capture | [`PerformanceMonitorManager.cs`](Assets/Scripts/PM5/PerformanceMonitorManager.cs) | `OnForceCurveUpdated` event, per-stroke |
| Input abstraction | [`RowingInputManager.cs`](Assets/Scripts/Input/RowingInputManager.cs) | LivePM5 / Recorded / Simulated — desk dev without erg |
| Session recording | [`RowingDataRecorder.cs`](Assets/Scripts/Input/RowingDataRecorder.cs), [`RowingSessionData.cs`](Assets/Scripts/Input/RowingSessionData.cs) | ScriptableObject per-frame capture, replayable |
| Pre-recorded sessions | [`HIIT30_Session.asset`](Assets/HIIT30_Session.asset), [`Zone2_Session.asset`](Assets/Zone2_Session.asset) | Real captured sessions for development without live erg |
| Stroke state machine | [`RowingInputManager.cs`](Assets/Scripts/Input/RowingInputManager.cs) | Drive / Recovery / Idle, `LastStrokeRatio` |
| HR Zone calculation | [`RowingInputManager.cs`](Assets/Scripts/Input/RowingInputManager.cs) | `CurrentHRZone` 1–5, configurable `userMaxHR` |
| Smoothed velocity | [`RowingInputManager.cs`](Assets/Scripts/Input/RowingInputManager.cs) | `CurrentSmoothedVelocity`, tunable smooth time |
| Force curve debug viz | [`ForceCurveVisualizer.cs`](Assets/Scripts/Debug/ForceCurveVisualizer.cs) | LineRenderer — ready to repurpose as diegetic HUD |
| Main thread dispatcher | [`UnityMainThreadDispatcher.cs`](Assets/Scripts/Utils/UnityMainThreadDispatcher.cs) | BLE async → Unity thread-safe |
| Camera follow rig | [`TPPCameraFollow.cs`](Assets/Scripts/Utils/TPPCameraFollow.cs) | Third-person smooth follow |
| PM5 debug UI | [`PM5TestUI.cs`](Assets/Scripts/Debug/PM5TestUI.cs) | Live stats panel |
| URP pipeline | [`URP-Balanced.asset`](Assets/Settings/URP-Balanced.asset), [`URP-Performant.asset`](Assets/Settings/URP-Performant.asset) | Two quality tiers |

> **Summary:** The data pipeline is production-quality. `RowingInputManager`'s three-mode design (Live / Recorded / Simulated) means the entire game can be built and tested at a desk without touching an erg. This is architecturally excellent and dramatically reduces iteration time.

### ❌ Not Started — Prioritised

| Component | Priority | Estimated Time |
|---|---|---|
| `IRowingMonitor` interface refactor | P0 | 1 week |
| Celestial Stream biome art + terrain | P0 | 5 weeks |
| Vertex displacement terrain shader | P0 | 1 week |
| Adaptive music system | P0 | 3 weeks |
| Force curve → audio modulation | P0 | 1 week |
| HR → LUT post-processing | P1 | 1 week |
| First-run experience (§4) | P1 | 1 week |
| Session share card renderer | P1 | 1 week |
| ARKit head tracking | P1 | 2 weeks |
| Strava API integration | P1 | 2 weeks |
| `WorldStateManager` + CloudKit | P1 | 2 weeks |
| Apple Watch / HealthKit | P2 | 4 weeks |
| Neon Canyon biome | P2 | 6 weeks |
| Stone Giant biome + `StoneGiant_Session.asset` | P2 | 6 weeks |
| Simulated tier (iPhone tap) | P2 | 2 weeks |
| Shared World (multipeer sync) | P3 | 4 weeks |
| Progression system | P3 | 3 weeks |
| Social / Aether Index | P4 | 3 weeks |

---

## 15. Risk & Feasibility Assessment

### Risk Matrix

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| **Hardware barrier** — $900 erg excludes most App Store users | HIGH | HIGH | **Free Simulated tier** (iPhone tap). Watch Tier 2 drops barrier to ~$200. Phase 1 targets existing Concept2 owners. |
| **Solo developer scope** — Three biomes + multi-hardware + social | HIGH | HIGH | **One biome first rule:** Celestial Stream to 95% before Mode 2 exists. Modes 2 and 3 shipped as paid DLC. |
| **Motion sickness** — FOV change + forward motion + physical exertion | MEDIUM | HIGH | FOV delta ≤ 5°/sec. Camera translates only on Y-axis (altitude). Fixed horizon line. Test with motion-sick volunteer in month 2. |
| **Apple Watch integration** — WatchKit + HealthKit background session | MEDIUM | MEDIUM | PM5 already delivers HR via `Stats.HeartRate`. Watch is enhancement. Deprioritise to P2. |
| **BLE foreground requirement** — iOS Bluetooth drops on screen lock | LOW | HIGH | Design screen-on enforcement. iOS BLE is reliable in foreground. Frame as "display on dock" experience. |
| **ARKit during exertion** — Sweat degrades face tracking | MEDIUM | LOW | Head tilt is cosmetic enhancement. If tracking drops, freeze at centre. Ship without it in v1.0 if needed. |
| **Force curve audio quality** — Audio assets must be production quality | LOW | HIGH | Budget for professional sound design for engine audio. This is the signature feature — it cannot ship with placeholder sounds. |
| **Strava API changes** | LOW | LOW | Design Strava as optional enhancement. App functions without it. |

### Time Estimate (Solo, ~15 hrs/week)

| Milestone | Duration | Running Total |
|---|---|---|
| `IRowingMonitor` refactor | 1 week | 1 week |
| Celestial Stream terrain + shader | 6 weeks | 7 weeks |
| Adaptive music + force curve audio | 4 weeks | 11 weeks |
| HR→LUT + first-run experience | 2 weeks | 13 weeks |
| Share card + session flow | 1 week | 14 weeks |
| ARKit steering | 2 weeks | 16 weeks |
| Strava integration | 2 weeks | 18 weeks |
| **v0.1 TestFlight — Stream only** | — | **≈ 4.5 months** |
| Apple Watch Tier 2 | 4 weeks | 22 weeks |
| Neon Canyon biome | 6 weeks | 28 weeks |
| Stone Giant biome | 6 weeks | 34 weeks |
| Progression + unlocks | 3 weeks | 37 weeks |
| Shared World (B2B) | 4 weeks | 41 weeks |
| Polish + App Store submission | 4 weeks | 45 weeks |
| **v1.0 App Store** | — | **≈ 11 months** |

---

## 16. Monetisation

### Consumer Pricing
| Tier | Price | Content |
|---|---|---|
| **Free (Simulated)** | $0 | Celestial Stream lite, no PM5 required, iPhone tap input |
| **Full Game** | $7.99 | All biomes, PM5 integration, full progression |
| **Vessel Skin Pack** | $2.99 | 3 vessel skins per biome |
| **Seasonal Pass** | $3.99/season | Seasonal event + exclusive cosmetic |

**Not recommended:** Subscription for consumer. The user base is too niche to sustain subscription churn. Premium respects the hardware investment already made.

### B2B Pricing
| Tier | Price | Content |
|---|---|---|
| **Studio Licence** | $199/year | 1 display, up to 8 ergs, instructor app |
| **Studio Pro** | $399/year | Unlimited ergs, session reporting, custom branding |
| **Chain/Franchise** | Custom | Multi-location, API access |

**B2B is the floor that funds B2C development.** Target: 50 studio licences in year 1 = $10,000–20,000 ARR. This covers tooling costs and validates the commercial model before consumer launch.

### Partner Distribution
- **Concept2 Partner Programme** — Free listing, newsletter feature, warm lead pipeline.
- **Strava App Gallery** — Free listing. Organic discovery from post-session feed appearances.
- **Apple App Store "Apps for Apple Watch"** editorial placement — apply when Tier 2 is ready.

---

## 17. Roadmap

```
2026 Q2  ─── ✅ Data pipeline complete
             IRowingMonitor refactor
             Celestial Stream terrain prototype

2026 Q3  ─── Celestial Stream feature-complete
             Force curve audio v1
             Adaptive music v1
             First-run experience
             Share card + Strava integration
             
2026 Q4  ─── TestFlight v0.1 (Celestial Stream)
             Concept2 Partner Programme submission
             Neon Canyon prototype
             Apple Watch Tier 2
             
2027 Q1  ─── Neon Canyon feature-complete
             Stone Giant prototype
             B2B Shared World prototype
             
2027 Q2  ─── Stone Giant feature-complete
             Progression system
             B2B beta with 3 rowing studios
             
2027 Q3  ─── App Store v1.0
             Strava App Gallery listing
             Season 1 event
             
2027 Q4  ─── WaterRower / RP3 BLE expansion (IRowingMonitor plug-in)
             Social / Aether Index
             iPhone Simulated Tier (free funnel)
```

---

## Appendix A — PM5 Data Channels

| Data | BLE Source | Unity Field | Used By |
|---|---|---|---|
| Watts | CSAFE multiplexed | `Stats.Watts` | All modes, displacement shader |
| SPM | CSAFE multiplexed | `Stats.SPM` | Canyon charge, music tempo |
| Heart Rate | CSAFE (HR strap) / Apple Watch | `Stats.HeartRate` | Colour LUT, HR zone audio |
| Distance | CSAFE multiplexed | `Stats.Distance` | Progression triggers, lore unlock |
| Elapsed Time | CSAFE multiplexed | `Stats.ElapsedTime` | Session end trigger |
| Force Curve | Nordic UART (per stroke) | `OnForceCurveUpdated` | Engine audio quality signature |
| Stroke State | CSAFE | Internal state machine | Drive/Recovery detection |
| Stroke Ratio | Computed (`_driveTimer / _recoveryTimer`) | `LastStrokeRatio` | Stone Giant balance, technique coaching |

---

## Appendix B — Competitor Analysis

| Product | Type | PM5 | Gameplay | Verdict |
|---|---|---|---|---|
| ErgZone | Race simulation | ✅ | Race track, avatar | Data dashboard, no immersion |
| Dark Horse Rowing | Video coaching | ✅ | None (video overlays) | Not a game |
| Hydrow app | Built-in display | ❌ | Video content | Walled garden, Hydrow only |
| Zwift (rowing beta) | Training platform | Partial | Basic avatar | Zwift brand but shallow rowing |
| **Aether Engine** | **Exergame** | **✅** | **World restoration, diegetic UI** | **No direct competitor** |

---

## Appendix C — Glossary

| Term | Definition |
|---|---|
| **PM5** | Concept2 Performance Monitor 5. BLE-capable display unit. |
| **CSAFE** | Communication Specification for Fitness Equipment. Protocol for PM5 polling. |
| **Zone 2** | 60–70% max HR. Optimal for aerobic base and fat oxidation. |
| **Force Curve** | Per-stroke graph of force vs. handle position. Bell = good. Jagged = fault. |
| **Diegetic UI** | UI existing within the game world. Speed shown as wind, not numbers. |
| **Aether** | In-world resource generated by rowing effort. Progression currency. |
| **The Silence** | The antagonist — an entropy force. Not a character. A condition. |
| **IRowingMonitor** | Proposed interface abstracting PM5 for multi-erg compatibility. |
| **Aether Index** | Global community metric: total Aether generated by all players. |

---

*This document is living. Increment version and date on each revision.*