# cocos_framework

**Repository Path**: Raindrips/cocos_framework

## Basic Information

- **Project Name**: cocos_framework
- **Description**: 使用 cocos 封装的模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cocos Creator Framework

适用于 Cocos Creator 3.8.x 的通用游戏开发框架，提供从纯逻辑工具到可挂载组件的完整基础设施。

通过 `tsconfig.json` 路径别名和 `import-map.json` 配置为 `cocos_framework/*`，可直接导入：

```typescript
import { EventManager } from 'cocos_framework/utils/EventManager';
import { UIManager } from 'cocos_framework/manager/ui/core/UIManager';
```

## 目录结构

```
cocos_framework/
├── core/           # 纯逻辑，无 cc 依赖
├── utils/          # 工具类，可能依赖 cc 但非组件
├── component/      # 可挂载的 @ccclass 组件
├── manager/        # UI 管理系统 + WebSocket
└── module/         # 独立功能模块（多文件系统）
```

## core/ — 纯逻辑层

不依赖 Cocos 引擎，可在任意环境下使用。

| 文件 | 说明 |
|---|---|
| `Instance.ts` | 通用单例工厂，`Instance.get<T>(clazz)` 缓存并返回唯一实例 |
| `SimpleEvent<T>` | 轻量级发布-订阅事件，支持 `add`/`remove`/`invoke`/`clear` |
| `StateMachine/` | 完整有限状态机，支持嵌套状态、守卫条件、事件驱动转换、Builder 链式 API |
| `BitSet<T>` | Map 位集，O(1) 布尔查询，跟踪 true 计数 |
| `FastBitSet` | Uint32Array 高性能位集，适用于密集整数索引 |
| `BorderSystem` | 网格边界检测，计算 2D 网格中每个单元格的活跃边 |
| `MathUtils` | 弧度/角度转换、两点间弧度计算 |
| `RandomUtils` | 浮点/整数范围随机数 |
| `StringUtils` | 字符串工具（去空格、中文字符长度计算） |
| `StringBuffer` | 字符串拼接器 |
| `DataUtils` | 日期时间格式化（HH:MM:SS、yyyy-mm-dd、"X 天前"等） |
| `Percent` | 百分比/比率计算器 |
| `PathUtil` | 路径工具（扩展名、文件名提取） |
| `UrlUtil` | URL 查询参数解析 |
| `md5` | RFC 1321 MD5 哈希实现 |
| `http/HttpClient` | HTTP 客户端，带类型化错误码（TIMEOUT、NETWORK_ERROR 等） |
| `http/downloadFile` | XHR 文件下载，支持进度回调 |

## utils/ — 工具层

依赖 Cocos 引擎 API，但本身不是组件。

| 文件 | 说明 |
|---|---|
| `EventManager` | 装饰器事件管理器单例，以类构造函数为类型安全事件键，支持 `@RegisterEvent` 装饰器 |
| `EventMgr` | 继承 `EventTarget` 的简单全局事件单例 |
| `InputUtil` | 键盘输入工具单例，`KeyCode` 到回调的映射 |
| `GlobalUpdateManager` | 全局帧更新管理器，注册带优先级的每帧回调 |
| `TimerMgr` | 自定义定时器管理器，支持延迟、重复、目标绑定 |
| `HttpUtils` | 简单 GET/POST 请求封装 |
| `ResourceLoader<T>` | 泛型缓存资源加载器，支持重试和进度回调 |
| `NodePathUtil` | 斜杠路径遍历节点树 |
| `RotationUtils` | 方向与四元数互转（2D/3D），角度插值 |
| `SocketUtils` | WebSocket 封装，状态机管理（None/Connecting/Connected） |
| `TerrainRaycaster` | 2D 物理射线检测封装 |
| `JumpAction` | 抛物线跳跃动画（类似 cocos2d-x jumpBy） |
| `SpiralTools` | 三节点螺旋汇聚动画 |
| `GatherEffectTools` | 多节点螺旋聚集动画（阿基米德螺旋 + 正弦抖动） |
| `SortComponent` / `SortHelper` / `SortNodeHelper` | 节点 zIndex 排序管理 |

## component/ — 组件层

可直接挂载到场景节点的 `@ccclass` 组件。

### 相机与控制

| 组件 | 说明 |
|---|---|
| `CameraController2D` | 2D 相机控制：鼠标拖拽平移、滚轮缩放、键盘移动 |
| `ThirdPersonCamera` | 3D 第三人称轨道相机，鼠标控制角度，射线碰撞避障 |
| `CameraShake` | 相机震动效果，可配置幅度、距离、速度、旋转 |
| `KeyMove` | 键盘方向移动，按键栈实现多键平滑方向处理 |
| `DragMove` | 鼠标/触摸拖拽移动节点（2D） |

### 动画与特效

| 组件 | 说明 |
|---|---|
| `AnimatorController` | 动画状态机封装，按名称播放 AnimationClip，支持异步完成回调 |
| `SpriteAnimator` | 逐帧精灵动画，按 SpriteFrame 分组，可配置帧率 |
| `SpineHelper` | Spine 动画辅助器，按名称播放，支持完成回调和状态锁定 |
| `SpiralTriangle` | 三节点阿基米德螺旋汇聚动画组件 |
| `BlackNode` | 全屏渐黑效果（Sprite 叠加 + tween 透明度） |
| `WhileBlink` | 单帧闪烁：激活节点后下一帧立即关闭 |
| `SmoothValue` | 数值平滑插值（速度模式/时长模式），支持回调 |

### 文本与调试

| 组件 | 说明 |
|---|---|
| `Typewriter` | 打字机文字逐字显示效果 |
| `DebugDraw` | 调试绘制组件（Graphics），支持线段、矩形、圆形 |
| `SerializableMap<K, V>` | 可序列化的 Map 实现，用于编辑器 Inspector |

### audio/ — 音频管理

| 组件 | 说明 |
|---|---|
| `AudioManager` | 单例音频管理器，按 AudioClip 控制音量/偏移，支持起始偏移和结束回调 |
| `AudioMgr` | 简单 BGM + 音效管理器，localStorage 持久化开关状态 |
| `AudioEffectManager` | 底层音频 API 抽象，基于 NodePool 的音频源节点管理 |

### node/ — 节点跟随

| 组件 | 说明 |
|---|---|
| `FollowNode` | 稳定跟随：同步不同父级层级下的节点位置/旋转/缩放 |
| `BorrowNode` | 将节点视觉附着到目标父节点，保持世界变换不变 |
| `FollowAttach` | 跟随附着变体，预加载缓存变换后同步到目标节点 |

### scene/ — 场景管理

| 组件 | 说明 |
|---|---|
| `SceneManager` | 场景管理：持久化根节点、场景预加载、加载画面处理 |

### shadule/ — 调度

| 组件 | 说明 |
|---|---|
| `FixedUpdate` | 固定时间步长更新循环（可配置 FPS），单例，发射 `fixed-update` 事件 |
| `TimerManager` | 单例定时器管理器，支持 GameTime/RealTime 模式，配置间隔、延迟、重复次数 |

### ui/extended-button/ — 扩展按钮

| 组件 | 说明 |
|---|---|
| `ExtendedButtonBase` | 标签式按钮禁用/启用系统，多标签独立锁定 |
| `ExtendedButtonDelay` | 延迟后自动重新启用按钮（Cocos `schedule`） |
| `ExtendedButtonLocalDelay` | 延迟后自动重新启用按钮（`setTimeout`，毫秒） |
| `ExtendedButtonStyleGray` | 禁用时按钮变灰，启用时恢复 |
| `GlobalButtonLock` | 全局锁定/解锁场景中所有 `ExtendedButtonBase` |
| `lockByPromise` | Promise 期间锁定按钮（如网络请求） |

## manager/ — 管理系统

### UI 管理系统 (`manager/ui/`)

完整的 UI 窗口管理架构：

```
UIManager (门面单例)
├── LayerManager    — UILayer 枚举映射到节点容器
├── WindowManager   — 窗口生命周期：注册 → 加载 prefab → 实例化 → 关闭
├── ModalManager    — 引用计数模态遮挡器
└── ObjectPoolManager — 字符串键控的节点对象池
```

**UILayer 层级**：`SceneUI` → `FixedUI` → `Window` → `Dialog` → `Guide` → `Top`

**窗口缓存策略 (CachePolicy)**：
- `Permanent` — 常驻内存
- `Pool` — 关闭时回收到对象池
- `Destroy` — 关闭时销毁

**窗口转换动画 (TransitionType)**：`None`（即时）、`Fade`（渐入渐出）

扩展 `BaseWindow` 实现 `IWindow` 接口（`onOpen`、`onClose`、`onFocus`、`onLostFocus`）即可接入系统。

### WebSocket (`manager/websocket/`)

| 文件 | 说明 |
|---|---|
| `WebSocketClient` | 功能完整的 WebSocket 客户端：自动重连（固定/指数退避）、心跳、string/ArrayBuffer/Blob |
| `WebSocketComponent` | Cocos 组件封装，`onLoad` 自动连接，`onDestroy` 自动断开 |

## module/ — 独立功能模块

### ecs/ — 实体组件系统

轻量级 ECS 实现：
- `EntityManager` — 创建/销毁实体（数字 ID）
- `ComponentManager` — 类型键控的组件存储，按实体索引
- `SystemManager` — 系统注册与生命周期（`onLoad`/`onEnable`/`onDisable`/`onUpdate`）
- `WorldManager` — ECS 世界门面，组合以上三者

### rvo2/ — 碰撞避免

RVO2（Reciprocal Velocity Obstacles）算法实现：
- `Agent` — 智能体，存储邻居、ORCA 线、优选速度
- `KdTree` — 高效邻居查询和障碍物树
- `Simulator` — 主模拟器，管理智能体、障碍物，执行模拟步进
- `Vector2D` / `Line` / `Obstacle` / `RVOMath` — 基础数学类型

### backpack/ — 背包/物品栏

纯数据背包系统：
- `Inventory` — 槽位式存储，支持 `add`/`remove`/`move`，事件通知
- `IItem` / `ISlot` — 物品类型（id、name、maxStack）和槽位类型（物品、数量、耐久度）
- `EventEmitter<T>` — 泛型事件发射器

### background-loop/ — 背景循环滚动

引擎无关的无限循环滚动系统：
- `BackgroundLoopCore` — 纯数学逻辑，支持水平/垂直/双向环绕
- `BackgroundLoopComponent` — Cocos 组件封装，Inspector 可配置
- `CocosSpriteNodeAdapter` — Cocos 引擎适配器

### input-command/ — 输入指令

指令绑定系统：
- `InputCommand` — 事件触发绑定（`onTrigger`/`offTrigger`/`handle`）
- `KeyCombo` — 组合键检测
- `IInputDevice` — 输入设备抽象接口

### skill-wheel/ — 技能轮盘

径向技能选择轮盘：
- `SkillWheelLogic` — 纯逻辑：扇区数、偏移角、死区、角度到索引
- `SkillWheelGraphics` — Graphics 渲染径向分段轮盘
- `SkillWheelInput` — 鼠标驱动输入，发射选择事件
- `SkillWheelView` — 图标节点环形布局
- `WheelSelector` — 独立的角度到扇区索引转换器

### pixel-button/ — 像素级按钮

基于像素透明度的精确点击检测：
- `PixelButton` — 像素完美按钮组件
- `checkPixels` — 读取 GPU 像素缓冲区检测 alpha
- 缓存版本支持 WeakMap 缓冲区缓存和 spriteFrame 变更自动失效

### recorder/ — 输入录制回放

确定性回放系统：
- `InputSampler` — 将方向 + 开火输入采样为位掩码
- `Recorder` — 逐帧记录输入位掩码并回放

## 设计原则

- **纯逻辑与引擎分离**：`core/` 完全不依赖 Cocos，可独立测试和复用
- **单例模式**：广泛使用，两种风格——`static Instance` 属性和 `Instance.get<T>(clazz)` 泛型工厂
- **组件化**：所有游戏逻辑继承 `Component`，使用 `@ccclass` 和 `@property` 装饰器
- **模块化**：`module/` 下每个子系统自包含，可按需引入
- **接口驱动**：管理系统通过接口（`IWindow`、`ITransition`、`IInputDevice`）解耦