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

# 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) | 模块登记规则定义分类和状态口径 |