- Checkpoint 1：清理 TickEnemies 侧 GC

- Checkpoint 2：解耦 Simulation 核心与 `Transform` 运行时依赖 - Checkpoint 3：收口 `EntitySync` 职责边界 - Checkpoint 4：拆分 Simulation Tick 阶段 - Checkpoint 5：补最小回归测试 - Checkpoint 6：补充 P1.5 结项文档
2026-02-21 13:39:14 +08:00
parent 200277a703
commit d55ead69a0
28 changed files with 1390 additions and 257 deletions
@@ -0,0 +1,72 @@
+---
+name: weapon-development
+description: Develop and extend the VampireLike weapon system. Use when creating new weapons, updating weapon state machines, changing target selection/effects/data parsing, or integrating weapon behavior with shop, inventory, and entity flow.
+---
+
+# Weapon Development
+
+## Quick Start
+
+1. Read full baseline spec: `./references/WeaponDevelopmentSkill.md`.
+2. Confirm change scope:
+   - weapon runtime (`WeaponBase`, concrete weapons)
+   - state flow (`Idle`, `Check_OutRange`, `Check_InRange`, `Attack`)
+   - target selector (`ITargetSelector`, `TargetSelectorType`)
+   - effect layer (`IWeaponAttackEffect`)
+   - data contract (`DRWeapon`, `WeaponData`)
+3. Keep behavior compatibility with current gameplay loop and UI/event chain.
+
+## Source Map
+
+- Weapon base: `../../Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponBase.cs`
+- Existing weapons:
+  - `../../Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponKnife/`
+  - `../../Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponHandgun/`
+  - `../../Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponSlash.cs`
+- Selectors:
+  - `../../Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/TargetSelector/`
+- Weapon data:
+  - `../../Assets/GameMain/Scripts/Entity/EntityData/Weapon/`
+- Entity show flow:
+  - `../../Assets/GameMain/Scripts/Entity/EntityExtension.cs`
+
+## Non-Negotiable Invariants
+
+- Do not duplicate logic already owned by `WeaponBase`.
+- Keep state transitions explicit and non-blocking.
+- Keep cooldown accumulation valid even when no target is found.
+- Keep attack logic and visual effect logic decoupled.
+- Use safe parsing (`TryParse` + defaults) for runtime weapon parameters.
+- Preserve compatibility with shop/inventory/UI refresh flow.
+
+## Change Recipes
+
+### Add a New Weapon
+
+1. Extend `WeaponType` without reordering existing enum values.
+2. Add `WeaponXxxData : WeaponData` for strong-typed fields.
+3. Add `WeaponXxx : WeaponBase` and implement only weapon-specific behavior.
+4. Build state files under `Weapon/WeaponXxx/` with partial class layout.
+5. Register display/data mapping path so `ShowWeapon` can instantiate correctly.
+
+### Add or Update a Target Selector
+
+1. Implement `ITargetSelector`.
+2. Update `TargetSelectorType`.
+3. Register creation in `WeaponBase.CreateSelector`.
+4. Validate target semantics with current-health rules where applicable.
+
+### Add or Update Attack Effect
+
+1. Implement `IWeaponAttackEffect`.
+2. Trigger effect from weapon attack state only.
+3. Keep damage resolution outside effect code.
+
+## Validation Checklist
+
+- Weapon can be shown, attached, and updated without exceptions.
+- State machine does not stall across target loss/reacquire.
+- Cooldown and range checks match design expectation.
+- Damage path and effect path remain decoupled.
+- UI/shop/inventory interactions stay stable after the change.
+- Update `./references/WeaponDevelopmentSkill.md` if contracts changed.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Weapon Development"
+  short_description: "Build and extend VampireLike weapon architecture"
+  default_prompt: "Use $weapon-development to implement a weapon system change with stable state flow and data contracts."
@@ -0,0 +1,134 @@
+# Weapon Development Skill（VampireLike）
+
+## 目标
+本文件是 `Entity.Weapon` 体系的开发规范与速查手册。
+后续新增武器或扩展机制时，优先按本文档执行，避免重复通读历史上下文。
+
+## 当前架构总览
+- 武器运行时入口：`WeaponBase`（`Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponBase.cs`）
+- 武器具体实现：`WeaponKnife`、`WeaponHandgun`、`WeaponSlash`
+- 目标选择策略：`ITargetSelector` + `TargetSelectorType`
+- 攻击可视化：`IWeaponAttackEffect`
+- 数据入口：`DRWeapon` -> `WeaponData`（及其子类）
+- 实体生成：`EntityExtension.ShowWeapon`
+
+## WeaponBase 统一职责（已上收）
+`WeaponBase` 负责以下通用逻辑，子类不要重复实现：
+- 生命周期模板：`OnShow/OnHide/OnAttachTo/OnDetachFrom`
+- 状态机管理：`RegisterState`、`EnsureStatesBuilt`、`TransitionTo`
+- 通用运行字段：`_target`、`_currAttackTimer`、`_sqrRange`
+- 启用门控：`OnUpdate` 中统一 `if (!_isEnabled) return`
+- 目标选择入口：`SelectTarget`、`SetTargetSelector`、`CreateSelector`
+- 距离判定：`IsInRange`（基于 XZ 平面距离）
+- 玩家攻击属性订阅：`BindAttackStatFromOwner` / `ReleaseAttackStatSubscription`
+
+## 状态机约定
+统一状态枚举：
+- `Idle`
+- `Check_OutRange`
+- `Check_InRange`
+- `Attack`
+- `Disabled`（可选）
+
+推荐流程：
+1. `Idle`：查找目标，计时器持续累积。
+2. `Check_OutRange`：有目标但不在攻击范围，继续转向并累积计时。
+3. `Check_InRange`：在攻击范围内，若 `currAttackTimer >= Cooldown` 切 `Attack`。
+4. `Attack`：执行攻击，重置计时器，结束后回 `Check_InRange`。
+
+关键规则：
+- 即使没有目标，也允许蓄力（计时器持续走）。
+- 一旦进入 `Check_InRange` 且冷却已满，应立即触发攻击。
+
+## 3D 场景下的距离/朝向原则
+- 射程与目标筛选：优先使用 XZ 平面距离（忽略 Y），调用 `AIUtility.GetSqrMagnitudeXZ`。
+- 视觉朝向与弹道：可按武器设计决定是否使用完整 3D 向量。
+  - `WeaponHandgun`：允许俯仰瞄准，逻辑上用射线命中对象判定伤害。
+  - 近战地面范围类（Knife/Slash）：伤害检测建议投影到地面（XZ）再判定。
+
+## 目标选择策略规范
+接口：`ITargetSelector.SelectTarget(WeaponBase weapon, IEnumerable<EntityBase> candidates, float maxSqrRange)`
+
+现有策略：
+- `NearestTargetSelector`
+- `HighestHealthTargetSelector`
+- `LowestHealthTargetSelector`
+
+语义约定：
+- `HighestHealth` / `LowestHealth` 必须按“当前血量”筛选。
+- 当前实现读取 `HealthComponent.CurrentHealth`。
+
+扩展策略步骤：
+1. 新建 selector 类并实现 `ITargetSelector`。
+2. 更新 `TargetSelectorType` 枚举。
+3. 在 `WeaponBase.CreateSelector` 中注册。
+4. 武器在 `OnWeaponShow` 或构造阶段选择策略。
+
+## 攻击可视化效果规范
+接口：`IWeaponAttackEffect.Play(WeaponBase weapon, Vector3 position, EntityBase target, float radius)`
+
+约定：
+- 可视化逻辑与伤害逻辑解耦。
+- 武器类只负责触发 `Play`，不把可视化细节塞回武器核心逻辑。
+- 当前阶段允许临时对象创建；后续若有性能压力再统一对象池化。
+
+## 数据层规范（DRWeapon / WeaponData）
+`DRWeapon` 提供通用字段：
+- `Attack`、`Cooldown`、`AttackRange`、`AttackSoundId`
+- `Pramas`（字典，Key 建议统一转小写）
+- `Modifiers`
+
+约定：
+- 参数解析尽量在数据层/初始化阶段完成。
+- 武器逻辑层读取 `WeaponData` 的强类型结果，不要散落 `Parse`。
+- 解析时必须容错：优先 `TryParse` + 默认值，避免运行时异常。
+
+## 新增武器标准流程
+1. 定义枚举
+   - 更新 `WeaponType`（保持递增值，避免重排已有值）。
+
+2. 建立数据类
+   - 新建 `WeaponXxxData : WeaponData`。
+   - 如果有独有参数，提供强类型字段或统一初始化逻辑。
+
+3. 建立行为类
+   - 新建 `WeaponXxx : WeaponBase`。
+   - 只实现差异化逻辑：`BuildStates`、`Check`、`Attack`、特有检测/动画。
+
+4. 建立状态类
+   - 推荐放在 `Weapon/WeaponXxx/` 目录，采用 partial 组织：
+     - `WeaponXxx.cs`
+     - `WeaponXxx.IdleState.cs`
+     - `WeaponXxx.CheckOutRangeState.cs`
+     - `WeaponXxx.CheckInRangeState.cs`
+     - `WeaponXxx.AttackState.cs`
+
+5. 建立可视化（可选）
+   - 新建 `WeaponXxxAttackEffect : IWeaponAttackEffect`，在武器中组合调用。
+
+6. 若为远程武器，建立子弹实体
+   - `BulletXxx : Bullet`
+   - `BulletXxxData : BulletData`
+   - 通过武器赋予伤害/阵营参数。
+   - 自动销毁应走对象池回收。
+
+7. 接入实体展示与数据表
+   - 确保 `DRWeapon` / `DREntity` 配置齐全。
+   - `EntityExtension.ShowWeapon` 可正确映射到 `Entity.Weapon.WeaponXxx`。
+
+8. 联动系统
+   - 背包、商店购买/出售、UI 展示、事件流刷新。
+
+## 代码检查清单（提交前）
+  - 是否重复实现了 `WeaponBase` 已有通用逻辑。
+    - 状态流转是否会卡死或漏转场。
+    - 冷却计时是否在无目标时仍正常累积。
+    - 目标失效（null/Unavailable/死亡）是否安全处理。
+    - 命中检测是否符合武器设计（地面范围/射线/扇形）。
+    - 数据参数是否全部容错解析。
+    - 可视化是否与伤害逻辑解耦。
+    - 是否正确订阅/解绑攻击属性（或复用基类方法）。
+
+## 已知注意点
+  - 目录中存在 `Pramas` 命名拼写历史包袱，保持兼容即可。
+    - 文档中的“规范”优先级高于历史实现；历史实现若偏离，按本规范逐步收敛。