# 项目概述

<cite>
**本文档引用的文件**
- [heros.md](file://assets/script/heros.md)
- [Design.md](file://assets/script/Design.md)
- [Main.ts](file://assets/script/Main.ts)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts)
- [Hero.ts](file://assets/script/game/hero/Hero.ts)
- [SkillEnt.ts](file://assets/script/game/skill/SkillEnt.ts)
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
- [GameMap.ts](file://assets/script/game/map/GameMap.ts)
- [package.json](file://package.json)
- [tsconfig.json](file://tsconfig.json)
- [config.json](file://assets/resources/config.json)
- [NetCode.json](file://assets/resources/config/game/NetCode.json)
</cite>

## 目录
1. [项目简介](#项目简介)
2. [核心设计理念](#核心设计理念)
3. [技术架构概览](#技术架构概览)
4. [项目结构分析](#项目结构分析)
5. [核心技术栈](#核心技术栈)
6. [核心功能模块](#核心功能模块)
7. [游戏机制详解](#游戏机制详解)
8. [数据管理系统](#数据管理系统)
9. [架构设计亮点](#架构设计亮点)
10. [总结](#总结)

## 项目简介

Heros是一款基于Cocos Creator开发的微信小游戏，融合了Roguelike塔防玩法与中国历史人物英雄设定的独特设计理念。游戏将传统的塔防策略与肉鸽（Roguelike）元素相结合，创造出既具有深度策略性又充满随机性和重玩价值的游戏体验。

### 游戏特色
- **历史英雄集合**：收录了春秋战国至楚汉争霸时期的34位历史名将，每位英雄都具有独特的背景故事和战斗特性
- **创新玩法**：自动战斗系统配合策略性奖励选择，简化操作同时保持深度策略性
- **文化传承**：通过游戏形式传播中国传统文化和历史知识
- **跨平台支持**：基于Cocos Creator开发，支持微信小程序等多平台部署

**章节来源**
- [heros.md](file://assets/script/heros.md#L1-L374)
- [Design.md](file://assets/script/Design.md#L1-L109)

## 核心设计理念

### 游戏核心概念
Heros采用单局制肉鸽塔防的核心玩法，玩家通过策略性地选择每波怪物清理后的奖励来强化自己的英雄队伍，最终挑战强大的Boss。这种设计实现了以下核心理念：

1. **策略性与随机性的平衡**：固定关卡结构搭配随机奖励选择，创造既可预测又充满惊喜的游戏体验
2. **资源管理深度**：有限的金币资源迫使玩家在短期收益与长期发展之间做出权衡
3. **英雄成长多样性**：每个英雄都有三条不同的成长路线，鼓励玩家尝试不同的策略组合

### 设计哲学
- **简化操作复杂性**：所有战斗均为自动进行，玩家只需在关键节点做出选择
- **深度策略性保留**：通过奖励系统和英雄特性维持游戏的策略深度
- **文化价值传递**：每个英雄都承载着丰富的历史文化内涵

**章节来源**
- [Design.md](file://assets/script/Design.md#L5-L25)

## 技术架构概览

### 整体架构设计

```mermaid
graph TB
subgraph "表现层"
UI[用户界面]
Scene[场景管理]
Animation[动画系统]
end
subgraph "业务逻辑层"
GameLogic[游戏逻辑]
BattleSystem[战斗系统]
RewardSystem[奖励系统]
HeroSystem[英雄系统]
end
subgraph "数据层"
SingletonModule[单例模块]
CloudStorage[云端存储]
LocalStorage[本地存储]
end
subgraph "技术框架"
CocosEngine[Cocos Creator引擎]
OopsFramework[Oops插件框架]
ECS[ECS架构]
MVVM[MVVM模式]
end
UI --> GameLogic
Scene --> BattleSystem
Animation --> HeroSystem
GameLogic --> SingletonModule
BattleSystem --> CloudStorage
RewardSystem --> LocalStorage
SingletonModule --> CocosEngine
CloudStorage --> OopsFramework
LocalStorage --> ECS
CocosEngine --> MVVM
OopsFramework --> ECS
```

**图表来源**
- [Main.ts](file://assets/script/Main.ts#L1-L41)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)

### 架构层次说明

1. **表现层**：负责用户界面展示、场景管理和动画播放
2. **业务逻辑层**：包含游戏核心逻辑、战斗系统、奖励系统和英雄系统
3. **数据层**：管理游戏数据、云端存储和本地缓存
4. **技术框架**：基于Cocos Creator引擎和Oops插件框架构建

**章节来源**
- [Main.ts](file://assets/script/Main.ts#L10-L41)

## 项目结构分析

### 目录结构概览

```mermaid
graph LR
subgraph "assets资源目录"
Resources[resources资源]
Script[script脚本]
Extensions[extensions扩展]
end
subgraph "核心脚本模块"
Game[game游戏模块]
Common[common通用模块]
Initialize[initialize初始化]
end
subgraph "功能子模块"
Hero[英雄系统]
Map[地图系统]
Skill[技能系统]
WX[微信云开发]
end
Resources --> Game
Script --> Common
Extensions --> Initialize
Game --> Hero
Game --> Map
Game --> Skill
Game --> WX
```

**图表来源**
- [Main.ts](file://assets/script/Main.ts#L1-L10)

### 主要目录说明

- **assets/resources**：存放游戏资源配置文件，包括语言包、地图配置和网络代码定义
- **assets/script**：核心游戏脚本代码，包含游戏逻辑、英雄系统、地图系统等
- **build-templates**：微信小游戏构建模板和云函数配置
- **doc**：项目文档，包含ECS架构、MVVM模式等技术文档

**章节来源**
- [config.json](file://assets/resources/config.json#L1-L21)

## 核心技术栈

### Cocos Creator引擎
- **版本**：3.8.6
- **特性**：跨平台游戏开发，支持Web、移动端和小程序
- **优势**：成熟的2D/3D游戏开发工具链，丰富的内置组件

### Oops Plugin Framework
基于MVVM架构的插件框架，提供：
- **Model-View-ViewModel分离**：清晰的代码组织结构
- **数据绑定机制**：自动化的UI更新
- **组件化开发**：模块化的功能组织

### TypeScript技术栈
- **编译器配置**：ES2017目标，严格模式
- **类型安全**：完整的TypeScript类型系统
- **现代语法**：支持最新的JavaScript特性

### 微信云开发SDK
- **云端数据存储**：支持玩家游戏数据的云端同步
- **用户认证**：基于微信平台的用户身份验证
- **云函数**：后端逻辑处理和数据管理

**章节来源**
- [package.json](file://package.json#L1-L13)
- [tsconfig.json](file://tsconfig.json#L1-L12)

## 核心功能模块

### 英雄系统

```mermaid
classDiagram
class Hero {
+HeroModelComp model
+HeroViewComp view
+BattleMoveComp move
+load(pos, scale, uuid, fight_pos)
+hero_init(uuid, node)
}
class HeroModelComp {
+number uuid
+string name
+HType type
+number lv
+number hp
+number mp
+number ap
+number def
}
class HeroViewComp {
+number hero_uuid
+string hero_name
+number lv
+number hp
+number mp
+number[] skills
+Attrs attrs
+do_atk()
+do_dead()
}
class BattleMoveComp {
+number direction
+number targetX
+boolean moving
+update()
}
Hero --> HeroModelComp
Hero --> HeroViewComp
Hero --> BattleMoveComp
```

**图表来源**
- [Hero.ts](file://assets/script/game/hero/Hero.ts#L1-L100)

英雄系统是游戏的核心组成部分，包含以下关键特性：

1. **英雄类型系统**：分为战士、远程、法师、辅助、刺客五大职业类型
2. **属性成长体系**：每个英雄有三条不同的成长方向
3. **自动战斗机制**：英雄根据配置自动释放技能攻击敌人
4. **技能系统**：支持普通攻击和大招技能的升级

**章节来源**
- [Hero.ts](file://assets/script/game/hero/Hero.ts#L20-L100)
- [heros.md](file://assets/script/heros.md#L300-L374)

### 地图系统

```mermaid
classDiagram
class GameMap {
+MapModelComp model
+MapViewComp view
+load()
}
class MapModelComp {
+number id
+string resPrefab
+reset()
}
class MapViewComp {
+Scene scene
+Node entityLayer
+Node mapLayer
+startBattle()
+endBattle()
}
GameMap --> MapModelComp
GameMap --> MapViewComp
```

**图表来源**
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L1-L36)
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L1-L43)

地图系统负责：
- **地图加载与渲染**：动态加载地图资源和显示地图场景
- **战斗区域管理**：定义战斗发生的具体区域
- **实体层管理**：管理英雄、怪物等游戏实体的显示层级

**章节来源**
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L15-L36)

### 技能系统

```mermaid
sequenceDiagram
participant Player as 玩家
participant Hero as 英雄
participant Skill as 技能实体
participant Target as 目标
Player->>Hero : 选择技能
Hero->>Skill : 创建技能实体
Skill->>Skill : 加载预制体
Skill->>Target : 执行技能效果
Target->>Hero : 反馈伤害结果
Hero->>Player : 更新状态显示
```

**图表来源**
- [SkillEnt.ts](file://assets/script/game/skill/SkillEnt.ts#L1-L78)

技能系统特点：
- **技能配置管理**：通过SkillSet统一管理技能配置
- **自动施法机制**：技能根据英雄配置自动施放
- **特效系统**：支持丰富的技能视觉效果

**章节来源**
- [SkillEnt.ts](file://assets/script/game/skill/SkillEnt.ts#L10-L78)

## 游戏机制详解

### 自动战斗系统

游戏采用全自动战斗模式，玩家无需手动操作，战斗过程完全自动化：

1. **战斗触发**：当英雄进入敌人攻击范围时自动开始战斗
2. **技能释放**：英雄根据配置自动释放普通攻击和大招
3. **战斗结束**：当一方所有单位死亡时战斗结束

### 奖励选择系统

每波怪物清理后提供三种奖励选项：
- **弱奖励**：消耗较少金币，提供基础属性提升
- **一般奖励**：平衡的属性提升和技能升级
- **强奖励**：高额金币消耗，提供强力属性加成

### 金币经济系统

- **金币获取**：通过击败怪物固定掉落获得
- **金币消耗**：用于购买奖励选项
- **策略性消费**：有限的金币总量要求玩家合理分配

**章节来源**
- [Design.md](file://assets/script/Design.md#L10-L35)

## 数据管理系统

### 微信云开发集成

```mermaid
sequenceDiagram
participant Client as 客户端
participant WxCloud as 微信云
participant Server as 云函数
participant Database as 数据库
Client->>WxCloud : 初始化云环境
Client->>WxCloud : 用户登录
WxCloud->>Server : 调用云函数
Server->>Database : 查询/保存数据
Database-->>Server : 返回数据
Server-->>WxCloud : 返回结果
WxCloud-->>Client : 完成操作
```

**图表来源**
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts#L1-L94)
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L100-L150)

### 数据同步机制

1. **云端数据优先**：微信客户端优先使用云端数据
2. **本地调试支持**：非微信客户端使用本地调试数据
3. **数据覆盖策略**：云端数据直接覆盖本地数据
4. **错误处理机制**：数据同步失败时提供回滚机制

**章节来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L80-L150)
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts#L20-L94)

## 架构设计亮点

### ECS架构应用

项目采用ECS（Entity-Component-System）架构模式，具有以下优势：

1. **组件化设计**：每个功能模块独立为组件，便于维护和扩展
2. **数据与逻辑分离**：模型、视图、控制器职责明确
3. **高性能执行**：系统按需处理相关组件，提高性能

### MVVM模式实现

通过Oops插件框架实现MVVM架构：
- **Model**：数据模型，管理游戏状态
- **View**：视图层，负责界面展示
- **ViewModel**：视图模型，连接Model和View

### 单例模式应用

SingletonModuleComp作为全局数据管理中心，提供：
- **全局状态管理**：统一管理游戏全局状态
- **数据持久化**：支持本地和云端数据存储
- **事件通信**：提供全局事件分发机制

**章节来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L15-L50)

## 总结

Heros项目展现了现代游戏开发的最佳实践，通过以下方面体现了优秀的架构设计：

### 技术创新
- **混合架构**：结合ECS和MVVM模式，实现高效的游戏开发
- **跨平台支持**：基于Cocos Creator的跨平台解决方案
- **云端集成**：充分利用微信云开发的便利性

### 游戏设计
- **策略深度**：通过奖励系统和英雄特性维持游戏深度
- **文化价值**：将历史文化融入游戏设计
- **用户体验**：简化操作的同时保持策略性

### 架构优势
- **模块化设计**：清晰的功能模块划分，便于维护和扩展
- **数据管理**：完善的本地和云端数据管理机制
- **性能优化**：合理的架构设计确保良好的游戏性能

该项目不仅是一个成功的商业游戏案例，也为类似项目提供了宝贵的架构参考和设计思路。通过深入理解其技术架构和设计理念，开发者可以更好地把握现代游戏开发的趋势和最佳实践。