# 24 · 地面检测系统

> **命名空间** `BaseGames.Player`  
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
> **依赖** `BaseGames.Core.Events` · `BaseGames.Player`

---

## 目录

1. [系统总览](#1-系统总览)
2. [多射线检测架构](#2-多射线检测架构)
3. [斜坡处理](#3-斜坡处理)
4. [单向平台穿越](#4-单向平台穿越)
5. [平台边缘检测](#5-平台边缘检测)
6. [GroundSurfaceSO — 地面物理材质](#6-groundsurfaceso--地面物理材质)
7. [地面类型枚举与脚步系统集成](#7-地面类型枚举与脚步系统集成)
8. [Coyote Time 实现](#8-coyote-time-实现)
9. [PlayerGroundDetector — 完整实现](#9-playergrounddetector--完整实现)
10. [编辑器友好设计](#10-编辑器友好设计)

---

## 1. 系统总览

地面检测系统负责：

```
GroundDetectionSystem 职责:
  ├─ IsGrounded             → 玩家是否站在地面上（含斜坡/单向平台）
  ├─ GroundNormal           → 当前地面法线（用于斜坡移动方向矫正）
  ├─ GroundSurfaceType      → 当前地面材质（Wood / Stone / Metal / Grass / Water）
  ├─ IsNearEdge             → 玩家是否站在平台边缘（用于下坠预警动画）
  ├─ CanDropThrough         → 是否可向下穿越当前平台
  └─ CoyoteTime             → 离地后的短暂缓冲跳跃窗口
```

**零耦合原则**：`PlayerGroundDetector` 是 `PlayerController` 的子组件，结果通过属性暴露；脚步系统通过 `GroundSurfaceType` 属性读取，不订阅内部事件。

---

## 2. 多射线检测架构

### 射线布局（脚部 BoxCast 方案）

使用 **BoxCast** 而非单点 Raycast，覆盖玩家脚部整个宽度，避免在平台边缘时误判：

```
    ┌──────────────┐
    │   Player     │
    │              │
    └──┬──┬──┬──┬──┘   ← 脚部 BoxCast 宽度 = Collider 宽度 × 0.9
       ↓  ↓  ↓  ↓
   ─────────────────   ← Ground Layer
```

```csharp
// 检测参数（GroundDetectionConfigSO 中配置）
public struct GroundCheckConfig
{
    public float BoxWidth;          // 脚部宽度（Collider 宽度 × 0.9，约 0.45f）
    public float BoxHeight;         // 射线长度（0.05f，仅检测贴地情况）
    public float OffsetY;           // 从脚底向下偏移（-0.02f，贴边检测）
    public LayerMask GroundLayers;  // Ground | OneWayPlatform
}
```

### 每帧检测流程

```csharp
void FixedUpdate()
{
    // 1. BoxCast 检测
    Vector2 origin = (Vector2)transform.position + Vector2.up * _config.OffsetY;
    RaycastHit2D hit = Physics2D.BoxCast(
        origin,
        new Vector2(_config.BoxWidth, 0.02f),
        0f,
        Vector2.down,
        _config.BoxHeight,
        _config.GroundLayers
    );

    // 2. 单向平台过滤：仅在 Rigidbody2D.velocity.y <= 0 时接受
    if (hit && hit.collider.gameObject.layer == LayerMask.NameToLayer("OneWayPlatform"))
    {
        hit = (_rb.velocity.y <= 0.1f) ? hit : default;
    }

    // 3. 更新状态
    bool wasGrounded = IsGrounded;
    IsGrounded = hit.collider != null;
    GroundNormal = IsGrounded ? hit.normal : Vector2.up;
    GroundCollider = IsGrounded ? hit.collider : null;

    // 4. 落地事件（仅首次着地触发）
    if (!wasGrounded && IsGrounded)
        OnLanded?.Invoke(Mathf.Abs(_rb.velocity.y));

    // 5. 离地时记录时间（用于 Coyote Time）
    if (wasGrounded && !IsGrounded)
        _lastGroundedTime = Time.time;
}
```

---

## 3. 斜坡处理

### 斜坡移动矫正

当 `GroundNormal` 偏离 `Vector2.up` 时，将水平移动方向投影到地面切线上，防止在斜坡上"漂浮"或减速：

```csharp
// PlayerMovement.Move() 内部
public Vector2 GetMoveDirectionOnSlope(float inputX)
{
    if (!_groundDetector.IsGrounded) return new Vector2(inputX, 0f);

    // 地面切线（法线顺时针旋转 90°）
    Vector2 tangent = new Vector2(_groundDetector.GroundNormal.y,
                                  -_groundDetector.GroundNormal.x);
    return tangent * inputX;
}
```

### 斜坡参数

| 参数 | 值 | 说明 |
|------|-----|------|
| `MaxSlopeAngle` | 50° | 超过此角度视为墙壁，无法行走 |
| `SlopeSpeedMultiplier_Up` | 0.85 | 上坡速度乘数 |
| `SlopeSpeedMultiplier_Down` | 1.0 | 下坡不减速 |
| `SlopeStickForce` | -5f | 下坡时施加的额外向下力，防止飞出斜坡 |

### 斜坡角度计算

```csharp
public float SlopeAngle => Vector2.Angle(GroundNormal, Vector2.up);
public bool  IsOnSlope   => SlopeAngle > 1f && SlopeAngle < _config.MaxSlopeAngle;
```

---

## 4. 单向平台穿越

### 穿越逻辑

```
触发穿越:
  玩家按住 ↓ + 跳跃键
        │
        ▼
  临时禁用 OneWayPlatform 碰撞
  (Physics2D.IgnoreLayerCollision)
        │
        ▼
  等待 0.25s（足以穿越平台厚度）
        │
        ▼
  恢复碰撞检测
```

```csharp
// PlayerMovement 中的穿越实现
public IEnumerator DropThroughPlatform()
{
    int playerLayer = gameObject.layer;
    int platformLayer = LayerMask.NameToLayer("OneWayPlatform");
    Physics2D.IgnoreLayerCollision(playerLayer, platformLayer, true);
    yield return new WaitForSeconds(0.25f);
    Physics2D.IgnoreLayerCollision(playerLayer, platformLayer, false);
}
```

### 下跳冲量

穿越时施加 `-2f` 的向下冲量，确保玩家能迅速离开平台（尤其是较厚的 Tilemap 单向平台）。

---

## 5. 平台边缘检测

### 用途

- 触发**边缘摇摇欲坠**动画（Blend Shape 或附加动画层）
- 阻止在悬崖边缘继续行走（可选，策划配置）
- 为 AI 敌人的寻路提供跌落预判（NavLink）

### 实现

在脚部左右两侧各发射一条短 Raycast，检测足部以下是否有地面：

```csharp
// 检测脚底左右是否悬空
bool edgeLeft  = !Physics2D.Raycast(
    (Vector2)transform.position + new Vector2(-_halfWidth, 0f),
    Vector2.down, _config.EdgeCheckDepth, _config.GroundLayers);
bool edgeRight = !Physics2D.Raycast(
    (Vector2)transform.position + new Vector2(+_halfWidth, 0f),
    Vector2.down, _config.EdgeCheckDepth, _config.GroundLayers);

IsNearEdge = (edgeLeft && !edgeRight) || (!edgeLeft && edgeRight);
IsOverVoid  = edgeLeft && edgeRight;   // 双侧悬空（极窄平台）
```

### 边缘检测配置

| 参数 | 值 | 说明 |
|------|-----|------|
| `EdgeCheckDepth` | 0.6f | 检测深度（略大于玩家身高的一半）|
| `EdgeCheckHorizontalOffset` | 0.22f | 距中心的水平距离（约等于碰撞体半宽）|

---

## 6. GroundSurfaceSO — 地面物理材质

每种地面类型对应一个 `GroundSurfaceSO` 资产，配置摩擦力、脚步声 Label、粒子特效引用：

```csharp
[CreateAssetMenu(menuName = "World/GroundSurface")]
public class GroundSurfaceSO : ScriptableObject
{
    [Header("物理属性")]
    public float FrictionCoefficient;   // 地面摩擦系数（影响加速/减速时长）
    public float BounceFactor;          // 弹性（0 = 不弹，默认 0）

    [Header("音效")]
    public string FootstepAddressLabel; // Addressable Label，如 "Footstep_Stone"
    public float  FootstepVolumeScale;  // 音量缩放

    [Header("特效")]
    public AssetReferenceGameObject LandingDustFX; // 落地粒子（Addressable 引用）
    public AssetReferenceGameObject FootstepDustFX; // 脚步粒子（可为 null）
}
```

**资产存放路径**：`Assets/ScriptableObjects/World/Surfaces/`

### 内置地面类型

| 资产名 | 摩擦系数 | 脚步声 Label | 说明 |
|--------|---------|------------|------|
| `Surface_Stone.asset` | 0.8 | `Footstep_Stone` | 石头、砖块 |
| `Surface_Wood.asset` | 0.7 | `Footstep_Wood` | 木质平台、地板 |
| `Surface_Metal.asset` | 0.5 | `Footstep_Metal` | 金属格栅、机关 |
| `Surface_Grass.asset` | 0.9 | `Footstep_Grass` | 草地、土路 |
| `Surface_Water_Shallow.asset` | 1.0 | `Footstep_Water` | 浅水（不触发游泳）|
| `Surface_Ice.asset` | 0.1 | `Footstep_Stone` | 冰面（极低摩擦）|

### Tilemap 关联

在 `TilemapCollider2D` 对应的 GameObject 上挂载 `GroundSurfaceTag` 组件，持有 `GroundSurfaceSO` 引用：

```csharp
public class GroundSurfaceTag : MonoBehaviour
{
    [SerializeField] public GroundSurfaceSO Surface;
}
```

`PlayerGroundDetector` 在 `hit.collider` 上调用 `GetComponent<GroundSurfaceTag>()` 获取当前地面材质（结果缓存，避免每帧 GetComponent）。

---

## 7. 地面类型枚举与脚步系统集成

```csharp
// PlayerGroundDetector 对外暴露
public GroundSurfaceSO CurrentSurface { get; private set; }
```

脚步系统（`FootstepSystem`，见 [20_AnimationEventSystem](./20_AnimationEventSystem.md)）在 Animation Event `FootstepLeft` / `FootstepRight` 触发时：

1. 读取 `PlayerGroundDetector.CurrentSurface`
2. 通过 `CurrentSurface.FootstepAddressLabel` 加载对应音效
3. 通过 `CurrentSurface.FootstepDustFX` 实例化粒子（可选）

---

## 8. Coyote Time 实现

**Coyote Time**（土狼时间）：玩家离地后仍有短暂窗口可以跳跃，提升平台跳跃手感。

```csharp
// PlayerGroundDetector 暴露接口
public bool CanCoyoteJump =>
    !IsGrounded &&
    Time.time - _lastGroundedTime <= _config.CoyoteTimeDuration &&
    !_usedCoyoteJump;

public void ConsumeCoyoteJump() => _usedCoyoteJump = true;

// 落地时重置
private void OnLandedInternal()
{
    _usedCoyoteJump = false;
    _lastGroundedTime = -999f; // 防止落地后立刻再次 Coyote
}
```

### Coyote Time 参数

| 参数 | 值 | 位置 |
|------|-----|------|
| `CoyoteTimeDuration` | 0.12s | `GroundDetectionConfigSO` |
| 重置条件 | 落地时 | 自动重置 |
| 使用次数 | 1 次（每次离地）| `_usedCoyoteJump` 标志位 |

---

## 9. PlayerGroundDetector — 完整实现

```csharp
namespace BaseGames.Player
{
    [DefaultExecutionOrder(-50)] // 在 PlayerController 之前执行
    public class PlayerGroundDetector : MonoBehaviour
    {
        // ── 配置 ──────────────────────────────────────────────────
        [SerializeField] GroundDetectionConfigSO _config;

        // ── 对外属性 ──────────────────────────────────────────────
        public bool             IsGrounded       { get; private set; }
        public Vector2          GroundNormal     { get; private set; } = Vector2.up;
        public Collider2D       GroundCollider   { get; private set; }
        public GroundSurfaceSO  CurrentSurface   { get; private set; }
        public bool             IsNearEdge       { get; private set; }
        public bool             IsOverVoid       { get; private set; }
        public float            SlopeAngle       => Vector2.Angle(GroundNormal, Vector2.up);
        public bool             IsOnSlope        => SlopeAngle > 1f && SlopeAngle < _config.MaxSlopeAngle;
        public bool             CanCoyoteJump    =>
            !IsGrounded &&
            Time.time - _lastGroundedTime <= _config.CoyoteTimeDuration &&
            !_usedCoyoteJump;

        // ── 内部状态 ──────────────────────────────────────────────
        Rigidbody2D   _rb;
        float         _lastGroundedTime  = -999f;
        bool          _usedCoyoteJump;
        Collider2D    _cachedSurfaceCollider;   // 缓存：避免每帧 GetComponent

        // ── 事件 ──────────────────────────────────────────────────
        public event System.Action<float> OnLanded;  // 参数：落地速度（绝对值）

        void Awake() => _rb = GetComponentInParent<Rigidbody2D>();

        void FixedUpdate()
        {
            CheckGround();
            CheckEdge();
        }

        void CheckGround()
        {
            Vector2 origin = (Vector2)transform.position + Vector2.up * _config.OffsetY;
            RaycastHit2D hit = Physics2D.BoxCast(
                origin,
                new Vector2(_config.BoxWidth, 0.02f),
                0f, Vector2.down, _config.BoxHeight,
                _config.GroundLayers);

            // 单向平台：仅在下落/静止时接受
            if (hit && hit.collider.gameObject.layer == LayerMask.NameToLayer("OneWayPlatform"))
                if (_rb.velocity.y > 0.1f) hit = default;

            bool wasGrounded = IsGrounded;
            IsGrounded      = hit.collider != null;
            GroundNormal    = IsGrounded ? hit.normal : Vector2.up;
            GroundCollider  = IsGrounded ? hit.collider : null;

            // 更新地面材质（有缓存，不每帧 GetComponent）
            if (IsGrounded && GroundCollider != _cachedSurfaceCollider)
            {
                _cachedSurfaceCollider = GroundCollider;
                CurrentSurface = GroundCollider.GetComponent<GroundSurfaceTag>()?.Surface;
            }
            else if (!IsGrounded) { _cachedSurfaceCollider = null; CurrentSurface = null; }

            // 事件派发
            if (!wasGrounded && IsGrounded)
            {
                _usedCoyoteJump = false;
                OnLanded?.Invoke(Mathf.Abs(_rb.velocity.y));
            }
            if (wasGrounded && !IsGrounded)
                _lastGroundedTime = Time.time;
        }

        void CheckEdge()
        {
            if (!IsGrounded) { IsNearEdge = false; IsOverVoid = false; return; }
            float hw = _config.EdgeCheckHorizontalOffset;
            bool edgeL = !Physics2D.Raycast(
                (Vector2)transform.position + new Vector2(-hw, 0f),
                Vector2.down, _config.EdgeCheckDepth, _config.GroundLayers);
            bool edgeR = !Physics2D.Raycast(
                (Vector2)transform.position + new Vector2(+hw, 0f),
                Vector2.down, _config.EdgeCheckDepth, _config.GroundLayers);
            IsNearEdge = (edgeL && !edgeR) || (!edgeL && edgeR);
            IsOverVoid  = edgeL && edgeR;
        }

        public void ConsumeCoyoteJump() => _usedCoyoteJump = true;
    }
}
```

### GroundDetectionConfigSO

```csharp
[CreateAssetMenu(menuName = "Player/GroundDetectionConfig")]
public class GroundDetectionConfigSO : ScriptableObject
{
    [Header("BoxCast 参数")]
    public float     BoxWidth                  = 0.45f;
    public float     BoxHeight                 = 0.08f;
    public float     OffsetY                   = -0.02f;
    public LayerMask GroundLayers;

    [Header("斜坡")]
    [Range(0f, 80f)]
    public float     MaxSlopeAngle             = 50f;
    public float     SlopeSpeedMultiplier_Up   = 0.85f;
    public float     SlopeStickForce           = -5f;

    [Header("边缘检测")]
    public float     EdgeCheckDepth            = 0.6f;
    public float     EdgeCheckHorizontalOffset = 0.22f;

    [Header("Coyote Time")]
    [Range(0f, 0.3f)]
    public float     CoyoteTimeDuration        = 0.12f;
}
```

---

## 10. 编辑器友好设计

### Gizmos 可视化

```csharp
#if UNITY_EDITOR
void OnDrawGizmosSelected()
{
    if (_config == null) return;
    Vector2 origin = (Vector2)transform.position + Vector2.up * _config.OffsetY;

    // BoxCast 范围
    Gizmos.color = IsGrounded ? Color.green : Color.red;
    Gizmos.DrawWireCube(origin + Vector2.down * _config.BoxHeight * 0.5f,
        new Vector3(_config.BoxWidth, 0.02f, 0f));

    // 边缘检测射线
    Gizmos.color = Color.yellow;
    float hw = _config.EdgeCheckHorizontalOffset;
    Gizmos.DrawRay((Vector2)transform.position + new Vector2(-hw, 0f), Vector2.down * _config.EdgeCheckDepth);
    Gizmos.DrawRay((Vector2)transform.position + new Vector2(+hw, 0f), Vector2.down * _config.EdgeCheckDepth);

    // 地面法线
    if (IsGrounded)
    {
        Gizmos.color = Color.cyan;
        Gizmos.DrawRay((Vector2)transform.position, GroundNormal * 0.5f);
    }
}
#endif
```

### 自定义 Inspector

```csharp
[CustomEditor(typeof(PlayerGroundDetector))]
public class PlayerGroundDetectorEditor : Editor
{
    public override VisualElement CreateInspectorGUI()
    {
        var root = new VisualElement();
        InspectorElement.FillDefaultInspector(root, serializedObject, this);

        // 运行时状态（只读）
        var statusGroup = new Foldout { text = "运行时状态（只读）" };
        var groundLabel  = new Label();
        var normalLabel  = new Label();
        var surfaceLabel = new Label();
        var edgeLabel    = new Label();
        statusGroup.Add(groundLabel);
        statusGroup.Add(normalLabel);
        statusGroup.Add(surfaceLabel);
        statusGroup.Add(edgeLabel);
        root.Add(statusGroup);

        root.schedule.Execute(() =>
        {
            if (target is PlayerGroundDetector det)
            {
                groundLabel.text  = $"IsGrounded: {det.IsGrounded}  SlopeAngle: {det.SlopeAngle:F1}°";
                normalLabel.text  = $"GroundNormal: {det.GroundNormal}";
                surfaceLabel.text = $"Surface: {(det.CurrentSurface != null ? det.CurrentSurface.name : "—")}";
                edgeLabel.text    = $"NearEdge: {det.IsNearEdge}  OverVoid: {det.IsOverVoid}  CoyoteOk: {det.CanCoyoteJump}";
            }
        }).Every(100);

        return root;
    }
}
```