[docs][refactor]: 将旧 01~06 中文教程合并整理为 modules/frameworks 文件夹结构
- 删除 01~05 旧中文教程目录 - 将 03 核心功能教程拆分为各 framework 模块的子文档 - 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/ - 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md - 更新所有交叉链接与文档关联表 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
398
modules/frameworks/通用框架/框架架构.md
Normal file
398
modules/frameworks/通用框架/框架架构.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# StrayFog 框架架构分析
|
||||
|
||||
> 本文档从实现视角分析 StrayFog 框架的整体架构。高层架构规则与程序集边界见 [rules/10-架构说明.md](../../../rules/10-架构说明.md)。
|
||||
|
||||
## 一、框架整体架构
|
||||
|
||||
### 1.1 模块划分
|
||||
|
||||
| 模块层级 | 路径 | 职责描述 |
|
||||
|---------|------|---------|
|
||||
| **Core 层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 |
|
||||
| **HF 层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理等 |
|
||||
| **General 层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具等 |
|
||||
|
||||
### 1.2 架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ StrayFog Framework │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
|
||||
│ │ GameGeneral │ │ GameHF │ │ Core │ │
|
||||
│ │ 状态机/工具类 │ │ 业务核心模块 │ │ 基础框架层 │ │
|
||||
│ └────────┬─────────┘ └────────┬─────────┘ └───────┬───────┘ │
|
||||
├───────────┼─────────────────────┼───────────────────┼───────────┤
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Unity Engine │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、Core 层架构
|
||||
|
||||
### 2.1 SimulateBehaviour 模拟行为系统
|
||||
|
||||
#### 2.1.1 核心接口
|
||||
|
||||
```csharp
|
||||
public interface ISimulateBehaviour
|
||||
{
|
||||
long simulateGlobalId { get; } // 模拟行为全局 ID
|
||||
int bindGameObjectInstanceId { get; } // 绑定对象实例 ID
|
||||
void BindGameObject(GameObject _go); // 绑定 GameObject
|
||||
void UnBindGameObject(); // 解绑 GameObject
|
||||
// ... 完整的 MonoBehaviour 生命周期方法
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.1.2 设计目的
|
||||
|
||||
| 设计目标 | 实现方式 |
|
||||
|---------|---------|
|
||||
| **解耦 MonoBehaviour** | 将逻辑从 MonoBehaviour 中剥离，便于测试和复用 |
|
||||
| **生命周期控制** | 完整模拟 Unity 生命周期，支持自定义调度 |
|
||||
| **对象池优化** | 配合对象池实现高效对象复用 |
|
||||
|
||||
#### 2.1.3 目录结构
|
||||
|
||||
```
|
||||
SimulateBehaviour/
|
||||
├── ISimulateBehaviour.cs # 核心接口定义
|
||||
├── Bind/ # 绑定实现
|
||||
│ ├── IBindSimulateBehaviour.cs
|
||||
│ ├── AbsBindSimulateBehaviour_Mono.cs # Mono 绑定基类
|
||||
│ ├── AbsBindSimulateBehaviour_UI.cs # UI 绑定基类
|
||||
│ └── BindSimulateBehaviour_Collect.cs # 收集器
|
||||
├── MonoBehaviour/ # 各生命周期模拟实现
|
||||
│ ├── SimulateMonoBehaviour_Awake__xxx.cs
|
||||
│ ├── SimulateMonoBehaviour_Update__xxx.cs
|
||||
│ └── ... (40+ 生命周期方法)
|
||||
└── UIBehaviour/ # UI 生命周期模拟
|
||||
├── SimulateUIBehaviour_Awake__xxx.cs
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 2.2 全局数据管理
|
||||
|
||||
**SFGlobalData.cs** - 全局路径和平台管理
|
||||
|
||||
```csharp
|
||||
public sealed class SFGlobalData
|
||||
{
|
||||
public static string assetBundleRoot; // AB 包根路径
|
||||
public static string streamingAssetsRoot; // 流式资源根路径
|
||||
public static string cdnassetBundleRoot; // CDN 资源路径
|
||||
public static RuntimePlatform Platform(); // 当前平台判断
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、HF 层架构
|
||||
|
||||
### 3.1 接口体系
|
||||
|
||||
#### 3.1.1 核心接口继承链
|
||||
|
||||
```
|
||||
IHFObject (基础对象接口)
|
||||
├── IHFRecycle (回收接口)
|
||||
│ └── void Recycle();
|
||||
├── IHFGlobal (全局对象接口)
|
||||
│ └── long globalId { get; }
|
||||
├── IHFClone (克隆接口)
|
||||
├── IHFLanguage (语言接口)
|
||||
├── IHFScene (场景接口)
|
||||
└── IHFSerializable (序列化接口)
|
||||
```
|
||||
|
||||
#### 3.1.2 接口职责表
|
||||
|
||||
| 接口 | 核心职责 | 关键字段/方法 |
|
||||
|-----|---------|--------------|
|
||||
| `IHFObject` | 基础对象标识 | 无 |
|
||||
| `IHFRecycle` | 对象回收机制 | `Recycle()` |
|
||||
| `IHFGlobal` | 全局唯一标识 | `globalId` |
|
||||
| `IHFClone` | 对象克隆能力 | 系列 Clone 方法 |
|
||||
| `IHFLanguage` | 多语言支持 | 语言切换 |
|
||||
| `IHFScene` | 场景管理 | 场景加载/卸载 |
|
||||
|
||||
### 3.2 对象池系统
|
||||
|
||||
#### 3.2.1 HFObjectMemPool - GameObject 对象池
|
||||
|
||||
```csharp
|
||||
public class HFObjectMemPool
|
||||
{
|
||||
private Queue<GameObject> m_UnoccupiedPool; // 空闲队列
|
||||
private Dictionary<int, GameObject> m_UsingPool; // 使用中字典
|
||||
public GameObject GetItem(out bool isnew); // 获取对象
|
||||
public void GiveBack(GameObject item); // 归还对象
|
||||
public void Recycle(); // 完全回收
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.2 HFScriptMemPool<T> - 泛型脚本对象池
|
||||
|
||||
```csharp
|
||||
public class HFScriptMemPool<T> : IHFRecycle
|
||||
where T : IHFRecycle
|
||||
{
|
||||
private Queue<T> m_UnoccupiedPool;
|
||||
private List<T> m_UsingPool;
|
||||
// 支持 MonoBehaviour 和普通类的自动创建
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.3 对象池设计特点
|
||||
|
||||
| 特性 | 实现方式 | 优势 |
|
||||
|-----|---------|-----|
|
||||
| **双池结构** | 空闲池 + 使用池 | 高效管理对象状态 |
|
||||
| **内存泄漏检测** | 归还时校验来源 | 及时发现问题 |
|
||||
| **泛型支持** | `HFScriptMemPool<T>` | 类型安全 |
|
||||
| **Mono 支持** | 自动创建 GameObject | 无缝集成 Unity |
|
||||
|
||||
### 3.3 事件系统
|
||||
|
||||
#### 3.3.1 核心接口
|
||||
|
||||
```csharp
|
||||
public interface IHFEventHandle<K,T> : IHFRecycle
|
||||
{
|
||||
void AddListener<T1>(K key, Action<T> callback); // 添加监听
|
||||
void RemoveListener<T1>(K key, Action<T> action); // 移除监听
|
||||
void Dispatch(T arg); // 分发事件
|
||||
void RemoveAll(K key); // 清空监听
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.3.2 AbsHFEventHandle 实现机制
|
||||
|
||||
```csharp
|
||||
public abstract class AbsHFEventHandle<K,T> : IHFEventHandle<K,T>
|
||||
where K : struct, Enum
|
||||
where T : IHFEventArg<K>
|
||||
{
|
||||
// 多级索引: EventId -> TypeHashCode -> Action 列表
|
||||
HFMultiKeyDictionary<K, int, IHFCacheEventAction<K,T>> mICacheEventActionMaping;
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.3.3 事件系统架构
|
||||
|
||||
```
|
||||
事件分发流程:
|
||||
Dispatch(arg)
|
||||
│
|
||||
▼
|
||||
获取 EventId 对应的 Action 字典
|
||||
│
|
||||
▼
|
||||
获取 参数类型 HashCode 对应的 CacheEventAction
|
||||
│
|
||||
▼
|
||||
遍历执行所有 Action<T>
|
||||
│
|
||||
▼
|
||||
调用 arg.Recycle() 回收事件参数
|
||||
```
|
||||
|
||||
### 3.4 AssetBundle 资源管理器
|
||||
|
||||
#### 3.4.1 HFABMgr 核心结构
|
||||
|
||||
```csharp
|
||||
public partial class HFABMgr : AbsHFSingleMonoBehaviour<HFABMgr>
|
||||
{
|
||||
public float progress { get; } // 加载进度
|
||||
Dictionary<int, HFAssetLoader> mHFAssetLoaderMaping; // 加载器映射
|
||||
Dictionary<int, HFAssetBundlePathAttribute> mHFAssetBundlePathAttributeMaping; // 属性映射
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.4.2 资源加载流程
|
||||
|
||||
```
|
||||
资源加载流程:
|
||||
OnStartLoad(request)
|
||||
│
|
||||
▼
|
||||
检查缓存 → 获取/创建 HFAssetLoader
|
||||
│
|
||||
▼
|
||||
loader.AddRequest(request)
|
||||
│
|
||||
▼
|
||||
loader.LoadAsset() → 异步加载
|
||||
│
|
||||
▼
|
||||
加载完成 → 回调处理
|
||||
```
|
||||
|
||||
#### 3.4.3 依赖管理
|
||||
|
||||
通过 Manifest 文件解析资源依赖关系：
|
||||
|
||||
```csharp
|
||||
HFAssetBundlePathAttribute OnGetDependencyAbpAttr(string _depManifestName)
|
||||
{
|
||||
// 解析依赖项名称 → 获取属性 → 缓存
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 相机管理系统
|
||||
|
||||
#### 3.5.1 HFCameraManager 架构
|
||||
|
||||
```csharp
|
||||
public partial class HFCameraManager : AbsHFSingleRunTime<HFCameraManager>
|
||||
{
|
||||
private Dictionary<int, AbsHFCameraItem> m_List_CameraItem; // 相机列表
|
||||
public HFMainCamera mainCamera; // 主相机
|
||||
|
||||
public void AddCamera(AbsHFCameraItem cameraItem); // 添加相机
|
||||
public void RemoveCamera(AbsHFCameraItem cameraItem); // 移除相机
|
||||
public AbsHFEventHandle GetCamera(string _cameraName); // 获取相机
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.5.2 相机堆栈管理
|
||||
|
||||
```
|
||||
相机层级架构:
|
||||
HFMainCamera (主相机)
|
||||
│
|
||||
├── CameraStack (相机堆栈)
|
||||
│ ├── CameraItem1 (Weight=10)
|
||||
│ ├── CameraItem2 (Weight=20)
|
||||
│ └── CameraItem3 (Weight=5)
|
||||
│
|
||||
└── 按 Weight 排序 → 渲染顺序控制
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、General 层架构
|
||||
|
||||
### 4.1 状态机系统
|
||||
|
||||
#### 4.1.1 核心类层次
|
||||
|
||||
```
|
||||
IGFStateMachineBehaviour (接口)
|
||||
│
|
||||
├── AbsGFStateMachineBehaviour (抽象基类)
|
||||
│ ├── AbsGFAttachStateBehaviour (状态行为)
|
||||
│ ├── AbsGFAttachLayerBehaviour (层行为)
|
||||
│ └── AbsGFAttachMachineBehaviour (机行为)
|
||||
│
|
||||
└── IGFStateMachineBehaviourClassify (分类接口)
|
||||
```
|
||||
|
||||
#### 4.1.2 状态机特性
|
||||
|
||||
| 特性 | 说明 |
|
||||
|-----|------|
|
||||
| **层级化设计** | 支持状态、层、机三个层级的行为绑定 |
|
||||
| **参数化驱动** | 通过参数控制状态切换 |
|
||||
| **Inspector 扩展** | 自定义编辑器支持 |
|
||||
|
||||
### 4.2 工具类
|
||||
|
||||
#### 4.2.1 扩展方法集合
|
||||
|
||||
**HFUGUIExtendEngine.cs** - UGUI 扩展方法（40+ 方法）
|
||||
|
||||
| 功能分类 | 方法示例 |
|
||||
|---------|---------|
|
||||
| **坐标转换** | `HFWorldToLocalPointInRectangle` |
|
||||
| **布局操作** | `HFFixedPositionInCanvas`, `HFForceRebuildLayoutImmediate` |
|
||||
| **RectTransform** | `HFIdentityStreech`, `HFCopyRectTransformFrom` |
|
||||
| **事件监听** | `HFAddListener` |
|
||||
|
||||
#### 4.2.2 其他工具
|
||||
|
||||
| 工具类 | 职责 |
|
||||
|-------|-----|
|
||||
| `HFAssetBundleHelper` | AB 包辅助工具 |
|
||||
| `HFDllHelper` | DLL 加载辅助 |
|
||||
| `HFEnumForAssetBundle` | AB 包相关枚举 |
|
||||
| `MinGameModel` | 微信小游戏适配 |
|
||||
|
||||
---
|
||||
|
||||
## 五、架构设计特点
|
||||
|
||||
### 5.1 设计模式应用
|
||||
|
||||
| 模式 | 应用场景 | 实现类 |
|
||||
|-----|---------|-------|
|
||||
| **单例模式** | 全局管理器 | `AbsHFSingleMonoBehaviour`, `AbsHFSingleRunTime` |
|
||||
| **工厂模式** | 对象创建 | 对象池的 GetItem |
|
||||
| **观察者模式** | 事件系统 | `IHFEventHandle` |
|
||||
| **策略模式** | 多平台适配 | `SFGlobalData.Platform()` |
|
||||
| **模板方法** | 生命周期 | `SimulateBehaviour` 系列 |
|
||||
|
||||
### 5.2 架构优势
|
||||
|
||||
| 优势 | 体现 |
|
||||
|-----|------|
|
||||
| **解耦性** | 逻辑与 MonoBehaviour 分离 |
|
||||
| **可测试性** | 纯逻辑类易于单元测试 |
|
||||
| **性能优化** | 对象池减少 GC |
|
||||
| **扩展性** | 接口驱动，易于扩展 |
|
||||
| **可维护性** | 清晰的模块划分 |
|
||||
|
||||
### 5.3 潜在改进点
|
||||
|
||||
| 改进方向 | 说明 |
|
||||
|---------|------|
|
||||
| **异步加载优化** | 可引入协程池或 Job System |
|
||||
| **资源依赖可视化** | 可增加依赖关系图工具 |
|
||||
| **性能监控** | 可增加加载时间、内存占用统计 |
|
||||
| **热更新支持** | 可考虑集成 Lua 或 ILRuntime |
|
||||
|
||||
---
|
||||
|
||||
## 六、总结
|
||||
|
||||
StrayFog 框架是一个结构清晰、设计完善的 Unity 游戏框架，核心特点包括：
|
||||
|
||||
1. **模拟行为系统** - 实现了完整的 MonoBehaviour 生命周期解耦
|
||||
2. **对象池机制** - 高效的内存管理策略
|
||||
3. **事件驱动架构** - 灵活的事件分发系统
|
||||
4. **资源管理体系** - 完善的 AssetBundle 加载和依赖管理
|
||||
5. **模块化设计** - 清晰的分层和职责划分
|
||||
|
||||
该框架适合中大型 Unity 项目使用，具备良好的扩展性和维护性。
|
||||
|
||||
---
|
||||
|
||||
**版本**: v1.0
|
||||
**分析日期**: 2024年
|
||||
**适用项目**: OnlineGame
|
||||
|
||||
---
|
||||
|
||||
## 文档关联
|
||||
|
||||
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
|
||||
|
||||
| 文档 | 关联原因 |
|
||||
|---|---|
|
||||
| [通用框架入口](README.md) | 本文件是通用框架模块的子文档 |
|
||||
| [架构说明](../../../rules/10-架构说明.md) | 高层架构规则与程序集边界 |
|
||||
| [实体系统](../实体系统/README.md) | 实体系统架构在本文件中分析 |
|
||||
| [对象池与运行时对象管理](../内存对象管理/README.md) | 对象池架构在本文件中分析 |
|
||||
| [事件系统](../事件系统/README.md) | 事件系统架构在本文件中分析 |
|
||||
| [资源管理](../资源管理/README.md) | 资源管理架构在本文件中分析 |
|
||||
| [相机系统](../相机系统/README.md) | 相机系统架构在本文件中分析 |
|
||||
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
|
||||
| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架架构互相引用 |
|
||||
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
|
||||
Reference in New Issue
Block a user