359 lines
13 KiB
Markdown
359 lines
13 KiB
Markdown
# 40 · 液态区域与游泳系统（Liquid & Swim System）
|
||
|
||
> **命名空间** `BaseGames.World.Liquid`
|
||
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)
|
||
> **依赖** `BaseGames.Player`（PlayerController · AbilitiesSaveData）· `BaseGames.Core.Events`
|
||
> **关联** 08_WorldSystem §6（HazardZone）· 03_PlayerSystem §4（PlayerState FSM）· 31_SaveDataSchema §2（`abilities.swim`）
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [系统总览](#1-系统总览)
|
||
2. [LiquidZone — 液态区域组件](#2-liquidzone--液态区域组件)
|
||
3. [液体类型与效果表](#3-液体类型与效果表)
|
||
4. [SwimState — 游泳状态](#4-swimstate--游泳状态)
|
||
5. [玩家进出液体流程](#5-玩家进出液体流程)
|
||
6. [酸液/熔岩特化（InstantKill 液体）](#6-酸液熔岩特化instantkill-液体)
|
||
7. [浮力与水下物理参数](#7-浮力与水下物理参数)
|
||
8. [水下视觉效果](#8-水下视觉效果)
|
||
9. [SaveData 集成](#9-savedata-集成)
|
||
10. [事件频道](#10-事件频道)
|
||
11. [编辑器友好设计](#11-编辑器友好设计)
|
||
|
||
---
|
||
|
||
## 1. 系统总览
|
||
|
||
液体系统处理地图中的水体、酸液、熔岩等可进入区域，解决：
|
||
|
||
- **水体**：进入后切换为游泳移动模式（`SwimState`），需要 `swim` 能力解锁
|
||
- **酸液/熔岩**：接触即触发即死（委托 `HazardZone InstantKill`，见 08_WorldSystem §6）
|
||
- **浮力**：进入液体后重力系数降低，玩家可上浮/下沉
|
||
- **水面特效**：进出液体时溅水粒子、水下后处理 Profile
|
||
|
||
```
|
||
液体系统职责:
|
||
├─ LiquidZone → 标记液态区域类型、触发进出液体事件
|
||
├─ SwimState → PlayerController FSM 中的水下游泳状态
|
||
├─ LiquidPhysicsConfig → ScriptableObject，水下物理参数
|
||
└─ WaterSurfaceEffect → 进出水面溅水粒子 + 音效
|
||
```
|
||
|
||
**零耦合原则**：`LiquidZone` 通过 SO 事件频道发布进出液体事件，`PlayerController` 订阅后自行切换状态，互不直接引用。
|
||
|
||
---
|
||
|
||
## 2. LiquidZone — 液态区域组件
|
||
|
||
```csharp
|
||
namespace BaseGames.World.Liquid
|
||
{
|
||
/// <summary>
|
||
/// 挂在液态区域的根 GameObject 上。
|
||
/// 子物件 [Surface] 挂载水面特效触发器；子物件 [Body] 挂载主区域碰撞体。
|
||
/// </summary>
|
||
[RequireComponent(typeof(Collider2D))]
|
||
public class LiquidZone : MonoBehaviour
|
||
{
|
||
[Header("液体类型")]
|
||
[SerializeField] LiquidType _liquidType = LiquidType.Water;
|
||
|
||
[Header("物理配置")]
|
||
[SerializeField] LiquidPhysicsConfigSO _physicsConfig;
|
||
|
||
[Header("事件频道")]
|
||
[SerializeField] LiquidEventChannelSO _onPlayerEntered; // payload: LiquidZone
|
||
[SerializeField] LiquidEventChannelSO _onPlayerExited; // payload: LiquidZone
|
||
|
||
[Header("视觉反馈")]
|
||
[SerializeField] MMF_Player _splashEnterFeedback;
|
||
[SerializeField] MMF_Player _splashExitFeedback;
|
||
|
||
public LiquidType Type => _liquidType;
|
||
public LiquidPhysicsConfigSO Physics => _physicsConfig;
|
||
}
|
||
}
|
||
```
|
||
|
||
### LiquidZone Prefab 层级结构
|
||
|
||
```
|
||
[LiquidZone_River_01]
|
||
├── SpriteRenderer（水体图块精灵，带流动 Shader）
|
||
├── PolygonCollider2D (IsTrigger) ← 主区域，检测 Player/Enemy
|
||
├── LiquidZone.cs
|
||
│
|
||
├── [Surface] ← 水面层（分离触发器，检测进出水面）
|
||
│ ├── BoxCollider2D (IsTrigger, 1px 高)
|
||
│ └── WaterSurfaceEffect.cs ← 触发溅水粒子
|
||
│
|
||
└── [Hazard]（酸液/熔岩时存在）
|
||
└── HazardZone.cs (_hazardType = InstantKill)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 液体类型与效果表
|
||
|
||
| `LiquidType` | 行为 | 需要能力 | 特殊说明 |
|
||
|-------------|------|---------|---------|
|
||
| `Water` | 进入 → 切换 SwimState（需 `swim` 解锁）| `swim` | 无 `swim` 时浮于水面（触发溺水计时）|
|
||
| `ShallowWater` | 仅减速，不切换 SwimState，无需能力 | 无 | 水深 ≤ 1.5 tile，适用于浅滩、水坑 |
|
||
| `Acid` | 接触即死（HazardZone InstantKill） | — | 效果与 HazardZone 完全相同，LiquidZone 仅负责视觉层 |
|
||
| `Lava` | 接触即死 + 持续灼烧特效 | — | 同上，另加火焰粒子 |
|
||
| `Mud` | 减速 50%，不切换状态 | 无 | 可结合谜题（踩过留脚印 SaveData 标记）|
|
||
|
||
---
|
||
|
||
## 4. SwimState — 游泳状态
|
||
|
||
`SwimState` 插入 `PlayerController` 的 **Base Layer FSM**，在 `InWater` 分支下工作：
|
||
|
||
```
|
||
Base Layer FSM（新增分支）:
|
||
AnyState ─── OnEnteredWater ──► SwimState
|
||
(LiquidType.Water && HasAbility.Swim)
|
||
├─ SwimIdleState
|
||
├─ SwimMoveState
|
||
├─ SwimDiveState
|
||
└─ SwimSurfaceState
|
||
SwimState ─── OnExitedWater ──► FallState（离开液体继承速度）
|
||
```
|
||
|
||
### SwimState 子状态
|
||
|
||
| 子状态 | 触发条件 | 说明 |
|
||
|--------|---------|------|
|
||
| `SwimIdleState` | 无方向输入 | 缓慢下沉（可配置），循环游泳动画 |
|
||
| `SwimMoveState` | 有方向输入（↑↓←→） | 8 向移动，速度受 `swimSpeed` 限制 |
|
||
| `SwimDiveState` | 按住 ↓ | 快速下潜，速度 × `diveSpeedMultiplier` |
|
||
| `SwimSurfaceState` | 接近水面 + 按 Jump | 跃出水面，施加 `surfaceJumpForce` 冲量 |
|
||
|
||
### 无 `swim` 能力时的溺水行为
|
||
|
||
若玩家进入 `LiquidType.Water` 时 **未解锁 `swim` 能力**：
|
||
|
||
1. 进入 `WaterDangerState`（新增子状态）
|
||
2. 玩家可在水面漂浮（按住 Jump 保持）
|
||
3. 启动 **溺水计时器**（`drownTime` 秒，默认 3.0s，可配置）
|
||
4. 计时器归零 → 触发 `OnPlayerDied`（与其他即死处理一致）
|
||
5. 若玩家在溺水期间离开液体，计时器重置
|
||
|
||
---
|
||
|
||
## 5. 玩家进出液体流程
|
||
|
||
### 进入液体
|
||
|
||
```
|
||
Player Rigidbody2D 进入 LiquidZone PolygonCollider2D（IsTrigger）
|
||
→ LiquidZone.OnTriggerEnter2D(Player)
|
||
├─ 播放 _splashEnterFeedback（MMF_Player：溅水粒子 + 入水音效）
|
||
├─ 发布 _onPlayerEntered 频道（payload: this LiquidZone）
|
||
└─ （HazardZone 子物件自动处理 InstantKill 逻辑，互不干扰）
|
||
|
||
PlayerController 监听 _onPlayerEntered:
|
||
→ 查询 _liquidType
|
||
├─ Water：检查 PlayerStats.HasAbility(swim)
|
||
│ ├─ [有] → FSM 切换至 SwimState
|
||
│ └─ [无] → FSM 切换至 WaterDangerState（溺水倒计时）
|
||
├─ ShallowWater：应用 LiquidPhysicsConfig.shallowSpeedScale
|
||
└─ Mud：应用 LiquidPhysicsConfig.mudSpeedScale
|
||
```
|
||
|
||
### 离开液体
|
||
|
||
```
|
||
Player Rigidbody2D 退出 LiquidZone（OnTriggerExit2D）
|
||
→ LiquidZone 发布 _onPlayerExited 频道
|
||
|
||
PlayerController:
|
||
→ 恢复正常 Gravity Scale（从 LiquidPhysicsConfig.underwaterGravityScale 恢复）
|
||
→ FSM 切换至 FallState（继承当前 Rigidbody2D.velocity）
|
||
→ 播放 _splashExitFeedback
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 酸液/熔岩特化（InstantKill 液体）
|
||
|
||
酸液和熔岩本质上是 **视觉增强的 HazardZone**，实际致死逻辑复用 `HazardZone（InstantKill）`：
|
||
|
||
```
|
||
[AcidZone_Cave_01]
|
||
├── SpriteRenderer（酸液精灵 + 涌动 Shader）
|
||
├── LiquidZone.cs (_liquidType = Acid) ← 负责视觉特效触发
|
||
├── [Surface]
|
||
│ └── WaterSurfaceEffect.cs（酸液飞溅粒子）
|
||
└── [Hazard]
|
||
└── HazardZone.cs (_hazardType = InstantKill) ← 负责致死逻辑
|
||
```
|
||
|
||
`LiquidZone`（Acid/Lava）在 `OnTriggerEnter2D` 中**不**发布 `_onPlayerEntered` 切换状态事件，只播放视觉反馈；致死由 `HazardZone` 独立处理，避免逻辑重叠。
|
||
|
||
---
|
||
|
||
## 7. 浮力与水下物理参数
|
||
|
||
### LiquidPhysicsConfigSO
|
||
|
||
```csharp
|
||
[CreateAssetMenu(menuName = "World/Liquid/LiquidPhysicsConfig")]
|
||
public class LiquidPhysicsConfigSO : ScriptableObject
|
||
{
|
||
[Header("水下重力")]
|
||
public float underwaterGravityScale = 0.3f; // 正常重力 × 0.3 → 缓慢下沉
|
||
public float sinkSpeed = 1.5f; // 无操作时下沉速度上限 (u/s)
|
||
|
||
[Header("游泳速度")]
|
||
public float swimSpeed = 5.0f; // 最大游泳速度 (u/s)
|
||
public float swimAcceleration = 12.0f; // 加速度
|
||
public float diveSpeedMultiplier = 1.8f; // 下潜速度倍率
|
||
|
||
[Header("跃出水面")]
|
||
public float surfaceJumpForce = 12.0f; // 出水跳跃冲量 Y 分量
|
||
|
||
[Header("浅水/泥泞")]
|
||
public float shallowSpeedScale = 0.65f; // 浅水移动速度缩放
|
||
public float mudSpeedScale = 0.50f; // 泥泞移动速度缩放
|
||
|
||
[Header("溺水")]
|
||
public float drownTime = 3.0f; // 无能力时溺水计时（秒）
|
||
}
|
||
```
|
||
|
||
### 参考调优值（游戏手感）
|
||
|
||
| 参数 | 推荐值 | 说明 |
|
||
|------|-------|------|
|
||
| `underwaterGravityScale` | 0.25–0.35 | 越小越"飘"，Hollow Knight 水感约 0.3 |
|
||
| `swimSpeed` | 4.5–5.5 | 略低于地面奔跑速度（约 70%）|
|
||
| `surfaceJumpForce` | 10–14 | 跃出水面感觉应比普通跳跃稍低 |
|
||
| `drownTime` | 2.5–3.5 | 太短会惩罚探索；太长失去压迫感 |
|
||
|
||
---
|
||
|
||
## 8. 水下视觉效果
|
||
|
||
### 水下后处理 Profile
|
||
|
||
进入 `LiquidType.Water` 时，`LiquidZone` 通过 SO 事件频道触发 Post-processing Volume 切换：
|
||
|
||
```
|
||
_onPlayerEntered 广播
|
||
→ UnderwaterPostProcessingController 监听
|
||
→ 激活 Volume_Underwater（Color Adjustment：青绿色 Filter + 亮度 -0.3）
|
||
→ 激活 ChromaticAberration（intensity = 0.4，模拟折射）
|
||
→ 屏幕边缘 Vignette 增强（intensity = 0.45）
|
||
|
||
_onPlayerExited 广播
|
||
→ UnderwaterPostProcessingController
|
||
→ 平滑过渡回 Volume_Default（过渡时长 0.4s）
|
||
```
|
||
|
||
### WaterSurfaceEffect 组件
|
||
|
||
```csharp
|
||
public class WaterSurfaceEffect : MonoBehaviour
|
||
{
|
||
[SerializeField] MMF_Player _playerEnterFeedback; // 入水溅水粒子 + 音效
|
||
[SerializeField] MMF_Player _playerExitFeedback; // 出水溅水粒子
|
||
|
||
void OnTriggerEnter2D(Collider2D col)
|
||
{
|
||
if (col.CompareTag("Player"))
|
||
_playerEnterFeedback?.PlayFeedbacks(col.transform.position);
|
||
}
|
||
|
||
void OnTriggerExit2D(Collider2D col)
|
||
{
|
||
if (col.CompareTag("Player"))
|
||
_playerExitFeedback?.PlayFeedbacks(col.transform.position);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. SaveData 集成
|
||
|
||
`abilities.swim` 字段由 `AbilitiesSaveData` 负责（见 31_SaveDataSchema_Unified §3）：
|
||
|
||
```json
|
||
"abilities": {
|
||
"doubleJump": false,
|
||
"wallGrab": false,
|
||
"dash": false,
|
||
"airDash": false,
|
||
"groundSlam": false,
|
||
"swim": false
|
||
}
|
||
```
|
||
|
||
- 初始值为 `false`（游戏开始时无游泳能力）
|
||
- 通过 `AbilityUnlock`（见 08_WorldSystem §8）交互后 `PlayerStats.UnlockAbility(AbilityType.Swim)` 写入存档
|
||
- 读档时 `PlayerStats.Init(SaveData)` 将 `swim` 字段同步到 `PlayerStats._abilities` 集合
|
||
|
||
> **注意**：`LiquidZone` 本身不持有 SaveData 字段；区域是否探索由 `MapSystem`（`discoveredRooms`）统一管理。
|
||
|
||
---
|
||
|
||
## 10. 事件频道
|
||
|
||
| 频道 SO | 类型 | 用途 |
|
||
|---------|------|------|
|
||
| `OnPlayerEnteredLiquid` | `LiquidEventChannelSO`（payload: `LiquidZone`）| 玩家进入液体 → PlayerController 切换状态 |
|
||
| `OnPlayerExitedLiquid` | `LiquidEventChannelSO`（payload: `LiquidZone`）| 玩家离开液体 → 恢复正常物理 |
|
||
| `OnPlayerDrownStart` | `VoidEventChannelSO` | 溺水计时开始 → HUD 显示溺水警告UI |
|
||
| `OnPlayerDrownCancel` | `VoidEventChannelSO` | 溺水计时取消（离开水体）|
|
||
|
||
```
|
||
LiquidEventChannelSO.cs:
|
||
[CreateAssetMenu(menuName = "Events/LiquidEventChannel")]
|
||
public class LiquidEventChannelSO : ScriptableObject
|
||
{
|
||
public event Action<LiquidZone> OnEventRaised;
|
||
public void Raise(LiquidZone zone) => OnEventRaised?.Invoke(zone);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 编辑器友好设计
|
||
|
||
### Custom Inspector（LiquidZone）
|
||
|
||
```
|
||
LiquidZone Inspector:
|
||
[液体属性]
|
||
LiquidType: ● Water ○ ShallowWater ○ Acid ○ Lava ○ Mud
|
||
Physics Config: [LiquidPhysicsConfigSO 引用]
|
||
[事件频道] （折叠）
|
||
[视觉反馈]
|
||
SplashEnter: [MMF_Player 引用]
|
||
SplashExit: [MMF_Player 引用]
|
||
─────────────────────────────
|
||
[▶ 预览入水特效] [▶ 预览出水特效] ← Editor Only 按钮
|
||
```
|
||
|
||
### Gizmos
|
||
|
||
- 编辑模式下 `LiquidZone` 用**半透明蓝色**（Water）/**半透明绿色**（Acid）/**半透明红色**（Lava）填充 PolygonCollider2D 范围
|
||
- `WaterSurfaceEffect` 的 1px 触发器在 Scene 视图中显示为**青色细线**
|
||
|
||
### 关卡搭建建议
|
||
|
||
```
|
||
Layer 命名约定:
|
||
Tilemap_Liquid_Water ← 水体图块（仅视觉，无碰撞）
|
||
Tilemap_Liquid_Surface ← 水面装饰图块（涟漪动画）
|
||
|
||
LiquidZone 组件挂在独立 GameObject 上（非 Tilemap），
|
||
PolygonCollider2D 手动覆盖液体区域轮廓，精度 ≥ 2 顶点/格。
|
||
```
|
||
|
||
---
|
||
|
||
*文档版本 1.0 · 2025*
|