# 项目总览与开发指南

## 1. 项目简介
本项目基于 Cocos Creator (v3.x) 打造的休闲射击闯关游戏。玩家在主界面点击「战斗」按钮后进入关卡布阵场景，放置方块并点击确定后正式开始战斗。当所有波次敌人被消灭则胜利；护栏血量降为 0 则失败，分别进入胜/败界面，可选择继续或返回主界面。

## 2. 目录结构
```
.
├── assets/                 # Cocos 资源与脚本
│   ├── data/               # 静态配置（武器、敌人等 JSON）
│   ├── scripts/            # TypeScript 业务脚本
│   │   ├── Core/           # 核心工具与基础设施
│   │   ├── CombatSystem/   # 战斗相关逻辑
│   │   ├── LevelSystem/    # 关卡/波次/游戏管理
│   │   └── ShopSystem/     # 商店与经济系统
└── README.md               # 本说明文档
```

## 3. 核心架构与设计模式
### 3.1 BaseSingleton
`Core/BaseSingleton.ts` 是所有 **组件型单例** 的基类，实现通用单例注册/回收逻辑。
使用方式：
```ts
@ccclass('PhysicsManager')
export class PhysicsManager extends BaseSingleton {
    protected init() {
        // 首次实例化时的初始化逻辑
    }
}
// 其他脚本中
PhysicsManager.getInstance().doSomething();
```

### 3.2 EventBus
`Core/EventBus.ts` 提供全局轻量事件总线，方便模块间解耦通信。
```ts
EventBus.getInstance().on(GameEvents.GAME_SUCCESS, () => { /* ... */ }, this);
EventBus.getInstance().emit(GameEvents.GAME_SUCCESS);
```

### 3.3 状态机拆分
* GameManager 负责高层流程调度，应继续拆分为：
  1. **UIStateManager**   – 处理界面打开/关闭
  2. **LevelStateManager**– 负责关卡进度、波次切换
  3. **CombatStateManager** – 管理战斗开始/暂停/结束状态
* 每个状态管理器继承 `BaseSingleton` 或纯数据类，根据需求选型。

## 4. 模块说明
### 4.1 Core
| 文件 | 说明 |
| --- | --- |
| BaseSingleton.ts | 单例基类 |
| EventBus.ts | 全局事件系统 |
| ConfigManager.ts | 统一加载武器/敌人等 JSON 配置 |
| PhysicsManager.ts | 物理系统封装（下一步改为继承 BaseSingleton） |

### 4.2 CombatSystem
| 关键脚本 | 说明 |
| --- | --- |
| EnemyController.ts | 敌人生成与行为控制（建议改为单例或数据驱动） |
| BlockManager.ts | 方块放置与武器挂载逻辑 |
| BallController.ts | 触发武器射击的小球控制 |

### 4.3 LevelSystem
| 关键脚本 | 说明 |
| --- | --- |
| GameManager.ts | 游戏主体流程（正在拆分） |
| LevelManager.ts | 关卡进度保存/读取（纯数据单例） |
| LevelConfigManager.ts | 异步加载关卡 JSON 配置 |

### 4.4 ShopSystem
| 脚本 | 说明 |
| --- | --- |
| ShopManager.ts | 处理货币、物品购买，现已继承 BaseSingleton |

## 5. 推荐重构清单
1. **PhysicsManager / EnemyController**
   * 继承 `BaseSingleton`，提供 `getInstance()` 全局访问。
2. **GameManager 拆分**
   * 将 UI 按钮监听、波次逻辑、奖励结算等剥离到独立管理器或 `State` 类。
3. **状态机封装**
   * 引入简单状态机工具（可手写或使用 npm 包），管理 `START → PLAYING → PAUSE → SUCCESS/DEFEAT` 生命周期。
4. **事件总线落地**
   * 在 UI、声音、统计等系统中统一监听 `GameEvents`，消除直接引用。
5. **配置/资源热更**
   * ConfigManager 支持热重载 JSON，提高策划迭代效率。

## 6. 开发规范
* **TypeScript**：开启 `strict` 模式，充分利用接口、泛型与可选链。
* **命名**：统一使用 `PascalCase` 类名、`camelCase` 方法/变量。
* **组件化**：UI Prefab 与脚本一一对应，公共组件抽到 `components/` 目录。
* **注释**：关键算法、公共 API 使用 JSDoc；中文注释描述业务逻辑。

## 7. 运行与发布
1. 使用 Cocos Creator 打开项目，确认 **构建面板**勾选 MD5 Cache、代码压缩混淆。
2. 调试时可在 **预览** 勾选调试绘制碰撞框。
3. Release 构建后，将 `build/` 目录部署到 Web 服务器或打包原生平台。

---
© 2024 游戏团队 – 欢迎提交 Issue 与 PR，共建更优秀的代码架构。