From a649d9fad2e60240c3dcea2bfed574d4797489ee Mon Sep 17 00:00:00 2001 From: SepComet <2428390463@qq.com> Date: Thu, 2 Apr 2026 09:35:09 +0800 Subject: [PATCH] update CodeX-TODO.md --- docs/CodeX-TODO.md | 212 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) diff --git a/docs/CodeX-TODO.md b/docs/CodeX-TODO.md index 4ef1548..46b8f95 100644 --- a/docs/CodeX-TODO.md +++ b/docs/CodeX-TODO.md @@ -1,5 +1,217 @@ # CodeX TODO +## SimulationWorld 路线收敛 + +### 当前结论 + +- 当前 `SimulationWorld` 唯一还成体系的执行路径，就是现有 Burst Job 管线。 +- 这条管线已经覆盖： + - 敌人移动：`EnemyMovementBurstJob` + - 敌人分离：`BuildEnemySeparationBucketsBurstJob` + `EnemySeparationBurstJob` + - 投射物移动：`ProjectileMovementBurstJob` + - 碰撞 broad-phase：`BuildCollisionBucketsBurstJob` + `QueryCollisionCandidatesBurstJob` +- 与之并存的旧路径仍然散落在实体和组件里： + - `MovementComponent.OnUpdate()` 仍在直接推进位移 + - `EnemySeparationSolverProvider` 仍在负责旧互斥逻辑 + - `EnemyBase` / `MeleeEnemy` / `RemoteEnemy` / `EnemyProjectile` / `NearestTargetSelector` 仍在用 `UseSimulationMovement` 做双路径分支 +- 文档中的 `UseJobSimulation` / `UseBurstJobs` 当前只有说明，没有代码实现。 +- 因此当前要做的不是“抛弃 Burst 路线”，而是反过来： + - 保留 `SimulationWorld` 的 Burst 逻辑作为唯一执行路径 + - 删除所有旧组件驱动/旧 fallback 路径 + - 把组件层收敛成 `SimulationWorld` 的输入、注册和表现壳层 + +### 目标定义 + +- `SimulationWorld` 成为唯一的运行时仿真执行入口。 +- 实体自身不再计算“下一帧位置”，而是只向 `SimulationWorld` 提供输入和配置。 +- `MovementComponent` 不再直接改 `Transform`，只负责： + - 保存移动开关/方向/速度等输入态 + - 向 `SimulationWorld` 注册或同步这些输入 +- 实体表现层只消费 `SimulationWorld` 的输出结果，不再自己推进位移或互斥。 +- 删除所有“Simulation / 非 Simulation”双路径分支，避免行为在两套逻辑里分叉。 + +### 必改项 + +#### 1. Tick 主入口收敛 + +- 文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.cs` +- 处理： + - 保留 `TickSimulationPipeline(in SimulationTickContext context)` 作为唯一执行主入口 + - 删除“开关关闭后直接跳过 SimulationWorld”的旧语义 + - 重定义 `UseSimulationMovement`： + - 要么删除 + - 要么仅保留为全局停机开关，而不是双路径路由开关 +- 备注： + - `GameStateBattle.OnUpdate` 目前已经把 `SimulationWorld.Tick(...)` 放在战斗主循环里，这个方向是对的 + +#### 2. 保留并固化 Burst/Job 敌人执行面 + +- 文件：`Assets/GameMain/Scripts/Simulation/Jobs/SimulationWorld.EnemyJobs.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/EnemyMovementBurstJob.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/EnemySeparationBurstJob.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/BuildEnemySeparationBucketsBurstJob.cs` +- 处理： + - 保留 Burst Job 调度，明确这就是敌人的唯一移动/互斥路径 + - 把实体侧“追击/停下/朝向目标”的输入全部规范成写入 sim state，而不是各实体自己推动 + - 明确 `_enemies` 是敌人移动和互斥的唯一状态源 + +#### 3. 保留并固化 Burst/Job 投射物执行面 + +- 文件：`Assets/GameMain/Scripts/Simulation/Jobs/SimulationWorld.ProjectileJobs.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/ProjectileMovementBurstJob.cs` +- 处理： + - 保留投射物移动 Job，作为唯一的投射物位置推进路径 + - 删除 `EnemyProjectile.OnUpdate` 中的自驱动移动和寿命推进逻辑 + - `EnemyProjectile` 只负责 show/hide、碰撞体开关、表现同步 + +#### 4. 保留并固化 Burst/Job 碰撞 broad-phase + +- 文件：`Assets/GameMain/Scripts/Simulation/Jobs/SimulationWorld.CollisionBroadPhase.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/QueryCollisionCandidatesBurstJob.cs` +- 处理： + - 保留现有碰撞分桶和候选查询 Job + - 把 area/sector/projectile 命中统一视为 `SimulationWorld` 能力，不再给实体侧保留另一套 fallback 查询逻辑 + - 确认武器系统全部通过 `SimulationWorld` 提供的查询/结算能力工作 + +#### 5. Native 通道与 Job 数据层保留，但去掉兼容性残留 + +- 文件：`Assets/GameMain/Scripts/Simulation/DataChannel/SimulationWorld.JobDataChannel.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/DataChannel/SimulationWorld.JobDataLifecycle.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/DataChannel/SimulationWorld.JobDataConversion.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/DataChannel/SimulationWorld.JobOutputCommit.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/*` +- 处理： + - 保留 Native 通道和 sim/job 转换层 + - 清理“只为旧测试和旧双路径兼容保留”的字段与注释 + - 把 job output 回写 `_enemies/_projectiles` 明确为正式架构，而不是过渡方案 +- 备注： + - 当前 `_collisionQueryInputs` 和 `_areaCollisionRequests` 还被测试直接反射，后续需要改测试而不是继续迁就反射 + +#### 6. Presentation 回写链路收敛 + +- 文件：`Assets/GameMain/Scripts/Simulation/Presentation/SimulationWorld.TransformSync.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/Presentation/SimulationWorld.HitPresentation.cs` +- 处理： + - 保留 `TransformSync` 从 `_enemies/_projectiles` 回写实体表现 + - 删除实体自身 `OnUpdate` 中对位置和朝向的直接推进 + - 明确表现层只消费 sim 输出，不再写回 sim 逻辑状态 + +#### 7. 生命周期注册与数据容器职责重定义 + +- 文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.EntitySync.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.EntityToSimData.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.SimEntityState.cs` +- 文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.RuntimeModules.cs` +- 处理： + - 明确 `SimulationWorld` 持有 `_enemies/_projectiles/_pickups` 作为正式运行时状态 + - 补“组件输入 -> sim state”同步接口，替代实体自己推进逻辑 + - 将注册/反注册、初始数据灌入、索引维护继续收拢在 `SimulationWorld` + +#### 8. 战斗入口与 GameEntry 依赖固化 + +- 文件：`Assets/GameMain/Scripts/Procedure/Game/GameStateBattle.cs` +- 文件：`Assets/GameMain/Scripts/Procedure/Game/ProcedureGame.cs` +- 文件：`Assets/GameMain/Scripts/Base/GameEntry.Custom.cs` +- 处理： + - 保持 `SimulationWorld` 是战斗主循环核心组件 + - `ClearSimulationState()` 继续保留，但要确认只清 sim 状态，不引入双路径 reset 语义 + - `GameEntry` 自动挂载 `SimulationWorld` 是合理的，应继续保留 + +### 需要一起改的外围依赖 + +#### 9. MovementComponent 收敛为输入/注册层 + +- 文件：`Assets/GameMain/Scripts/Components/MovementComponent.cs` +- 文件：`Assets/GameMain/Scripts/Utility/EnemySeperator/EnemySeparationSolverProvider.cs` +- 处理： + - 删除 `MovementComponent.OnUpdate()` 中直接改 `Transform.position` 的逻辑 + - 删除对 `EnemySeparationSolverProvider.Resolve/Register/Unregister` 的运行时依赖 + - `MovementComponent` 仅保留： + - 速度/方向/移动开关 + - 互斥半径/迭代参数 + - 向 `SimulationWorld` 注册、反注册、同步输入 +- 备注： + - 这部分是你刚说的核心：位置计算归 `SimulationWorld`，`MovementComponent` 只负责注册和输入 + +#### 10. 实体侧双路径和自驱动移动清理 + +- 文件：`Assets/GameMain/Scripts/Entity/EntityLogic/Enemy/EnemyBase.cs` +- 文件：`Assets/GameMain/Scripts/Entity/EntityLogic/Enemy/MeleeEnemy.cs` +- 文件：`Assets/GameMain/Scripts/Entity/EntityLogic/Enemy/RemoteEnemy.cs` +- 文件：`Assets/GameMain/Scripts/Entity/EntityLogic/Enemy/EnemyProjectile.cs` +- 文件：`Assets/GameMain/Scripts/Entity/EntityLogic/Player.cs` +- 文件：`Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/TargetSelector/NearestTargetSelector.cs` +- 处理： + - 删除 `UseSimulationMovement` 分支判断 + - 删除 `MeleeEnemy` / `RemoteEnemy` 中对 `_movementComponent.OnUpdate()` 的调用 + - 删除 `Player` 中通过 `MovementComponent.OnUpdate()` 推进玩家位置的逻辑，改为只提交输入方向 + - 删除 `EnemyProjectile` 中“Simulation 驱动 or 自驱动”双模式 + - `NearestTargetSelector` 直接依赖 `SimulationWorld` 空间索引，不再 fallback 到遍历分支 + +#### 11. Debug 面板与旧互斥调试项清理 + +- 文件：`Assets/GameMain/Scripts/CustomComponent/DebugPanel/RuntimeDebugPanelComponent.cs` +- 处理： + - 保留 `SimulationWorld` 的碰撞和 broad-phase 指标 + - 删除 `EnemySeparationSolverProvider` 的旧 solver 切换 UI 和相关文案 + - 面板上不再出现“双路径”或“旧 solver”调试入口 + +#### 12. 测试整体重建 + +- 文件：`Assets/Tests/Simulation/EditMode/SimulationWorldTickTests.cs` +- 文件：`Assets/Tests/Simulation/PlayMode/SimulationWorldPlayModeTests.cs` +- 处理： +- 当前测试强依赖： + - `_useSimulationMovement` + - `_collisionQueryInputs` + - `_areaCollisionRequests` + - Job 通道与碰撞候选计数 + - 一旦抛弃现有 Burst/Job 路线，这批测试大概率需要整体重写 +- 建议： + - 不要继续维护“反射私有字段 + 验证 Native 通道”的测试模式 + - 改为验证外部可观察行为： + - 敌人移动 + - 投射物生命周期 + - 范围命中结果 + - 实体 hide/remove 生命周期 + +#### 13. 文档同步 + +- 文件：`docs/P1.5 Simulation-Supplement.md` +- 文件：`docs/P2 Job System + Burst 落地.md` +- 文件：`docs/TodoList.md` +- 处理： + - 标明当前代码已不再保留 P1.5 的 `SimulationWorld` 执行路径 + - 删除或修正文档里关于 `SetUseSimulationMovement(bool)`、`UseJobSimulation`、`UseBurstJobs` 的失真描述 + +### 推荐实施顺序 + +1. 先确认唯一执行路径 +- `SimulationWorld` Burst 管线作为唯一运行时执行路径 +- 实体和组件只保留输入、注册、表现职责 + +2. 再处理战斗入口 +- 先改 `GameStateBattle` / `GameEntry` / `ProcedureGame` +- 让运行时明确依赖当前 Burst 管线，不再保留双路径语义 + +3. 再清理旧组件驱动路径 +- 先收敛 `MovementComponent` +- 再删敌人/玩家/投射物实体里的自驱动移动 +- 再删旧 fallback 查询和旧互斥 solver + +4. 最后重建测试和文档 +- 先让行为稳定 +- 再补新的回归测试和文档 + +### 当前建议 + +- 不建议试图“恢复 P1.5 开关”。 + - 当前代码里并没有一条完整可切换的 P1.5 `SimulationWorld` 路径，恢复开关只会制造更多伪分支。 +- 更合理的做法是直接承认现状： + - 保留 Burst 化 `SimulationWorld` 作为唯一执行路径 + - 删掉所有组件自驱动和 fallback 分支 +- 下一步应按上面的收敛顺序推进，不要再尝试维护“双路径可切换”。 + ## Weapon 现状梳理 ### 1. 数据层结构