Files
Cielonos/docs/Cielonos_项目总结文档.md
2026-04-18 13:57:19 -04:00

675 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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*