367 lines
16 KiB
Markdown
367 lines
16 KiB
Markdown
# WeaponSO 武器调参指南
|
||
|
||
**配置文件**：`Assets/_Game/Data/Combat/Weapons/WPN_*.asset`
|
||
**对应脚本**：`WeaponSO.cs` · `ComboStepConfig` · `WeaponVFXConfig`
|
||
**创建工具**：Unity 菜单 `BaseGames/Data/Weapon Editor`（勿直接在 Project 窗口创建）
|
||
**影响系统**：`WeaponManager` · `WeaponHitBoxInstance` · `PlayerCombat` · `FormController`
|
||
|
||
---
|
||
|
||
## 一、架构概述
|
||
|
||
```
|
||
WeaponSO
|
||
├── 基础信息（weaponId / displayName / icon / weaponType）
|
||
├── groundComboSteps[] ── 地面连击（任意段数）
|
||
├── airComboSteps[] ── 空中攻击（通常 1 段）
|
||
├── upStep ── 上劈（固定单段）
|
||
├── downStep ── 下劈（固定单段）
|
||
├── hitBoxPrefab ── 武器 HitBox Prefab（含 WeaponHitBoxInstance）
|
||
├── vfxConfig ── 特效配置
|
||
└── soulPowerGain ── 命中灵力获取量
|
||
|
||
每段攻击的核心数据由 ComboStepConfig 描述：
|
||
ComboStepConfig
|
||
├── clip ── Animancer ClipTransition（动画片段）
|
||
├── damageSource ── DamageSourceSO（伤害参数）
|
||
├── hitBoxEnter/Exit ── HitBox 激活窗口（归一化 0-1）
|
||
├── comboInputOpen/Close── 连击接受窗口（归一化 0-1）
|
||
├── cancelWindowOpen ── 跳跃/冲刺取消窗口（归一化 0-1）
|
||
├── recoveryTime ── 动画结束后硬直（秒）
|
||
├── comboTimeout ── 等待下一段连击的超时（秒）
|
||
└── hitBoxId ── 指定激活 Prefab 中的具名 HitBox（空=方向默认）
|
||
```
|
||
|
||
**WeaponManager** 监听 `FormController.OnFormChanged`，依据当前形态或护符 Override 切换 `ActiveWeapon`，并在 `[WeaponSocket]` 下实例化/池化对应 `hitBoxPrefab`。
|
||
|
||
---
|
||
|
||
## 二、基础信息字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `weaponId` | string | 全局唯一 ID，命名规范：`Weapon_<主题名>`，如 `Weapon_SkyBlade`。**必须唯一，运行时依此检索。** |
|
||
| `displayName` | string | UI 显示名，如 `天裂刃`。 |
|
||
| `icon` | Sprite | HUD / 物品栏图标。 |
|
||
| `weaponType` | WeaponType | 枚举，影响动画控制器分支和特殊逻辑：`TianHun`（天魂）/ `DiHun`（地魂）/ `MingHun`（命魂）/ `Custom`。 |
|
||
|
||
---
|
||
|
||
## 三、ComboStepConfig 字段详解
|
||
|
||
### 3.1 动画 & 伤害
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `clip` | ClipTransition | Animancer 动画片段引用。在 Inspector 中直接拖入 AnimationClip 资产，Animancer 自动包装为 Transition。 |
|
||
| `damageSource` | DamageSourceSO | 本段攻击的伤害数据 SO（详见第五节）。**每段连击可独立配置不同伤害参数**，如首段轻击、末段重击。 |
|
||
|
||
### 3.2 HitBox 激活窗口（归一化 0-1）
|
||
|
||
> 所有归一化时间均相对于该段动画片段的**总时长**。0 = 动画开始，1 = 动画结束。
|
||
|
||
| 字段 | 范围 | 说明 |
|
||
|---|---|---|
|
||
| `hitBoxEnter` | [0, 1] | HitBox Collider2D 开启时间点。过早会导致判定在动作启动前已生效（容易打中玩家不期待的时机）。 |
|
||
| `hitBoxExit` | [0, 1] | HitBox Collider2D 关闭时间点。`hitBoxExit > hitBoxEnter`，差值越大判定活跃窗口越长。 |
|
||
|
||
**经验准则**：
|
||
- 轻击：窗口宽度约 `0.25-0.35`（如 `Enter=0.25, Exit=0.55`）
|
||
- 重击：窗口宽度约 `0.35-0.55`（动作前摇长，Enter 较晚）
|
||
- 判定窗口开始前应能看到挥砍动作的启动帧，避免"隐形打击"
|
||
|
||
### 3.3 连击输入窗口（归一化 0-1）
|
||
|
||
| 字段 | 范围 | 说明 |
|
||
|---|---|---|
|
||
| `comboInputOpen` | [0, 1] | 从此时间点起**开始接受**下一段连击输入。设为 `0` = 动画一开始就可以缓冲输入。 |
|
||
| `comboInputClose` | [0, 1] | 从此时间点起**停止接受**连击输入（必须在 `comboInputOpen` 之后）。设为 `0` = 持续到动画结束。 |
|
||
|
||
**经验准则**：
|
||
- `comboInputOpen` 建议设在 HitBox 激活之后（让玩家确认打中后才能输入连击）
|
||
- 对于高速连击，`comboInputOpen = 0`（从头缓冲）可提升流畅感
|
||
- `comboInputClose = 0`（持续到动画结束）是最宽松的设定，适合友好手感
|
||
|
||
### 3.4 取消窗口（归一化 0-1）
|
||
|
||
| 字段 | 范围 | 说明 |
|
||
|---|---|---|
|
||
| `cancelWindowOpen` | [0, 1] | 从此时间点起**允许跳跃/冲刺打断**本段攻击。设为 `0` = 仅在动画结束后的恢复期内允许取消。 |
|
||
|
||
**经验准则**：
|
||
- 过早打开（如 `0.2`）会让攻击感觉"没有重量"，玩家容易意外取消
|
||
- 推荐在动画进入收招阶段时开放，约 `0.5-0.6`
|
||
- 下劈攻击（Pogo 跳）通常设得较早（`0.3`），便于空中快速接跳
|
||
|
||
### 3.5 时间参数（秒，受攻速倍率缩放）
|
||
|
||
| 字段 | 最小值 | 说明 |
|
||
|---|---|---|
|
||
| `recoveryTime` | 0 | 动画结束后的**硬直时间**（秒），期间跳跃/冲刺无法打断。模拟挥空后的惯性/踉跄。 |
|
||
| `comboTimeout` | 0 | 硬直结束后**等待连击输入的时间**（秒）。超时则返回 Idle 状态。设为 `0` = 立即返回 Idle。 |
|
||
|
||
> ⚠️ 这两个参数受攻速倍率缩放。`recoveryTime = 0.05f` 是默认最低有效值，不建议设 `0`（否则帧序列可能出现单帧状态切换问题）。
|
||
|
||
### 3.6 HitBox 绑定 ID
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `hitBoxId` | 留空 → 使用该方向的**默认 HitBox**（WeaponHitBoxInstance 中对应方向的字段）；<br>非空 → **按 Id 精确激活** Prefab 中对应子节点的 HitBox，可为每段连击配置不同的判定形状。 |
|
||
|
||
**使用时机**：
|
||
- 连击首段和末段的判定范围不同时（如末段范围更大）
|
||
- 需要多个独立判定区域时（如武器特殊技能）
|
||
|
||
---
|
||
|
||
## 四、DamageSourceSO 关键参数
|
||
|
||
每个 `ComboStepConfig.damageSource` 引用一个独立的 `DamageSourceSO` 资产，资产命名规范：`CMB_DmgSrc_<武器ID>_<段序号>.asset`，存放于 `_Game/Data/Combat/DamageSources/`。
|
||
|
||
| 字段 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `BaseDamage` | 10 | 本段攻击基础伤害值（整型）。 |
|
||
| `DamageMultiplier` | 1.0 | 倍率，最终伤害 = `Round(BaseDamage × DamageMultiplier)`。 |
|
||
| `Type` | Normal | 伤害元素类型（`Normal` / `Fire` / `Poison` / `Ice` / `Lightning` / `Void` / `True`）。`True` = 无视防御的真实伤害。 |
|
||
| `Category` | NormalAttack | 来源分类，影响护符/技能的条件判断（如"普通攻击命中时触发"）。 |
|
||
| `Flags` | CanBeParried | 行为标志（可组合）。常见组合见下表。 |
|
||
| `Tags` | MeleeHit | 交互标签（可组合），配合 DamageTags 枚举使用。 |
|
||
| `KnockbackForce` | 5.0 | 击退力度（单位/秒，直接施加速度）。 |
|
||
| `HitStunDuration` | 0.1 | 击中后的受击硬直时间（秒）。 |
|
||
| `BreakLevel` | Light | 攻击方打断等级，与敌人 `PoiseLevel` 比较决定是否打断霸体。 |
|
||
| `FxType` | Slash | 命中特效类型，决定播放哪套打击感反馈预设。 |
|
||
|
||
**DamageFlags 常用组合**：
|
||
|
||
| 组合 | 适用场景 |
|
||
|---|---|
|
||
| `CanBeParried` | 普通攻击（可被格挡） |
|
||
| `CanBeParried \| CanClash` | 可碰撞武器（弹反对碰） |
|
||
| `Unblockable` | 突破技/破防攻击 |
|
||
| `CanBeParried \| PerfectParryOnly` | 高危攻击，仅完美格挡才能弹反 |
|
||
| `NoKnockback` | 固定伤害（毒、灼烧等 DoT 不需要击退） |
|
||
|
||
---
|
||
|
||
## 五、WeaponVFXConfig 字段
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `onEquipPresetId` | 切换到此武器时播放的特效预设 ID，对应 `IFeedbackPlayer.TriggerPreset`。空 = 不播放切换特效。 |
|
||
| `weaponTrailPrefab` | 挥斩拖尾 Prefab（null = 不显示拖尾）。拖尾 Prefab 应含 `TrailRenderer` 或自定义拖尾脚本。 |
|
||
| `trailColor` | 拖尾颜色，可在 Inspector 中用 HDR 色板设定发光颜色。默认白色。 |
|
||
|
||
---
|
||
|
||
## 六、战斗参数
|
||
|
||
| 字段 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `soulPowerGain` | 10 | **命中确认时增加的灵力值**，覆盖 PlayerCombat 全局默认值（也为 10）。可对强力武器设更高值（如 DiHun 重击设 15-20），鼓励玩家积极进攻。 |
|
||
|
||
---
|
||
|
||
## 七、推荐配置
|
||
|
||
### 7.1 时间轴可视化参考
|
||
|
||
以下图示展示一段典型地面连击的时间轴布局（归一化 0-1）：
|
||
|
||
```
|
||
0 ────────────────────────────────────── 1 （动画片段）
|
||
│←── HitBox 激活窗口 ──→│
|
||
hitBoxEnter(0.25) hitBoxExit(0.60)
|
||
|
||
│←── 连击输入开放 ─────────────────────→│
|
||
comboInputOpen(0.20) comboInputClose(0=持续到结束)
|
||
|
||
│← 取消窗口(可跳/冲) →│
|
||
cancelWindowOpen(0.50)
|
||
|
||
完整时间轴：
|
||
[动画] ────────────────────────── [recoveryTime] [comboTimeout]
|
||
|←─ 0.05s ──→||←── 0.25s ──→|
|
||
```
|
||
|
||
### 7.2 天魂 TianHun（高频轻击，如天裂刃）
|
||
|
||
> 定位：高频连击，4 段地面 + 1 段空中，每段伤害低但命中频繁，玩家可快速积累灵力。
|
||
|
||
#### 地面连击（4 段）
|
||
|
||
| 参数 | 第 1 段 | 第 2 段 | 第 3 段 | 第 4 段（末段） |
|
||
|---|---|---|---|---|
|
||
| `hitBoxEnter` | 0.25 | 0.20 | 0.20 | 0.30 |
|
||
| `hitBoxExit` | 0.55 | 0.50 | 0.55 | 0.70 |
|
||
| `comboInputOpen` | 0.20 | 0.15 | 0.15 | 0 |
|
||
| `comboInputClose` | 0 | 0 | 0 | 0 |
|
||
| `cancelWindowOpen` | 0.55 | 0.50 | 0.50 | 0.60 |
|
||
| `recoveryTime` | 0.05 | 0.05 | 0.05 | 0.08 |
|
||
| `comboTimeout` | 0.20 | 0.20 | 0.20 | 0.15 |
|
||
|
||
#### 空中攻击（1 段）
|
||
|
||
| 参数 | 推荐值 |
|
||
|---|---|
|
||
| `hitBoxEnter` | 0.10 |
|
||
| `hitBoxExit` | 0.70 |
|
||
| `comboInputOpen` | 0 |
|
||
| `cancelWindowOpen` | 0.40 |
|
||
| `recoveryTime` | 0.05 |
|
||
|
||
#### 上劈 / 下劈
|
||
|
||
| 参数 | 上劈 | 下劈 |
|
||
|---|---|---|
|
||
| `hitBoxEnter` | 0.20 | 0.10 |
|
||
| `hitBoxExit` | 0.65 | 0.85 |
|
||
| `cancelWindowOpen` | 0.55 | 0.30（早开放，便于 Pogo） |
|
||
| `recoveryTime` | 0.05 | 0.05 |
|
||
|
||
#### DamageSource 参数（天魂各段参考）
|
||
|
||
| 参数 | 第 1-3 段 | 第 4 段（末段） |
|
||
|---|---|---|
|
||
| `BaseDamage` | 8 | 12 |
|
||
| `DamageMultiplier` | 1.0 | 1.2 |
|
||
| `KnockbackForce` | 3.0 | 5.0 |
|
||
| `HitStunDuration` | 0.08 | 0.12 |
|
||
| `BreakLevel` | Light | Medium |
|
||
| `FxType` | Slash | Slash |
|
||
| `Flags` | CanBeParried | CanBeParried |
|
||
|
||
**soulPowerGain**：`10`（每段命中均为标准值，高频命中本身已能快速积累）
|
||
|
||
---
|
||
|
||
### 7.3 地魂 DiHun（低频重击，如地震锤）
|
||
|
||
> 定位：2 段地面，前摇长、打击感强，单段伤害高，击退效果明显，适合破霸体。
|
||
|
||
#### 地面连击（2 段）
|
||
|
||
| 参数 | 第 1 段 | 第 2 段（蓄力重击） |
|
||
|---|---|---|
|
||
| `hitBoxEnter` | 0.40 | 0.50 |
|
||
| `hitBoxExit` | 0.70 | 0.85 |
|
||
| `comboInputOpen` | 0.35 | 0 |
|
||
| `comboInputClose` | 0 | 0 |
|
||
| `cancelWindowOpen` | 0.65 | 0.70 |
|
||
| `recoveryTime` | 0.12 | 0.20 |
|
||
| `comboTimeout` | 0.30 | 0.20 |
|
||
|
||
#### 空中攻击（1 段，范围攻击）
|
||
|
||
| 参数 | 推荐值 |
|
||
|---|---|
|
||
| `hitBoxEnter` | 0.20 |
|
||
| `hitBoxExit` | 0.80 |
|
||
| `cancelWindowOpen` | 0.60 |
|
||
| `recoveryTime` | 0.10 |
|
||
|
||
#### DamageSource 参数（地魂各段参考）
|
||
|
||
| 参数 | 第 1 段 | 第 2 段 |
|
||
|---|---|---|
|
||
| `BaseDamage` | 18 | 28 |
|
||
| `DamageMultiplier` | 1.0 | 1.3 |
|
||
| `KnockbackForce` | 7.0 | 12.0 |
|
||
| `HitStunDuration` | 0.15 | 0.25 |
|
||
| `BreakLevel` | Medium | Heavy |
|
||
| `FxType` | Heavy | Heavy |
|
||
| `Flags` | CanBeParried \| CanClash | CanBeParried \| CanClash |
|
||
|
||
**soulPowerGain**：`18`（重击命中奖励更多灵力，鼓励玩家进行高风险的大招命中）
|
||
|
||
---
|
||
|
||
### 7.4 命魂 MingHun（穿透直线斩，命镰）
|
||
|
||
> 定位：3 段地面，带穿透 Tag，直线攻击范围长，无强力击退，适合多目标清线。
|
||
|
||
#### 地面连击（3 段）
|
||
|
||
| 参数 | 第 1 段 | 第 2 段 | 第 3 段（穿透斩） |
|
||
|---|---|---|---|
|
||
| `hitBoxEnter` | 0.20 | 0.20 | 0.25 |
|
||
| `hitBoxExit` | 0.55 | 0.55 | 0.75 |
|
||
| `comboInputOpen` | 0.20 | 0.20 | 0 |
|
||
| `comboInputClose` | 0 | 0 | 0 |
|
||
| `cancelWindowOpen` | 0.50 | 0.50 | 0.60 |
|
||
| `recoveryTime` | 0.06 | 0.06 | 0.10 |
|
||
| `comboTimeout` | 0.25 | 0.25 | 0.20 |
|
||
|
||
#### DamageSource 参数（命魂各段参考）
|
||
|
||
| 参数 | 第 1-2 段 | 第 3 段（穿透） |
|
||
|---|---|---|
|
||
| `BaseDamage` | 10 | 16 |
|
||
| `DamageMultiplier` | 1.0 | 1.1 |
|
||
| `KnockbackForce` | 2.0 | 3.0 |
|
||
| `HitStunDuration` | 0.10 | 0.12 |
|
||
| `BreakLevel` | Light | Light |
|
||
| `FxType` | Slash | Void |
|
||
| `Flags` | CanBeParried | CanBeParried |
|
||
| `Tags` | MeleeHit | MeleeHit \| DeathFormOnly |
|
||
|
||
**soulPowerGain**：`12`（中等收益，穿透多目标时单次激活返回较多灵力）
|
||
|
||
---
|
||
|
||
## 八、三武器横向对比
|
||
|
||
| 属性 | TianHun（天魂） | DiHun（地魂） | MingHun（命魂） |
|
||
|---|---|---|---|
|
||
| 连击段数 | 4 段 | 2 段 | 3 段 |
|
||
| 单段基础伤害 | 8-12 | 18-28 | 10-16 |
|
||
| 击退力度 | 低（3-5） | 高（7-12） | 极低（2-3） |
|
||
| HitStun | 短（0.08-0.12s） | 长（0.15-0.25s） | 中（0.10-0.12s） |
|
||
| BreakLevel | Light → Medium | Medium → Heavy | Light |
|
||
| HitBox 窗口宽度 | 窄（~0.30） | 宽（~0.35） | 中（~0.35-0.50） |
|
||
| recoveryTime 末段 | 0.08s | 0.20s | 0.10s |
|
||
| soulPowerGain | 10 | 18 | 12 |
|
||
| 特色 | 高频灵力积累 | 破霸体/强力击退 | 穿透多目标 |
|
||
|
||
---
|
||
|
||
## 九、HitBox Prefab 配置要点
|
||
|
||
命名规范：`WPN_{weaponId}_HitBox.prefab`，存放于 `Assets/_Game/Prefabs/Weapons/`
|
||
|
||
```
|
||
[WPN_SkyBlade_HitBox] ← WeaponHitBoxInstance 脚本
|
||
├── [HitBox_Ground] Id="" ← 方向默认（Inspector 引用到 _hitBoxGround）
|
||
├── [HitBox_Ground_3] Id="g3" ← 第 3 段专属判定（更大范围）
|
||
├── [HitBox_Up] Id="" ← 上劈默认（Inspector 引用到 _hitBoxUp）
|
||
├── [HitBox_Down] Id="" ← 下劈默认（Inspector 引用到 _hitBoxDown）
|
||
└── [HitBox_Air] Id="" ← 空中默认（Inspector 引用到 _hitBoxAir）
|
||
```
|
||
|
||
- **不要**在 HitBox Prefab 上挂 Rigidbody2D（由父节点 Player 提供物理）
|
||
- Collider2D 默认 **disabled**，由 `HitBox.Activate()` 开启
|
||
- 多段攻击需要不同判定形状时，添加具名子节点，在对应 `ComboStepConfig.hitBoxId` 中填写对应 Id
|
||
|
||
---
|
||
|
||
## 十、常见调参问题排查
|
||
|
||
| 现象 | 可能原因 | 排查方向 |
|
||
|---|---|---|
|
||
| 攻击时判定出现太早，感觉"不对" | `hitBoxEnter` 过小 | 调高至 0.25-0.35，与动画挥砍帧对齐 |
|
||
| 连击无法触发，只能打第 1 段 | `comboInputOpen` 太晚或 `comboInputClose` 太早 | 调低 `comboInputOpen`（或设 0），确认 `comboInputClose` 为 0 |
|
||
| 攻击后无法立即跳跃/冲刺 | `cancelWindowOpen` 过大或 `recoveryTime` 过长 | 降低 `cancelWindowOpen`（0.50-0.55），减小 `recoveryTime` |
|
||
| 末段后角色卡顿太久才能动 | `recoveryTime` + `comboTimeout` 总计过长 | 减小其中一个或两者都减小 |
|
||
| HitBox 命中范围与动画不匹配 | HitBox Prefab 中 Collider2D 形状未对齐 | 在 Scene 视图的 Gizmos 开启后，逐帧检查碰撞体位置 |
|
||
| 连击结束后立刻返回 Idle，没有残影感 | `comboTimeout = 0` | 设为 `0.15-0.25s`，让玩家有余裕进行下一段连击 |
|
||
| 重击前摇太短，没有"蓄力感" | `hitBoxEnter` 过小（前摇太短就进入判定） | 调高至 0.40-0.55，延长前摇 |
|
||
| 空中攻击结束后角色位移异常 | HitBox 取消窗口过早，冲刺接入空攻状态 | 调高 `cancelWindowOpen`（≥ 0.50）或检查状态机过渡条件 |
|
||
| 命中无灵力回复 | `damageSource` 引用为空，或 `soulPowerGain = 0` | 检查每个 ComboStepConfig 的 `damageSource` 字段不为 null |
|
||
|
||
---
|
||
|
||
## 十一、修改历史
|
||
|
||
| 日期 | 修改内容 |
|
||
|---|---|
|
||
| 2026-05-22 | 初版：覆盖 WeaponSO 全部字段说明、三武器推荐配置及调参排查表 |
|