UnityAI/modules/frameworks/实体系统/注意事项.md

实体系统开发注意事项和最佳实践

1. 枚举定义相关

enHFCTCEvent 枚举

• 新增项：Custom = 281 - 用于自定义事件
• 用途：在 HFEvent_OnDamage 等自定义事件中使用
• 注意：添加新事件时，确保数值不与其他事件冲突

enEntityLayer 枚举

• 现有项：None=0, Role, Monster, Max
• 注意：没有 Enemy 项，敌人应归类为 Monster

2. 实体-系统-模型 (ESM) 架构相关

HFAbsEntity 访问方式

• Transform 访问：使用 entity.gameObject.transform.position 而不是 entity.transform.position
• 属性访问：使用公共属性如 entity.NormalATK 而不是私有字段 entity.m_NormalATK
• 系统获取：HFAbsEntity 没有 GetSystem<T>() 方法，只有 GetModel<T>() 方法
• 模型获取：通过 entity.GetModel<T>() 获取模型实例

系统间通信

• 推荐方式：通过事件系统进行通信，而不是直接获取其他系统
• 事件分发：使用 event.Dispatch() 而不是 HFFunCatalogue.Event.TCEvent.SendEvent()

3. 数据表字段映射

Role 表字段

• Lifefold -> 生命值
• Attackfold -> 攻击力
• Defensefold -> 防御力
• AttackRange -> 攻击范围
• CriticalRate -> 暴击率
• CriticalDamage -> 暴击伤害
• 注意：Role 表中没有速度字段 (SPD)

4. 动画系统相关

FSM (有限状态机) 系统

• HFFMSModel 现在包含 CurrentSkeletonAnimation 属性
• 访问方式：通过 FSM.CurrentSkeletonAnimation 访问 SkeletonAnimation
• 动画速度设置：使用 skeletonAnimation.timeScale = speed

5. AI 系统相关

HFAIModel_Enemy

• 伤害处理：通过事件系统 (HFEvent_OnDamage) 而不是直接获取系统
• 攻击逻辑：创建并分发伤害事件，让其他系统处理实际伤害计算

6. 错误处理和调试

常见错误类型

• CS0117: 枚举中不包含指定定义 - 检查枚举项是否存在
• CS1061: 类型不包含指定定义 - 检查属性/方法名是否正确
• CS0122: 成员因保护级别不可访问 - 使用公共 API 而不是私有字段

修复策略

• 优先使用公共属性而不是私有字段
• 通过事件系统进行组件间通信
• 正确访问 GameObject 的 Transform 组件
• 使用正确的枚举值

7. 架构模式

系统-模型 (System-Model) 模式

• AbsHFMoveSystem 需要指定泛型参数
• AbsHFAIModel 不能直接获取系统，应通过事件或模型进行通信
• AbsHFAnimationModel 需要配合 AbsHFFMSModel 使用

事件驱动架构

• 自定义事件需继承 AbsHFEventArg<enHFCTCEvent>
• 事件 ID 使用 enHFCTCEvent.Custom 或其他预定义事件
• 事件分发使用 Dispatch() 方法

---

文档关联

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

文档	关联原因
实体系统入口	本文件是实体系统模块的子文档
Entity 开发指南	与开发指南中的 System-Model、属性系统互补
事件系统	自定义事件派发相关
modules/模块索引.md	模块索引是项目知识总入口
rules/10-架构说明.md	架构说明定义总体分层和依赖方向
rules/20-开发规则.md	公共 API 访问方式与开发规则互相引用
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径