Android Performance Tuner 简介 (Unity)
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本指南将介绍如何使用 Unity 插件记录和上传来自 Unity 2017.4 或更高版本的帧时间数据。
对于使用 C 或 C++ 的游戏引擎,请参阅原生游戏引擎指南。
背景
渲染性能是游戏体验的关键组成部分。渲染性能取决于以下两项输入:
- 帧速率:绘制帧的频率。
- 图形画质设置:呈现帧时的保真度,包括模拟保真度和图形。
对于游戏,良好的渲染性能定义如下:
- 提供稳定一致的帧速率(即,以理想频率渲染的帧的百分比)。
- 以尽可能高的频率渲染帧,同时保持稳定性,通常为 30 或 60 FPS,具体取决于游戏类型。
- 根据用户屏幕尺寸和密度,为用户呈现最大程度的细节,同时仍保持所需的稳定帧速率。
Android Frame Pacing 库会限制大部分的帧时间变化,为游戏提供稳定的帧速率。帧时间的其余变化是由游戏过程中某些场景显示的细节程度以及设备的图形功能决定的。使用 Android Performance Tuner 可以找出游戏过程中帧时间比目标值慢或快的时间,并将这些问题和优化建议关联到以下方面:
- 具体画质设置
- 游戏中的特定场景
- 特定设备型号或设备规格
记录和上传数据
Tuning Fork 库依赖于由 Android Frame Pacing 库为每帧调用的其中一个 tick 函数(或者,在较低版本的 Unity 中由 Unity 引擎调用,因为此类 Unity 中不存在 Frame Pacing 库)。在库中,此 tick 信息汇总成直方图,然后通过 HTTP 端点定期上传至 Google Play。每个 tick 都被记录为与一个插桩键和注解相关联。您可以使用 Unity 插件定义注解。
插桩键
插桩键指示 tick 来自帧中的什么位置,并且是必须传递给每个 tick 函数调用的整数。此操作由 Unity 插件自动完成。如果您在游戏的 Unity 设置中启用了“Optimized Frame Pacing”选项(适用于 Unity 2019.3.14 或更高版本),Android Performance Tuner 将使用来自 Android Frame Pacing 库的信息以报告增强型指标。
注释
注解可以提供有关记录 tick 时游戏在进行何种操作的背景信息。例如,注释可以识别以下任何信息:
- 当前游戏关卡
- 正在加载特定场景
- 屏幕上出现“大 Boss”
- 任何其他相关的游戏状态信息
注解在 Unity 插件提供的对话框中定义。
在内部,Tuning Fork 库使用 Google 的协议缓冲区格式存储注释和保真度参数。它是一种明确定义的多语言协议,适用于可扩展的结构化数据。如需了解详情,请参阅协议缓冲区文档。
保真度参数
保真度参数会影响游戏的性能和图形保真度,例如网格细节层次、纹理分辨率和抗锯齿方法。与注解一样,保真度参数在 Unity 插件提供的对话框中定义。
内存和 CPU 开销
Tuning Fork 库使用的所有内存在初始化时进行分配,以避免游戏过程中出现意外。数据大小取决于插桩键的数量、可能的注解数量以及每个直方图中的存储分区数量;它的值为所有这些数值相乘后再乘以 4(每个存储分区 4 个字节)得出的字节数。此外,所有直方图还有两个副本,用于双缓冲方式的提交。
提交操作在单独的线程中执行,不会阻碍 tick 调用。如果上传连接不可用,提交操作会加入队列以供之后上传。
调用 tick 函数几乎没有处理开销:它只计算直方图存储分区数组的一个索引,并递增整数计数。
网络请求
该库向服务器端点发出两种类型的请求:
- 初始化时的
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 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-01。
[null,null,["最后更新时间 (UTC):2025-08-01。"],[],[],null,["# Overview of Android Performance Tuner (Unity)\n\nThis 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----------\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----------------------\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\n### Instrument 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\n### Annotations\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-------------------\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-----------------------\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------------\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\n### Offline 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------------\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--------------------------------------------\n\nFor information about integrating Android Performance Tuner in Unity, see\n[Enable the API](/games/sdk/performance-tuner/unity/enable-api)."]]