# IGP Unity SDK - KCP 心跳与 RTT 指南

## 目标

这份指南说明如何在 Unity 游戏里读取和利用：

- hosted data plane / KCP 连接状态
- 心跳保活
- RTT 统计
- 网络质量 UI

## 最短用法

```csharp
using UnityEngine;
using IGP.UnitySDK;

public class NetworkHealthProbe : MonoBehaviour
{
    [SerializeField] private IGPRuntimeManager runtimeManager;

    void Update()
    {
        if (runtimeManager.KcpRTTStats == null)
        {
            return;
        }

        var avgMs = runtimeManager.KcpRTTStats.AvgRTT * 1000f;
        Debug.Log($"KCP alive={runtimeManager.IsKcpAlive}, avgRTT={avgMs:F0}ms");
    }
}
```

## Inspector 相关字段

`IGPRuntimeManager` 当前包含这些网络相关配置：

- `Enable KCP`
- `Kcp Heartbeat Interval`
- `Enable Kcp Heartbeat`
- `Show RTT Stats`

建议默认先保持：

- `Enable KCP = true`
- `Enable Kcp Heartbeat = true`
- `Kcp Heartbeat Interval = 1.0`

## 常用运行时状态

| 属性 | 作用 |
| --- | --- |
| `IsHostedDataPlaneAttached` | 宿主数据面是否已经附着 |
| `IsKcpConnected` | 当前数据面是否建立连接 |
| `IsKcpAlive` | 心跳是否仍然健康 |
| `KcpRTTStats` | 当前 RTT 统计对象 |

## 根据状态调节心跳

```csharp
using IGP.UnitySDK;

public sealed class AdaptiveHeartbeat : MonoBehaviour
{
    [SerializeField] private IGPRuntimeManager runtimeManager;

    public void EnterBattle()
    {
        runtimeManager.SetHeartbeatIntervalForGameState(GameState.InBattle);
    }

    public void EnterMatch()
    {
        runtimeManager.SetHeartbeatIntervalForGameState(GameState.InGame);
    }

    public void EnterLobby()
    {
        runtimeManager.SetHeartbeatIntervalForGameState(GameState.Idle);
    }
}
```

推荐值：

- `Idle`: 5s
- `InGame`: 1s
- `InBattle`: 100ms

## UI 展示建议

开发期可以直接启用 `Show RTT Stats`。  
正式游戏里更推荐自己接一层 UGUI：

```csharp
using UnityEngine;
using UnityEngine.UI;
using IGP.UnitySDK;

public sealed class NetworkHud : MonoBehaviour
{
    [SerializeField] private IGPRuntimeManager runtimeManager;
    [SerializeField] private Text rttText;

    void Update()
    {
        var stats = runtimeManager.KcpRTTStats;
        if (stats == null || stats.SampleCount == 0)
        {
            rttText.text = "RTT: --";
            return;
        }

        rttText.text = $"RTT: {stats.AvgRTT * 1000f:F0}ms";
    }
}
```

## 开发建议

推荐：

- 把 `IsKcpAlive` 当成游戏内连接健康信号
- 把 `KcpRTTStats` 接到调试 HUD
- 在战斗态和大厅态之间切换心跳频率

避免：

- 把心跳间隔压到 `50ms` 以下
- 只看 `IsKcpConnected`，不看 `IsKcpAlive`
- 忽略高 RTT 对玩法同步的影响

## 对应 sample

如果你需要一个带 UI 和日志的综合入口，先看：

- `Samples~/HostedPlayground`

如果你只想验证最小链路，先看：

- `Samples~/HostedQuickstart`
