在自己的 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

服務狀態