UnityAI/modules/frameworks/框架架构.md

StrayFog 框架架构分析

本文档从实现视角分析 StrayFog 框架的整体架构。高层架构规则与程序集边界见 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 核心接口

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 - 全局路径和平台管理

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 对象池

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 - 泛型脚本对象池

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 核心接口

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 实现机制

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 核心结构

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 文件解析资源依赖关系：

HFAssetBundlePathAttribute OnGetDependencyAbpAttr(string _depManifestName)
{
    // 解析依赖项名称 → 获取属性 → 缓存
}

3.5 相机管理系统

3.5.1 HFCameraManager 架构

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

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
通用框架入口	本文件是通用框架模块的子文档
架构说明	高层架构规则与程序集边界
实体系统	实体系统架构在本文件中分析
对象池与运行时对象管理	对象池架构在本文件中分析
事件系统	事件系统架构在本文件中分析
资源管理	资源管理架构在本文件中分析
相机系统	相机系统架构在本文件中分析
modules/模块索引.md	模块索引是项目知识总入口
rules/20-开发规则.md	开发规则与框架架构互相引用
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径