322 lines
9.1 KiB
Markdown
322 lines
9.1 KiB
Markdown
# 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框架开发人员 |