vampire-like/docs/CodeX-TODO.md

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. 数据层结构

• Assets/GameMain/DataTables/Weapon.txt

  • 武器基础数据表。
  • 当前 Params 列已经切换为标准 JSON 对象。
  • 约束：
    • 空参数统一写 {}
    • 不再兼容 []
    • key 名应与对应 ParamsData 属性名一致

• Assets/GameMain/Scripts/DataTable/DRWeapon.cs

  • 负责解析武器表基础字段。
  • 保留两份参数视图：
    • ParamsJson
      • 原始 JSON 字符串，供 WeaponData 强类型反序列化使用。
    • Pramas
      • 由 ParamsJson 转成的 Dictionary<string, string>。
      • 仅用于描述/UI 等弱类型读取场景。

• Assets/GameMain/Scripts/Entity/EntityData/Weapon/WeaponData.cs

  • 保留所有武器共用字段：
    • Attack
    • Cooldown
    • AttackRange
    • Price
    • Rarity
    • Modifiers
    • ParamsJson
    • Params
  • 提供 ParseParams<TParams>() 作为武器子类的强类型参数解析入口。

• Assets/GameMain/Scripts/Entity/EntityData/Weapon/*

  • 每个具体武器子类持有自己的 ParamsData：
    • WeaponKnifeData -> WeaponKnifeParamsData
    • WeaponHandgunData -> WeaponHandgunParamsData
    • WeaponSlashData -> WeaponSlashParamsData
    • WeaponLightningData -> WeaponLightningParamsData

2. 逻辑层结构

• Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponBase.cs

  • 武器统一基类。
  • 负责：
    • 生命周期
    • 状态机切换
    • 选敌
    • Simulation area/sector query 接入
    • 绑定玩家攻击属性

• 当前已有四种武器实现模板：

  • WeaponKnife
    • 近身前刺 + 圆形范围命中
  • WeaponHandgun
    • 单次 Raycast 瞬发命中
  • WeaponSlash
    • 扇形范围命中
  • WeaponLightning
    • 锁定目标点 + 落点范围打击

• 参数读取方式

  • 已改为在具体武器中直接读取对应 ParamsData
  • 不再在武器逻辑中手动解析字符串参数

3. 当前已接通的参数

• WeaponKnifeParamsData

  • HitRadius

• WeaponHandgunParamsData

  • 暂无字段，待扩展

• WeaponSlashParamsData

  • SectorAngle

• WeaponLightningParamsData

  • HitRadius
  • HoverHeight

4. 当前结构的优点

• 公共字段仍集中在 WeaponData，不会把通用逻辑拆散
• 武器专属参数已经强类型化，初始化更稳定
• 数据表可读性比旧的 KV 字符串格式更高
• 新武器扩展时，可以复用：
  • 表
  • DRWeapon
  • WeaponData
  • WeaponBase
  • AttackEffect
  • Simulation area/sector query

5. 当前结构的限制

• 仍然不是“纯配置驱动行为”
  • 行为差异主要还在具体武器类里
• Handgun 参数化程度还不够
  • 目前还不适合直接高效派生霰弹枪、狙击枪、 burst 枪
• Pramas 命名拼写仍保留旧名字
  • 目前为了兼容存量调用，暂不改

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 模式都能命中