在自己的 PC 上比较 Unity 性能运行（试点）

这个可选试点在你管理的 PC 上测量可重复的场景，由 Framedash 保存汇总并比较证据。先人工查看结果；CI 和自动判定是后续独立步骤。这种非空间比较不需要注册地图。

前提条件

Unity 2022.3 或更新版本与 Framedash Unity SDK 0.1.8，Node.js 20 或更新版本与 CLI 0.1.11。Unity 0.1.7 / CLI 0.1.10 及更早版本不包含这些功能。
Framedash 项目、供播放器上传的 events:write 密钥，以及独立的 analytics:read 比较密钥。使用环境变量或私有文件，不要提交密钥。
未启用 COPPA 的组织。保护处理会删除必要属性，所以比较 API 返回403。请保留必要的隐私设置；本地完成或 HTTP 应答不能证明使用资格。

在 Unity Package Manager 中使用固定标签的 Git URL，并安装 CLI。

https://github.com/crane-valley/framedash-unity-sdk.git#v0.1.8

npm install --global @framedash/cli@0.1.11

1. 保持条件一致

将同一基准构建运行两次，再运行候选。包括重试在内，每次执行都使用新的小写 UUID v4。保持场景、硬件配置、画质、分辨率、设置、引擎/平台、SDK 版本、预热和帧数一致。无改动重复运行的构建 ID 和提交也必须与基准一致。记录驱动、电源/温控策略、VSync/FPS 限制。相同标签不能证明实际环境一致。

2. 测量场景

完成设置后，在播放器主线程调用，并替换成实际的构建、提交和配置。标签应是配置名称，不要使用设备序列号或个人信息。标签不能只有空白，最多128个 UTF-16 代码单元，不含 ASCII 控制字符。保存输出的运行 ID；若 started 为false，不要继续测量。

var sdk = Framedash.TelemetrySDK.Initialize(
    apiKey: System.Environment.GetEnvironmentVariable("FRAMEDASH_API_KEY"),
    buildId: "build-a");
var options = new Framedash.PerformanceRunOptions
{
    RunId = System.Guid.NewGuid().ToString("D"),
    Scenario = "route-a",
    Hardware = "lab-pc-a",
    Graphics = "high-vsync-off",
    Resolution = "1920x1080",
    Configuration = "release-dx12-driver-profile-a",
    Commit = "commit-sha",
    Branch = "main",
    WarmupFrames = 120,
    TargetFrames = 3600,
};
bool started = sdk.BeginPerformanceRun(options);
UnityEngine.Debug.Log("Performance run: " + options.RunId + ", started=" + started);

在 Unity 播放器循环运行时执行场景。示例排除120个预热间隔，再收集3,600个间隔，并不保证固定时长。选择足以覆盖测量窗口的可重复场景，并另外限制进程运行时间。场景完成后，在主线程调用：

bool complete = sdk.EndPerformanceRun();
bool acknowledged = sdk.FlushBlocking(5000);
UnityEngine.Debug.Log("complete=" + complete + ", acknowledged=" + acknowledged);

检查两个返回值，再检查服务器结果。complete 仅表示本地证据；标记入队失败、缓冲区溢出、缺失样本或提前结束都不能成功。acknowledged 确认 HTTP 应答，不证明持久保存。中止使用 EndPerformanceRun(completed: false)。崩溃或测量期间关闭 SDK 会保持未完成。单独运行 run-profile-test 不会启动此测量。

3. 读取比较

使用日志中的项目 ID 和三个运行 ID。只读取最近7天。没有无改动重复运行时可省略 --repeat，但不能据此认定测量稳定。

framedash run-diff --project-id "$FRAMEDASH_PROJECT_ID" \
  --api-key-file analytics-read.key \
  --baseline "$BASELINE_RUN_ID" --candidate "$CANDIDATE_RUN_ID" \
  --repeat "$REPEAT_RUN_ID" --format json

解读证据

JSON 包含条件、时间戳、有效/丢弃/预热样本数、时长、P50/P95/P99 区间，以及严格超过1,000/60、1,000/30、50和100ms的次数及每1,000帧的比率。table/csv提供分位数简表。

测量的是 SDK Update 回调间的实际经过时间，不是 GPU 时间或画面呈现间隔；第一个回调被排除。分位数是上界不包含在内的直方图区间，差分保守地计算候选减基准。正差表示更长的帧间隔。这些范围及无改动重复差异不是统计置信区间。一次重复和最低1,000帧不能确立噪声水平或统计可靠性。

退出码	含义
`0`	证据可比较。候选变慢仍为0，不是回归判定。
`2`	无法得出比较结果。检查缺失、未完成或条件不一致。
`1`	命令/API错误，包括无效响应。

故障排查

没有记录： 检查上传密钥、项目、运行 ID 和7天范围，并在有限次数内等待摄取完成。flush成功不够。
未完成： 检查结束结果、帧数与丢弃样本。无效、非正或>=32,768ms的间隔作为丢弃样本消耗测量窗口。预热范围0..60,000，目标1,000..1,000,000。用新ID重新运行整个场景。
条件不同： 修正声明和实际条件，不要将不同设备或构建改成相同标签来强行比较。重复运行必须使用基准构建与提交。
冲突/记录过多： 不要重复使用ID；每次运行在去重前最多读取16条原始记录。
403： 检查项目访问权、analytics:read、账户权益和 COPPA 使用资格，不要降低隐私保护。

与团队成员查看结果，记录下一步调查和设置时间，并在修复后重新测量。此报告不确定根因，也不保证发布安全。现有 CI 性能门控保持原行为。参见 API 概览和 Unity SDK 设置。

面向 AI 代理: llms.txt

服务状态