Cleanup 1

2026-04-02 11:21:07 +08:00
parent 5ed792b09f
commit 1052cc0136
26 changed files with 600 additions and 2057 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02
@@ -0,0 +1,61 @@
+## Context
+
+当前战斗运行时已经把 `SimulationWorld.Tick(...)` 接入主循环，并由 Burst Job 管线承担敌人移动、敌人分离、投射物推进与碰撞 broad-phase 的主体计算。但组件与实体层仍保留旧路径，包括 `MovementComponent.OnUpdate()` 直接改位移、`EnemyProjectile.OnUpdate()` 自驱动、`NearestTargetSelector` fallback 查询，以及 `EnemySeparationSolverProvider` 的旧互斥职责。这使运行时行为、调试入口和测试方式都围绕双路径假设展开。
+
+本次变更横跨 `SimulationWorld`、实体/组件、战斗入口、调试面板、测试和文档，属于一次架构收敛，而不是单点修补。约束是：必须保留现有 Burst/Job 管线与 `_enemies/_projectiles/_pickups` 作为正式状态源，避免重新引入另一套仿真框架。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 让 `SimulationWorld` 成为战斗中的唯一仿真执行入口。
+- 把实体与组件职责收敛为输入提交、注册同步和表现消费。
+- 删除旧双路径分支、旧互斥 solver 依赖和与之绑定的调试入口。
+- 将测试改为验证可观察行为，而不是依赖私有字段反射或 Native 通道细节。
+- 同步文档，使其准确反映单一路径架构。
+
+**Non-Goals:**
+- 不重写现有 Burst/Job 算法本身。
+- 不在本次变更中扩展新武器或新仿真能力。
+- 不恢复或保留可切换的 P1.5 / 非 `SimulationWorld` 执行路径。
+- 不以兼容旧测试为目标保留多余字段或调试钩子。
+
+## Decisions
+
+### 1. 保留现有 Burst Job 管线，删除双路径路由语义
+- 决策：以 `SimulationWorld.TickSimulationPipeline(in SimulationTickContext context)` 作为唯一执行面，移除 `UseSimulationMovement` 的运行时路由职责；如果保留该字段，也只能作为全局停机开关而不是分支入口。
+- 原因：现有可工作的完整路径只有 Burst Job 管线，继续维护组件驱动 fallback 没有等价能力，只会增加漂移。
+- 备选方案：恢复旧路径并保留切换开关。否决原因是旧路径已不完整，恢复成本高且会持续制造测试矩阵和调试噪音。
+
+### 2. 以 sim state 作为唯一真相源，实体侧只提交输入与消费输出
+- 决策：`_enemies`、`_projectiles`、`_pickups` 继续作为正式运行时状态源；`MovementComponent`、敌人、玩家、投射物只维护输入态、注册态和表现同步所需数据，不再直接推进世界位置或互斥。
+- 原因：状态集中后，Job 输入/输出和 presentation write-back 才能形成闭环，避免实体私自改写坐标导致状态撕裂。
+- 备选方案：保留实体局部自驱动，再由 `SimulationWorld` 尽量同步。否决原因是会持续产生写冲突和追责困难。
+
+### 3. 保留 `SimulationWorld` 查询/结算能力，移除实体 fallback 查询
+- 决策：碰撞 broad-phase、area/sector/projectile 命中查询统一由 `SimulationWorld` 提供；目标选择器与武器逻辑直接依赖该能力，不再回退到遍历或组件侧查询。
+- 原因：查询能力只有与仿真状态源共用同一空间索引时才一致，fallback 查询会导致命中范围与真实运行时不同步。
+- 备选方案：保留 fallback 作为调试或兜底。否决原因是这会掩盖真实问题，并让生产行为与测试行为不一致。
+
+### 4. 测试与调试面板跟随单一路径重建
+- 决策：移除旧 solver 切换 UI 和依赖私有字段的测试模式，改为验证敌人移动、投射物生命周期、范围命中、实体 hide/remove 等外部行为，并仅展示当前 `SimulationWorld` 的指标。
+- 原因：单一路径架构下，私有 Native 通道结构属于实现细节，不应成为长期契约。
+- 备选方案：继续保留反射测试以降低短期改动量。否决原因是会固化错误抽象边界。
+
+## Risks / Trade-offs
+
+- [风险] 删除旧分支后，部分依赖 `MovementComponent.OnUpdate()` 或 projectile 自驱动的实体可能短期失效。 → 缓解：优先收敛战斗入口和输入同步接口，再逐类替换敌人、玩家、投射物的调用点。
+- [风险] 测试从白盒切到黑盒后，定位 Native 通道回归会更慢。 → 缓解：保留必要运行时指标与日志，但不把私有字段暴露为长期契约。
+- [风险] 文档和代码阶段性不同步会误导后续开发。 → 缓解：将文档同步列为同一 change 的完成条件，而不是后续补做。
+- [权衡] 放弃双路径意味着失去旧逻辑的快速兜底。 → 缓解：通过更稳定的单路径测试覆盖和可观测指标替代兜底分支。
+
+## Migration Plan
+
+1. 先收敛战斗主入口与 `SimulationWorld` tick 语义，明确单一路径。
+2. 再将 `MovementComponent`、敌人、玩家、投射物改为输入/注册/表现职责，移除旧 solver 与 fallback 查询。
+3. 最后清理调试面板、重建测试、更新文档，确保仓库不再暴露旧路径语义。
+4. 回滚策略仅限于回退整个 change；不设计运行时开关回滚。
+
+## Open Questions
+
+- `UseSimulationMovement` 是否完全删除，还是保留为仅用于全局停机/诊断的只读配置，需要在实现前最终确认。
+- 玩家位移是否已经有完整的 `SimulationWorld` 输入同步接口；若没有，需要先补足最小接口再移除 `MovementComponent.OnUpdate()` 调用。
@@ -0,0 +1,24 @@
+## Why
+
+`SimulationWorld` 当前已经以 Burst Job 管线承担主要仿真职责，但运行时仍残留组件自驱动、实体 fallback 和旧调试/测试路径，导致移动、碰撞和生命周期逻辑在两套语义之间分叉。继续维护这些旧路径只会放大行为漂移和测试脆弱性，因此需要把运行时彻底收敛到单一路径。
+
+## What Changes
+
+- 将 `SimulationWorld` Burst/Job 管线固化为战斗中的唯一仿真执行入口。
+- 删除 `UseSimulationMovement` 一类双路径路由语义，以及实体、组件中的自驱动移动和 fallback 查询逻辑。
+- 将 `MovementComponent`、敌人/投射物实体、目标选择器收敛为输入同步、注册管理和表现消费层。
+- 清理 `EnemySeparationSolverProvider` 及其调试面板入口，移除旧互斥 solver 的运行时依赖。
+- 重建测试与文档，使其面向外部可观察行为，而不是旧私有字段和 Native 通道反射。
+
+## Capabilities
+
+### New Capabilities
+- `simulationworld-runtime-convergence`: Define `SimulationWorld` as the sole runtime simulation path for movement, projectile stepping, collision queries, presentation sync, and related battle integration.
+
+### Modified Capabilities
+
+## Impact
+
+- Affected code: `Assets/GameMain/Scripts/Simulation/**`, `Assets/GameMain/Scripts/Components/MovementComponent.cs`, `Assets/GameMain/Scripts/Entity/EntityLogic/**`, `Assets/GameMain/Scripts/Procedure/Game/**`, `Assets/GameMain/Scripts/CustomComponent/DebugPanel/RuntimeDebugPanelComponent.cs`, `Assets/Tests/Simulation/**`, `docs/P1.5 Simulation-Supplement.md`, `docs/P2 Job System + Burst 落地.md`, `docs/TodoList.md`.
+- Runtime impact: battle update order, enemy/player/projectile movement, collision candidate queries, target selection, presentation write-back, and simulation lifecycle reset behavior.
+- Breaking impact: removes legacy runtime branches and debug affordances that assume a non-`SimulationWorld` execution path exists.
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: SimulationWorld SHALL be the sole battle simulation executor
+The battle runtime MUST execute movement, projectile stepping, collision broad-phase, and related simulation state updates through `SimulationWorld`, and it MUST NOT route these responsibilities through an alternative non-`SimulationWorld` runtime path.
+
+#### Scenario: Battle tick advances through SimulationWorld
+- **WHEN** the battle update loop advances a gameplay frame
+- **THEN** `SimulationWorld` executes the simulation pipeline for that frame as the authoritative runtime update path
+
+#### Scenario: Legacy routing switch does not select an alternate executor
+- **WHEN** runtime configuration related to simulation movement is evaluated
+- **THEN** it does not select or re-enable a separate legacy movement execution path
+
+### Requirement: Runtime entities SHALL submit input and consume simulation output only
+Enemy entities, the player entity, projectile entities, and `MovementComponent` MUST submit movement or behavior input into `SimulationWorld` state and MUST consume position, facing, hit, or lifecycle results from simulation output, rather than computing world-space advancement independently.
+
+#### Scenario: MovementComponent no longer advances transforms directly
+- **WHEN** movement input, speed, or separation parameters change on an entity
+- **THEN** the component synchronizes those values to `SimulationWorld` state without directly moving the entity transform
+
+#### Scenario: Entity presentation follows simulation output
+- **WHEN** simulation state is committed for enemies or projectiles
+- **THEN** entity presentation updates consume the committed output to refresh transforms, facing, visibility, or removal state
+
+### Requirement: Spatial queries SHALL use SimulationWorld-owned data and services
+Target selection, projectile hits, area hits, and sector hits MUST use `SimulationWorld` spatial indexing and query services, and MUST NOT fall back to legacy entity-side traversal or solver-specific query paths.
+
+#### Scenario: Target selection uses simulation spatial data
+- **WHEN** weapon or AI logic requests nearby or nearest targets
+- **THEN** the query resolves against `SimulationWorld` maintained spatial data for the current frame
+
+#### Scenario: Projectile and area hit evaluation stay on simulation path
+- **WHEN** projectile, area, or sector hit logic runs during combat
+- **THEN** hit candidates are produced from `SimulationWorld` collision and query capabilities instead of a fallback entity-side path
+
+### Requirement: Runtime surfaces SHALL reflect the single-path architecture
+Runtime debug surfaces, automated tests, and architecture documents MUST reflect that the project supports one authoritative `SimulationWorld` execution path rather than dual-path behavior.
+
+#### Scenario: Debug panel omits legacy solver controls
+- **WHEN** runtime simulation debugging is displayed
+- **THEN** it shows current `SimulationWorld` metrics without exposing legacy solver switching or dual-path controls
+
+#### Scenario: Regression tests validate observable single-path behavior
+- **WHEN** simulation regression coverage is maintained
+- **THEN** tests validate observable outcomes such as movement, projectile lifetime, hit results, and hide/remove lifecycle instead of asserting private compatibility fields for legacy paths
@@ -0,0 +1,23 @@
+## 1. Battle Runtime Convergence
+
+- [x] 1.1 Update `SimulationWorld` and battle entry points so the Burst/Job simulation pipeline is the only runtime execution path.
+- [x] 1.2 Remove or redefine `UseSimulationMovement` and related semantics so it can no longer route combat through a legacy non-simulation path.
+- [x] 1.3 Confirm `ClearSimulationState()` and battle bootstrap/reset flows only clear simulation-owned state without reintroducing dual-path behavior.
+
+## 2. Entity and Component Path Cleanup
+
+- [x] 2.1 Refactor `MovementComponent` into an input/register/sync layer and remove direct transform advancement plus `EnemySeparationSolverProvider` runtime dependence.
+- [x] 2.2 Remove enemy and player calls that self-advance movement or branch on `UseSimulationMovement`, replacing them with simulation input submission and presentation consumption.
+- [x] 2.3 Remove projectile self-driven movement/lifetime logic and make projectile presentation follow `SimulationWorld` output only.
+
+## 3. Query, Debug, and Regression Alignment
+
+- [x] 3.1 Route target selection and hit queries exclusively through `SimulationWorld` spatial data and remove legacy fallback traversal paths.
+- [x] 3.2 Clean the runtime debug panel so it exposes current `SimulationWorld` metrics without legacy solver or dual-path controls.
+- [x] 3.3 Rewrite simulation regression tests to validate observable behavior such as movement, projectile lifetime, hit results, and hide/remove lifecycle.
+
+## 4. Documentation and Verification
+
+- [x] 4.1 Update simulation architecture documents and todo notes to describe the single authoritative `SimulationWorld` path and remove stale switch descriptions.
+- [x] 4.2 Run targeted verification for battle movement, projectile flow, query behavior, and updated tests to confirm no legacy execution path remains.
+