# Cielonos — 游戏概念与项目总结

> 本文档是 Cielonos 项目的完整状态快照，作为所有后续设计、开发和评审工作的单一参考源。
> 最后更新：2026-07-02

---

## 游戏身份

- **类型**：二次元风格 3D 第三人称 Roguelike 动作游戏
- **视觉风格**：Anime / 二次元（PotaToon 卡通渲染管线 + 风格化 VFX）
- **世界观主题**：科幻 / 机甲（"Automata" 敌人阵营、科技武器、辅助无人机 AuxiliaryDrone）
- **引擎**：Unity 6 (6000.3.7f1)，URP 渲染管线
- **目标平台**：PC + 主机（PlayStation / Xbox）
- **音频方案**：Wwise（Audiokinetic 专业音频中间件）
- **自有工具库**：SLSUtilities 程序集（自研 Feedback 系统、FunctionalAnimation 系统、及其它通用工具）

---

## 核心玩法循环

1. **选择武器与装备** → 进入一局 Roguelike Run
2. **地图导航**：程序化生成地图（MapGenerator），选择节点路线（风险/收益分支）
3. **区域战斗**：进入战斗节点，完成波次清怪
4. **获取奖励**：通过 RewardTable 获取装备/升级，强化当前 Build
5. **推进或阵亡**：推进至 Boss 或阵亡结束本局
6. **Meta 进度**：（待完善）局间持久升级

### 运行系统（RunManager）
- 阶段流转：Idle → GeneratingMap → NodeSelection → ZoneExecution → NodeCompletion → RunEnd
- 节点类型：战斗房间、商店（MechanicalTable / LogisticsCenter）、医疗站（MedicalStation）、奖励台（RewardTable）、出口门（ExitGate）
- 支持运行种子（可复现）、侦查范围扩展、掉落稀有度系统

---

## 战斗系统

### 架构
- **CombatManager**：中央战斗编排器，管理回合、命中判定、反应施加
- **AttackArea 模块化系统**：所有攻击由可组合子模块构成（HitSubmodule、MoveSubmodule、ReactionSubmodule、ImpulseSubmodule、RaycastSubmodule 等）
- **攻击区域类型**：NormalArea（近战）、Projectile（远程）、Link（光束/锁链）

### FuncAnim 事件驱动战斗
动画是纯粹的时间载体，所有游戏逻辑通过 FuncAnimPayload 在关键帧触发：
- `SpawnVFX` — VFX 生成
- `PlaySoundFX` — Wwise 音频事件
- `ApplyBuff / RemoveBuff` — 状态效果
- `InvokeAnimScFunction` — 武器代码回调
- `ManualMove` — 脚本化位移
- `SetStatus / SetGravity / SetRootMotionMultipliers` — 状态切换
- `ChangeCollisionLayers` — 命中区域开关

### MusicBeatSystem（节奏战斗）
- CombatMusicController 管理音乐播放 + 拍子追踪
- BeatJudgement 评估命中/失误/完美
- BeatMarkerUI / BeatTimelineUI 视觉节拍指示

### 反馈系统（SLSUtilities/Feedback — 自研）
- Cinemachine 震动（位置、旋转、距离、轨道、FOV）
- 后处理效果（Bloom、色差、暗角、RGB 分裂故障、径向模糊）
- TimeScaleModifier（子弹时间 / 顿帧）
- AfterImage（残影生成器）
- 替代了已弃用的 More Mountains Feel

---

## 武器系统

每把武器通过 Partial Class 按职责拆分（主类、Functions、AnimationCallbacks、AttackAreas、Buff/Fusion 等）。

### 活跃武器（Demo 核心）

#### Polychrome（太刀）
- **机制**：激情（Passion）系统联动、完美格挡/弹反（ParryAttackFromDodge）、空中连击
- **攻击序列**：AttackL0-L5（6 段地面连击）、AttackRA/RB、AirAttack
- **防御**：NormalBlock、PerfectBlock、ParryAttack
- **特殊**：技能攻击（Skill）、终极技（UltimateAttack）
- **Feedback**：12+ 种命中反馈资产
- **状态**：高完成度，正在使用

#### FutureWand（能量法杖）
- **机制**：蓄力射击（HoldAttack Start/Loop/End）、弹丸系统、闪电生成、弹药系统
- **攻击序列**：AttackL0-L5（6 段连击）、AttackRA/RB
- **特殊**：终极旋转/释放（UltimateSpin/Release）
- **VFX 单元**：GroundArea、NormalBolt、UltimateBeam、CubicBolt、SpinArea、Lightning、Tornado（8 个 VFXData 单元）
- **状态**：高完成度，正在使用

### 待使用武器

#### DualHarmony（双持）
- 基础 FuncAnim 已有（AttackL0/L1、AttackR0）
- 双武器连击结构，暂未投入使用

### 已废弃武器（素材保留）
- **Yasha**（长柄武器）
- **Lampsis**

---

## 敌人系统

所有敌人属于 "Automata" 阵营。每种敌人拥有独立的 AttackData、AttributeData、TimerData、VFXData 资产。

### Boss

| 代号 | 类型 | 特点 |
|------|------|------|
| **C1_Axe** | Boss 级近战重击型 | 斧头挥砍，环境冲击 VFX。当前 Boss 战设计基本满意 |

### 杂兵（活跃）

| 代号 | 类型 | 特点 |
|------|------|------|
| **L1_Assault_Pawn** | 轻型突击兵 | 快速攻击，蓝色斩击/尖刺/子弹 VFX 套件（5 种） |
| **L2_Assault_Stinger** | 远程突击型 | 远程攻击模式 |

> 当前杂兵战斗设计存在较多缺陷，是优先改进方向。

### 待使用敌人

| 代号 | 类型 | 特点 |
|------|------|------|
| **M1_Suppression_Centurion** | 重型坦克 | 格挡机制（NormalBlock/PerfectBlock）、隐身、龙卷风、剑斩（11 种 VFX） |

### 已废弃 / 测试用
- **NexusCrab** — 完全废弃
- **IFD1_Test** — 测试占位

### 通用敌人 VFX 库（CommomVFX/）
- 24 个可复用 VFX 预制体，按攻击等级分类：
  - 普通攻击：斩击、方向命中、全方位命中、移动斩击/冲击、子弹/枪口闪光
  - 危险攻击：更高视觉强度的对应效果
  - 格挡/弹反：普通和完美格挡警示
  - 攻击破坏/强制等级警告：3 种视觉标识

---

## 装备系统

### 主动支援装备（SupportEquipmentBase）— 7 种
FusionInjector、IceCone、PerceptiveMetalPlating、Scanner、ThermalDetonator、VoidAnchor 等

### 被动装备（PassiveEquipmentBase）— 24 种
AdaptiveArmor、ArmorPiercingRound、Ascension、BellowsThruster、CorrosiveCoating、DecayAccelerationCoil、DecayPropagator、DetonationWarhead、FusionCatalyst、KineticFocusLens、LastStandProtocol、MemoryExoskeleton、MetabolicCatalyst、OverloadBattery、Passion、PlasmaResonator、PowerFurnace、QuantumShieldGenerator、ReactivePlating、ReflectionPrism、SpatialWarpCaliper、SupercriticalCore、SymbioticLoop、VipersFang

### 消耗品（ConsumableBase）— 5+ 种
AutomaticShield、EnergyReservoir、PermanentCoating、PrefabricatedComponent、RareMaterial、Salvo

---

## 角色系统

### 架构
- **CharacterBase**：基类，管理生命周期、属性、Buff、事件
- **Fraction 阵营系统**：Player、AlliedMinion、Enemy、Neutral

### 子控制器（Subcontroller — 重逻辑组合单元）
- CollisionSubcontroller — 碰撞检测与物理反应
- LandMovementSubcontroller — 地面移动 + 跳跃/闪避
- PlayerAnimationSubcontroller — 动画状态 + Override Controller 管理
- RenderSubcontroller — 视觉渲染与材质
- BodyPartsSubcontroller — 骨骼/身体部位命中区追踪
- AudioSubcontroller — Wwise 音效播放
- ReactionSubcontroller — 受击反应、击退、硬直
- FeedbackSubcontroller — 屏幕震动、泛光、VFX、后处理

### 子模块（Submodule — 轻量工具组合单元）
- SelfTimeSubmodule — 独立 deltaTime（支持慢动作）
- AttributeSubmodule — 数值/百分比叠加属性修正
- EventSubmodule — 事件广播（onAttack、onGetHit、onDie 等）
- BuffSubmodule — Buff/Debuff 堆叠与更新
- StatusSubmodule — 状态标记（眩晕、无敌等）

### 玩家特有
- PlayerInventorySubcontroller — 背包 + 装备槽管理
- PlayerInputSubcontroller — 输入轮询 + 预输入缓冲
- PlayerInteractionSubcontroller — NPC/物体交互
- PlayerFunctions — 冲刺、跳跃、闪避

---

## Buff / 状态系统

### 框架
- BuffBase → CharacterBuffBase → ProbabilityBuffBase（概率触发）/ ProgressBuffBase（累积堆叠）

### 已实现效果
- **伤害型**：Burn（灼烧 DoT）、Decay（衰败 HP 流失）
- **控制型**：Freeze（冻结）、ElectronicParalysis（电子麻痹/眩晕）、Incapacitation（失能）
- **增益型**：EnergyRecovery（能量恢复）、Invincible（无敌帧）
- **减益型**：Weak（虚弱/属性下降）
- **修正型**：BreakthroughResistanceModification（韧性减免）、VerticalMoveModification

---

## 属性系统

- **AttributeGroup**：定义属性池（Health、Energy、Attack、Defense 等）
- **计算堆叠**：基础值 → 数值加成 → 百分比累加 → 百分比乘算
- **代码生成**：StaticAttributeClassGenerationWindow 自动生成强类型访问器

---

## UI 系统

### 战斗 HUD（PlayerCanvas/）
- BossInfoUnit — Boss 血条/状态
- EnemyInfoUnit — 敌人信息
- DodgeFunctionIcon — 闪避能力指示
- MainWeaponFunctionIcon — 武器攻击/技能图标
- SupportEquipmentIcon — 支援装备状态
- CombatSystemsUI — 被动能力图标
- BeatMarkerUI / BeatTimelineUI — 节拍指示

### 菜单/导航（MainGamePages/）
- InventoryItemSelector — 背包管理
- RewardChoiceSelector — 战后奖励选择（Roguelike 核心）
- MechanicalTableSelector — 装备/锻造选择
- LogisticsCenterSelector — 资源/补给中心
- MapNode — Roguelike 地图节点
- ItemDetailTextModule — 物品详情

### 对话/交互
- DialogUIPage — Yarn Spinner 对话界面
- ConfirmUIPage / InteractionUIArea — 选择/提示

---

## 叙事系统

- **Yarn Spinner** 集成（git 依赖）
- **StoryDirector** 协调对话/剧情
- **触发器**：AreaNarrativeTrigger（区域触发）、TimerNarrativeTrigger（计时触发）
- **回调函数**：CustomFunctions、NPC_CFs、Tutorial_CFs
- **NPC**：GuideNpc（引导 NPC）、SupportPersonnel（支援人员）

---

## 场景结构

| 场景 | 用途 | 内容 |
|------|------|------|
| **Menu** | 主菜单 | 开始游戏、设置、退出 |
| **Loading** | 加载界面 | 资产加载、场景过渡 |
| **CityArena** | 核心战斗场景 | Roguelike 战斗循环的主场景容器（玩家、敌人、地图 UI、CombatManager） |
| **Fortress** | 据点/基地 | NPC、升级、剧情推进 |
| **CharacterTest** | 开发测试 | 角色动画/控制器测试 |

> **场地说明**：目前唯一的战斗场地是 DefaultStreet（城市街道），作为 CityArena 场景中的环境。当前没有环境设计能力和时间投入更多场地。

---

## 内容规模统计

| 类别 | 数量 |
|------|------|
| C# 脚本文件 | 468 |
| 动画片段 | 294+ |
| VFX 预制体（自定义） | 200+ |
| 商业 VFX 包 | 15 |
| 总预制体 | 183 |
| 场景 | 6 |
| 活跃武器 | 2 |
| Boss | 1（C1_Axe） |
| 杂兵敌人 | 2（L1_Assault_Pawn、L2_Assault_Stinger） |
| 被动装备 | 24 |
| 主动支援装备 | 7 |

---

## 技术架构模式总结

1. **Submodule/Subcontroller 组合**：避免深层继承，通过可插拔的子模块（轻量）和子控制器（重逻辑）组合能力
2. **ScriptableObject 数据驱动**：AttackData、ComboData、VFXData、FunctionData 等全部为资产文件，代码与数据解耦
3. **FuncAnim 事件驱动**（SLSUtilities/FunctionalAnimation — 自研）：动画关键帧触发 Payload 对象执行游戏逻辑，实现动画时序与代码逻辑的干净分离
4. **EventSubmodule 观察者模式**：所有角色发布事件（onAttack、onGetHit、onDie），系统松耦合订阅
5. **模块化战斗区域**：攻击由可组合子模块构建（命中、移动、反应、变换、射线检测等），无需子类化即可定制攻击
6. **Partial Class 职责拆分**：武器和角色按功能维度拆分到多个文件（主类、Functions、AnimationCallbacks、AttackAreas）