【重构】整理文档目录结构，创建5个分类文件夹，拆分业务开发指南为8个独立文档，添加README入口导航

2026-05-22 10:41:34 +08:00
parent 4139f8d392
commit e4198ddd16
13 changed files with 710 additions and 567 deletions
--- a/03_核心功能/事件系统使用指南.md
+++ b/03_核心功能/事件系统使用指南.md
@@ -0,0 +1,151 @@
+# StrayFog 框架事件系统使用指南
+
+## 一、事件系统概述
+
+事件系统分为两类：
+- **STCEvent**：Server To Client（服务器到客户端消息）
+- **CTCEvent**：Client To Client（客户端内部消息）
+
+---
+
+## 二、定义事件
+
+### 2.1 定义事件枚举和参数
+
+```csharp
+// 事件ID枚举
+public enum GameEventId
+{
+    PlayerLevelUp,
+    EnemyKilled,
+    GoldChanged
+}
+
+// 事件参数基类
+public class GameEventArgs : IHFEventArg<GameEventId>, IHFRecycle
+{
+    public GameEventId eventId { get; set; }
+    
+    public void Recycle()
+    {
+        // 重置状态
+        eventId = default;
+    }
+}
+
+// 具体事件参数
+public class PlayerLevelUpEventArgs : GameEventArgs
+{
+    public int playerId;
+    public int oldLevel;
+    public int newLevel;
+}
+```
+
+---
+
+## 三、UI窗口事件监听
+
+### 3.1 在窗口中注册CTCEvent
+
+```csharp
+[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/CardDeck/CardDeckWindow.prefab")]
+[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic, isIgnoreCloseByESC = false)]
+public class CardDeckWindow : AbsHFUIWindow
+{
+    protected override void OnOpen(Action _onOpenComplete)
+    {
+        base.OnOpen(_onOpenComplete);
+        // 注册客户端内部消息监听（CTCEvent）
+        HFFunCatalogue.Event.CTCEvent.AddListener<HFEvent_CTC_CardUpdate>(enHFCTCEvent.CardUpdate, OnCardUpdate);
+    }
+
+    protected override void OnClose(Action _onCloseComplete)
+    {
+        base.OnClose(_onCloseComplete);
+        // 取消客户端内部消息监听
+        HFFunCatalogue.Event.CTCEvent.RemoveListener<HFEvent_CTC_CardUpdate>(enHFCTCEvent.CardUpdate, OnCardUpdate);
+    }
+
+    void OnCardUpdate(HFEventArgBase arg)
+    {
+        HFEvent_CTC_CardUpdate cardArg = arg as HFEvent_CTC_CardUpdate;
+        // 更新卡组UI显示
+    }
+}
+```
+
+> **注意**：UI窗口中**不监听服务器事件（STCEvent）**，服务器事件应在Logic层的Manager中监听。
+
+---
+
+## 四、Manager事件监听
+
+### 4.1 使用AbsHFSingleMonoBehaviour（需要Update）
+
+```csharp
+public class PlayerManager : AbsHFSingleMonoBehaviour<PlayerManager>
+{
+    protected override int[] simulateBehaviourEvents => new int[] 
+    { 
+        enHFSimulateBehaviourEvent.Mono_Update, 
+        enHFSimulateBehaviourEvent.Mono_FixedUpdate 
+    };
+
+    protected override void OnAfterCreateInstance()
+    {
+        base.OnAfterCreateInstance();
+        RegisterServerEvents();
+    }
+
+    void RegisterServerEvents()
+    {
+        HFFunCatalogue.Event.STCEvent.AddListener<HFEvent_STC_PlayerInfo>(enHFSTCEvent.PlayerInfo, OnPlayerInfo);
+    }
+
+    void OnPlayerInfo(HFEventArgBase arg)
+    {
+        HFEvent_STC_PlayerInfo info = arg as HFEvent_STC_PlayerInfo;
+        // 处理服务器返回的玩家信息
+        // 触发客户端事件通知UI更新
+        HFEvent_CTC_PlayerLevelUp evt = HFFunCatalogue.New<HFEvent_CTC_PlayerLevelUp>();
+        evt.playerId = info.playerId;
+        evt.newLevel = info.level;
+        HFFunCatalogue.Event.CTCEvent.Dispatch(evt);
+    }
+}
+```
+
+### 4.2 使用AbsHFSingleRunTime（纯逻辑）
+
+```csharp
+public class ConfigManager : AbsHFSingleRunTime<ConfigManager>
+{
+    protected override void OnAfterCreateInstance()
+    {
+        base.OnAfterCreateInstance();
+        // 加载配置表
+        LoadConfigTables();
+    }
+
+    void LoadConfigTables()
+    {
+        // 加载配置数据
+    }
+}
+```
+
+---
+
+## 五、Manager类型对比
+
+| 类型 | 说明 | 适用场景 |
+|-----|------|---------|
+| `AbsHFSingleMonoBehaviour` | 生成GameObject，可注册MonoBehaviour事件 | 需要Update/FixedUpdate等生命周期 |
+| `AbsHFSingleRunTime` | 纯内存单例，无GameObject | 不需要生命周期事件 |
+
+---
+
+**版本**: v1.0  
+**生效日期**: 2026年  
+**适用范围**: GiftGameX项目业务开发人员
--- a/03_核心功能/对象池使用指南.md
+++ b/03_核心功能/对象池使用指南.md
@@ -0,0 +1,101 @@
+# StrayFog 框架对象池使用指南
+
+## 一、GameObject对象池
+
+### 1.1 基本用法
+
+```csharp
+public class BulletManager : MonoBehaviour
+{
+    [SerializeField] private GameObject bulletPrefab;
+    private HFObjectMemPool m_BulletPool;
+    
+    void Awake()
+    {
+        // 创建对象池
+        m_BulletPool = new HFObjectMemPool(bulletPrefab, transform);
+    }
+    
+    public void Fire(Vector3 position, Quaternion rotation)
+    {
+        bool isNew;
+        GameObject bullet = m_BulletPool.GetItem(out isNew);
+        
+        bullet.transform.position = position;
+        bullet.transform.rotation = rotation;
+        
+        // 如果是新创建的对象，初始化组件
+        if (isNew)
+        {
+            bullet.GetComponent<BulletComponent>().Initialize();
+        }
+    }
+    
+    public void RecycleBullet(GameObject bullet)
+    {
+        m_BulletPool.GiveBack(bullet);
+    }
+    
+    void OnDestroy()
+    {
+        // 清理对象池
+        m_BulletPool.Recycle();
+    }
+}
+```
+
+---
+
+## 二、脚本对象池
+
+### 2.1 基本用法
+
+```csharp
+public class EventArgPool : MonoBehaviour
+{
+    private HFScriptMemPool<GameEventArgs> m_ArgPool;
+    
+    void Awake()
+    {
+        m_ArgPool = new HFScriptMemPool<GameEventArgs>();
+    }
+    
+    public GameEventArgs GetEventArgs(GameEventId eventId)
+    {
+        bool isNew;
+        GameEventArgs arg = m_ArgPool.GetItem(out isNew);
+        arg.eventId = eventId;
+        return arg;
+    }
+    
+    public void RecycleEventArgs(GameEventArgs arg)
+    {
+        m_ArgPool.GiveBack(arg);
+    }
+}
+```
+
+---
+
+## 三、使用注意事项
+
+### 3.1 对象池设计特点
+
+| 特性 | 说明 |
+|-----|-----|
+| **双池结构** | 空闲池 + 使用池，高效管理对象状态 |
+| **内存泄漏检测** | 归还时校验来源，及时发现问题 |
+| **泛型支持** | `HFScriptMemPool<T>` 提供类型安全 |
+| **Mono支持** | 自动创建GameObject，无缝集成Unity |
+
+### 3.2 性能优化建议
+
+- 频繁创建销毁的对象必须使用对象池
+- 合理设置对象池初始容量
+- 定期清理空闲对象避免内存泄漏
+
+---
+
+**版本**: v1.0  
+**生效日期**: 2026年  
+**适用范围**: GiftGameX项目业务开发人员
--- a/03_核心功能/相机系统使用指南.md
+++ b/03_核心功能/相机系统使用指南.md
@@ -0,0 +1,86 @@
+# StrayFog 框架相机系统使用指南
+
+## 一、创建自定义相机
+
+### 1.1 继承AbsHFCameraItem
+
+```csharp
+public class UIOverlayCamera : AbsHFCameraItem
+{
+    [SerializeField] private Camera uiCamera;
+    [SerializeField] private int weight = 10;
+    
+    public override Camera CameraItem => uiCamera;
+    public override int Weight => weight;
+    
+    protected override void OnInitialize()
+    {
+        base.OnInitialize();
+        // 自定义初始化逻辑
+        uiCamera.clearFlags = CameraClearFlags.Depth;
+        uiCamera.depth = 100;
+    }
+}
+```
+
+---
+
+## 二、管理相机堆栈
+
+### 2.1 使用相机管理器
+
+```csharp
+public class CameraController : MonoBehaviour
+{
+    void Start()
+    {
+        // 获取相机管理器
+        HFCameraManager cameraMgr = HFCameraManager.Instance;
+        
+        // 添加自定义相机
+        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
+        cameraMgr.AddCamera(uiCamera);
+        
+        // 获取主相机
+        Camera mainCam = cameraMgr.mainCamera.MainCamera;
+    }
+    
+    void OnDestroy()
+    {
+        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
+        HFCameraManager.Instance.RemoveCamera(uiCamera);
+    }
+}
+```
+
+### 2.2 相机堆栈架构
+
+```
+相机层级架构:
+HFMainCamera (主相机)
+    │
+    ├── CameraStack (相机堆栈)
+    │       ├── CameraItem1 (Weight=10)
+    │       ├── CameraItem2 (Weight=20)
+    │       └── CameraItem3 (Weight=5)
+    │
+    └── 按Weight排序 → 渲染顺序控制
+```
+
+---
+
+## 三、相机管理API
+
+### 3.1 常用方法
+
+| 方法 | 说明 |
+|-----|------|
+| `AddCamera()` | 添加相机到堆栈 |
+| `RemoveCamera()` | 从堆栈移除相机 |
+| `GetCamera()` | 获取指定相机 |
+
+---
+
+**版本**: v1.0  
+**生效日期**: 2026年  
+**适用范围**: GiftGameX项目业务开发人员
--- a/03_核心功能/资源管理使用指南.md
+++ b/03_核心功能/资源管理使用指南.md
@@ -0,0 +1,86 @@
+# StrayFog 框架资源管理使用指南
+
+## 一、AssetBundle资源加载
+
+### 1.1 加载资源示例
+
+```csharp
+public class ResourceLoader : MonoBehaviour
+{
+    public void LoadPlayerModel(int resId, Action<GameObject> onLoaded)
+    {
+        // 通过HFFunCatalogue统一入口加载资源
+        // resId: 从Res配置表中读取的资源ID
+        HFFunCatalogue.Asset.LoadAsset(resId, (res, obj) => 
+        {
+            if (obj != null)
+            {
+                GameObject model = res.GetAsset<GameObject>();
+                onLoaded?.Invoke(model);
+            }
+            else
+            {
+                Debug.LogError($"加载失败: resId={resId}");
+            }
+        });
+    }
+}
+```
+
+### 1.2 实体资源加载示例
+
+```csharp
+// 在Entity中加载资源
+HFFunCatalogue.Asset.LoadAsset(data.EntityRes.Id, (res, obj) => {
+    if (!entity.isDeath)
+    {
+        var Boddy = res.GetAsset<GameObject>();
+        data.SetBoddy(Boddy);
+    }
+});
+```
+
+---
+
+## 二、资源管理API
+
+### 2.1 常用方法
+
+| 类别 | 管理器 | 常用方法 |
+|-----|-------|---------|
+| **资源** | `HFABMgr` | `LoadAsset()`, `OnStartLoad()` |
+
+### 2.2 资源加载流程
+
+```
+资源加载流程:
+OnStartLoad(request)
+    │
+    ▼
+检查缓存 → 获取/创建 HFAssetLoader
+    │
+    ▼
+loader.AddRequest(request)
+    │
+    ▼
+loader.LoadAsset() → 异步加载
+    │
+    ▼
+加载完成 → 回调处理
+```
+
+---
+
+## 三、资源管理注意事项
+
+### 3.1 性能优化建议
+
+- 及时释放不再使用的资源
+- 使用异步加载避免卡顿
+- 合理使用资源缓存
+
+---
+
+**版本**: v1.0  
+**生效日期**: 2026年  
+**适用范围**: GiftGameX项目业务开发人员