# 玩家跳跃 / 冲刺手感调参指南

**配置文件**：`Assets/_Game/ScriptableObjects/Player/PlayerMovementConfig.asset`  
**对应脚本**：`PlayerMovementConfigSO.cs`  
**影响状态**：`JumpState` · `FallState` · `DashState` · `AerialDashState`

---

## 一、跳跃系统

### 1.1 物理模型概述

跳跃分为三段，每段使用不同的有效重力：

```
vy ↑
    │   ╭──╮      ← ② 顶点悬停段：|vy| < ApexThreshold，
    │  ╯    ╰╮       重力 = DefaultGravityScale × ApexGravityMultiplier
    │ ╯       ╰────  ← ③ 下落段（FallState）：
    │╯                   重力 = DefaultGravityScale（由 Unity 施加）
    │ ↑ ① 上升段          + FallGravityMult 额外速度叠加
────┼──────────────→ 时间
```

| 阶段 | 激活状态 | 有效重力 |
|---|---|---|
| ① 上升 | `JumpState`（|vy| ≥ ApexThreshold） | `9.81 × DefaultGravityScale` |
| ② 顶点悬停 | `JumpState`（|vy| < ApexThreshold） | `9.81 × DefaultGravityScale × ApexGravityMultiplier` |
| ③ 下落 | `FallState` | `9.81 × DefaultGravityScale` + `9.81 × (FallGravityMult−1) / FixedDeltaTime` |

---

### 1.2 参数说明与推荐值

#### 基础重力

| 参数 | 类型 | 当前默认 | 推荐（高速手感） | 说明 |
|---|---|---|---|---|
| `DefaultGravityScale` | float | 3.0 | **6.0** | Rigidbody2D 的 gravityScale。越高上升减速越快、跳跃弧线越短促。**这是影响整体跳跃节奏的最核心参数。** |

> ⚠️ 修改 `DefaultGravityScale` 后必须同步调整 `JumpForce`，否则弹跳高度会改变。

#### 跳跃初速

| 参数 | 类型 | 当前默认 | 推荐（高速手感） | 说明 |
|---|---|---|---|---|
| `JumpForce` | float | 19.0 | **24.0** | 按下跳跃键瞬间赋予的垂直速度（单位/秒）。 |
| `DoubleJumpForce` | float | 19.0 | **24.0** | 二段跳/空中追加跳的垂直速度。通常与 JumpForce 保持一致以获得等高跳跃。 |

**跳跃高度速查公式**（忽略顶点悬停段）：

$$H_{apex} \approx \frac{JumpForce^2}{2 \times 9.81 \times DefaultGravityScale}$$

| DefaultGravityScale | JumpForce = 19 | JumpForce = 24 |
|---|---|---|
| 3.0 | ≈ 6.1 单位 | ≈ 9.8 单位 |
| 5.0 | ≈ 3.7 单位 | ≈ 5.9 单位 |
| 6.0 | ≈ 3.1 单位 | ≈ 4.9 单位 |

#### 顶点悬停

| 参数 | 类型 | 当前默认 | 推荐（高速手感） | 说明 |
|---|---|---|---|---|
| `ApexThreshold` | float | 3.0 | **3.0** | 当 \|垂直速度\| 低于此值时触发悬停。单位：单位/秒。 |
| `ApexGravityMultiplier` | float [0,1] | 0.3 | **0.3** | 悬停期间重力系数。0 = 完全停止；1 = 无效果。 |

**调整方向**：
- 想要更明显的"飘"感 → 调高 `ApexThreshold`（更早进入悬停）或调低 `ApexGravityMultiplier`
- 想要更紧实干脆 → 调低 `ApexThreshold`（接近 0 等于关闭功能）

#### 下落段

| 参数 | 类型 | 当前默认 | 推荐（高速手感） | 说明 |
|---|---|---|---|---|
| `FallGravityMult` | float | 3.5 | **2.5** | 在 FallState 中每 FixedUpdate 额外叠加的速度量 = `9.81 × (FallGravityMult−1) × fixedDeltaTime`。注意：已有 DefaultGravityScale 提供基础重力，此值是**叠加量**，不是总倍率。 |
| `MaxFallSpeed` | float | 22.0 | **28.0** | 终端速度（最大下落速度，单位/秒）。防止无限加速。 |

> 💡 `DefaultGravityScale = 6` 时，基础下落加速度已达 `58.9 m/s²`，`FallGravityMult` 只需设 2.5（额外 14.7 m/s²）即可达到总体 `73.6 m/s²` 的快速下落，等效重力倍率约 **7.5×**。`FallGravityMult` 不需要再设很高。

#### 变高跳（松键截断）

| 参数 | 类型 | 当前默认 | 推荐（高速手感） | 说明 |
|---|---|---|---|---|
| `JumpCutMultiplier` | float [0,1] | 0.35 | **0.35** | 松开跳跃键时将当前垂直速度乘以此值。越小 → 短跳越矮，跳跃高度范围越大。 |
| `CoyoteTime` | float | 0.12 | **0.10** | 离开平台边缘后仍可起跳的宽限时间（秒）。 |

#### 最小 / 最大跳跃高度配置方法

跳跃分**短按**（立即松键，速度被截断）和**长按**（全程按住，达到最大高度）：

**高度计算公式**（忽略顶点悬停段微小修正）：

$$H_{max} = \frac{JumpForce^2}{2 \times 9.81 \times DefaultGravityScale}$$

$$H_{min} = \frac{(JumpForce \times JumpCutMultiplier)^2}{2 \times 9.81 \times DefaultGravityScale} = H_{max} \times JumpCutMultiplier^2$$

**反向推导（已知目标高度求参数）**：

$$JumpForce = \sqrt{2 \times 9.81 \times DefaultGravityScale \times H_{max}}$$

$$JumpCutMultiplier = \sqrt{\frac{H_{min}}{H_{max}}}$$

**不同比例对应的 JumpCutMultiplier 参考表**（DefaultGravityScale = 6）：

| 目标 H_max | 目标 H_min | 比例 | JumpForce | JumpCutMultiplier |
|---|---|---|---|---|
| 5.0 单位 | 1.25 单位 | 1:4 | 24.3 | **0.50** |
| 5.0 单位 | 0.80 单位 | 1:6 | 24.3 | **0.41** |
| 5.0 单位 | 0.50 单位 | 1:10 | 24.3 | **0.32** |
| 4.0 单位 | 0.60 单位 | 1:7 | 21.7 | **0.39** |

> 💡 当前推荐值 `JumpCutMultiplier = 0.35` 对应约 **1:8** 的高度比，短按跳跃约为长按的 12%，手感短促有力。  
> 若希望短按有一个明显可见的小跳（约 1 格高），比例控制在 **1:4 ~ 1:5**，`JumpCutMultiplier ≈ 0.45 ~ 0.50`。

---

### 1.3 推荐参数组合

以下三组参数可直接在 SO 中录入作为起点：

| 风格 | DefaultGravityScale | JumpForce | ApexThreshold | ApexGravityMultiplier | FallGravityMult | JumpCutMultiplier |
|---|---|---|---|---|---|---|
| **高速紧实（类空洞骑士）** | 6.0 | 24.0 | 3.0 | 0.30 | 2.5 | 0.35 |
| **标准平台（居中）** | 4.5 | 21.0 | 2.5 | 0.35 | 3.0 | 0.40 |
| **漂浮感（慢节奏）** | 3.0 | 19.0 | 4.0 | 0.20 | 2.0 | 0.50 |

---

### 1.4 跳跃节奏速查（高速紧实组合）

使用 `DefaultGravityScale=6, JumpForce=24, ApexThreshold=3, ApexGravityMultiplier=0.3` 时：

- 上升段时长（vy: 24 → 3）：`(24−3) / (9.81×6) ≈ 0.357s`
- 顶点悬停时长（vy: 3 → 0，重力×0.3）：`3 / (9.81×6×0.3) ≈ 0.170s`
- 总上升时长：`≈ 0.53s`
- 顶点高度：`≈ 5.0 单位`
- 下落至起跳点时长（总重力 ~73.6 m/s²）：`≈ 0.37s`
- **总跳跃时长：≈ 0.90s**

---

## 二、冲刺系统

### 2.1 物理模型概述

```
地面冲刺：  ──────────────────────►  结束 → 双轴速度归零 → Idle/Fall
            重力关闭  DashSpeed      ZeroVelocity() + 恢复重力

空中冲刺：  ──────────────────────►  结束 → 双轴速度归零 → FallState（垂直坠落）
            重力关闭  DashSpeed      ZeroVelocity() + 恢复重力
```

**两者使用完全相同的 `DashSpeed` × `DashDuration`，冲刺距离由设计保证一致。**  
若实测感觉有差异，是地面摩擦/碰撞响应造成的视觉误差，不影响实际数值距离。

**结束行为差异**（设计意图，非 bug）：

| | 地面冲刺结束 | 空中冲刺结束 |
|---|---|---|
| 速度处理 | **`ZeroVelocity()`** — 双轴立即归零 | **`ZeroVelocity()`** — 双轴立即归零 |
| 视觉效果 | 角色在冲刺末端原位停止 | 角色在原位瞬间停止，垂直坠落 |
| 撞墙提前结束 | 同上，`ZeroVelocity()` + 恢复重力 | 同左 |

### 2.2 参数说明与推荐值

| 参数 | 类型 | 当前默认 | 推荐（类空洞骑士） | 说明 |
|---|---|---|---|---|
| `DashSpeed` | float | 25.0 | **22.0** | 冲刺水平速度（单位/秒）。影响单次冲刺位移 = `DashSpeed × DashDuration`。 |
| `DashDuration` | float | 0.35 | **0.30** | 冲刺持续时长（秒）。 |
| `DashCooldown` | float | 0.60 | **0.50** | 落地后到可再次冲刺的等待时长（秒）。 |
| `MaxAerialDashes` | int | 1 | **1** | 每次腾空可使用的空中冲刺次数，落地重置。 |

**单次冲刺水平位移速查**：

| DashSpeed | DashDuration | 水平位移 |
|---|---|---|
| 25.0 | 0.35s | **8.75 单位** |
| 22.0 | 0.30s | **6.60 单位** |
| 20.0 | 0.32s | **6.40 单位** |

> 💡 项目网格如果是 1 unit = 1 格，推荐控制冲刺位移在 **6-8 格**；过长会导致跳过障碍物布局。

### 2.3 无敌帧参数

| 参数 | 类型 | 推荐值 | 说明 |
|---|---|---|---|
| `DashInvincibilityDuration` | float | 0.20 | 冲刺无敌窗口时长（秒）。仅为前段，窗口结束前角色仍在冲刺中可被打断。 |
| `DashInvincibilityCooldown` | float | 0.90 | 无敌帧专属冷却（秒）。CD 内再次冲刺不获得无敌，防止连冲无限无敌。 |

> ⚠️ 无敌功能还依赖 `PlayerStats` 中的 `HasAbility(InvincibleDash)` 能力解锁，未解锁时此参数无效。

---

## 三、常见调参问题排查

| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 跳跃感觉很"飘"，落地慢 | `DefaultGravityScale` 过低，或 `FallGravityMult` 过低 | 调高 DefaultGravityScale（→5-6），同步调高 JumpForce |
| 顶点没有悬停感 | `ApexThreshold` 过低或 `ApexGravityMultiplier` 过高 | 调高 ApexThreshold（→3-5），调低 ApexGravityMultiplier（→0.2-0.3） |
| 短按跳跃与长按高度差不明显 | `JumpCutMultiplier` 过高 | 调低至 0.25-0.35 |
| 空中冲刺结束后角色向前飞 | 旧版本 bug（已修复）：AerialDashState 结束时未归零速度 | 确认使用当前版本代码 |
| 冲刺距离太长，穿越关卡障碍 | `DashSpeed × DashDuration` 过大 | 降低 DashSpeed 或 DashDuration |
| 冲刺 CD 太长，影响流畅感 | `DashCooldown` 过高 | 降至 0.4-0.5s |
| 离开平台边缘后无法起跳 | `CoyoteTime` 太短 | 调高至 0.10-0.15s |

---

## 四、修改历史

| 日期 | 修改内容 |
|---|---|
| 2026-05-17 | 初版：新增顶点悬停参数（`ApexThreshold` / `ApexGravityMultiplier`）；修复空中冲刺结束速度未归零问题；`JumpCutMultiplier` 默认值从 0.45 调整为 0.35 |