# Cloudbound Bounce

**Repository Path**: Absure/cloudbound-bounce

## Basic Information

- **Project Name**: Cloudbound Bounce
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
    <img src="Logo/Logo.png" width="256" height="256" alt="HoppyGame Framework" style="display: block; margin: 20px auto -90px;">
</p>

# HoppyGame Framework

[![Version](https://img.shields.io/badge/version-v2.3-blue.svg)]()
[![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE.md)
[![Unity Version](https://img.shields.io/badge/unity-2019+-blue)](https://unity.com)
[![Platform](https://img.shields.io/badge/platform-Win%20%7C%20Android%20%7C%20iOS%20%7C%20Mac%20%7C%20Linux%20%7C%20WebGL-orange)]()
[![QQ Group](https://img.shields.io/badge/QQ%E7%BE%A4-399346678-blue)](https://qm.qq.com/q/bswKDNjWJU)
[![Code Quality](https://img.shields.io/badge/code%20quality-9.5%2F10-brightgreen)]()

> HoppyGame Framework 是一个现代化的 Unity 游戏开发框架，采用模块化架构设计，提供热更新、资源管理、状态机、对象池等核心功能，支持快速开发 Unity 游戏项目。

## ✨ 核心特性

- 🏗️ **双层架构设计**: Runtime（框架层）+ HotUpdate（业务层），职责清晰、易于维护
- 🎯 **统一访问入口**: 所有模块通过 `GameMain` 统一访问，降低学习成本
- 🔄 **状态机系统**: 强大的 FSM 状态管理，支持游戏流程和角色 AI
- 📦 **对象池系统**: 高效的对象复用机制，优化内存和 GC 性能
- ⚡ **高性能 Tick**: HashSet 优化的 Tick 系统，O(1) 注册/注销，支持 Update/FixedUpdate/LateUpdate
- 🎵 **音频系统**: 完整的音频解决方案，支持 FMOD 和 Unity BuiltIn
- 📋 **流程管理**: 基于 FSM 的游戏生命周期管理（热更新 → 资源下载 → 进入游戏）
- 🔧 **资源管理**: 集成 YooAsset，带引用计数和自动缓存
- 🔥 **热更新支持**: HybridCLR 代码热更新技术
- 🌐 **网络通信**: 内置 WebSocket 系统，支持自动重连和心跳保活
- ⏱️ **计时器系统**: 倒计时、循环定时、延迟执行，基于 UniTask
- 💾 **存档系统**: 多存档槽、加密持久化，支持 JSON/Binary
- 🔴 **红点系统**: 前缀树优化，支持三种红点类型和可视化配置
- 📊 **配置表系统**: 集成 Luban，类型安全的数据表访问
- 📝 **完善文档**: 完整的 XML 注释 + Docs 文档，符合企业级代码规范

## 📋 环境要求

- **Unity 版本**: 2019.4 或更高版本（推荐 2021.3 LTS）
- **.NET 版本**: .NET Framework 4.6+ / .NET Standard 2.0+
- **支持平台**: Windows, Android, iOS, macOS, Linux, WebGL

## 🚀 快速开始

### 安装方式

#### 方法一：Git 克隆（推荐）
```bash
git clone https://gitee.com/Absure/hoppy-game_-dbf.git
```

#### 方法二：作为子模块添加
```bash
git submodule add https://gitee.com/Absure/hoppy-game_-dbf.git Assets/HoppyGame
```

### 基础使用

```csharp
// ===== 统一访问入口（HotUpdate 层） =====
// 业务系统（System 层）通过 GameMain.XXX 直接访问
var ui       = GameMain.UI;        // UI 系统
var audio    = GameMain.Audio;     // 音频系统
var redDot   = GameMain.RedDot;    // 红点系统
var dataTable= GameMain.DataTable; // 配置表系统
var timer    = GameMain.Timer;     // 计时器系统
var ws       = GameMain.WebSocket; // WebSocket 系统
var save     = GameMain.SaveGame;  // 存档系统

// 框架模块（HGComponent 层）通过 GetModule<T> 获取
var tick     = GameMain.GetModule<Tick>();
var resource = GameMain.GetModule<Resource>();
var fsm      = GameMain.GetModule<FsmManager>();
var pools    = GameMain.GetModule<ObjectPools>();

// ===== 实际使用示例 =====

// 1. 异步加载资源（带引用计数和缓存）
var prefab = await GameMain.Resource.Asset.LoadAssetAsync<GameObject>("Player");
// 用完后释放引用
GameMain.Resource.Asset.ReleaseAsset("Player");

// 2. 对象池
var bullet = GameMain.GetModule<ObjectPools>().Pull("Bullet");
GameMain.GetModule<ObjectPools>().Push(bullet);

// 3. 播放音效 / BGM
GameMain.Audio.PlaySound("UI_Click");
GameMain.Audio.PlayBGM("Main_Theme");

// 4. 倒计时（带取消支持）
var cts = new CancellationTokenSource();
GameMain.Timer.CountdownAsync(30f,
    onTick:     remaining => Debug.Log($"剩余 {remaining}s"),
    onComplete: ()        => Debug.Log("时间到！"),
    cancellationToken: cts.Token).Forget();

// 5. 延迟执行
GameMain.Timer.DelayAsync(2f, () => Debug.Log("2秒后执行")).Forget();

// 6. WebSocket 连接
GameMain.WebSocket.OnConnected     += ()      => Debug.Log("已连接");
GameMain.WebSocket.OnMessageReceived+= msg    => Debug.Log($"收到: {msg}");
GameMain.WebSocket.Connect("wss://api.example.com");
await GameMain.WebSocket.Send("Hello Server");

// 7. 存档（多存档槽）
await GameMain.SaveGame.SaveData("PlayerData", playerData, slot: 0);
var data = GameMain.SaveGame.LoadData<PlayerData>("PlayerData", slot: 0);

// 8. 红点系统
GameMain.RedDot.SetDirty("main/mail");

// 9. 配置表
var itemConfig = GameMain.DataTable.GetTable<ItemTable>();

// 10. 注册 Tick（Update/FixedUpdate/LateUpdate）
// 让你的类实现 ITickable / IFixedTickable / ILateTickable 接口
GameMain.GetModule<Tick>().Register(this);    // 注册
GameMain.GetModule<Tick>().Unregister(this);  // 注销
```

## 🏗️ 架构设计

HoppyGame 框架采用**双层架构 + 统一访问入口**设计：

```
┌─────────────────────────────────────────────────────────────────────┐
│                      统一访问入口 (GameMain)                          │
│              GameMain.XXX — 所有业务层模块的统一入口                   │
└────────────────────────────┬────────────────────────────────────────┘
                             │
             ┌───────────────┴───────────────┐
             │                               │
             ▼                               ▼
┌────────────────────────┐      ┌────────────────────────────┐
│   Runtime 层（框架层）   │      │    HotUpdate 层（业务层）    │
│   不可热更新 · AOT       │      │    可热更新 · HybridCLR      │
├────────────────────────┤      ├────────────────────────────┤
│ • GameEntry            │      │ • GameMain (业务入口)        │
│ • GameModule           │      │ • UISystem                 │
│ • Tick (Update驱动)    │      │ • AudioSystem              │
│ • Resource + Asset     │      │ • RedDotSystem             │
│ • ObjectPools          │      │ • DataTableSystem          │
│ • FsmManager           │      │ • TimerSystem              │
│ • ProcedureManager     │      │ • WebSocketSystem          │
│ • Launcher             │      │ • SaveGameSystem           │
└────────────────────────┘      └────────────────────────────┘
             │                               │
             └───────────────┬───────────────┘
                             ▼
              ┌──────────────────────────┐
              │    第三方库（Plugins）     │
              │ • YooAsset（资源管理）    │
              │ • HybridCLR（热更新）     │
              │ • UniTask（异步）         │
              │ • Luban（配置表）         │
              │ • NativeWebSocket        │
              │ • SaveGameFree（存档）    │
              └──────────────────────────┘
```

### 核心设计原则

- **双层架构**: Runtime 层（框架基础设施，不可热更新）+ HotUpdate 层（业务逻辑，可热更新）
- **统一访问**: 业务层通过 `GameMain.XXX` 访问系统，框架层通过 `GameMain.GetModule<T>()` 访问组件
- **引用计数**: 资源系统支持引用计数和自动缓存，防止重复加载和内存泄漏
- **单一职责**: 每个模块负责特定的功能领域，不跨层依赖
- **性能优化**: HashSet Tick、无 GC 释放列表、自动释放闲置资源
- **代码规范**: 完整的 XML 注释，符合企业级开发标准

## 📁 项目结构

```
HoppyGame_DBF/
├── Assets/
│   ├── GameMain/
│   │   ├── Scripts/
│   │   │   ├── Runtime/                    # 运行时核心（不可热更新）
│   │   │   │   ├── Base/                   # 基础组件
│   │   │   │   │   ├── HGComponent.cs      # 组件基类
│   │   │   │   │   └── Singleton.cs        # 单例基类
│   │   │   │   ├── Modules/                # 核心模块
│   │   │   │   │   ├── Fsm/                # 有限状态机
│   │   │   │   │   ├── ObjectPool/         # 对象池（ObjectPools + SinglePoolData）
│   │   │   │   │   ├── Procedure/          # 流程管理（热更新流程）
│   │   │   │   │   ├── Resource/           # 资源管理（Resource + Asset + AssetCache）
│   │   │   │   │   ├── TickUpdate/         # Tick 驱动系统
│   │   │   │   │   └── Launcher/           # 启动器
│   │   │   │   ├── GameEntry.cs            # Unity 入口，注册所有 HGComponent
│   │   │   │   └── GameModule.cs           # 模块管理器（单例）
│   │   │   ├── HotUpdate/                  # 热更新代码（可热更新）
│   │   │   │   └── GameLogic/
│   │   │   │       ├── GameMain.cs         # 热更新入口，注册所有 System
│   │   │   │       └── SystemModules/
│   │   │   │           ├── UIModule/       # UI 系统
│   │   │   │           ├── Audio/          # 音频系统（FMOD + BuiltIn）
│   │   │   │           ├── RedDotModule/   # 红点系统
│   │   │   │           ├── DataTableModule/# 配置表系统
│   │   │   │           ├── Timer/          # 计时器系统
│   │   │   │           ├── WebSocket/      # WebSocket 系统
│   │   │   │           └── SaveGame/       # 存档系统
│   │   │   └── Editor/                     # 编辑器工具
│   └── Plugins/                            # 第三方插件
├── Docs/                                   # 项目文档
│   ├── 00_框架总览/
│   ├── 01_核心系统/
│   ├── 02_管理器模块/
│   └── 03_功能系统/
├── Tools/
│   └── DataTables/                         # 数据表工具（Luban）
├── Bundles/                                # 资源包
└── HybridCLRData/                          # HybridCLR 数据
```

## 🛠️ 核心模块

### 🔄 有限状态机 (FSM)
强大的状态管理解决方案，支持角色 AI、UI 状态、游戏流程等多种场景。
- 类型安全的状态转换
- 完整的进入/更新/退出生命周期
- 支持多状态机并发

### ⚡ Tick 系统
基于 HashSet 的高性能帧更新驱动，替代 MonoBehaviour Update。
- 支持 Update / FixedUpdate / LateUpdate 三种时机
- O(1) 注册和注销，自动防止重复注册
- 异常对象延迟批量移除，不影响其他对象

### 📦 对象池系统
高效的对象复用机制，显著提升性能，减少 GC 压力。
- 自动对象回收和复用
- 支持预热和容量管理
- YooAsset / Resources 双加载模式

### 🔧 资源管理系统
集成 YooAsset，带引用计数和 LRU 缓存的现代化资源管理。
- 同步/异步加载（支持进度回调）
- 引用计数防止提前卸载
- 自动释放闲置资源（可配置间隔）
- 原始文件（JSON/Binary）加载支持

### 📋 流程管理系统
基于 FSM 的游戏生命周期管理，从启动到运行的完整流程控制。
- 热更新流程：版本检查 → 资源下载 → 初始化
- 清晰的 Procedure 抽象，易于自定义扩展

### 🎵 音频系统
完整的音频管理解决方案，支持 FMOD 和 Unity 内置音频双模式。
- BGM / SFX 分组管理
- 音量控制、淡入淡出
- 异步资源加载

### ⏱️ 计时器系统 (TimerSystem)
基于 UniTask 的轻量计时器，全部支持 CancellationToken 取消。
- `CountdownAsync` — 整秒倒计时
- `CountdownWithProgressAsync` — 平滑进度倒计时（0~1）
- `IntervalAsync` — 循环定时执行
- `DelayAsync` — 单次延迟执行
- `LoopWithProgressAsync` — 带进度循环定时

### 🌐 WebSocket 系统 (WebSocketSystem)
功能完整的 WebSocket 客户端，基于 NativeWebSocket。
- 自动重连（可配置最大次数和间隔）
- 心跳保活（可配置间隔）
- 服务端主动断连自动触发重连
- 连接/消息/错误/断开事件回调

### 💾 存档系统 (SaveGameSystem)
基于 SaveGameFree 的多存档槽持久化系统。
- 支持任意可序列化类型
- JSON / Binary 双序列化格式
- AES 加密（可关闭）
- 多存档槽（Slot 0, 1, 2...）
- 自动重试（失败最多 3 次）

### 🔴 红点系统 (RedDotSystem)
前缀树优化的红点通知系统，支持可视化配置。
- 三种红点类型：纯红点、数字红点、自定义
- 前缀树结构，脏标记只向上传播
- 编辑器工具：可视化配置、代码生成

### 📊 配置表系统 (DataTableSystem)
集成 Luban 的类型安全配置表系统。
- 自动生成 C# 类，类型安全
- 支持 JSON / Binary 格式
- 与 YooAsset 资源加载集成

## 🎯 开发状态

### ✅ 已完成功能
- [x] 双层架构设计（Runtime / HotUpdate）
- [x] 统一模块访问入口（GameMain）
- [x] 依赖注入系统（IOC 容器）
- [x] 状态机系统（FsmManager）
- [x] 对象池系统（HashSet 优化 Tick，O(1)）
- [x] Tick 系统（Update / FixedUpdate / LateUpdate）
- [x] 流程管理系统（ProcedureManager）
- [x] 资源管理系统（YooAsset + 引用计数 + 自动缓存）
- [x] 热更新支持（HybridCLR）
- [x] UI 系统（链式 API + 类型处理器）
- [x] 音频系统（FMOD + BuiltIn 双模式）
- [x] 红点系统（前缀树优化 + 可视化编辑器）
- [x] 配置表系统（Luban）
- [x] 计时器系统（UniTask + CancellationToken）
- [x] WebSocket 系统（自动重连 + 心跳保活）
- [x] 存档系统（多槽位 + 加密 + 自动重试）
- [x] 数据持久化（SaveGame）
- [x] 完整的 XML 注释

### 🚧 开发中功能
- [ ] 性能监控工具（Profile 面板）
- [ ] 本地化支持（多语言）

### 📋 计划功能
- [ ] 自动化测试框架
- [ ] CI/CD 集成
- [ ] 编辑器工具增强（框架调试窗口）

## 📖 文档

| 分类 | 文档 |
|------|------|
| 框架总览 | [框架完整使用指南](./Docs/00_框架总览/框架完整使用指南.md) |
| 核心系统 | [有限状态机 (FSM)](./Docs/01_核心系统/FSM/) · [流程管理](./Docs/01_核心系统/Procedure/) · [启动流程](./Docs/01_核心系统/LaunchSystem/) |
| 管理器模块 | [对象池](./Docs/02_管理器模块/ObjectPool/) · [音频管理器](./Docs/02_管理器模块/AudioManager/) · [资源管理器](./Docs/02_管理器模块/Resource/) |
| 功能系统 | [红点系统](./Docs/03_功能系统/RedPointSystem/) · [计时器](./Docs/03_功能系统/TimerSystem/) · [WebSocket](./Docs/03_功能系统/WebSocketSystem/) · [存档系统](./Docs/03_功能系统/SaveGameSystem/) |

## 🤝 贡献指南

我们欢迎各种形式的贡献！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 开发环境设置

```bash
# 克隆项目
git clone https://gitee.com/Absure/hoppy-game_-dbf.git

# 进入项目目录
cd hoppy-game_-dbf

# 使用 Unity 2021.3 LTS 或更高版本打开项目
# 项目会自动配置相关依赖
```

## 📝 更新日志

详细的更新日志请查看 [CHANGELOG.md](./CHANGELOG.md)

### [v2.3] - 2026-03-08

**代码质量评分：9.5/10** ⭐

#### 🐛 Bug 修复
- ✅ **Asset.cs**: 修复并发异步加载引用计数泄漏（缓存命中失败路径未平衡 Retain/Release）
- ✅ **Asset.cs**: 修复同步加载命中"加载中"缓存时的引用计数泄漏
- ✅ **Asset.cs**: 修复 `LoadRawFile` 重复加载时旧句柄覆盖泄漏
- ✅ **WebSocketSystem.cs**: 修复 `OnError` + `OnClose` 双重触发 `StartReconnect()` 的问题
- ✅ **WebSocketSystem.cs**: 修复 `Disconnect()` 后 `_isDisposed` 重置时机错误导致意外重连
- ✅ **WebSocketSystem.cs**: 修复重连时旧 WebSocket 实例未安全清理
- ✅ **WebSocketSystem.cs**: `Send()` 返回类型从 `Task` 统一为 `UniTask`
- ✅ **SinglePoolData.cs**: `Dispose()` 添加 `Pool.Clear()` 兜底，防止资源引用泄漏

#### ⚡ 性能优化
- 🚀 **Asset.cs**: `ReleaseUnusedAssets` / `ReleaseIdleAssets` 改用复用 `List<string>` 替代 LINQ ToList，消除 GC 分配
- 🚀 **Asset.cs**: 自动释放闲置资源改为固定间隔检查（5s），避免每帧 LINQ 遍历

#### 🧹 代码质量
- 📝 删除 `Retain()` 后的冗余 `UpdateUseTime()` 调用
- 📝 `OnError` 注释明确说明不在此处触发重连，逻辑收拢到 `OnClose`
- 📝 `Disconnect()` 文档注释说明 `_isDisposed` 不在此重置的原因

### [v2.2]

**代码质量评分：9.0/10** ⭐

#### 🏗️ 架构优化
- ✨ **统一访问入口**: 实现 GameMain 统一模块访问，所有模块通过 `GameMain.XXX` 访问
- 🎯 **快捷属性**: 添加常用模块的快捷访问属性（Resource, Tick, UI, Audio 等）
- 📐 **双层架构**: 明确 Runtime（框架层）与 HotUpdate（业务层）的职责边界
- 🔄 **API 统一**: HotUpdate 层代码全面迁移到统一访问方式

#### ⚡ 性能优化
- 🚀 **Tick 系统优化**: 从 List 改为 HashSet，注册/注销性能从 O(n) 提升到 O(1)
- ⏱️ **防重复注册**: HashSet 自动防止重复注册，提升系统稳定性
- 🎯 **批量移除优化**: 异常对象延迟批量移除，避免遍历时修改集合

#### 🧹 代码质量
- 📝 **完整 XML 注释**: 为核心类添加完整文档注释
- 🔢 **消除 Magic Number**: 提取所有魔法数字为有意义的常量
- 🗑️ **删除冗余代码**: 移除未使用代码，简化架构

### [v2.1]
- 🎯 **UI系统重构**: 实现职责分离架构
- ⚡ **并发优化**: UI 批量预加载改为并行处理
- 🔗 **链式API**: 新增 UIRequestBuilder

### [v0.0.1]
- ✨ 重构架构，引入依赖注入系统
- 🔧 修复代码质量问题和命名规范
- 📝 重写项目文档

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE.md](./LICENSE.md) 文件了解详情。

## 👥 社区与支持

- 🐛 **问题反馈**: [提交 Issue](https://gitee.com/Absure/hoppy-game_-dbf/issues)
- 💬 **QQ交流群**: [399346678](https://qm.qq.com/q/bswKDNjWJU)
- 📧 **邮箱**: dhaopi@163.com

## 🙏 致谢

感谢以下开源项目的支持：
- [HybridCLR](https://github.com/focus-creative-games/hybridclr) - 热更新解决方案
- [YooAsset](https://github.com/tuyoogame/YooAsset) - 资源管理系统
- [Luban](https://github.com/focus-creative-games/luban) - 数据表工具
- [UniTask](https://github.com/Cysharp/UniTask) - 高性能异步
- [NativeWebSocket](https://github.com/endel/NativeWebSocket) - WebSocket 客户端
- [SaveGameFree](https://github.com/BayatGames/SaveGameFree) - 存档系统

感谢所有为这个项目做出贡献的开发者！

---

<p align="center">Made with ❤️ by HoopyGame Studio</p>