chore: initial commit

Docs/DesignSpec/05_MovementSystem.md

@@ -0,0 +1,267 @@
+# 05 · 移动系统规范
+
+> **所属文档集** [← 返回索引](./README.md)  
+> **摘要**：玩家移动的物理模型、跳跃机制、冲刺、墙壁力学与手感参数。
+
+---
+
+## 目录
+
+1. [移动设计目标](#1-移动设计目标)
+2. [地面移动](#2-地面移动)
+3. [跳跃模型](#3-跳跃模型)
+4. [冲刺系统](#4-冲刺系统)
+5. [墙壁力学](#5-墙壁力学)
+6. [空中冲刺（Aerial Dash）](#6-空中冲刺aerial-dash)
+7. [下冲（Plunge）](#7-下冲plunge)
+8. [地面与碰撞检测](#8-地面与碰撞检测)
+9. [移动配置参数](#9-移动配置参数)
+
+---
+
+## 1. 移动设计目标
+
+| 目标 | 实现方式 |
+|------|---------|
+| **精确可控** | 即时响应方向输入，没有"滑动"惯性 |
+| **灵活多样** | 多种移动选项（跳跃、冲刺、墙跳、空中冲刺）|
+| **手感沉重** | 快速下落（fall multiplier），跳跃顶点缓降 |
+| **容错空间** | 土狼时间、跳跃缓冲降低输入失误惩罚 |
+| **进阶可深** | 空中冲刺+墙跳的组合技深度 |
+
+---
+
+## 2. 地面移动
+
+### 2.1 水平移动
+
+| 状态 | 速度 | 说明 |
+|------|------|------|
+| 行走（轻推摇杆）| `walkSpeed` | 6 units/s |
+| 奔跑（全推摇杆）| `runSpeed` | 9 units/s |
+
+- 水平速度**即时响应**输入，无加速/减速惯性
+- 松开输入时立即停止（不滑行）
+
+> **设计决策**：不使用加速/减速曲线  
+> **原因**：类银河恶魔城强调精确跳台，惯性会使平台跳跃难以预判落点
+
+### 2.2 朝向
+
+- 朝向随水平输入即时翻转
+- 攻击/技能状态中锁定朝向（不随输入改变）
+
+---
+
+## 3. 跳跃模型
+
+### 3.1 跳跃类型
+
+| 类型 | 触发条件 | 初速度 | 备注 |
+|------|---------|--------|------|
+| 地面跳跃 | 地面 + 跳跃键 | `jumpForce` | 标准跳跃 |
+| 土狼跳 | 离地后 `coyoteTime` 内 + 跳跃键 | `jumpForce` | 视为地面跳跃 |
+| 双跳 | 空中 + 跳跃键 + `DoubleJump` 已解锁 + 未使用过 | `doubleJumpForce` | 每次落地重置 |
+| 墙跳（背墙）| 贴墙 + 跳跃键 | 水平: `wallJumpAwayHForce`，垂直: `wallJumpVerticalForce` | 背离墙壁方向 |
+| 墙跳（对墙）| 贴墙 + 朝墙方向 + 跳跃键 | 水平: `wallJumpTowardHForce`，垂直: `wallJumpVerticalForce` | 朝墙壁方向 |
+
+### 3.2 可变跳跃高度
+
+松开跳跃键时，若玩家垂直速度仍向上，截断为原值的 50%。  
+→ 长按获得完整跳跃高度；短按获得约一半高度。
+
+### 3.3 重力模型
+
+使用**非对称重力**以获得"果断"手感：
+
+| 阶段 | 重力倍率 |
+|------|---------|
+| 上升阶段 | ×1.0（基础重力）|
+| 下落阶段 | ×`fallMultiplier`（默认 2.5）|
+| 短跳（松键后上升）| ×`lowJumpMultiplier`（默认 2.0）|
+| 跳跃顶点（速度接近 0）| 短暂降低至 ×0.6（缓降感）|
+
+### 3.4 跳跃缓冲（Jump Buffer）
+
+在落地前 `jumpBufferDuration`（默认 0.15s）内按下跳跃键，落地后立即触发跳跃。  
+→ 消除玩家"刚好落地后跳跃失败"的挫败感。
+
+---
+
+## 4. 冲刺系统
+
+### 4.1 地面冲刺
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 方向 | 当前朝向（水平，不可向上/下）| 地面冲刺只能水平 |
+| 速度 | `dashSpeed` (18 units/s) | 远高于跑步速度 |
+| 时长 | `dashDuration` (0.18s) | 固定时长 |
+| 冷却 | `dashCooldown` (0.5s) | 冷却期间不可再冲刺 |
+| 无敌帧 | 冲刺全程 | 不受任何伤害 |
+| 穿透 | 可穿过敌人 | 不被敌人阻挡 |
+
+### 4.2 冲刺取消
+
+冲刺中不可被低优先级状态打断。但以下情况可中断：
+- 受到 `Unblockable` 攻击（仅此一项，普通攻击在冲刺无敌期间被忽略）
+
+---
+
+## 5. 墙壁力学
+
+### 5.1 墙抓（WallGrab）
+
+> **默认解锁**，不需要能力门
+
+当玩家在空中贴近可抓取的墙壁并输入朝墙方向时，进入 WallGrabState：
+
+| 行为 | 说明 |
+|------|------|
+| 悬挂 | 玩家停止下落，附着在墙上 |
+| 高度记忆 | 记录抓墙时的 Y 坐标（`wallGrabAnchorY`）|
+| 超出记忆值 | 玩家可向上爬（无上限）|
+| 低于记忆值 | 按 `wallGrabSlideSpeed` 缓慢下滑（不快速下落）|
+| 持续时间 | 无时间限制（可一直抓）|
+
+### 5.2 墙跳类型
+
+| 类型 | 触发 | 水平冲力 | 垂直冲力 |
+|------|------|---------|---------|
+| **背墙跳** | 跳跃键（无方向或反向）| `wallJumpAwayHForce` (10) | `wallJumpVerticalForce` (15) |
+| **对墙跳** | 朝墙方向 + 跳跃键 | `wallJumpTowardHForce` (3) | `wallJumpVerticalForce` (15) |
+
+背墙跳弹离效果强，用于快速脱离；对墙跳爬升效果强，用于沿墙向上攀爬。
+
+> **设计决策**：两种墙跳共用垂直分量  
+> **原因**：统一手感基准，区别仅在水平表现
+
+### 5.3 墙跳后的输入锁定
+
+背墙跳后：
+- 水平方向输入锁定 0.1s（防止玩家立即贴回同一面墙）
+
+---
+
+## 6. 空中冲刺（Aerial Dash）
+
+> **需要解锁** `AerialDash` 能力
+
+### 6.1 基本规则
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 方向 | 8 方向（摇杆方向量化）| 与地面冲刺最大区别 |
+| 速度 | `aerialDashSpeed` (15 units/s) | 略低于地面冲刺 |
+| 时长 | `aerialDashDuration` (0.20s) | |
+| 无敌帧 | 冲刺全程 | 同地面冲刺 |
+| 充能次数 | 默认 1 次（护符可升至 2 次）| 每次空中各自独立 |
+
+### 6.2 充能重置条件
+
+| 触发条件 | 说明 |
+|---------|------|
+| 落地 | 触地瞬间恢复 |
+| 墙跳成功 | 墙跳给予新的空中冲刺机会 |
+| **近战攻击命中** | 命中敌人即恢复（鼓励进攻性空中移动）|
+| **弹反成功** | 弹反视为命中，给予恢复 |
+
+> **设计决策**：命中恢复充能  
+> **原因**：这是《丝之歌》核心机制，使得玩家可以通过激进攻击保持永续空中移动。  
+> **体验目标**：顶级玩家应该能通过攻击和弹反的组合在空中无限机动。
+
+### 6.3 方向量化规则
+
+摇杆输入方向量化为 8 个标准方向（45° 间隔）：
+- 上/下/左/右（4 个主方向）
+- 左上/右上/左下/右下（4 个斜方向）
+- 若无输入，默认朝当前朝向水平冲刺
+
+---
+
+## 7. 下冲（Plunge）
+
+> **无需解锁**，基础能力
+
+### 7.1 触发条件
+
+```
+空中 + 向下方向输入 + 冲刺键
+（优先级高于普通空中冲刺）
+```
+
+### 7.2 行为规范
+
+| 阶段 | 说明 |
+|------|------|
+| 激活 | 取消垂直速度，施加极大向下速度（`plungeSpeed` = 28 units/s）|
+| 下冲中 | 全程无敌帧；保留少量水平速度（原值 ×0.2）|
+| 落地 | 触发冲击波 AoE，范围内敌人受伤 + 强硬直 |
+| 落地后 | 轻微弹起（`verticalBounce` = 4 units/s）→ 回 IdleState |
+| 充能消耗 | 消耗 1 次空中冲刺充能（与 AerialDash 共享）|
+
+### 7.3 冲击波参数
+
+| 参数 | 值 |
+|------|-----|
+| 冲击波半径 | 2.0 units |
+| 冲击伤害 | 基础攻击 ×2.0 |
+| 硬直时长 | 0.8s |
+| 是否可弹反 | 否 |
+
+---
+
+## 8. 地面与碰撞检测
+
+### 8.1 地面检测
+
+- 在角色脚部发起**小矩形区域检测**，检测 Ground 层
+- 每帧更新，检测结果对外暴露为只读属性 `isGrounded`
+- **单向平台**（OneWayPlatform）：  
+  - 从下方跳跃时穿过（检测忽略该层）  
+  - 站在上方时视为地面  
+  - 向下 + 跳跃键：临时忽略单向平台层，允许下穿
+
+### 8.2 土狼时间（Coyote Time）
+
+离开地面后（如走出平台边缘）的 `coyoteTime`（默认 0.12s）内仍视为"在地面"：
+- 这段时间内可触发地面跳跃
+- 只对自然离地有效（跳跃后不产生土狼时间）
+
+### 8.3 墙壁检测
+
+- 在角色左右两侧各发出一条水平射线
+- 检测 Wall 层
+- 结果：`isWallLeft` / `isWallRight`
+- 区分"可抓墙"和"不可抓墙"（通过墙壁属性标记）
+
+---
+
+## 9. 移动配置参数
+
+| 参数 | 推荐值 | 说明 |
+|------|--------|------|
+| `walkSpeed` | 6.0 | 地面行走速度（units/s）|
+| `runSpeed` | 9.0 | 地面奔跑速度（units/s）|
+| `jumpForce` | 16.0 | 跳跃初始垂直速度 |
+| `doubleJumpForce` | 14.0 | 双跳初始垂直速度 |
+| `wallJumpAwayHForce` | 10.0 | 背墙跳水平分量 |
+| `wallJumpTowardHForce` | 3.0 | 对墙跳水平分量 |
+| `wallJumpVerticalForce` | 15.0 | 墙跳垂直分量 |
+| `wallJumpInputLockDuration` | 0.1s | 背墙跳后水平输入锁定时长 |
+| `wallGrabSlideSpeed` | 2.0 | 抓墙下滑速度（低于记忆高度时）|
+| `dashSpeed` | 18.0 | 地面冲刺速度 |
+| `dashDuration` | 0.18s | 地面冲刺时长 |
+| `dashCooldown` | 0.5s | 冲刺冷却时间 |
+| `aerialDashSpeed` | 15.0 | 空中冲刺速度 |
+| `aerialDashDuration` | 0.20s | 空中冲刺时长 |
+| `plungeSpeed` | 28.0 | 下冲速度 |
+| `plungeImpactRadius` | 2.0 | 下冲冲击波半径 |
+| `plungeBounceForce` | 4.0 | 落地后弹起速度 |
+| `fallMultiplier` | 2.5 | 下落额外重力倍率 |
+| `lowJumpMultiplier` | 2.0 | 短跳额外重力倍率 |
+| `apexGravityScale` | 0.6 | 跳跃顶点重力缩减倍率 |
+| `coyoteTimeDuration` | 0.12s | 土狼时间窗口 |
+| `jumpBufferDuration` | 0.15s | 跳跃预输入缓冲窗口 |
+| `groundCheckSize` | (0.8, 0.05) | 地面检测矩形尺寸 |
+| `wallCheckDistance` | 0.1 | 墙壁检测射线长度 |