# Cielonos 项目总结文档

## 项目概述

**项目名称**: Cielonos  
**项目类型**: 二次元风格、3D、第三人称、Roguelike动作游戏  
**Unity版本**: Unity 6+ (使用URP渲染管线)  
**目标平台**: PC/Console (主平台), Mobile (次平台)  
**开发语言**: C#

---

## 核心架构

### 1. 系统架构模式
项目采用**Submodule/Subcontroller架构模式**，将复杂系统拆分为可组合的子模块：

```
CharacterBase
├── Submodules (数据/逻辑层)
│   ├── SelfTimeSubmodule (时间控制)
│   ├── AttributeSubmodule (属性管理)
│   ├── EventSubmodule (事件系统)
│   ├── BuffSubmodule (Buff系统)
│   └── StatusSubmodule (状态系统)
└── Subcontrollers (表现/交互层)
    ├── MovementSubcontroller (移动控制)
    ├── AnimationSubcontroller (动画控制)
    ├── RenderSubcontroller (渲染控制)
    ├── CollisionSubcontroller (碰撞控制)
    └── 其他...
```

### 2. 命名空间组织
```
Cielonos.MainGame/
├── Characters/           # 角色系统
│   ├── Player/          # 玩家控制
│   ├── Automata/         # AI敌人
│   └── Base/            # 角色基础类
├── Buffs/               # Buff系统
├── Map/                 # 地图系统
├── Managers/            # 游戏管理器
└── UI/                  # UI系统
```

---

## 核心系统详解

### 1. 角色系统 (CharacterBase)

#### 1.1 角色阵营 (Fraction)
```csharp
public enum Fraction
{
    Player = 0,           // 玩家
    AlliedMinion = 1,     // 友军
    Enemy = 10,           // 敌人
    Neutral = 20          // 中立
}
```

#### 1.2 角色子系统 (Submodules)
- **AttributeSubmodule**: 属性系统，支持动态属性修改和加成计算
- **BuffSubmodule**: Buff/DeBuff管理系统
- **StatusSubmodule**: 状态系统（眩晕、束缚、无敌等）
- **EventSubmodule**: 事件系统（受伤、攻击、死亡等）

#### 1.3 角色控制器 (Subcontrollers)
- **MovementSubcontroller**: 移动控制（支持地面/空中/游泳等）
- **AnimationSubcontroller**: 动画控制（Animator管理）
- **RenderSubcontroller**: 渲染控制（材质、特效）
- **CollisionSubcontroller**: 碰撞控制
- **BodyPartsSubcontroller**: 身体部位管理
- **AudioSubcontroller**: 音频控制
- **ReactionSubcontroller**: 反应系统（格挡、闪避）
- **FeedbackSubcontroller**: 反馈系统

### 2. 属性系统 (AttributeSystem)

#### 2.1 属性组 (AttributeGroup)
```csharp
public partial class AttributeGroup
{
    public Dictionary<string, float> original;  // 原始属性
    public Dictionary<string, float> current;  // 当前属性（受Buff影响）
}
```

#### 2.2 属性修饰系统
支持多种修饰方式：
- **Flat值**: 直接加减数值
- **百分比加成**: 累加型百分比
- **百分比倍率**: 乘算型百分比

#### 2.3 伤害计算
```csharp
public float GetDamageValue(AttackValue attackValue)
{
    // 基础伤害 × 攻击者属性加成 × 受伤者属性加成
    // × 最终伤害倍率
}
```

### 3. 战斗系统 (BattleSystem)

#### 3.1 攻击类型 (AttackType)
```csharp
public enum AttackType
{
    Energy = 1,      // 能量伤害
    Kinetics = 2,    // 动能伤害
    Explosion = 3,   // 爆炸伤害
    Magic = 4,       // 魔法伤害
    Pure = 5,        // 纯粹伤害
    Blank = 6        // 无类型伤害
}
```

#### 3.2 突破等级 (BreakthroughType)
```csharp
public enum BreakthroughType
{
    None = 0,         // 无突破
    Weak = 10,        // 弱突破
    Medium = 20,      // 中突破
    Heavy = 30,       // 强突破
    Disruption = 40,  // 打断突破
    Forced = 50,      // 强制突破
    Unstoppable = 100 // 不可阻挡
}
```

#### 3.3 攻击区域系统 (AttackArea)
**攻击区域是战斗系统核心组件**，支持：
- **攻击判定**: 基于碰撞体的命中检测
- **力效果**: 击退、击飞、吸引等
- **命中反馈**: 打击特效、音效、伤害数字
- **移动轨迹**: 直线、追踪、弧线等

**攻击区域子模块**:
- TransformSubmodule: 位置/旋转/缩放控制
- AttackSubmodule: 攻击逻辑
- TimeSubmodule: 时间控制
- HitSubmodule: 命中判定
- MoveSubmoduleBase: 移动轨迹
- RaycastSubmodule: 射线检测
- ForceSubmodule: 力学效果
- ReactionSubmodule: 反应触发

### 4. Buff系统 (BuffSystem)

#### 4.1 Buff分类
```csharp
public enum BuffType
{
    Positive,   // 正面Buff
    Negative,   // 负面Debuff
    Neutral     // 中性Buff
}
```

#### 4.2 驱散等级 (BuffDispelLevel)
```csharp
public enum BuffDispelLevel
{
    Basic = 0,          // 弱驱散
    Strong = 10,        // 强驱散
    DeathOnly = 20,     // 仅死亡驱散
    Undispellable = 100 // 不可驱散
}
```

#### 4.3 内置Buff类型
- **Freeze**: 冰冻（停止移动和攻击）
- **Burn**: 灼烧（持续伤害）
- **Decay**: 衰败（属性下降）
- **ElectronicDisturbance**: 电子干扰
- **ElectronicParalysis**: 电子麻痹
- **Weak**: 虚弱（攻击力下降）
- **GeneralIncapacitation**: 失能

### 5. 状态系统 (StatusSystem)

#### 5.1 负面状态
```csharp
StatusType.Incapacitation = 0,  // 失能（完全丧失行动）
StatusType.Inhibition = 1,      // 抑制（禁用技能）
StatusType.Disarm = 2,          // 缴械（禁用攻击）
StatusType.Restraint = 3,       // 束缚（禁用移动）
StatusType.Disability = 4,       // 残废（禁用反应）
StatusType.Stun = 100,           // 眩晕
```

#### 5.2 正面状态
```csharp
StatusType.Invincible = 1000,   // 无敌
StatusType.Invisible = 1001,    // 隐身
```

### 6. 物品系统 (ItemSystem)

#### 6.1 物品基类 (ItemBase)
**核心属性**:
- FuncAnimDataCollection: 功能动画数据
- AttackData: 攻击数据
- ComboData: 连击数据
- FunctionData: 技能数据
- AmmoData: 弹药数据
- BlockData: 格挡数据
- OverloadData: 超载数据

**物品子模块**:
- AttributeSubmodule: 被动属性
- ComboSubmodule: 连击系统
- FunctionSubmodule: 功能系统
- AmmoSubmodule: 弹药管理
- OverloadSubmodule: 超载管理

#### 6.2 主武器系统 (MainWeaponBase)
当前已实现武器：
- **Polychrome**: 多彩武器（可变形态）
- **FutureWand**: 未来法杖

#### 6.3 武器数据
```csharp
public class AttackUnit
{
    public string name;
    public AnimationClip animationClip;
    public AttackData attackData;
    public ComboData comboData;
    public Dictionary<string, FuncAnimData> funcAnims;
}
```

### 7. AI系统 (Automata)

#### 7.1 AI架构
基于**Opsive Behavior Designer**实现行为树：
- **行为树 (BehaviorTree)**: AI决策逻辑
- **AI子树 (AI Subtrees)**: 可复用的行为模块
- **自定义Task**: 自定义行为节点

#### 7.2 AI动作系统
```csharp
// 移动动作
AdvanceRetreat: 前进/后退
PrecisePursue: 精确追踪
Standoff: 保持距离
Strafe: 侧向移动

// 攻击动作
ApplyBuff: 施加Buff
PlayFuncAnim: 播放功能动画

// 条件判断
CheckAttribute: 检查属性
CheckBuff: 检查Buff状态
CheckStatus: 检查角色状态
IsEnoughEnergy: 检查能量
```

#### 7.3 内置敌人类型
- **HumanoidAndroid**: 人形机器人
- **LegionCenturion**: 军团百夫长（精英敌人）
- **NexusCrab**: 蟹型机器人

### 8. 动画系统 (AnimationSystem)

#### 8.1 功能动画 (Functional Animation)
**核心概念**: 动画不仅是表现，还承载游戏逻辑
```csharp
public class FuncAnimData
{
    public AnimInfo animInfo;           // 动画基础信息
    public List<FuncAnimInterval> intervals;  // 时间区间定义
    public Dictionary<string, List<FuncAnimEvent>> events;  // 事件触发点
}
```

#### 8.2 动画打断系统
```csharp
public enum DisruptionType
{
    None,                  // 完全不可打断
    NormalExternal,       // 普通外部打断
    NormalAction,         // 普通动作打断
    StrongAction,         // 强动作打断
    SpecialAction,        // 特殊动作打断
    Uninterruptible       // 完全不可打断
}
```

#### 8.3 动画分层
- **FullBody**: 全身动画层
- **UpperBody**: 上半身动画层（可与移动叠加）

### 9. 功能动画Payload系统

功能动画Payload是触发游戏逻辑的核心机制：

```csharp
// 可用Payload类型
SpawnVFX:         生成特效
PlaySoundFX:      播放音效
SetStatus:        设置状态
SetGravity:       设置重力
SetBreakthroughResistance: 设置抗打断
ChangeCollisionLayers: 改变碰撞层
InvokeAnimScFunction: 调用动画控制器函数
SwitchFuncAnim:   切换功能动画
```

---

## UI系统

### 1. 玩家Canvas (PlayerCanvas)
包含以下UI区域：
- **PlayerInfoUIArea**: 玩家信息区
  - HealthBar: 生命值条
  - EnergyBar: 能量条
- **MainWeaponUIArea**: 主武器UI
  - FunctionIcon: 技能图标
  - MainWeaponSwitchLine: 武器切换指示
- **BossInfoUnit**: Boss信息单元
- **EnemyInfoUnit**: 敌人信息单元

### 2. HUD系统
- **DamageNumber**: 伤害数字（DamageNumbersPro）
  - 支持不同攻击类型（Energy/Kinetics/Explosion/Magic）
  - 支持暴击/普通显示
  - 支持护盾格挡显示

---

## 地图系统 (MapSystem)

### 1. Zone管理
```csharp
public class ZoneData
{
    public List<SpawnPointKey> playerSpawns;      // 玩家出生点
    public Dictionary<SpawnPointKey, string> enemySpawns;  // 敌人配置
}
```

### 2. 地图管理器 (MapManager)
- **Zone切换**: 异步加载/卸载场景
- **ScreenFader**: 场景过渡淡入淡出
- **SpawnPoint**: 出生点管理

### 3. 现有场景
- **Loading.unity**: 加载场景
- **Menu.unity**: 菜单场景
- **MainGame.unity**: 主游戏场景
- **Default/DefaultStreet.unity**: 默认地图
  - ZoneData0, ZoneData1, ZoneData2: 区域数据

---

## 渲染系统

### 1. 渲染管线
- **URP (Universal Render Pipeline)**: 通用渲染管线
- **支持平台**: PC (高画质)、Mobile (优化画质)

### 2. 卡通渲染
使用**POTA-Toon**实现二次元风格渲染：
- 多光源支持
- 复杂透明网格渲染（OIT技术）
- 角色局部后处理

### 3. 后处理效果
自定义后处理着色器：
- **AnimeACES**: ACES色调映射
- **AnimeBloom**: 卡通Bloom
- **AdvancedVignette**: 高级暗角
- **AdvancedChromaticAberration**: 色差
- **SpeedLines**: 速度线效果
- **Sharpen**: 锐化
- **RGBSplitGlitch**: RGB分离故障效果
- **RadialBlur**: 径向模糊
- **StrobeFlash**: 闪光效果

### 4. 自定义着色器
- **DitherLit**: Dither透明着色器
- **MeshShader**: 网格特效着色器
  - Burn: 燃烧效果
  - Freeze: 冰冻效果
  - Outline: 描边效果
  - Weak: 虚弱效果

---

## 特效系统 (VFX)

### 1. VFX资源
- **HUDTexts**: 伤害数字预设
- **MeshFXs**: 网格特效
  - Freeze.prefab: 冰冻特效
  - Shocking.prefab: 电击特效
- **Models**: 模型资源（Slash3.fbx）
- **Textures**: 特效纹理
  - Glow/: 发光纹理
  - Line/: 线条纹理
  - Mask/: 遮罩纹理
  - Noise/: 噪声纹理
  - Particles/: 粒子纹理
  - Ring/: 环形纹理
  - Smoke/: 烟雾纹理
  - Trail/: 轨迹纹理
  - Turbulence/: 湍流纹理

### 2. 特效数据 (VFXData)
```csharp
public class VFXData
{
    public Dictionary<string, VFXInfo> vfxCollection;
}
```

### 3. 武器特效
敌人攻击特效预设：
- **Hit.prefab**: 命中特效
- **NormalBlock.prefab**: 普通格挡特效
- **PerfectBlock.prefab**: 完美格挡特效
- **NormalSlash.prefab**: 普通斩击
- **NormalMovingSlash.prefab**: 移动斩击
- **PowerfulSlash.prefab**: 强力斩击

---

## 音频系统

### 1. 音频中间件
- **Wwise**: 专业游戏音频引擎
- **背景音乐管理**: BackgroundMusicManager
- **音效管理**: AudioManager

### 2. 音频容器 (AudioContainer)
```csharp
public class AudioContainer
{
    public Dictionary<string, AK.Wwise.Event> soundEventDictionary;
}
```

### 3. 音频资源
- **WwiseGenerated**: Wwise生成的音频代码
- **AudioPoint.prefab**: 场景音频点

---

## 工具和插件

### 1. Unity官方/社区插件
| 插件名称 | 用途 |
|---------|------|
| **Sirenix Odin Inspector** | 高级编辑器扩展 |
| **DOTween/Pro** | 动画和过渡 |
| **UniRx** | 响应式编程 |
| **Easy Save 3** | 数据持久化 |
| **I2 Localization** | 国际化支持 |
| **RootMotion FinalIK** | 逆向运动学 |
| **MagicaCloth2** | 布料模拟 |
| **KINEMATION** | 骨骼动画 |
| **DamageNumbersPro** | 伤害数字系统 |
| **Modern UI Pack** | UI组件库 |
| **MMFeedbacks (Feel)** | 反馈系统 |
| **IngameDebugConsole** | 调试控制台 |
| **Lean Pool/Common** | 对象池 |
| **Opsive Behavior Designer** | AI行为树 |
| **Hovl Studio VFX** | 特效资源包 |
| **Arcanor VFX** | 特效资源包 |

### 2. 自定义工具
- **Wingman**: 镜头系统
- **AutoLOD**: LOD自动生成
- **AtlasSplit**: 图集分割工具

---

## 输入系统

### 1. Input System
使用Unity新InputSystem：
```csharp
// Input/PlayerInputActions.cs
```

### 2. 玩家输入控制器
```csharp
public class PlayerInputSubcontroller
{
    // 处理键盘/手柄输入
    // 输入缓冲系统
    // 输入优先级
}
```

### 3. 预输入系统 (Preinput)
支持**预输入缓冲**，提高响应手感

---

## 资源配置

### 1. 基础集合 (BaseCollections)
```csharp
MainGameBaseCollection:   主游戏资源配置
MapBaseCollection:         地图配置
EditorBaseCollection:      编辑器配置
```

### 2. 物品资源
- **MainWeapons**: 主武器预设
  - FutureWand.prefab
  - Polychrome.prefab

---

## 场景管理

### 1. 加载流程
```
Menu → Loading → MainGame
         ↓
    异步加载场景
         ↓
    最小加载时间保证
         ↓
    场景激活
```

### 2. 过渡效果
- **ScreenFader**: 屏幕淡入淡出
- **DOTween**: 过渡动画

---

## 核心设计模式

### 1. 单例模式
```csharp
public class Singleton<T> where T : MonoBehaviour
{
    public static T Instance { get; private set; }
}
```

### 2. 子系统模式
```
Owner (持有者)
├── Submodule (子模块 - 逻辑/数据)
└── Subcontroller (子控制器 - 表现/交互)
```

### 3. 事件驱动
```csharp
public class EventSubmodule
{
    // 使用UniRx实现响应式事件
    public Subject<AttackResult> onDealAttack;
}
```

### 4. 对象池
使用LeanPool进行对象池管理

---

## 开发状态

### ✅ 已完成系统
1. 基础角色系统
2. 属性和Buff系统
3. 战斗/攻击系统
4. 动画系统
5. AI行为树框架
6. 物品系统框架
7. UI系统框架
8. 场景管理
9. 地图系统框架
10. 基础敌人AI
11. 输入系统
12. 伤害数字系统

### 🚧 待完善系统
1. 完整武器系统（更多武器类型）
2. 敌人AI行为树（完善所有敌人行为）
3. 关卡生成系统（Roguelike核心）
4. 技能树系统
5. 成就系统
6. 存档系统
7. 多人系统（如果需要）
8. 教程系统
9. 配置文件系统

---

## 项目目录结构

```
d:\Projects\Cielonos\
├── Assets/
│   ├── Scripts/                    # 所有游戏脚本
│   │   ├── Core/                   # 核心系统
│   │   ├── MainGame/               # 主游戏逻辑
│   │   ├── Menu/                   # 菜单系统
│   │   └── SLSUtilities/           # 工具库
│   ├── Prefabs/                    # 预制体
│   │   ├── Core/                   # 核心预制体
│   │   └── MainGame/               # 游戏预制体
│   ├── Scenes/                     # 场景
│   ├── Resources/                  # 资源文件
│   ├── Settings/                   # URP设置
│   ├── Shaders/                    # 自定义着色器
│   ├── Plugins/                    # 第三方插件
│   └── OtherPlugins/               # 其他插件
├── docs/                           # 文档目录
└── .agents/                        # Agent技能配置
```

---

## 关键文件索引

### 核心类
- CharacterBase: `Assets/Scripts/MainGame/Characters/Base/CharacterBase.cs`
- Player: `Assets/Scripts/MainGame/Characters/Player/Player.cs`
- Automata: `Assets/Scripts/MainGame/Characters/Automata/Automata.cs`
- BattleManager: `Assets/Scripts/MainGame/Managers/BattleManager/BattleManager.cs`
- MainGameManager: `Assets/Scripts/MainGame/Managers/MainGameManager.cs`
- MapManager: `Assets/Scripts/MainGame/Map/MapManager.cs`
- BuffBase: `Assets/Scripts/MainGame/Base/BuffSystem/BuffBase.cs`
- AttackAreaBase: `Assets/Scripts/MainGame/AttackArea/AttackAreaBase.cs`
- ItemBase: `Assets/Scripts/MainGame/Characters/Player/Items/Base/ItemBase.cs`

### 场景文件
- MainGame.unity: 主游戏场景
- Default/DefaultStreet.unity: 默认地图
- Loading.unity: 加载场景
- Menu.unity: 菜单场景

---

## 技术栈总结

| 类别 | 技术/工具 |
|------|----------|
| 引擎 | Unity 6+ (URP) |
| 渲染 | POTA-Toon卡通渲染 |
| AI | Opsive Behavior Designer |
| 动画 | Mecanim + 自定义功能动画 |
| 音频 | Wwise |
| UI | Modern UI Pack + 自定义 |
| 后处理 | 自定义URP后处理 |
| 物理 | Unity Physics |
| 输入 | InputSystem |
| 特效 | Shuriken + 自定义VFX |
| 动画IK | RootMotion FinalIK |
| 布料 | MagicaCloth2 |
| 响应式 | UniRx |
| 序列化 | Sirenix Odin Inspector |
| 对象池 | LeanPool |
| 缓动 | DOTween |

---

*文档生成日期: 2026-04-17*  
*生成者: Game Designer Agent*