lms
571e299642
- 描述改为全局分层入口，引导至各模块使用指南 - 删除 Lua/ILRuntime 过时改进点，改为 HybridCLR 说明 - 更新版本、日期和适用项目 - 修正移动后的文档关联路径 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
399 lines
14 KiB
Markdown
399 lines
14 KiB
Markdown
# StrayFog 框架架构分析
|
||
|
||
> 本文档从实现视角描述 StrayFog 框架的整体分层与全局入口。各模块的详细实现、API 与使用规则见其自身的 README / 使用指南；高层架构规则与程序集边界见 [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 |
|
||
| **资源依赖可视化** | 可增加依赖关系图工具 |
|
||
| **性能监控** | 可增加加载时间、内存占用统计 |
|
||
| **热更新支持** | 当前热更新方案为 HybridCLR；若未来需要替换，需单独评估兼容性、包体大小和构建流程 |
|
||
|
||
---
|
||
|
||
## 六、总结
|
||
|
||
StrayFog 框架是一个结构清晰、设计完善的 Unity 游戏框架，核心特点包括：
|
||
|
||
1. **模拟行为系统** - 实现了完整的 MonoBehaviour 生命周期解耦
|
||
2. **对象池机制** - 高效的内存管理策略
|
||
3. **事件驱动架构** - 灵活的事件分发系统
|
||
4. **资源管理体系** - 完善的 AssetBundle 加载和依赖管理
|
||
5. **模块化设计** - 清晰的分层和职责划分
|
||
|
||
该框架适合中大型 Unity 项目使用，具备良好的扩展性和维护性。
|
||
|
||
---
|
||
|
||
**版本**: v1.1
|
||
**最后更新日期**: 2026-07-15
|
||
**适用项目**: 使用 StrayFog / UnityAI 框架的 Unity 项目
|
||
|
||
---
|
||
|
||
## 文档关联
|
||
|
||
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
|
||
|
||
| 文档 | 关联原因 |
|
||
|---|---|
|
||
| [通用框架入口](通用框架/README.md) | Core / General 层详细说明 |
|
||
| [架构说明](../../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) | 模块登记规则定义分类和状态口径 |
|