# Systems Index: 夜裔 (Nightborn)

> **Status**: Draft
> **Created**: 2026-04-27
> **Last Updated**: 2026-04-27
> **Source Concept**: design/gdd/game-concept.md
> **Architecture Note**: L0 = Pure C# (no Unity), L1 = Unity Adapter, L2 = Unity Presentation

---

## Overview

夜裔需要17个系统，分布在三层架构中：L0纯C#核心逻辑（10个系统，零Unity依赖，可直接NUnit测试）、L1 Unity适配层（5个系统，薄MonoBehaviour封装）、L2 Unity表现层（2个系统）。Combat Logic和Form Switch State Machine是瓶颈系统——它们的设计质量直接决定核心循环是否成立。所有系统设计遵循操作优于数值、形态即战术的核心支柱。

---

## Systems Enumeration

| # | System Name | Layer | Category | Priority | Status | Design Doc | Depends On |
|---|-------------|-------|----------|----------|--------|------------|------------|
| 1 | Blood Energy Economy | L0 | Combat Logic | MVP | Approved | [GDD](blood-energy-economy.md) | — |
| 2 | Combat Logic | L0 | Combat Logic | MVP | Reviewed | [GDD](combat-logic.md) | — |
| 3 | Form Switch State Machine | L0 | Combat Logic | MVP | Approved | [GDD](form-switch-state-machine.md) | Blood Energy Economy |
| 4 | Enemy AI Logic | L0 | Combat Logic | MVP | Not Started | — | Combat Logic |
| 5 | Boss AI Logic | L0 | Combat Logic | MVP | Not Started | — | Enemy AI Logic, Combat Logic |
| 6 | Wave Manager Logic | L0 | Combat Logic | MVP | Not Started | — | Enemy AI Logic |
| 7 | Death/Respawn Rules | L0 | Player | MVP | Not Started | — | Combat Logic |
| 8 | Skill Tree Data & Rules | L0 | Progression | VS | Not Started | — | Form Switch State Machine |
| 9 | Save/Load Logic | L0 | Persistence | VS | Not Started | — | Skill Tree Data & Rules |
| 10 | Score Calculator | L0 | Meta | Full | Not Started | — | Combat Logic, Wave Manager Logic |
| 11 | Input Adapter | L1 | Unity Adapter | MVP | Not Started | — | — |
| 12 | Camera Controller | L1 | Unity Adapter | MVP | Not Started | — | — |
| 13 | Level Loader | L1 | Unity Adapter | MVP | Not Started | — | — |
| 14 | Audio Player | L1 | Unity Adapter | MVP | Not Started | — | — |
| 15 | VFX Spawner | L1 | Unity Adapter | MVP | Not Started | — | Combat Logic, Form Switch State Machine |
| 16 | UI/HUD | L2 | Presentation | MVP | Not Started | — | Blood Energy, Form Switch, Combat, Wave Manager |
| 17 | Menu System | L2 | Presentation | VS | Not Started | — | Input Adapter, Level Loader, Save/Load Logic |

---

## Categories

| Category | Description | Systems |
|----------|-------------|---------|
| **Combat Logic** | Pure-C# systems driving the moment-to-moment combat | Blood Energy, Combat Logic, Form Switch, Enemy AI, Boss AI, Wave Manager |
| **Player** | Player-state systems | Death/Respawn Rules |
| **Progression** | Growth and unlocks over sessions | Skill Tree Data & Rules |
| **Persistence** | Save state and continuity | Save/Load Logic |
| **Meta** | Secondary game systems | Score Calculator |
| **Unity Adapter** | Thin MonoBehaviour wrappers bridging to Unity | Input Adapter, Camera Controller, Level Loader, Audio Player, VFX Spawner |
| **Presentation** | Player-facing displays | UI/HUD, Menu System |

---

## Priority Tiers

| Tier | Definition | Target Milestone | Systems |
|------|------------|------------------|---------|
| **MVP** | Required for core loop — "is this fun?" | First playable (2-3 months) | 14 systems (all L0 combat + L1 + minimal L2) |
| **Vertical Slice** | One polished area, full experience demo | Demo (3-4 months) | 3 systems (Skill Tree, Save/Load, Menu) |
| **Full Vision** | Complete content and polish | Release (4-6 months) | 2 systems (Score Calculator, full Boss AI) |

---

## Dependency Map

### L0 — Pure C# Logic Layer

**Foundation (no dependencies)**:
1. Blood Energy Economy — standalone resource ruleset, feeds every combat decision
2. Combat Logic — standalone damage formulas and hit geometry

**Core (depends on Foundation)**:
3. Form Switch State Machine — depends on: Blood Energy Economy
4. Enemy AI Logic — depends on: Combat Logic
5. Death/Respawn Rules — depends on: Combat Logic

**Feature (depends on Core)**:
6. Boss AI Logic — depends on: Enemy AI Logic, Combat Logic
7. Wave Manager Logic — depends on: Enemy AI Logic
8. Skill Tree Data & Rules — depends on: Form Switch State Machine
9. Save/Load Logic — depends on: Skill Tree Data & Rules
10. Score Calculator — depends on: Combat Logic, Wave Manager Logic

### L1 — Unity Adapter Layer

11. Input Adapter — no game-logic dependencies (reads Unity Input, emits C# events)
12. Camera Controller — no game-logic dependencies (reads C# player position, drives Unity Camera)
13. Level Loader — no game-logic dependencies (loads Unity scenes per C# level data)
14. Audio Player — depends on: Combat Logic, Form Switch State Machine (listens to C# events)
15. VFX Spawner — depends on: Combat Logic, Form Switch State Machine (listens to C# events)

### L2 — Unity Presentation Layer

16. UI/HUD — depends on: Blood Energy, Form Switch, Combat, Wave Manager (reads C# state)
17. Menu System — depends on: Input Adapter, Level Loader, Save/Load Logic

---

## Recommended Design Order

| Order | System | Priority | Layer | Rationale | Est. Effort |
|-------|--------|----------|-------|-----------|-------------|
| 1 | Blood Energy Economy | MVP | L0 | Foundation resource — Form Switch depends on it | S |
| 2 | Combat Logic | MVP | L0 | Foundation hit/damage — Enemy AI depends on it | S |
| 3 | Form Switch State Machine | MVP | L0 | **Core pillar system** — the entire game feel starts here | M |
| 4 | Enemy AI Logic | MVP | L0 | Enemy behavior must exercise the switching loop | M |
| 5 | Wave Manager Logic | MVP | L0 | Encounter structure — the 5-minute loop | M |
| 6 | Death/Respawn Rules | MVP | L0 | Game loop closure — lose, learn, retry | S |
| 7 | Input Adapter | MVP | L1 | No input = can't test anything | S |
| 8 | Camera Controller | MVP | L1 | Basic visibility for testing | S |
| 9 | Level Loader | MVP | L1 | Scene infrastructure | S |
| 10 | VFX Spawner | MVP | L1 | Visual feedback for switching and hits | M |
| 11 | Audio Player | MVP | L1 | Minimum audio feedback for hits and switches | S |
| 12 | UI/HUD | MVP | L2 | Blood energy and form indicator — minimum playable info | S |
| 13 | Boss AI Logic | MVP | L0 | Single-phase boss — tests the full switching loop under pressure | M |
| 14 | Skill Tree Data & Rules | VS | L0 | Progression depth after core loop validated | M |
| 15 | Save/Load Logic | VS | L0 | Persistence needed once progression exists | S |
| 16 | Menu System | VS | L2 | Proper main menu + pause | S |
| 17 | Score Calculator | Full | L0 | Performance tracking for challenge mode | S |

---

## Circular Dependencies

- None found ✓

---

## High-Risk Systems

| System | Risk Type | Risk Description | Mitigation |
|--------|-----------|-----------------|------------|
| Form Switch State Machine | Design | Switch feel calibration — too tight feels clunky, too loose loses meaning | Prototype first with placeholder art, iterate timing with playtest |
| Wave Manager Logic | Design | Enemy composition must create meaningful form-switching pressure — if all forms work equally well, switching becomes optional | Design enemy types and wave compositions together, not separately |
| Enemy AI Logic | Scope | Each enemy type must strongly encourage a specific form — designing 3-5 types with clear form affinity is the core design challenge | Start with 3 enemy types, each with a hard "favors one form" rule |
| VFX Spawner | Technical | Geometric particle system performance at high enemy density on target hardware | Profile early with 100+ enemies; fallback: reduce particle count per event |
| UI/HUD | Design | Must convey form state, blood energy, and threat in <200ms glance — readability at frenetic pace | Test HUD mockups with static screenshots before implementation |

---

## Progress Tracker

| Metric | Count |
|--------|-------|
| Total systems identified | 17 |
| Design docs started | 3 |
| Design docs reviewed | 2 |
| Design docs approved | 2 |
| MVP systems designed | 3/14 |
| Vertical Slice systems designed | 0/3 |

---

## Next Steps

- [x] Design MVP-tier systems in dependency order — Blood Energy Economy and Combat Logic designed
- [x] Run `/design-system Blood Energy Economy` — Complete (Approved)
- [x] Run `/design-system Combat Logic` — Complete (Reviewed, revised)
- [x] Run `/design-system Form Switch State Machine` — Complete (Approved, revised after review)
- [ ] Run `/prototype form-switch-state-machine` on the highest-risk system early
- [ ] Run `/design-review` on remaining GDDs
- [ ] Run `/gate-check pre-production` when all MVP GDDs are authored and reviewed