Android Performance Tuner (Unity) 總覽
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本指南介紹如何使用 Unity 外掛程式從 Unity 2017.4 或更高版本記錄及上傳影格時間資料。
對於使用 C 或 C++ 的遊戲引擎，請參閱原生遊戲引擎指南。
背景
遊戲體驗的其中一個關鍵是呈現效能。呈現效能是下列兩個輸入的結果：
- 影格速率：影格的繪製頻率。
- 圖形品質設定：影格呈現的保真度，包括模擬畫面保真度和圖形。
遊戲的良好呈現效能定義如下：
- 提供穩定且一致的影格速率 (即以所需頻率呈現影格百分比)。
- 盡可能以最高頻率呈現影格，同時維持穩定性。通常是 30 或 60 FPS，視遊戲類型而定。
- 在指定使用者的螢幕尺寸和密度設定的情況下，盡可能為使用者提高細節等級，同時又能達到所需的穩定影格速率。
Android Frame Pacing 程式庫會限制影格時間的大部分變化，為遊戲提供穩定影格速率。影格時間的剩餘變化是由於遊戲過程中特定情境顯示的細節等級，以及裝置的圖形功能所致。使用 Android Performance Tuner 時，您可以在遊戲過程中找出影格時間比目標慢或快的時間點，瞭解這些問題和下列可改善項目的關聯：
- 特定畫質設定
- 遊戲中的特定情境
- 特定裝置型號或裝置規格
記錄及上傳資料
Tuning Fork 程式庫依賴的是由 Android Frame Pacing 程式庫針對每個影格呼叫的其中一個滴答函式 (或者對於不存在 Frame Pacing 程式庫的較舊版 Unity，則由 Unity 引擎呼叫)。在程式庫中，此刻點資訊會彙整為直方圖，然後定期透過 HTTP 端點上傳至 Google Play。每個刻點都會記錄為與檢測金鑰和註解相關聯。您可使用 Unity 外掛程式定義註解。
檢測金鑰
檢測金鑰代表刻點在影格中的位置，是傳遞給每個刻點函式呼叫的整數。這項作業是由 Unity 外掛程式自動執行。如果遊戲的 Unity 設定已啟用「Optimized Frame Pacing」選項 (在 Unity 2019.3.14 或以上版本中可用)，Android Performance Tuner 將使用 Android Frame Pacing 程式庫的資訊報告加強型指標。
註解
註解可提供您遊戲當下發生情況的情境資訊。舉例來說，註解可標示下列任一項目：
- 目前的遊戲等級
- 正在載入特定情境
- 畫面上顯示「大頭目」
- 任何其他相關遊戲狀態資訊
您可以在 Unity 外掛程式提供的對話方塊中定義註解。
Tuning Fork 程式庫在內部使用 Google 的通訊協定緩衝區格式來儲存註解和擬真度參數。這是一種可明確定義的多語言通訊協定，適用於可擴充的結構化資料。詳情請參閱通訊協定緩衝區說明文件。
擬真度參數
擬真度參數會影響遊戲的效能和圖形擬真度，例如網格細緻度、紋理解析度和鋸齒消除方法。與註解一樣，擬真度參數也是在 Unity 外掛程式提供的對話方塊中定義。
記憶體與 CPU 負擔
為避免在遊戲過程中產生意外，系統會在初始化時分配 Tuning Fork 程式庫使用的所有記憶體。資料大小取決於檢測金鑰的數量、可能的註解數量，以及每個直方圖中的值區數量；它是上述所有數量乘以每個值區的四個位元組的倍數。此外，所有直方圖都有兩個副本，方便以雙緩衝方式提交。
提交內容是在獨立執行緒上，不會阻斷滴答呼叫。如果沒有可用的上傳連線，系統會將提交內容排入佇列，以便稍後上傳。
呼叫刻點函式幾乎不會產生處理負擔，只會將索引計算為直方圖值區陣列，並增加整數計數。
網路要求
程式庫會向伺服器端點發出兩種要求：
- 初始化時的
generateTuningParameters 要求
- 在遊戲過程中，將資料傳送至伺服器的定期
uploadTelemetry 要求
離線玩家
如果初始化時沒有可用的連線，隨著撤回次數的增加，需要重試要求數次。如果上傳時沒有任何連線，則系統會快取上傳。上傳內容會以檔案的形式儲存在暫存儲存空間中。
規定
如要在遊戲中使用這個外掛程式，請使用系統支援的 Unity 版本：
- Unity 2017.4 以上版本和 .NET 4.6 版
- 如要使用 APK 擴充檔案，必須使用 Unity 2018.2
- 如要改善影格速度和 GPU 測量結果，必須使用 Unity 2019.3.14 以上版本
- 如需支援 Addressables 場景，必須使用 Unity 2019.3 以上版本和 Addressables 套件 1.19.4 以上版本
在 Unity 中整合 Android Performance Tuner
如要進一步瞭解如何在 Unity 中整合 Android Performance Tuner，請參閱「啟用 API」。
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間：2025-08-26 (世界標準時間)。
[null,null,["上次更新時間：2025-08-26 (世界標準時間)。"],[],[],null,["This guide describes how to use a Unity plugin to record and upload frame time\ndata from **Unity 2017.4 or later**.\n| **Note:** For a guided tutorial, see the [Integrating Android Performance Tuner into your Unity game Codelab](https://codelabs.developers.google.com/codelabs/android-performance-tuner-unity).\n\nFor game engines using C or C++, see the\n[guide for native game engines](/games/sdk/performance-tuner/custom-engine).\n\nBackground\n\nA key component of the game experience is *rendering performance*. Rendering\nperformance is an outcome of the following two inputs:\n\n- Frame rate: How often a frame is drawn.\n- Graphical quality settings: Level of fidelity at which a frame is presented, including simulation fidelity as well as graphics.\n\nFor games, good rendering performance is defined as the following:\n\n- Delivering a stable, consistent frame rate (that is, the percentage of frames rendering at the desired frequency).\n- Rendering frames at the highest frequency possible while maintaining stability, typically 30 or 60 FPS depending on the type of game.\n- Maximizing the level of detail for a user given their screen size and density while still achieving a desired, stable frame rate.\n\nThe [Android Frame Pacing library](/games/sdk/frame-pacing) limits much of the\nvariation in frame times, providing a stable frame rate for games. The remaining\nvariation in frame times is due to the level of detail displayed during certain\nscenes in gameplay and the graphical capabilities of the device. Using\nAndroid Performance Tuner, you can pinpoint times during gameplay when the frame time\nis slower or faster than your target, and correlate these issues and\nopportunities to:\n\n- Specific quality settings\n- Specific scenes in your game\n- Specific device models or device specs\n\nRecord and upload data\n\nThe Tuning Fork library relies on one of its tick functions being called\neach frame by the Android Frame Pacing library (or by the Unity engine for older\nversions of Unity where the Frame Pacing Library is not present). Within the\nlibrary, this tick information is aggregated into histograms which are then\nperiodically uploaded to Google Play through an HTTP endpoint. Each tick is\nrecorded as being associated with an [instrument key](#instrument-keys) and an\n[annotation](#annotations). You define annotations using the Unity plugin.\n\nInstrument keys\n\nAn instrument key indicates where in the frame the tick comes from and is an\ninteger that must be passed to each tick function call. This is done\nautomatically by the Unity plugin. If the Optimized Frame Pacing option is\nenabled in the Unity settings for your game (available in\nUnity version 2019.3.14 or later), Android Performance Tuner will use\ninformation from the Android Frame Pacing library to report enhanced metrics.\n\nAnnotations\n\nAnnotations give contextual information about what your game is doing when a\ntick is recorded. For example, an annotation could identify any of the\nfollowing:\n\n- The current game level\n- A specific scene is loading\n- A \"big boss\" is on the screen\n- Any other relevant game state information\n\nAnnotations are defined in a dialog provided by the Unity plugin.\n\nInternally, the Tuning Fork library uses Google's protocol buffer format\nto store annotations and fidelity parameters. This is a well-defined,\nmulti-language protocol for extensible, structured data. For more information,\nsee the\n[Protocol Buffers documentation](https://developers.google.com/protocol-buffers/).\n\nFidelity parameters\n\nFidelity parameters influence the performance and graphical fidelity of your\ngame, such as mesh level-of-detail, texture resolution, and anti-aliasing\nmethod. Like annotations, fidelity parameters are defined in a dialog provided\nby the Unity plugin.\n\nMemory and CPU overhead\n\nAll memory used by the Tuning Fork library is allocated at\ninitialization in order to avoid surprises during gameplay. The size of the data\ndepends on the number of instrument keys, number of possible annotations, and\nnumber of buckets in each histogram; it is a multiple of all of these times four\nbytes for each bucket. There are also two copies of all histograms to allow for\nsubmission in a double-buffered fashion.\n\nSubmission occurs on a separate thread and doesn't block tick calls. If no\nupload connection is available, the submission is queued for later upload.\n\nThere is little processing overhead to calling a tick function: it simply\ncalculates an index into the array of histogram buckets and increments an\ninteger count.\n\nWeb requests\n\nThe library makes two kinds of requests to the server endpoint:\n\n- A `generateTuningParameters` request at initialization\n- Periodically during gameplay, an `uploadTelemetry` request to send data to the server\n\nOffline players\n\nIf there is no available connection at initialization, the request is retried\nseveral times with an increasing back-off time. If there is no connection at\nupload, the upload is cached. Uploads are stored as files in temporary storage.\n\nRequirements\n\nTo use the plugin in your game, use a supported version of Unity:\n\n- Unity version 2017.4 or later and [.NET version 4.6](https://dotnet.microsoft.com/download/dotnet-framework/net46)\n- To use APK Expansion files, Unity 2018.2 is required\n- For improved frame pacing and GPU measurements, Unity version 2019.3.14 or later is required\n- For Addressables scenes support, Unity 2019.3 or later and [Addressables package 1.19.4](https://docs.unity3d.com/Packages/com.unity.addressables@0.8/manual/index.html) or later are required.\n\nIntegrate Android Performance Tuner in Unity\n\nFor information about integrating Android Performance Tuner in Unity, see\n[Enable the API](/games/sdk/performance-tuner/unity/enable-api)."]]
