【新增】创建Entity文件夹及Entity开发指南文档，包含Entity分类、创建规范、生命周期、System-Model架构、属性系统、对象池等内容

2026-05-29 15:01:50 +08:00
parent da3f24b086
commit 0c4a4b53ed
2 changed files with 325 additions and 0 deletions
--- a/03_核心功能/Entity/Entity开发指南.md
+++ b/03_核心功能/Entity/Entity开发指南.md
@@ -0,0 +1,322 @@
+# StrayFog 框架 Entity开发指南
+
+## 一、Entity概述
+
+Entity是游戏世界中所有游戏对象的抽象基类，包括玩家、敌人、塔楼、城堡等。Entity系统提供统一的对象管理、生命周期控制和**System-Model架构**。
+
+### 1.1 Entity分类
+
+Entity分类根据具体业务需求定义，以下为示例分类（项目实际分类以业务为准）：
+
+| 类别 | 说明 | 示例 |
+|-----|------|------|
+| **Human** | 具有生命、移动能力的实体 | Player、Enemy |
+| **Tower** | 防御塔实体 | 箭塔、炮塔 |
+| **Castle** | 城堡/基地实体 | 玩家基地 |
+| **Obstacle** | 障碍物实体 | 墙壁、陷阱 |
+
+> **说明**：实际项目中需根据业务需求定义Entity类型，继承`HFAbsEntity`基类并实现对应逻辑。
+
+### 1.2 核心数据结构
+
+```csharp
+// Entity唯一标识
+public long onlyid { get; }      // 运行时唯一ID
+public int EntityId { get; }     // 资源配置ID
+public enEntityLayer entityType { get; }  // Entity类型
+public enEntityCamp entityCamp { get; }   // 阵营
+public bool isDeath { get; }     // 是否死亡
+```
+
+---
+
+## 二、Entity创建规范
+
+### 2.1 继承结构
+
+```csharp
+// 核心基类
+public abstract partial class HFAbsEntity : AbsHFSimulateBehaviour
+{
+    public long onlyid { get; private set; }
+    public enEntityLayer entityType { get; private set; }
+    public enEntityCamp entityCamp { get; private set; }
+    public int EntityId { get; private set; }
+    public bool isDeath { get; private set; }  // 逻辑死亡标记
+    
+    // 初始化方法
+    public void Init() { ... }
+    public virtual void OnInit() { ... }
+    
+    // 死亡方法（表现层）
+    public void Death() { ... }           // 触发死亡事件
+    public virtual void OnDeath() { ... } // 子类重写处理表现死亡逻辑
+    
+    // 逻辑死亡（数据层）
+    protected void Logic_Death() { ... }        // 设置isDeath=true，数据层死亡
+    protected virtual void OnLogicDeath() { ... } // 子类重写处理逻辑死亡逻辑
+}
+
+// 具体Entity示例 - Human类型
+public class HFEntity_Human : HFAbsEntity
+{
+    protected override void OnRunAwake()
+    {
+        base.OnRunAwake();
+        AddSystem<HFFeatureSystem>();
+        AddSystem<HFAnimationSystem_Human>();
+        AddSystem<HFApathMoveSystem>();
+        AddSystem<HFSkillSystem>();
+    }
+    
+    public override void OnInit()
+    {
+        // 初始化配置数据
+    }
+    
+    public override void OnDeath()
+    {
+        // 死亡处理逻辑
+    }
+}
+```
+
+### 2.2 命名规范
+
+| 类型 | 命名规则 | 示例 |
+|-----|---------|------|
+| Entity类 | `HFEntity_{TypeName}` | `HFEntity_Human`、`HFEntity_Tower` |
+| 系统类 | `HF{SystemName}System[_TypeName]` | `HFAnimationSystem_Human` |
+| 模型类 | `HF{ModelName}Model[_TypeName]` | `HFAnimationModel_Human` |
+| 数据结构 | `st{DataName}` | `stAbilityData`、`stDamageInfo` |
+
+---
+
+## 三、Entity生命周期
+
+### 3.1 生命周期方法
+
+| 方法 | 调用时机 | 职责 | 层级 |
+|-----|---------|------|-----|
+| `OnRunAwake()` | 对象创建时 | 添加System组件 | 表现层 |
+| `Init()` | 初始化时调用 | 重置死亡状态、调用OnInit | - |
+| `OnInit()` | Init内部调用 | 子类重写，初始化配置数据 | 数据层 |
+| `Logic_Death()` | HP归零时调用 | 设置`isDeath=true`，调用OnLogicDeath | 数据层 |
+| `OnLogicDeath()` | Logic_Death内部调用 | 子类重写处理逻辑死亡逻辑 | 数据层 |
+| `Death()` | 逻辑死亡后调用 | 触发死亡事件、调用OnDeath | 表现层 |
+| `OnDeath()` | Death内部调用 | 子类重写，处理表现死亡逻辑（动画、特效等） | 表现层 |
+| `OnRecycle()` | 对象回收时 | 清理资源、释放引用 | - |
+
+> **重要区分**：
+> - **逻辑死亡**：`Logic_Death()` 由伤害计算触发，设置`isDeath=true`，仅影响数据层
+> - **表现死亡**：`Death()` 在逻辑死亡后调用，触发死亡事件和表现效果（动画、音效等）
+
+### 3.2 创建流程
+
+```csharp
+// 1. 对象池创建Entity
+HFEntityPool.Instance.CreateEntity<HFEntity_Human>(onlyid, entityId, 
+    () => HFClassEntityManager.Instance.GetClassEntity<HFEntity_Human>(),
+    (entity) => {
+        // 设置阵营
+        entity.SetEntityCamp(enEntityCamp.Player);
+        // 初始化
+        entity.Init();
+    });
+```
+
+---
+
+## 四、System-Model架构
+
+### 4.1 架构设计
+
+Entity采用**System-Model分离架构**：
+
+- **System层**：处理表现逻辑（Update、状态转换）
+- **Model层**：处理数据逻辑（数据存储、计算）
+
+### 4.2 添加系统
+
+```csharp
+public class HFEntity_Human : HFAbsEntity
+{
+    protected override void OnRunAwake()
+    {
+        base.OnRunAwake();
+        
+        // 添加系统（按执行顺序）
+        AddSystem<HFFeatureSystem>();      // 属性系统
+        AddSystem<HFAnimationSystem_Human>(); // 动画系统
+        AddSystem<HFApathMoveSystem>();    // 寻路移动系统
+        AddSystem<HFSkillSystem>();        // 技能系统
+    }
+}
+```
+
+### 4.3 常用系统
+
+| 系统 | 职责 | 适用Entity |
+|-----|------|-----------|
+| `HFFeatureSystem` | 属性管理 | 所有Entity |
+| `HFAnimationSystem` | 动画控制 | Human、Tower |
+| `HFMoveSystem` | 移动控制 | Human |
+| `HFAISystem` | AI行为 | Enemy、Tower |
+| `HFSkillSystem` | 技能系统 | Human、Tower |
+
+### 4.4 获取Model
+
+```csharp
+// 通过System类型获取Model
+HFAnimationModel_Human animModel = GetModel<HFAnimationModel_Human>();
+
+// 通过System对象获取Model
+HFSkillSystem skillSystem = ...;
+HFSkillModel skillModel = GetModel<HFSkillModel>(skillSystem);
+```
+
+---
+
+## 五、属性系统
+
+### 5.1 属性分类
+
+| 属性类型 | 说明 | 示例 |
+|---------|------|------|
+| **基础属性** | 配置表读取，基础值 | HP、SPD、MoveSpeed |
+| **战斗属性** | 实际战斗中使用，受Buff影响 | Fight_SPD、Fight_ATK |
+
+### 5.2 属性数据结构
+
+```csharp
+public partial class HFAbsEntity
+{
+    // 基础属性（配置表）
+    private float m_Hp;
+    private float m_MaxHp;
+    private float m_SPD;
+    private float m_MoveSpeed;
+    private float m_NormalATK;
+    private float m_Critical;
+    private float m_CriticalDamage;
+    
+    // 战斗属性（实时计算）
+    private float m_Fight_SPD;
+    private float m_Fight_NormalATK;
+    // ...
+}
+```
+
+### 5.3 属性变更
+
+```csharp
+// 临时属性变更（Buff）
+public void ChangeData(stAbilityData data)
+{
+    if (data.IsPermanent)
+    {
+        // 永久属性变更
+        switch (data.ChangeTarget)
+        {
+            case enEntitityAbility.SPD:
+                m_SPD += data.Value;
+                break;
+            case enEntitityAbility.NormalATK:
+                m_NormalATK += data.Value;
+                break;
+        }
+    }
+    else
+    {
+        // 临时属性变更（存入Buff字典）
+        OnAddEntityAbilityData(data);
+    }
+    
+    // 刷新战斗属性
+    OnRefushEntityAbility(data.ChangeTarget);
+    // 通知所有Model属性变更
+    ChangeAbility(data.ChangeTarget);
+}
+```
+
+---
+
+## 六、Entity对象池
+
+### 6.1 对象池职责
+
+```csharp
+public abstract partial class AbsHFEntityPool : IHFObject
+{
+    public abstract enEntityLayer entityType { get; }
+    
+    // 根据onlyid获取Entity
+    public virtual HFAbsEntity SelectByOnlyid(long onlyid) { ... }
+    
+    // 根据资源ID获取所有Entity
+    public List<HFAbsEntity> SelectByResId(int resid) { ... }
+    
+    // 删除Entity
+    public virtual bool DelEntityByOnlyid(long onlyid) { ... }
+    
+    // 获取所有Entity
+    public List<HFAbsEntity> GetAllEntities() { ... }
+}
+```
+
+### 6.2 使用示例
+
+```csharp
+// 创建Entity
+HFEntityPool.Instance.CreateEntity<HFEntity_Human>(
+    onlyid: 1001,
+    entityId: 10001,
+    func: () => HFClassEntityManager.Instance.GetClassEntity<HFEntity_Human>(),
+    action: (entity) => {
+        entity.SetEntityCamp(enEntityCamp.Player);
+        entity.Init();
+    });
+
+// 获取Entity
+HFAbsEntity entity = HFEntityPool.Instance.SelectByOnlyid(1001);
+HFEntity_Human human = entity as HFEntity_Human;
+
+// 删除Entity
+HFEntityPool.Instance.DelEntityByOnlyid(1001);
+```
+
+---
+
+## 七、开发规范
+
+### 7.1 文件路径
+
+| 类型 | 路径 |
+|-----|------|
+| Entity基类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/AbsEntity/` |
+| 具体Entity | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/EntityTag/` |
+| 系统类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/System/` |
+| 模型类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/Model/` |
+| 对象池 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/EntityPool/` |
+
+### 7.2 编码规范
+
+1. **必须继承** `HFAbsEntity` 基类
+2. **必须在** `OnRunAwake()` 中添加所需System
+3. **必须重写** `OnInit()` 初始化配置数据
+4. **必须重写** `OnDeath()` 处理死亡逻辑
+5. **禁止**在Entity中直接访问Manager，通过`HFFunCatalogue`访问
+6. **禁止**在Entity中持有场景引用
+
+### 7.3 性能优化
+
+- 使用对象池复用Entity实例
+- 使用 `AddSystem<T>()` 延迟初始化系统
+- 属性变更通过 `ChangeAbility()` 通知所有Model
+- 死亡Entity通过 `OnDeathFinish()` 回调回收
+
+---
+
+**版本**: v1.1  
+**生效日期**: 2026年  
+**适用范围**: StrayFog框架开发人员
--- a/README.md
+++ b/README.md
@@ -14,6 +14,9 @@
 - [资源管理使用指南](03_核心功能/资源管理使用指南.md)
 - [相机系统使用指南](03_核心功能/相机系统使用指南.md)

+#### Entity相关
+- [Entity开发指南](03_核心功能/Entity/Entity开发指南.md) - Entity创建规范、生命周期、System-Model架构、属性系统、对象池
+
 #### UI相关
 - [UI开发指南](03_核心功能/UI/UI开发指南.md) - 窗口开发、组件使用、事件绑定、对象池、开发规范
 - [UI界面拼接设计指南](03_核心功能/UI/UI界面拼接设计指南.md) - 界面模块化设计、布局规划、模块组装