lms
d3312e19cf
- 实体系统注意事项标题避免与 Unity DOTS ECS 混淆 - 70-项目设置.md 重命名为 70-AI工具扫描范围.md - 更新 00-项目概览/项目规则入口/README 中的链接文字 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# 实体系统开发注意事项和最佳实践
|
||
|
||
## 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<T>** 需要指定泛型参数
|
||
- **AbsHFAIModel** 不能直接获取系统，应通过事件或模型进行通信
|
||
- **AbsHFAnimationModel** 需要配合 `AbsHFFMSModel` 使用
|
||
|
||
### 事件驱动架构
|
||
- 自定义事件需继承 `AbsHFEventArg<enHFCTCEvent>`
|
||
- 事件 ID 使用 `enHFCTCEvent.Custom` 或其他预定义事件
|
||
- 事件分发使用 `Dispatch()` 方法
|
||
|
||
---
|
||
|
||
## 文档关联
|
||
|
||
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
|
||
|
||
| 文档 | 关联原因 |
|
||
|---|---|
|
||
| [实体系统入口](README.md) | 本文件是实体系统模块的子文档 |
|
||
| [Entity 开发指南](开发指南.md) | 与开发指南中的 System-Model、属性系统互补 |
|
||
| [事件系统](../事件系统/README.md) | 自定义事件派发相关 |
|
||
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
|
||
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
|
||
| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 公共 API 访问方式与开发规则互相引用 |
|
||
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
|