# Cielonos 项目工程总结与后续开发参考

本文件是对当前 3D 二次元 Roguelike 动作游戏项目 **Cielonos**（Soullies/Cielonos）的工程结构、已实现系统及核心设计的完整总结。旨在为后续的开发与系统扩展提供清晰的参考依据。

---

## 1. 项目基本定位与核心愿景
* **品类**：二次元幻想风 3D 第三人称 Roguelike 动作游戏 (ARPG) + Geopolitical 局外政治议程。
* **叙事背景**：玩家扮演人类唯一的战略希望——“高维投影少女”（Protagonist），由其 Technician（“Mother”）通过注入高维认知写入（Cognitive Writing）进行战斗与现实重构。主角因高维感知认知受损，在战场上看不到普通人类，且在战场上是绝对“不可直视”的（普通人类直视其战斗会精神失常或死亡）。
* **核心乐趣**：局内的 Roguelike 动作 Build 搭配（多武器切换 Combo + 局内 Buff 化学反应） + 局外的 Fortress 浮空基地运营、NPC 羁绊及多阵营政治议程博弈（Alliance, Techno-Syndicate, Arcane Parliament, Mecha-Order）。

---

## 2. 工程结构与核心模块分析

当前项目工程主要基于 **Unity 2022+ (URP)** 开发，融入了 Wwise 音频、Yarn Spinner 叙事、Odin Inspector 连招编辑等专业工作流。

### 2.1 动作与战斗系统 (`Assets/Scripts/MainGame/Characters/` & `AttackArea/`)
* **角色基类 (`CharacterBase.cs`)**：
  * 使用多组件化设计，具备生命周期管理、伤害计算与护盾抵扣 (`TakeDamage`)、击飞/受击反馈等基础逻辑。
  * 包含 `AttributeSubmodule` 统一管理属性（Health, Armor, Shield, Speed 等），基于优先级队列注册属性修改器（Buff）。
  * 拥有 `FuncAnimSubmodule`，这是一个高度可自定义的动作片段替换框架（基于 Animator Override Batch 机制），动作段与逻辑高度解耦。
* **玩家控制器 (`Player.cs` & `Subcontrollers/`)**：
  * `PlayerLandMovementSubcontroller`：负责精细的陆地移动、闪避（Dodge，含完美闪避 Perfect Dodge 判定）、跳跃逻辑。
  * `PlayerInputSubcontroller`：基于 Unity New Input System 的输入映射，支持局内操作与局外 UI 交互模式的平滑切换。
  * `EquipmentSubmodule`：管理玩家身上的 **4 种装备槽位**（主武器、辅助装备、被动装备、消耗品），并实现**主武器切换（Switch Combo）**时的动作缓冲区刷新及切枪机制。
* **连招树配置 (`ComboData.cs` & `Assets/Scripts/MainGame/Items/Data/`)**：
  * 通过 ScriptableObject 编辑并在 Odin Inspector 中进行连招逻辑树的可视化配置。
  * 运行时由 `ComboSubmodule` 驱动，根据玩家输入操作（如 "L" / "R"）进行节点分支转移并播放特定的战斗动画。
* **已实现主武器 (`Assets/Scripts/MainGame/Items/MainWeapons/`)**：
  * `Yasha`（近战太刀）：经典的多段连招（LightAttack0~5）、空中突袭落地的 GroundImpact。
  * `Polychrome`（多彩）：拥有更复杂的连招判定与专属的 ExtraUI（如能量槽）。
  * `DualHarmony` 与 `FutureWand`：分别对应特异机制与法杖式远程攻击。

### 2.2 Roguelike 局内循环 (`Assets/Scripts/MainGame/GameRun/` & `Interactions/`)
* **会话管理器 (`RunManager.cs`)**：
  * 驱动整局 Run 的状态机（Idle, MapSelection, Transitioning, InCombat, InShop, InRest, InMechanical, Settlement）。
  * 维护一局 Run 的运行时状态（`RunState`），包含当前地图坐标、历史探索节点、消耗品和击杀统计等。
  * 接入雷达系统（雷达范围、永久揭示节点类型）等为局内遗物/装备提供 API。
* **节点地图 (`RunMapData.cs` & `Map/`)**：
  * 局内采用类似《杀戮尖塔》的多分叉网格图（`MapGenerator` 生成），包含：
    * `NormalBattle` / `EliteBattle` / `BossBattle`：战斗房间（加载 sandbox 式 CityArena 场景）。
    * `LogisticsCenter`（商店）：购买各档位武器与装备。
    * `MedicalStation`（医疗站）：回复生命。
    * `MechanicalTable`（机械强化台）：用于重构/升级局内装备。
* **场景加载与流程控制**：
  * `MainGameManager.cs`：主管理器，在战斗场景（`CityArena`）和基地场景（`Fortress`）初始化不同逻辑。
  * 结合 `UIPageManager` 在打开 UI 页面时自动锁定/解锁鼠标与物理输入。

### 2.3 剧情与叙事系统 (`Assets/Story/` & `Narrative/`)
* 采用 **Yarn Spinner** 作为核心对话与文本驱动工具。
* 包含 `StoryDirector.cs`，管理剧情任务、对话触发器（`NarrativeTriggers`）及运行时对话数据的传递。
* 配备了 `CielonosStoryProject.yarnproject` 及 `Tutorial_Guide.yarn`，定义了基础的引导流程及 NPC IDs。

---

## 3. 后续工作方向与规划（脱离 Demo 路线图）

要让 Cielonos 从 Demo 迈向可玩的完整游戏，需要系统性地完善局外循环、打磨局内手感、细化 AI 机制，并实现剧情阵营系统的联动：

```mermaid
graph TD
    A[脱离 Demo 路线图] --> B[核心战斗打磨]
    A --> C[局外系统构建]
    A --> D[关卡与 AI 丰富]
    A --> E[叙事与议程联动]

    B --> B1[Switch Combo 切枪特效与连击增益]
    B --> B2[Buff 化学反应体系 - 属性附着与爆破]
    
    C --> C1[基地 R&D 终端 - 局外蓝图/经费解锁]
    C --> C2[浮空要塞 NPC 局外交互与整备]
    
    D --> D1[Opsive 行为树高级 AI - 防守/反击/阶段转换]
    D --> D2[地图生成随机事件 Event 节点实现]

    E --> E1[Geopolitical Agenda 政治议程面板]
    E --> E2[Fortress 情绪禁令机制 - 异常值波动控制]
```

### 3.1 核心战斗与 Build 体系深挖
1. **多武器切换联动 (Switch Combo)**：
   * 细化武器在切换瞬间的“切枪伤害”或“切枪加成”（如 Yasha 切换到 FutureWand 时释放特殊的追踪弹幕）。
   * 在 UI 上提供明显的切枪可操作时间视窗（完美切枪时点）。
2. **Buff 元素与化学反应 (Buff Chemistry)**：
   * 细化多阵营装备带来的 Buff 体系。例如 Arcane 装备附着“魔导熵”，结合 Syndicate 的“计算标记”可触发“概率运算暴击”。
   * 完善属性状态机，使得 Buff 之间的反应可配置化（`BuffSubmodule` 扩展）。

### 3.2 浮空要塞 (Fortress) 与局外 meta-progression
1. **R&D 科研与装备解锁系统**：
   * 引入局外升级货币：“经费”（Marks）与“蓝图”（Blueprints，Elite/Boss 概率掉落）。
   * 建立局外解锁终端（科技树 UI），允许玩家利用蓝图解锁原本无法在局内商店购买的高阶武器、辅助装备，或提升主角基础面板。
2. **政治议程系统 (Geopolitical Agenda)**：
   * 建立阵营好感度/资源平衡面板。玩家在 Fortress 场景的终端上处理地缘政治决议，在几大阵营（Alliance West/East, Syndicate, Parliament）中做抉择。
   * 不同的阵营决议会直接解锁不同路线的科技树蓝图购买权限。

### 3.3 敌人 AI 与关卡事件
1. **Opsive 行为树战术精细化**：
   * 当前的 Enemy AI 仅有基础攻击，应利用 Blackboard 变量根据关卡深度动态开启 AI 的防守、防反、闪避与大招释放逻辑（例如普通攻击会被敌人架招，迫使玩家使用破盾技）。
2. **地图 Event 随机节点补充**：
   * 局内网格除了战斗/商店/医疗/机械台，需要实现 `Event` 节点。通过 Yarn Spinner 对话形式提供叙事选择，给予局内临时增益或以血换物等 Roguelike 经典事件。

---

## 4. 后续开发核心提问

为了让我们能够精准对齐当前的开发进度并制定出一套高效的、可落地的 Implementation Plan，希望您能先解答以下几个关键问题：

1. **当前战斗手感与完成度**：目前主角的移动、闪避、连击（以太刀 Yasha 为例）在编辑器中测试时，整体的动画流畅度与受击反馈（Hitstop、硬直、Blink 效果）是否已经调整到满意的基准？是否存在已知的物理碰撞或动画批处理 Overrides 相关的 Bug 需要首要修复？
2. **武器与装备资源的丰富度**：对于主武器（如远程/近战）与辅助装备的 3D 模型、特效（VFX）以及动作资源（Animation Clips），美术资产储备是否充裕？下一步是需要我们从底层开始以代码形式补充大量新武器的功能逻辑，还是优先完善已有的 Yasha、Polychrome 等武器的机制细节？
3. **基地 Fortress 场景与 UI**：目前 Fortress 场景是否已经完成了关卡场景的搭建并具有可交互的 NPC 占位？另外，关于 meta-progression 面板（蓝图研究、经费升级）以及地缘政治“议程决议”的 UI，是否已有相关的 UI 设计稿或 Prefab 框架，还是完全需要从零设计并基于 UI Toolkit / UGUI 搭建？