9.6 KiB
9.6 KiB
Weapon Development Skill（VampireLike）
目标
本文件是 Entity.Weapon 体系的开发规范与速查手册。
后续新增武器、扩展参数、调整状态机或联动商店/背包时，优先按本文档执行，避免重复通读历史上下文。
当前架构总览
- 武器运行时入口：
WeaponBase（Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponBase.cs） - 武器具体实现：
WeaponKnife、WeaponHandgun、WeaponSlash、WeaponLightning - 目标选择策略：
ITargetSelector+TargetSelectorType - 攻击可视化：
IWeaponAttackEffect - 数据入口：
DRWeapon->WeaponData（及其子类） - 实体生成：
EntityExtension.ShowWeapon - 商店接入：
ShopFormUseCase.CreateWeaponData
WeaponBase 统一职责（已上收）
WeaponBase 负责以下通用逻辑，子类不要重复实现：
- 生命周期模板：
OnShow/OnHide/OnAttachTo/OnDetachFrom - 状态机管理：
RegisterState、EnsureStatesBuilt、TransitionTo - 通用运行字段：
_target、_currAttackTimer、_sqrRange - 启用门控：
OnUpdate中统一if (!_isEnabled) return - 目标选择入口：
SelectTarget、SetTargetSelector、CreateSelector - 距离判定：
IsInRange（基于 XZ 平面距离） - Simulation 命中请求：
TryQueueAreaCollisionQuery、TryQueueSectorCollisionQuery - 玩家攻击属性订阅：
BindAttackStatFromOwner/ReleaseAttackStatSubscription
约束：
- 不要在子类里重复实现
WeaponBase已有能力。 - 行为差异优先收敛在：
BuildStates、Check、Attack、少量专属辅助方法。
当前武器模板分类
1. WeaponKnife
- 模式：近身前刺 + 圆形范围命中
- 典型参数：
HitRadius - 适合派生：长枪、刺剑、短矛、震地锤近身版
2. WeaponHandgun
- 模式：单次
Raycast瞬发命中 - 当前参数化程度较低，仍适合作为远程枪械母版继续扩展
- 适合派生：手枪、霰弹枪、狙击枪、三连发枪
3. WeaponSlash
- 模式：扇形范围命中
- 典型参数：
SectorAngle - 适合派生：大剑、斧头、半月斩、横扫类武器
4. WeaponLightning
- 模式：锁定目标点 + 落点范围打击
- 典型参数：
HitRadius、HoverHeight - 适合派生：闪电、陨石杖、圣光柱、空袭类武器
状态机约定
统一状态枚举：
IdleCheck_OutRangeCheck_InRangeAttackDisabled（可选）
推荐流程：
Idle：查找目标，计时器持续累积。Check_OutRange：有目标但不在攻击范围，继续转向并累积计时。Check_InRange：在攻击范围内，若currAttackTimer >= Cooldown切Attack。Attack：执行攻击，重置计时器，结束后回Check_InRange。
关键规则：
- 即使没有目标，也允许蓄力（计时器持续走）。
- 一旦进入
Check_InRange且冷却已满，应立即触发攻击。 - 攻击过程中若需要多帧动画，使用
_isAttacking控制状态退出时机。
3D 场景下的距离/朝向原则
- 射程与目标筛选：优先使用 XZ 平面距离（忽略 Y），调用
AIUtility.GetSqrMagnitudeXZ。 - 视觉朝向与弹道：可按武器设计决定是否使用完整 3D 向量。
WeaponHandgun：允许俯仰瞄准，逻辑上用射线命中对象判定伤害。- 近战地面范围类（Knife/Slash）：伤害检测建议投影到地面（XZ）再判定。
- 落点类（Lightning）：锁点可取目标当前位置，但范围判定仍建议按地面距离收口。
目标选择策略规范
接口：ITargetSelector.SelectTarget(WeaponBase weapon, IEnumerable<EntityBase> candidates, float maxSqrRange)
现有策略：
NearestTargetSelectorHighestHealthTargetSelectorLowestHealthTargetSelector
语义约定：
NearestTargetSelector在 Simulation 启用时优先走空间索引。HighestHealth/LowestHealth当前基于运行时生命值选择目标。- 若新增新策略，必须明确“按当前值”还是“按最大值”筛选，避免语义漂移。
扩展策略步骤：
- 新建 selector 类并实现
ITargetSelector。 - 更新
TargetSelectorType枚举。 - 在
WeaponBase.CreateSelector中注册。 - 武器在
OnWeaponShow或初始化阶段选择策略。
攻击可视化效果规范
接口：IWeaponAttackEffect.Play(WeaponBase weapon, Vector3 position, EntityBase target, float radius)
约定：
- 可视化逻辑与伤害逻辑解耦。
- 武器类只负责触发
Play，不把可视化细节塞回武器核心逻辑。 - 当前阶段允许临时对象创建；后续若有性能压力再统一对象池化。
- 命中特效、范围预警、扇形描边都属于 effect 层，不属于伤害层。
数据层规范（DRWeapon / WeaponData）
DRWeapon
提供通用字段：
AttackCooldownAttackRangeAttackSoundIdParamsJsonPramasModifiers
约定：
Params列现在使用标准 JSON 对象。- 空参数统一写
{}。 - 不再兼容
[]。 Pramas保留为描述/UI 的兼容字典视图，不再作为武器逻辑主读取入口。
WeaponData
提供公共武器字段与通用解析入口：
- 公共战斗字段：
Attack、Cooldown、AttackRange - 公共展示字段：
Title、IconAssetName、Rarity、Price - 参数入口：
ParamsJson、Params - 通用强类型解析：
ParseParams<TParams>()
约定：
- 参数解析优先在数据层完成。
- 武器逻辑层读取强类型
ParamsData，不要散落字符串Parse。 - 只有描述/UI 等弱类型场景才继续读取
Params字典。
具体武器数据子类
每种武器数据子类都应持有自己的 ParamsData：
WeaponKnifeData -> WeaponKnifeParamsDataWeaponHandgunData -> WeaponHandgunParamsDataWeaponSlashData -> WeaponSlashParamsDataWeaponLightningData -> WeaponLightningParamsData
当前已接通字段：
WeaponKnifeParamsDataHitRadius
WeaponHandgunParamsData- 暂无字段
WeaponSlashParamsDataSectorAngle
WeaponLightningParamsDataHitRadiusHoverHeight
JSON 约束：
- key 名应与
ParamsData属性名一致。 - 统一使用 JSON 对象，不要再使用自定义 KV 串。
- 不建议在
ParamsJson中使用制表符和跨行内容，避免 txt 表分列出错。
新增武器标准流程
-
定义枚举
- 更新
WeaponType，保持递增值，避免重排已有值。
- 更新
-
建立数据类
- 新建
WeaponXxxData : WeaponData。 - 新建
WeaponXxxParamsData。 - 在构造阶段调用
ParseParams<TParams>()，把参数初始化为强类型字段。
- 新建
-
建立行为类
- 新建
WeaponXxx : WeaponBase。 - 只实现差异化逻辑：
BuildStates、Check、Attack、特有检测/动画。
- 新建
-
建立状态类
- 推荐放在
Weapon/WeaponXxx/目录，采用 partial 组织：WeaponXxx.csWeaponXxx.IdleState.csWeaponXxx.CheckOutRangeState.csWeaponXxx.CheckInRangeState.csWeaponXxx.AttackState.cs
- 推荐放在
-
建立可视化（可选）
- 新建
WeaponXxxAttackEffect : IWeaponAttackEffect，在武器中组合调用。
- 新建
-
接入实体展示与数据表
- 确保
DRWeapon/DREntity配置齐全。 EntityExtension.ShowWeapon可正确映射到Entity.Weapon.WeaponXxx。- 商店/背包创建入口能正确构造
WeaponXxxData。
- 确保
-
联动系统
- 背包、商店购买/出售、UI 展示、事件流刷新。
-
验证点
- 武器能正确生成、附着、更新。
ParamsData与数据表一致。- 描述文本仍正确展示。
- Simulation 模式和非 Simulation 模式都能命中。
扩展优先级建议
第一批：低成本高收益
- 长枪 / 刺剑
- 基于
WeaponKnife
- 基于
- 大剑 / 半月斩
- 基于
WeaponSlash
- 基于
- 战锤 / 震地锤
- 基于
WeaponLightning或WeaponKnife
- 基于
- 霰弹枪
- 基于参数化后的
WeaponHandgun
- 基于参数化后的
- 狙击枪
- 基于参数化后的
WeaponHandgun
- 基于参数化后的
- 陨石杖 / 圣光柱
- 基于
WeaponLightning
- 基于
第二批：中成本扩展
- 链式闪电
- 穿透弹 / 火球
- 地雷 / 陷阱
- 回旋镖
暂缓项
- 持续激光
- 喷火器
- 环绕飞剑
- 常驻法球
- 状态异常驱动的复杂武器流派
原因：
- 当前武器主流程仍是单次攻击结算。
- 持续伤害、异常状态和常驻 orbit 行为尚未形成统一挂点。
WeaponHandgun 后续建议
当前 WeaponHandgun 参数化仍偏弱，建议作为下一阶段母版优先扩展。
建议新增字段：
PelletCountSpreadAnglePenetrationCountFireOriginOffsetXFireOriginOffsetYFireOriginOffsetZHitMarkerSizeHitMarkerYOffsetHitMarkerDuration
完成后可快速派生：
- 手枪
- 霰弹枪
- 狙击枪
- 三连发枪
代码检查清单（提交前）
- 是否重复实现了
WeaponBase已有通用逻辑。 - 状态流转是否会卡死或漏转场。
- 冷却计时是否在无目标时仍正常累积。
- 目标失效（null/Unavailable/死亡）是否安全处理。
- 命中检测是否符合武器设计（地面范围/射线/扇形/落点）。
- 数据参数是否全部收敛到
ParamsData。 - 可视化是否与伤害逻辑解耦。
- 是否正确订阅/解绑攻击属性（或复用基类方法）。
- 商店、背包、武器描述是否仍保持兼容。
已知注意点
- 目录中存在
Pramas命名拼写历史包袱，当前保持兼容即可。 - 文档中的“规范”优先级高于历史实现；历史实现若偏离，按本规范逐步收敛。
- 当前更推荐“公共
WeaponData+ 专属ParamsData”结构，不建议把每种武器做成一套完全独立的数据总线。