# Cocos_Flag_Framework

**Repository Path**: sinner13y/cocos-flag-gameframework

## Basic Information

- **Project Name**: Cocos_Flag_Framework
- **Description**: Cocos Creator Game Framework
这是一个基于 Cocos Creator 3.8.6 开发的游戏框架，提供了一套完整的游戏开发解决方案，包括数据存储、UI系统、消息系统、音频管理等功能模块。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: 3.x
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cocos Creator Game Framework

这是一个基于 Cocos Creator 3.8.6 开发的游戏框架，提供了一套完整的游戏开发解决方案，包括数据存储、UI系统、消息系统、音频管理等功能模块。

## 项目概述

本项目是一个为 Cocos Creator 游戏开发设计的面向对象框架，旨在提供一套标准化、模块化的解决方案，帮助开发者快速构建游戏项目。框架采用 TypeScript 编写，充分利用了 Cocos Creator 的特性和 TypeScript 的类型安全优势。

## 面向对象设计

本框架采用了面向对象的设计理念，具有以下特点：

1. **封装性**：每个功能模块都被封装在独立的类中，隐藏了实现细节，只暴露必要的接口。
2. **继承性**：通过继承机制实现代码复用，例如所有UI组件继承自基类，所有可持久化数据继承自Savable类。
3. **多态性**：通过接口和抽象类实现多态，不同子类可以以统一的方式被使用。
4. **抽象性**：使用抽象类和接口定义通用行为，具体实现由子类完成。

这种设计使得代码更加模块化、可维护和可扩展。

## 技术栈

- Cocos Creator 3.8.6
- TypeScript
- 面向对象设计模式

## 功能模块

### 1. 数据存储系统 (DataStorage)

数据存储系统提供了一套完整的数据持久化解决方案，包括：

- [Savable](DataStorage/Savable.ts) 基类：所有需要持久化的数据类都应该继承此类
- [DataStorage](DataStorage/DataStorage.ts) 核心类：负责实际的数据读写操作
- [AutoSaveField](DataStorage/AutoSaveField.ts) 自动保存字段：支持自动保存的字段类型
- 装饰器支持：使用 `@SavableClass` 和 `@AutoSave` 装饰器简化数据类的定义

特点：
- 支持多种数据类型（布尔值、整数、浮点数、字符串）
- 延迟保存机制，避免频繁的磁盘操作
- 自动初始化和加载机制

### 2. UI 系统

UI 系统提供了一套完整的用户界面管理方案：

- [UIViewBase](UI/UIViewBase.ts) 视图基类：所有 UI 视图的基类
- [UIItemBase](UI/UIItemBase.ts) UI 项基类：所有 UI 元素的基类
- [UIManager](UI/UIManager.ts) UI 管理器：负责 UI 的创建、显示和管理
- [UILayer](UI/UILayer.ts) UI 层级：定义 UI 的层级结构
- [UICanvas](UI/UICanvas.ts) UI 画布：UI 的根节点组件

特点：
- 层级化 UI 管理
- 自动按钮事件注册
- 支持参数传递的 UI 推入/弹出机制

使用方法：
1. 在场景的 Canvas 节点上挂载 [UICanvas](UI/UICanvas.ts) 组件以初始化 UI 系统
2. 可以设置 firstView 属性指定启动时显示的第一个视图
3. 通过 UIManager.push/pop 方法推入或弹出 UI 视图

### UI 管理

推入一个 UI 视图：
```
UIManager.push("HomeView");
```

弹出一个 UI 视图：
```
UIManager.pop("HomeView");
```

> 注意：使用UI系统前需要将 [UICanvas](UI/UICanvas.ts) 组件挂载到场景的Canvas节点上，这样会在游戏启动时自动初始化UI层级系统。[UICanvas](UI/UICanvas.ts) 组件还支持设置默认显示的视图及其层级。

### 3. 消息系统

消息系统实现了松耦合的组件间通信机制：

- [MessageSys](Message/MessageSys.ts) 消息事件核心类
- [MessageListener](Message/MessageListener.ts) 消息监听器
- [MessageDefine](Message/MessageDefine.ts) 消息定义

特点：
- 支持全局消息广播
- 支持类型化消息分发
- 自动清理无效监听器

### 4. 音频系统

音频系统提供了一套完整的音频播放和管理方案：

- [AudioManager](Sound/AudioManager.ts) 音频管理器
- [AudioController](Sound/AudioController.ts) 音频控制器
- [AudioSavable](Sound/AudioSavable.ts) 音频设置存储类

特点：
- 支持背景音乐和音效分离管理
- 音量和开关状态持久化
- 支持循环播放和独占播放模式

### 5. 日志系统

[Log](Log.ts) 类提供了一套统一的日志输出方案：

- 支持不同日志等级（信息、警告、错误）
- 可控制日志开关
- 统一的日志格式

### 6. 工具类

[iBox](iBox.ts) 是一个多功能工具类，提供了丰富的实用函数：

- 本地数据存储（字符串、整数、浮点数）
- 震动反馈
- 随机数生成
- 数值处理
- 计时器
- 贝塞尔曲线运动

### 7. 游戏状态管理

- [GameState](Game/GameState.ts) 定义了游戏的各种状态
- [GameTimer](Game/GameTimer.ts) 游戏计时器
- [Task](Game/Task.ts) 任务系统

### 8. 成就系统 (Achievement)

成就系统提供了一套完整的成就管理解决方案：

- [AchievementSys](Game/Achievement/AchievementSys.ts) 成就系统核心类：负责成就的注册、进度跟踪、解锁和奖励发放
- 支持多种成就类型（计数型、特定值型、时间相关型）
- 自动持久化成就状态
- 通过消息系统通知成就状态变化

特点：
- 支持成就定义和数据分离管理
- 提供成就进度跟踪和状态查询
- 支持隐藏成就（在达成前不显示）
- 通过消息系统实时通知成就状态变化
- 自动保存成就数据，防止数据丢失

## 使用说明

### 数据持久化

要创建一个可持久化的数据类，需要：

1. 继承 [Savable](DataStorage/Savable.ts) 基类
2. 使用 `@SavableClass` 装饰器标记类
3. 定义需要持久化自动保存的字使用 `@AutoSave` 装饰器标记

示例：
```typescript
@SavableClass
export class GameSettings extends Savable {
    @AutoSave(100) // 填写默认值
    public musicVolume: AutoSaveField<number>;
    
    @AutoSave("zh-CN") // 填写默认值
    public language: AutoSaveField<string>;
    
    @AutoSave({ key: "version", defaultValue: "1.0.0", type: String }) //规范写法
    public version: AutoSaveField<string>;

    // ...
}


//获取Savable子类实例使用
const settings = DataStorage.getSavable(GameSettings);
//第二种获取方法
const settings = GameSettings.getInstance();
```

### UI 管理

推入一个 UI 视图：
```typescript
UIManager.push("HomeView");
```

弹出一个 UI 视图：
```typescript
UIManager.pop("HomeView");
```

### 消息通信

发送消息：
```typescript
MessageSys.SendMessage("GameStart");
```

监听消息：
```typescript
const listener = MessageSys.AddNode(this.node,"__type__");
listener.Listener("GameStart", this.onGameStart);
```

### 成就系统

#### 注册成就定义
```typescript
// 获取成就系统实例
const achievementSys = DataStorage.getSavable(AchievementSys);

// 注册成就
achievementSys.registerAchievement({
    id: "first_win",
    name: "首场胜利",
    description: "赢得第一场比赛",
    type: AchievementType.Counter,
    targetValue: 1
});

achievementSys.registerAchievement({
    id: "collect_100_coins",
    name: "收集者",
    description: "收集100个金币",
    type: AchievementType.Counter,
    targetValue: 100
});
```

#### 更新成就进度
```typescript
// 当玩家获得金币时更新成就进度
achievementSys.updateProgress("collect_100_coins", 1);

// 当玩家赢得比赛时解锁成就
achievementSys.updateProgress("first_win", 1);
```

#### 监听成就事件
```typescript
// 监听成就解锁事件
const listener = MessageSys.AddNode(this.node , "__type__");
listener.AddListener(AchievementMessage.ACHIEVEMENT_UNLOCKED, (data) => {
    Log.i(`成就解锁: ${data.id}`);
    // 显示成就解锁提示
    UIManager.push("AchievementUnlockView", { achievementId: data.id });
});

// 监听成就进度更新事件
const listener = MessageSys.AddNode(this.node , "__type__");
listener.AddListener(AchievementMessage.ACHIEVEMENT_PROGRESS, (data) => {
    Log.i(`成就进度更新: ${data.id} - ${data.currentValue}/${data.targetValue}`);
    // 更新UI上的进度条
});
```

#### 查询成就状态
```typescript
// 检查成就是否已解锁
if (achievementSys.isUnlocked("first_win")) {
    Log.i("首场胜利成就已解锁");
}

// 获取成就进度百分比
const progress = achievementSys.getProgressPercentage("collect_100_coins");
Log.i(`收集者成就进度: ${progress * 100}%`);

// 获取成就详细信息
const achievementData = achievementSys.getAchievementData("collect_100_coins");
if (achievementData && achievementData.status === AchievementStatus.Unlocked) {
    // 显示领取奖励按钮
}
```

#### 领取成就奖励
```typescript
// 领取成就奖励
achievementSys.claimReward("first_win");

// 监听奖励领取事件
const listener = MessageSys.AddNode(this.node , "__type__");
listener.AddListener(AchievementMessage.ACHIEVEMENT_REWARDED, (data) => {
    Log.i(`成就奖励已领取: ${data.id}`, data.reward);
    // 给予玩家奖励
});
```

## 开发规范

1. 使用 TypeScript 进行开发
2. 所有日志输出应通过 [Log](Log.ts) 类进行
3. 数据持久化应继承 [Savable](DataStorage/Savable.ts) 基类
4. UI 组件应继承 [UIViewBase](UI/UIViewBase.ts) 或 [UIItemBase](UI/UIItemBase.ts)
5. 遵循面向对象设计原则，保持代码模块化

## 项目结构

```
assets/
├── game-frame/           # 游戏框架核心代码
│   ├── DataStorage/      # 数据存储系统
│   ├── Game/             # 游戏核心逻辑
│   ├── Message/          # 消息系统
│   ├── Sound/            # 音频系统
│   ├── UI/               # UI系统
│   ├── Log.ts            # 日志系统
│   └── iBox.ts           # 工具类
└── Project/              # 项目特定代码
```

## 注意事项

1. 项目使用 TypeScript 但关闭了严格模式 (`"strict": false`)
2. 框架基于 Cocos Creator 3.8.6 版本开发
3. 部分功能可能需要根据具体项目需求进行调整