tanqiu/README.md

项目总览与开发指南

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 是所有 组件型单例 的基类，实现通用单例注册/回收逻辑。 使用方式：

@ccclass('PhysicsManager')
export class PhysicsManager extends BaseSingleton {
    protected init() {
        // 首次实例化时的初始化逻辑
    }
}
// 其他脚本中
PhysicsManager.getInstance().doSomething();

3.2 EventBus

Core/EventBus.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，共建更优秀的代码架构。