UnityAI/modules/frameworks/实体系统/开发指南.md

Entity 开发指南

一、Entity 概述

Entity 是游戏世界中所有游戏对象的抽象基类，包括玩家、敌人、塔楼、城堡等。Entity 系统提供统一的对象管理、生命周期控制和 System-Model 架构。

1.1 Entity 分类

Entity 分类根据具体业务需求定义，以下为示例分类（项目实际分类以业务为准）：

类别	说明	示例
Human	具有生命、移动能力的实体	Player、Enemy
Tower	防御塔实体	箭塔、炮塔
Castle	城堡/基地实体	玩家基地
Obstacle	障碍物实体	墙壁、陷阱

说明：实际项目中需根据业务需求定义 Entity 类型，继承 HFAbsEntity 基类并实现对应逻辑。

1.2 核心数据结构

// 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 继承结构

// 核心基类
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 创建流程

// 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 添加系统

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

// 通过 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 属性数据结构

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 属性变更

// 临时属性变更（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 对象池职责

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 使用示例

// 创建 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 框架开发人员

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
实体系统入口	本文件是实体系统模块的子文档
通用技能系统使用指南	技能系统是 Entity 常用子系统
对象池与运行时对象管理	Entity 池机制相关
事件系统	Entity 间通信常依赖事件系统
modules/模块索引.md	模块索引是项目知识总入口
rules/10-架构说明.md	架构说明定义总体分层和依赖方向
rules/20-开发规则.md	编码规范与开发规则互相引用
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径