make plan

2026-04-02 13:31:57 +08:00 · 2026-04-02 13:31:57 +08:00 · dce5598c70
parent a94a86b68b
commit dce5598c70
2 changed files with 139 additions and 475 deletions
--- a/docs/CodeX-TODO.md
+++ b/docs/CodeX-TODO.md
@ -1,467 +1,144 @@
 # CodeX TODO
-## SimulationWorld 路线收敛
+## GPU Instancing 改造路线
 ### 当前结论
 - 当前 `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` 继续作为敌人 `position / rotation / state` 的唯一真相源。
- 实体自身不再计算“下一帧位置”，而是只向 `SimulationWorld` 提供输入和配置。
+- 新增 `InstanceRendererComponent` 作为 Presentation 侧批量渲染组件，不把批次构建和 GPU Buffer 管理塞回 `SimulationWorld`。
- `MovementComponent` 不再直接改 `Transform`，只负责：
+- 先做 `Graphics.DrawMeshInstanced` 低风险版，确认链路跑通后，再决定是否升级到 `DrawMeshInstancedIndirect`。
-  - 保存移动开关/方向/速度等输入态
+- P3 首阶段只处理“敌人批量渲染”，不同时扩大到投射物、掉落物和所有特效。
  - 向 `SimulationWorld` 注册或同步这些输入
 - 实体表现层只消费 `SimulationWorld` 的输出结果，不再自己推进位移或互斥。
 - 删除所有“Simulation / 非 Simulation”双路径分支，避免行为在两套逻辑里分叉。
-### 必改项
+### 架构边界
-#### 1. Tick 主入口收敛
+- `SimulationWorld`
  - 只负责逻辑 Tick、生命周期同步、状态容器与碰撞结算。
  - 不负责 `Mesh / Material / MaterialPropertyBlock / ComputeBuffer`。
 - `InstanceRendererComponent`
  - 只负责收集可渲染实例、按 `Mesh + Material + Shadow + Layer + RenderState` 分组、构建 batch、发起 draw call。
  - 只消费 `SimulationWorld` 输出，不反写 sim 状态。
 - `TransformSync`
  - P3 第一阶段继续保留，用于 HPBar、受击特效、挂点和现有表现依赖。
  - 不要求一开始就把所有敌人 `Transform` 写回移除，否则风险过高。
 - 敌人 GameObject
  - 第一阶段继续保留，用于碰撞、生命周期、事件桥和表现挂点。
  - 仅逐步移除“每敌人独立 MeshRenderer”这条渲染路径。
- 文件：`Assets/GameMain/Scripts/Simulation/SimulationWorld.cs`
+### 组件规划
 - 处理：
  - 保留 `TickSimulationPipeline(in SimulationTickContext context)` 作为唯一执行主入口
  - 删除“开关关闭后直接跳过 SimulationWorld”的旧语义
  - 重定义 `UseSimulationMovement`：
    - 要么删除
    - 要么仅保留为全局停机开关，而不是双路径路由开关
 - 备注：
  - `GameStateBattle.OnUpdate` 目前已经把 `SimulationWorld.Tick(...)` 放在战斗主循环里，这个方向是对的
-#### 2. 保留并固化 Burst/Job 敌人执行面
+1. 新增批量渲染组件骨架
   - 建议文件：
     - `Assets/GameMain/Scripts/CustomComponent/InstanceRendering/InstanceRendererComponent.cs`
     - `Assets/GameMain/Scripts/CustomComponent/InstanceRendering/EnemyInstanceRegistry.cs`
     - `Assets/GameMain/Scripts/CustomComponent/InstanceRendering/EnemyInstanceBatch.cs`
   - 建议职责：
     - `InstanceRendererComponent`：帧级调度、统一提交 draw call。
     - `EnemyInstanceRegistry`：维护 `EntityId -> RenderBinding`，缓存 mesh/material/archetype。
     - `EnemyInstanceBatch`：缓存每组矩阵、颜色、闪白参数和批次拆分结果。
- 文件：`Assets/GameMain/Scripts/Simulation/Jobs/SimulationWorld.EnemyJobs.cs`
+2. 接入 `GameEntry`
- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/EnemyMovementBurstJob.cs`
+   - 文件：`Assets/GameMain/Scripts/Base/GameEntry.Custom.cs`
- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/EnemySeparationBurstJob.cs`
+   - 处理：
- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/BuildEnemySeparationBucketsBurstJob.cs`
+     - 增加 `GameEntry.InstanceRenderer`
- 处理：
+     - 与 `SimulationWorld` 一样在启动时自动获取或挂载组件
  - 保留 Burst Job 调度，明确这就是敌人的唯一移动/互斥路径
  - 把实体侧“追击/停下/朝向目标”的输入全部规范成写入 sim state，而不是各实体自己推动
  - 明确 `_enemies` 是敌人移动和互斥的唯一状态源
-#### 3. 保留并固化 Burst/Job 投射物执行面
+### 第一阶段：低风险版 `DrawMeshInstanced`
- 文件：`Assets/GameMain/Scripts/Simulation/Jobs/SimulationWorld.ProjectileJobs.cs`
+1. 建立渲染注册表
- 文件：`Assets/GameMain/Scripts/Simulation/JobStruct/ProjectileMovementBurstJob.cs`
+   - 注册时机：敌人 show 时缓存渲染资源引用，hide 时释放注册。
- 处理：
+   - 注册内容：
-  - 保留投射物移动 Job，作为唯一的投射物位置推进路径
+     - `EntityId`
-  - 删除 `EnemyProjectile.OnUpdate` 中的自驱动移动和寿命推进逻辑
+     - `Mesh`
-  - `EnemyProjectile` 只负责 show/hide、碰撞体开关、表现同步
+     - `Material`
-
+     - 阴影/Layer/子类型信息
-#### 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. 数据层结构
 - `Assets/GameMain/DataTables/Weapon.txt`
  - 武器基础数据表。
  - 当前 `Params` 列已经切换为标准 JSON 对象。
   - 约束：
-    - 空参数统一写 `{}`
+     - 注册表只缓存渲染资源和 archetype，不缓存位置真相数据。
    - 不再兼容 `[]`
    - key 名应与对应 `ParamsData` 属性名一致
- `Assets/GameMain/Scripts/DataTable/DRWeapon.cs`
+2. 从 `SimulationWorld` 读取实例数据
-  - 负责解析武器表基础字段。
+   - 读取来源：`_enemies` 或对外只读查询接口。
-  - 保留两份参数视图：
+   - 每帧收集：
-    - `ParamsJson`
+     - `Matrix4x4`
-      - 原始 JSON 字符串，供 `WeaponData` 强类型反序列化使用。
+     - 朝向/缩放
-    - `Pramas`
+     - `flashAmount`
-      - 由 `ParamsJson` 转成的 `Dictionary<string, string>`。
+     - `baseColor`
-      - 仅用于描述/UI 等弱类型读取场景。
+     - 其他实例化参数
   - 约束：
     - 由 sim 输出生成当前帧渲染数据，不从敌人 `Transform` 反推逻辑状态。
- `Assets/GameMain/Scripts/Entity/EntityData/Weapon/WeaponData.cs`
+3. 按批次分组并提交
-  - 保留所有武器共用字段：
+   - 分组键至少包含：
-    - `Attack`
+     - `Mesh`
-    - `Cooldown`
+     - `Material`
-    - `AttackRange`
+     - `ShadowCastingMode`
-    - `Price`
+     - `ReceiveShadows`
-    - `Rarity`
+     - `Layer`
-    - `Modifiers`
+     - 需要的渲染状态位
-    - `ParamsJson`
+   - 提交方式：
-    - `Params`
+     - 每批最多 `1023` 实例
-  - 提供 `ParseParams<TParams>()` 作为武器子类的强类型参数解析入口。
+     - 使用 `Graphics.DrawMeshInstanced`
     - 通过 `MaterialPropertyBlock` 下发实例颜色和闪白参数
- `Assets/GameMain/Scripts/Entity/EntityData/Weapon/*`
+4. 接入现有 Instanced Shader
-  - 每个具体武器子类持有自己的 `ParamsData`：
+   - 文件：`Assets/GameMain/Materials/Shaders/SimpleInstancedFlash.shader`
-    - `WeaponKnifeData -> WeaponKnifeParamsData`
+   - 处理：
-    - `WeaponHandgunData -> WeaponHandgunParamsData`
+     - 复用现有 `_BaseColor / _FlashColor / _FlashAmount` 实例化属性
-    - `WeaponSlashData -> WeaponSlashParamsData`
+     - 确认敌人材质启用 instancing
-    - `WeaponLightningData -> WeaponLightningParamsData`
+     - 不在第一阶段同时改复杂动画或多 Pass 材质
-### 2. 逻辑层结构
+5. 替换敌人独立 Renderer 路径
   - 第一阶段做法：
     - 保留敌人实体和挂点
     - 禁用敌人身上的 `MeshRenderer/SkinnedMeshRenderer`
     - 改由 `InstanceRendererComponent` 统一绘制
   - 约束：
     - 碰撞、伤害、掉落、状态切换仍完全走现有逻辑链路
- `Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponBase.cs`
+### 第二阶段：高上限版 `DrawMeshInstancedIndirect`
  - 武器统一基类。
  - 负责：
    - 生命周期
    - 状态机切换
    - 选敌
    - Simulation area/sector query 接入
    - 绑定玩家攻击属性
- 当前已有四种武器实现模板：
+1. 升级批次数据结构
-  - `WeaponKnife`
+   - 将 `Matrix4x4[]` 和实例属性数组迁移到 `ComputeBuffer` / `GraphicsBuffer`
-    - 近身前刺 + 圆形范围命中
+   - 建立按 archetype 持久复用的 buffer，避免每帧重建
  - `WeaponHandgun`
    - 单次 Raycast 瞬发命中
  - `WeaponSlash`
    - 扇形范围命中
  - `WeaponLightning`
    - 锁定目标点 + 落点范围打击
- 参数读取方式
+2. 升级提交方式
-  - 已改为在具体武器中直接读取对应 `ParamsData`
+   - 使用 `Graphics.DrawMeshInstancedIndirect`
-  - 不再在武器逻辑中手动解析字符串参数
+   - 为实例数量、剔除结果和参数下发建立独立 buffer
-### 3. 当前已接通的参数
+3. 逐步加入可选优化
   - 视锥剔除
   - 距离分层
   - LOD
   - 大规模敌人下的批次复用和 buffer 容量管理
- `WeaponKnifeParamsData`
+4. 进入该阶段的前提
-  - `HitRadius`
+   - `DrawMeshInstanced` 版本已验证视觉正确
   - `5k` 规模下 draw call 或主线程提交成本仍是瓶颈
   - 否则不要过早把复杂度拉到 `Indirect`
- `WeaponHandgunParamsData`
+### 风险控制
  - 暂无字段，待扩展
- `WeaponSlashParamsData`
+- 不要把 GPU batch 容器放进 `SimulationWorld` 主状态里。
-  - `SectorAngle`
+- 不要让碰撞、索引或目标选择依赖 `InstanceRendererComponent`。
 - 不要一上来就移除 `TransformSync`，先保住现有 HPBar/特效/挂点行为。
 - 不要在第一阶段同时处理敌人、投射物、掉落物三类 instancing。
- `WeaponLightningParamsData`
+### 验证口径
  - `HitRadius`
  - `HoverHeight`
-### 4. 当前结构的优点
+1. 功能回归
   - 敌人朝向、受击闪白、死亡隐藏、精英/普通配色与当前一致
   - `Battle -> LevelUp -> Shop -> Battle` 循环不丢渲染实例
- 公共字段仍集中在 `WeaponData`，不会把通用逻辑拆散
+2. Profiling 指标
- 武器专属参数已经强类型化，初始化更稳定
+   - `0.5k / 1k / 1.5k / 2k / 5k` 敌人
- 数据表可读性比旧的 KV 字符串格式更高
+   - `Draw Calls`
- 新武器扩展时，可以复用：
+   - `SetPass Calls`
-  - 表
+   - `Main Thread`
-  - `DRWeapon`
+   - Render Thread / GPU 时间
  - `WeaponData`
  - `WeaponBase`
  - AttackEffect
  - Simulation area/sector query
-### 5. 当前结构的限制
+3. 阶段验收
-
+   - 第一阶段验收：
- 仍然不是“纯配置驱动行为”
+     - 先证明 `DrawMeshInstanced` 跑通且视觉一致
-  - 行为差异主要还在具体武器类里
+     - Draw Calls 相比当前路径明显下降
- `Handgun` 参数化程度还不够
+   - 第二阶段验收：
-  - 目前还不适合直接高效派生霰弹枪、狙击枪、 burst 枪
+     - `5k` 敌人规模下主线程提交和渲染耗时继续下降
- `Pramas` 命名拼写仍保留旧名字
+     - buffer 生命周期稳定，无泄漏、无错绘、无实例残留
  - 目前为了兼容存量调用，暂不改
 ## Weapon 扩展计划
 ### P0: 稳定当前数据链路
 - 检查 `Weapon.txt` 中全部行：
  - `Params` 必须都是 JSON 对象
  - 空参数统一为 `{}`
 - 检查后续新增字段时：
  - 数据表 key 与 `ParamsData` 属性名保持一致
 - 补一轮基础验证：
  - 商店描述
  - 玩家初始武器生成
  - 商店购买武器生成
 ### P1: 先把 Handgun 参数化做完整
 目标：
 - 把 `WeaponHandgun` 做成远程枪械母版，而不是只有一把“手枪”
 建议新增参数：
 - `PelletCount`
 - `SpreadAngle`
 - `PenetrationCount`
 - `FireOriginOffsetX`
 - `FireOriginOffsetY`
 - `FireOriginOffsetZ`
 - `HitMarkerSize`
 - `HitMarkerYOffset`
 - `HitMarkerDuration`
 落地后可直接派生：
 - 手枪
 - 霰弹枪
 - 狙击枪
 - 三连发手炮
 ### P2: 优先做低成本高收益的新武器
 优先顺序建议：
 1. 长枪 / 刺剑
   - 基于 `WeaponKnife`
   - 重点调：
     - 前刺距离
     - 命中半径
     - 冷却
 2. 大剑 / 半月斩
   - 基于 `WeaponSlash`
   - 重点调：
     - `SectorAngle`
     - 攻击范围
     - 动画时长
 3. 战锤 / 震地锤
   - 基于 `WeaponLightning` 或 `WeaponKnife`
   - 重点调：
     - 落点半径
     - 前摇
     - 低频高伤
 4. 霰弹枪
   - 基于参数化后的 `WeaponHandgun`
   - 重点调：
     - 散射
     - 多 pellet
     - 近距离爆发
 5. 狙击枪
   - 基于参数化后的 `WeaponHandgun`
   - 重点调：
     - 单发高伤
     - 超远射程
     - 慢冷却
 6. 陨石杖 / 圣光柱
   - 基于 `WeaponLightning`
   - 重点调：
     - `HoverHeight`
     - 爆炸半径
     - 冷却
 ### P3: 中成本扩展
 1. 链式闪电
   - 在首目标命中后，继续寻找附近目标
   - 需要新增：
     - 连锁次数
     - 连锁半径
     - 每跳衰减
 2. 穿透弹 / 火球
   - 复用现有 projectile/simulation 基础
   - 需要明确：
     - 穿透次数
     - 命中后是否爆炸
 3. 地雷 / 陷阱
   - 本质是延时触发 area hit
   - 需要新增：
     - 布置后触发时机
     - 持续时间
     - 触发半径
 4. 回旋镖
   - 需要双阶段投射物状态
   - 成本高于普通枪械/范围武器
 ### P4: 暂缓项
 以下方向暂不建议优先投入：
 - 持续激光
 - 喷火器
 - 环绕飞剑
 - 常驻法球
 - 冰冻/中毒/击退等状态驱动武器流派
 原因：
 - 当前武器框架核心仍是“单次攻击结算”
 - 持续伤害与异常状态还没有形成统一挂点
 ## 新武器接入步骤模板
 1. 在 `Weapon.txt` 新增一行
   - 配好基础字段
   - `Params` 写 JSON 对象
 2. 新增 `WeaponType`
   - 在 `Assets/GameMain/Scripts/Definition/Enum/WeaponType.cs`
 3. 新增武器数据子类
   - 新建 `WeaponXXXData`
   - 新建 `WeaponXXXParamsData`
   - 在构造里调用 `ParseParams<TParams>()`
 4. 新增武器逻辑类
   - 继承 `WeaponBase`
   - 接入状态机
   - 读取 `ParamsData`
 5. 接入生成入口
   - 玩家初始武器
   - 商店购买武器
   - 其他掉落/奖励入口
 6. 验证点
   - 武器生成正确
   - 参数生效正确
   - 描述文本正确
   - Simulation 模式和非 Simulation 模式都能命中
--- a/docs/TodoList.md
+++ b/docs/TodoList.md
@ -60,12 +60,6 @@
  - 先不迁移完整行为，只保证创建、回收、索引同步路径可用。
  - 完成标准：投射物/掉落物实体生命周期正常，无索引越界与回收遗漏。
 - [x] Checkpoint 7：P1 阶段回归与性能记录
  - 回归用例：战斗 10 分钟、`Battle -> LevelUp -> Shop -> Battle` 循环、掉落吸附与拾取。
  - Profiling 对比：记录 `0.5k / 1k / 1.5k / 2k` 敌人下 Main Thread、GC Alloc、敌人更新耗时。
  - 输出文档：`P1 Simulation 分层设计 + 回滚开关说明 + 对比数据`。
  - 完成标准：核心流程稳定，无新增 Error/Exception；可一键回滚到旧更新路径。
 **验收标准**
 - 敌人移动/追踪由 Simulation 统一调度，不再逐个 Enemy MonoBehaviour 执行核心逻辑。
@ -166,13 +160,6 @@
  - 清理战斗帧中不必要的主线程循环（尤其逐实体逻辑）。
  - 完成标准：Profiler 可见主要计算在 Worker Threads；Main Thread 峰值更平滑。
 - [ ] Checkpoint 9：P2 回归、压测与结项文档
  - 回归用例：10 分钟战斗、`Battle -> LevelUp -> Shop -> Battle` 循环、掉落拾取链路。
  - 压测口径：`0.5k / 1k / 1.5k / 2k` 敌人，记录 Main Thread、Job Workers、GC Alloc、关键 Marker。
  - 输出文档：`P2 Job/Burst 改造说明 + 开关/回滚策略 + 前后对比数据`。
  - 完成标准：结论可复现，可作为 P3 GPU Instancing 的输入基线。
  - 当前状态：`P2 TickEnemies` 在 `2k` 规模下相对 `P1.5` 已降至 `9.44 ms`（约 `-56.4%`），CPU 目标已满足；仍需补齐 `GC Alloc` 与三项回归证据后再勾选。
 **验收标准**
 - 在 2k 敌人规模下，CPU Main Thread 明显下降（目标 >= 30%）。
 - Profiler 中战斗帧 GC Alloc 接近 0（持续帧）。