160 lines
7.7 KiB
Markdown
160 lines
7.7 KiB
Markdown
# Simulation Development Skill（VampireLike）
|
||
|
||
## 目标
|
||
本文件是 `Simulation` 分层的开发规范与速查手册。
|
||
后续调整敌人移动、补齐投射物/掉落物逻辑、推进 Job/Burst 改造时，优先按本文档执行，避免反复通读全部代码。
|
||
|
||
## 当前架构总览（P1.5 已落地）
|
||
- Simulation 主目录：`Assets/GameMain/Scripts/Simulation/`
|
||
- 核心组件：`SimulationWorld`（`GameFrameworkComponent`）
|
||
- 数据容器：
|
||
- `List<EnemySimData> _enemies`
|
||
- `List<ProjectileSimData> _projectiles`
|
||
- `List<PickupSimData> _pickups`
|
||
- Tick 临时缓冲：
|
||
- `List<EnemyTickWorkItem> _enemyTickWorkItems`
|
||
- `List<EnemySeparationAgent> _enemySeparationAgents`
|
||
- 索引绑定：`EntityBinding`（`EntityId <-> SimulationIndex` 双向映射）
|
||
- 生命周期同步：`SimulationWorld.EntitySync`（监听实体 Show/Hide 事件）
|
||
- 表现层回写：`SimulationWorld.Presentation`（`LateUpdate` 写回 `Transform`）
|
||
- Tick 上下文：`SimulationTickContext`（`DeltaTime`、`RealDeltaTime`、`PlayerPosition`）
|
||
|
||
## 运行时主链路（按帧）
|
||
1. `GameEntry.InitCustomComponents()` 获取或自动挂载 `SimulationWorld`
|
||
文件：`Assets/GameMain/Scripts/Base/GameEntry.Custom.cs`
|
||
2. `ProcedureGame.OnEnter()` 清理旧 Simulation 数据
|
||
文件：`Assets/GameMain/Scripts/Procedure/Game/ProcedureGame.cs`
|
||
3. `GameStateBattle.OnUpdate()` 中先执行刷怪，再执行 `SimulationWorld.Tick(...)`
|
||
文件：`Assets/GameMain/Scripts/Procedure/Game/GameStateBattle.cs`
|
||
4. `SimulationWorld.Tick()` 仅在 `UseSimulationMovement == true` 时执行敌人 Tick
|
||
5. `SimulationWorld.LateUpdate()` 执行 `Presentation.OnLateUpdate()`，将仿真结果写回敌人 `Transform`
|
||
|
||
## 生命周期与数据同步设计
|
||
`EntitySync` 通过事件驱动保持 Simulation 容器与实体生命周期一致：
|
||
|
||
| 事件 | 组名 | 行为 |
|
||
|-------------------------------|-------------------------|----------------------------------------------------------------|
|
||
| `ShowEntitySuccessEventArgs` | `Enemy` | `RegisterEnemyLifecycle` + `UpsertEnemy` |
|
||
| `HideEntityCompleteEventArgs` | `Enemy` | `UnregisterEnemyLifecycle` + `RemoveEnemyByEntityId` |
|
||
| `ShowEntitySuccessEventArgs` | `Drop` | `RegisterPickupLifecycle` + `UpsertPickup` |
|
||
| `HideEntityCompleteEventArgs` | `Drop` | `UnregisterPickupLifecycle` + `RemovePickupByEntityId` |
|
||
| `ShowEntitySuccessEventArgs` | `Bullet` / `Projectile` | `RegisterProjectileLifecycle` + `UpsertProjectile` |
|
||
| `HideEntityCompleteEventArgs` | `Bullet` / `Projectile` | `UnregisterProjectileLifecycle` + `RemoveProjectileByEntityId` |
|
||
|
||
关键规则：
|
||
- 删除容器元素统一使用“末尾覆盖 + `RemoveAt(lastIndex)` + `EntityBinding.RemapIndex`”。
|
||
- `Upsert` 语义：`EntityId` 已存在则覆盖，不存在则追加。
|
||
|
||
## EnemySimData 合约（当前实现）
|
||
文件：`Assets/GameMain/Scripts/Simulation/SimData/EnemySimData.cs`
|
||
|
||
- `EntityId`：实体唯一标识
|
||
- `Position / Forward / Rotation`：逻辑输出与表现层写回字段
|
||
- `Speed`：来自 `EnemyData.SpeedBase`
|
||
- `AttackRange`：当前固定初始化为 `1f`
|
||
- `AvoidEnemyOverlap / EnemyBodyRadius / SeparationIterations`：从 `MovementComponent` 读取
|
||
- `TargetType / State`：状态扩展预留
|
||
|
||
当前状态值（`SimulationWorld` 常量）：
|
||
- `0`：Idle
|
||
- `1`：Chasing
|
||
- `2`：InAttackRange
|
||
|
||
## TickEnemies 当前算法（P1.5 分阶段）
|
||
文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.cs`
|
||
|
||
`TickEnemies` 入口保持纯数据热路径，不直接读写 `Transform`，按四阶段执行：
|
||
1. `BuildInput`
|
||
- 计算到玩家平面距离
|
||
- 产出 `EnemyTickWorkItem`
|
||
- 生成分离输入 `EnemySeparationAgent`
|
||
2. `Move/Separation`
|
||
- 计算追踪位移与朝向
|
||
- 通过 `EnemySeparationSolverProvider.ResolveSimulation(...)` 做互斥求解
|
||
3. `StateUpdate`
|
||
- 按距离与可追逐状态更新 `Idle/Chasing/InAttackRange`
|
||
4. `WriteBack`
|
||
- 回写 `EnemySimData`（`Position/Forward/Rotation/State`）
|
||
|
||
## 互斥求解器双通道（Legacy + Simulation）
|
||
文件：
|
||
- `Assets/GameMain/Scripts/Utility/EnemySeperator/IEnemySeparationSolver.cs`
|
||
- `Assets/GameMain/Scripts/Utility/EnemySeperator/EnemySeparationSolverProvider.cs`
|
||
- `Assets/GameMain/Scripts/Utility/EnemySeperator/GridBucketEnemySeparationSolver.cs`
|
||
|
||
说明：
|
||
- `SetSimulationAgents/ResolveSimulation`：供 Simulation 纯数据路径调用。
|
||
- `Register/Unregister/Resolve(Transform, ...)`：保留旧路径兼容与回滚能力。
|
||
- `GridBucketEnemySeparationSolver` 已加入桶列表复用池（`_bucketListPool`）以降低 GC。
|
||
|
||
## 表现层回写（Presentation）规则
|
||
文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.Presentation.cs`
|
||
|
||
- 仅在 `UseSimulationMovement == true` 时执行
|
||
- 遍历 `EnemyManager.Enemies`，按 `EntityId` 查找 `EnemySimData`
|
||
- 写回顺序：
|
||
- 始终写回 `position`
|
||
- 优先使用 `rotation`
|
||
- 若 `rotation` 无效，则回退到 `forward`
|
||
|
||
## 与旧移动系统的关系（重要）
|
||
- `MeleeEnemy` / `RemoteEnemy` 在 `OnUpdate` 开头门控：
|
||
- 开启 Simulation：直接 `return`
|
||
- 关闭 Simulation：走旧 `MovementComponent`
|
||
- 回滚能力来自同一构建内的 `UseSimulationMovement` A/B 开关。
|
||
|
||
## Projectile / Pickup 现状
|
||
- `ProjectileSimData`、`PickupSimData` 已具备容器、绑定与生命周期同步通道
|
||
- 当前仍未接入独立 Tick 行为，仅完成“创建/回收/索引同步”占位目标
|
||
|
||
## P1.5 实测基线（P2 输入）
|
||
基线文档：`docs/P1.5 Simulation-Supplement.md`
|
||
|
||
关键结论：
|
||
- `TickEnemies GC` 在 `500/1000/1500/2000` 敌人数下均为 `0 KB`
|
||
- `GC Allocated In Frame` 从 P1 的 `29.5~109.7 KB` 降至 `2.1 KB`
|
||
- `TickEnemies` 热路径耗时（四阶段合计）对比 P1 降幅约 `22.8%~26.8%`
|
||
- Android 端评估以 CPU `ms` 为主，`fps` 受 60 上限影响
|
||
|
||
## 自动化回归（P1.5 已补）
|
||
目录：
|
||
- `Assets/Tests/Simulation/EditMode/SimulationWorldTickTests.cs`
|
||
- `Assets/Tests/Simulation/PlayMode/SimulationWorldPlayModeTests.cs`
|
||
|
||
覆盖点：
|
||
- 敌人追踪玩家
|
||
- 进入攻击距离后停止移动
|
||
- 实体移除后的索引 remap 稳定性
|
||
|
||
## 后续扩展规范（必须遵守）
|
||
1. 先扩数据，再扩行为
|
||
先在 `SimData` 增字段，再改 `EntitySync` 初始化与 `Tick` 逻辑，最后改表现层消费。
|
||
|
||
2. 保留 A/B 路径
|
||
任何迁移都必须可在同一构建内通过开关回退到旧路径。
|
||
|
||
3. 生命周期只走 EntitySync
|
||
禁止在敌人业务代码中手动改写 Simulation 容器，避免双写导致索引错乱。
|
||
|
||
4. 维持“逻辑输出 / 表现消费”边界
|
||
Simulation 只产出逻辑结果，不直接触发 UI、特效、音频事件。
|
||
|
||
5. 删除策略统一用 swap-back
|
||
所有 Simulation 容器删除都必须 remap 索引，严禁 `RemoveAt(i)` 直接删中间项。
|
||
|
||
6. 热路径禁用托管分配
|
||
`TickEnemies`、互斥求解、阶段化循环里禁止 LINQ/临时集合扩张。
|
||
|
||
## P2 前的已知技术债
|
||
- `AttackRange` 目前固定值 `1f`，尚未由配置化数值驱动
|
||
- `EnemySimData.TargetType/State` 语义仍偏轻量，未形成完整状态机合约
|
||
- Projectile/Pickup 尚未迁移真实 Tick 行为
|
||
|
||
## 提交前检查清单
|
||
- 是否保持了 `UseSimulationMovement` 关闭时行为不变
|
||
- 是否保持了 `EntityId <-> SimulationIndex` 一致性（含移除 remap）
|
||
- 是否避免在 Tick 热路径引入新 GC
|
||
- 是否将新字段接入了 `EntitySync -> Tick -> Presentation` 全链路
|
||
- 是否补充了最小回归验证（至少 Battle 循环、敌人移除、索引稳定性）
|
||
- 是否同步更新本 Skill 文档与 `docs/P1.5 Simulation-Supplement.md`
|