Overview of Android Performance Tuner (Unity)

This guide describes how to use a Unity plugin to record and upload frame time data from Unity 2017.4 or later.

For game engines using C or C++, see the guide for native game engines.

Background

A key component of the game experience is rendering performance. Rendering performance is an outcome of the following two inputs:

  • Frame rate: How often a frame is drawn.
  • Graphical quality settings: Level of fidelity at which a frame is presented, including simulation fidelity as well as graphics.

For games, good rendering performance is defined as the following:

  • Delivering a stable, consistent frame rate (that is, the percentage of frames rendering at the desired frequency).
  • Rendering frames at the highest frequency possible while maintaining stability, typically 30 or 60 FPS depending on the type of game.
  • Maximizing the level of detail for a user given their screen size and density while still achieving a desired, stable frame rate.

The Android Frame Pacing library limits much of the variation in frame times, providing a stable frame rate for games. The remaining variation in frame times is due to the level of detail displayed during certain scenes in gameplay and the graphical capabilities of the device. Using Android Performance Tuner, you can pinpoint times during gameplay when the frame time is slower or faster than your target, and correlate these issues and opportunities to:

  • Specific quality settings
  • Specific scenes in your game
  • Specific device models or device specs

Record and upload data

The Tuning Fork library relies on one of its tick functions being called each frame by the Android Frame Pacing library (or by the Unity engine for older versions of Unity where the Frame Pacing Library is not present). Within the library, this tick information is aggregated into histograms which are then periodically uploaded to Google Play through an HTTP endpoint. Each tick is recorded as being associated with an instrument key and an annotation. You define annotations using the Unity plugin.

Instrument keys

An instrument key indicates where in the frame the tick comes from and is an integer that must be passed to each tick function call. This is done automatically by the Unity plugin. If the Optimized Frame Pacing option is enabled in the Unity settings for your game (available in Unity version 2019.3.14 or later), Android Performance Tuner will use information from the Android Frame Pacing library to report enhanced metrics.

Annotations

Annotations give contextual information about what your game is doing when a tick is recorded. For example, an annotation could identify any of the following:

  • The current game level
  • A specific scene is loading
  • A "big boss" is on the screen
  • Any other relevant game state information

Annotations are defined in a dialog provided by the Unity plugin.

Internally, the Tuning Fork library uses Google’s protocol buffer format to store annotations and fidelity parameters. This is a well-defined, multi-language protocol for extensible, structured data. For more information, see the Protocol Buffers documentation.

Fidelity parameters

Fidelity parameters influence the performance and graphical fidelity of your game, such as mesh level-of-detail, texture resolution, and anti-aliasing method. Like annotations, fidelity parameters are defined in a dialog provided by the Unity plugin.

Memory and CPU overhead

All memory used by the Tuning Fork library is allocated at initialization in order to avoid surprises during gameplay. The size of the data depends on the number of instrument keys, number of possible annotations, and number of buckets in each histogram; it is a multiple of all of these times four bytes for each bucket. There are also two copies of all histograms to allow for submission in a double-buffered fashion.

Submission occurs on a separate thread and doesn't block tick calls. If no upload connection is available, the submission is queued for later upload.

There is little processing overhead to calling a tick function: it simply calculates an index into the array of histogram buckets and increments an integer count.

Web requests

The library makes two kinds of requests to the server endpoint:

  • A generateTuningParameters request at initialization
  • Periodically during gameplay, an uploadTelemetry request to send data to the server

Offline players

If there is no available connection at initialization, the request is retried several times with an increasing back-off time. If there is no connection at upload, the upload is cached. Uploads are stored as files in temporary storage.

Requirements

To use the plugin in your game, use a supported version of Unity:

  • Unity version 2017.4 or later and .NET version 4.6
  • To use APK Expansion files, Unity 2018.2 is required
  • For improved frame pacing and GPU measurements, Unity version 2019.3.14 or later is required
  • For Addressables scenes support, Unity 2019.3 or later and Addressables package 1.19.4 or later are required.

Integrate Android Performance Tuner in Unity

For information about integrating Android Performance Tuner in Unity, see Enable the API.