This guide describes how to use a Unity plugin to record and upload frame time
data from **Unity 2017.4 or later**.
| **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).

For game engines using C or C++, see the
[guide for native game engines](https://developer.android.com/games/sdk/performance-tuner/custom-engine).

## 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](https://developer.android.com/games/sdk/frame-pacing) 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](https://developer.android.com/games/sdk/performance-tuner/unity#instrument-keys) and an
[annotation](https://developer.android.com/games/sdk/performance-tuner/unity#annotations). 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](https://developers.google.com/protocol-buffers/).

## 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](https://dotnet.microsoft.com/download/dotnet-framework/net46)
- 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](https://docs.unity3d.com/Packages/com.unity.addressables@0.8/manual/index.html) or later are required.

## Integrate Android Performance Tuner in Unity

For information about integrating Android Performance Tuner in Unity, see
[Enable the API](https://developer.android.com/games/sdk/performance-tuner/unity/enable-api).