Unity SDK 使用说明

下载路径：https://gitee.com/zd304/perfkitty/tree/master/UnitySDK

程序集：PerfKitty.UnitySDK.dll
命名空间：PerfKitty.UnitySDK
目标框架：.NET Standard 2.0

1. 接入图

flowchart LR
    A[Unity 项目] --> B[Assets/Plugins/PerfKitty]
    B --> C[PerfKitty.UnitySDK.dll]
    C --> D[127.0.0.1:27991]
    D --> E[PerfKitty]

项目	要求
Unity API Compatibility Level	.NET Standard 2.0 或兼容版本
通信地址	127.0.0.1:27991
必需文件	PerfKitty.UnitySDK.dll

安装目录

UnityProject/
└─ Assets/
   └─ Plugins/
      └─ PerfKitty/
         └─ PerfKitty.UnitySDK.dll

代码文件顶部引入：

using PerfKitty.UnitySDK;

2. 调用流程

stateDiagram-v2
    [*] --> Disabled
    Disabled --> Enabled: Enable(true)
    Enabled --> Collecting: RecordValue
    Collecting --> Collecting: 自动定时 Flush
    Collecting --> Collecting: FlushNow()
    Enabled --> Disabled: Disable()
    Collecting --> Disabled: Disable()

sequenceDiagram
    participant G as Unity Game
    participant S as Unity SDK
    participant P as PerfKitty

    G->>S: Enable(true, 1000)
    loop 每帧/事件
        G->>S: RecordValue(...)
    end
    S->>P: 每 1000ms 聚合并发送
    G->>S: FlushNow()
    G->>S: Disable()

3. API 总览

API	用途	默认行为
Enable(bool, int)	启用或关闭采集	1000 ms 刷新
Disable()	停止并清空状态	清空待发送指标
FlushNow()	立即发送当前数据	无数据时不发送
RecordValue(..., int, ...)	记录整数指标	Avg 聚合
RecordValue(..., float, ...)	记录浮点指标	Avg 聚合
PerfKittyAggregate	选择聚合方式	Avg

---

4. PerfKittyAggregate

public enum PerfKittyAggregate

值	输出值	示例输入 10, 20, 30
Last	最后一次	30
Min	最小值	10
Max	最大值	30
Avg	平均值	20
Sum	总和	60

flowchart LR
    V[多次 RecordValue] --> L[Last]
    V --> N[Min]
    V --> X[Max]
    V --> A[Avg]
    V --> S[Sum]
    L --> F[Flush]
    N --> F
    X --> F
    A --> F
    S --> F

---

5. Enable

public static void Enable(
    bool enabled,
    int flushIntervalMs = 1000)

参数	说明
enabled	true 启用；false 等同于 Disable()
flushIntervalMs	自动发送间隔，必须大于 0

情况	结果
Enable(true)	每 1000 ms 自动发送
Enable(true, 500)	每 500 ms 自动发送
Enable(false)	关闭并清空状态
间隔小于或等于 0	抛出 ArgumentOutOfRangeException

---

6. Disable

public static void Disable()

flowchart LR
    A[Disable] --> B[停止定时器]
    B --> C[清空采集状态]

需要发送最后一批数据时，先调用 FlushNow()，再调用 Disable()。

---

7. FlushNow

public static void FlushNow()

当前状态	结果
SDK 未启用	忽略
没有待发送指标	忽略
存在待发送指标	立即聚合并发送
PerfKitty 未监听端口	可能抛出网络异常

---

8. RecordValue：整数

public static void RecordValue(
    string category,
    string key,
    int value,
    PerfKittyAggregate aggregate = PerfKittyAggregate.Avg)

参数	示例	说明
category	"Rendering"	指标分类，不能为空
key	"DrawCalls"	指标名称，不能为空
value	128	整数值
aggregate	Max	聚合方式，默认 Avg

PerfKittyUnity.RecordValue(
    "Rendering",
    "DrawCalls",
    128,
    PerfKittyAggregate.Max);

---

9. RecordValue：浮点数

public static void RecordValue(
    string category,
    string key,
    float value,
    PerfKittyAggregate aggregate = PerfKittyAggregate.Avg)

参数	示例	说明
category	"Frame"	指标分类，不能为空
key	"FrameTimeMs"	指标名称，不能为空
value	16.67f	浮点值
aggregate	Avg	聚合方式，默认 Avg

PerfKittyUnity.RecordValue(
    "Frame",
    "FrameTimeMs",
    16.67f);

指标定义规则

同一次启用周期内，category + key 必须保持相同的数值类型和聚合方式。

首次定义	后续调用	结果
FPS / int / Avg	FPS / int / Avg	正常
FPS / int / Avg	FPS / float / Avg	InvalidOperationException
FPS / int / Avg	FPS / int / Max	InvalidOperationException

flowchart TD
    A[category + key] --> B{定义是否一致}
    B -->|类型和聚合一致| C[累计数据]
    B -->|类型或聚合变化| D[抛出定义冲突异常]

---

10. 异常速查

异常	原因	处理
ArgumentOutOfRangeException	刷新间隔小于或等于 0	使用正整数毫秒值
ArgumentException	category 或 key 为空	提供稳定名称
InvalidOperationException	同名指标定义发生变化	固定类型和聚合方式，或先 Disable()
网络相关异常	本机端口未监听或连接失败	确认 PerfKitty 已启动

11. 完整使用示例

using PerfKitty.UnitySDK;
using UnityEngine;

public sealed class PerfKittyExample : MonoBehaviour
{
    [SerializeField]
    private int flushIntervalMs = 1000;

    private void OnEnable()
    {
        PerfKittyUnity.Enable(true, flushIntervalMs);
    }

    private void Update()
    {
        var frameTimeMs = Time.unscaledDeltaTime * 1000.0f;
        var fps = frameTimeMs > 0.0f
            ? Mathf.RoundToInt(1000.0f / frameTimeMs)
            : 0;

        PerfKittyUnity.RecordValue(
            "Frame",
            "FrameTimeMs",
            frameTimeMs,
            PerfKittyAggregate.Avg);

        PerfKittyUnity.RecordValue(
            "Frame",
            "FPS",
            fps,
            PerfKittyAggregate.Avg);
    }

    private void OnApplicationPause(bool paused)
    {
        if (paused)
        {
            PerfKittyUnity.FlushNow();
        }
    }

    private void OnDisable()
    {
        PerfKittyUnity.FlushNow();
        PerfKittyUnity.Disable();
    }
}