From 0c4a4b53ed18aaf84292f1ac8a285d15bf5bccfa Mon Sep 17 00:00:00 2001 From: Shiliang Date: Fri, 29 May 2026 15:01:50 +0800 Subject: [PATCH] =?UTF-8?q?=E3=80=90=E6=96=B0=E5=A2=9E=E3=80=91=E5=88=9B?= =?UTF-8?q?=E5=BB=BAEntity=E6=96=87=E4=BB=B6=E5=A4=B9=E5=8F=8AEntity?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97=E6=96=87=E6=A1=A3=EF=BC=8C?= =?UTF-8?q?=E5=8C=85=E5=90=ABEntity=E5=88=86=E7=B1=BB=E3=80=81=E5=88=9B?= =?UTF-8?q?=E5=BB=BA=E8=A7=84=E8=8C=83=E3=80=81=E7=94=9F=E5=91=BD=E5=91=A8?= =?UTF-8?q?=E6=9C=9F=E3=80=81System-Model=E6=9E=B6=E6=9E=84=E3=80=81?= =?UTF-8?q?=E5=B1=9E=E6=80=A7=E7=B3=BB=E7=BB=9F=E3=80=81=E5=AF=B9=E8=B1=A1?= =?UTF-8?q?=E6=B1=A0=E7=AD=89=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 03_核心功能/Entity/Entity开发指南.md | 322 +++++++++++++++++++++++++++ README.md | 3 + 2 files changed, 325 insertions(+) create mode 100644 03_核心功能/Entity/Entity开发指南.md diff --git a/03_核心功能/Entity/Entity开发指南.md b/03_核心功能/Entity/Entity开发指南.md new file mode 100644 index 0000000..def6392 --- /dev/null +++ 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(); + AddSystem(); + AddSystem(); + AddSystem(); + } + + 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(onlyid, entityId, + () => HFClassEntityManager.Instance.GetClassEntity(), + (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(); // 属性系统 + AddSystem(); // 动画系统 + AddSystem(); // 寻路移动系统 + AddSystem(); // 技能系统 + } +} +``` + +### 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(); + +// 通过System对象获取Model +HFSkillSystem skillSystem = ...; +HFSkillModel skillModel = GetModel(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 SelectByResId(int resid) { ... } + + // 删除Entity + public virtual bool DelEntityByOnlyid(long onlyid) { ... } + + // 获取所有Entity + public List GetAllEntities() { ... } +} +``` + +### 6.2 使用示例 + +```csharp +// 创建Entity +HFEntityPool.Instance.CreateEntity( + onlyid: 1001, + entityId: 10001, + func: () => HFClassEntityManager.Instance.GetClassEntity(), + 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()` 延迟初始化系统 +- 属性变更通过 `ChangeAbility()` 通知所有Model +- 死亡Entity通过 `OnDeathFinish()` 回调回收 + +--- + +**版本**: v1.1 +**生效日期**: 2026年 +**适用范围**: StrayFog框架开发人员 \ No newline at end of file diff --git a/README.md b/README.md index 026bf81..82bcd28 100644 --- 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) - 界面模块化设计、布局规划、模块组装