Google is committed to advancing racial equity for Black communities. See how.

Define annotations, fidelity parameters, and quality levels

This document describes how to set annotations, fidelity parameters, and quality levels in your Unity project.

Annotations

Annotations give contextual information about what your game is doing when a tick is recorded.

Default annotations

The plugin defines two default annotations for you:

  • scene: Contains the identifier of the current scene being played; useful in cases where most of your levels map to a single scene in your project
  • loading_state: Identifies when a scene is loading; by default, this is set to NOT_LOADING

To see these annotations in UI, do the following:

  1. Select Google > Android Performance Tuner.
  2. Select the Annotation parameters tab and then click Use custom parameters.

    Figure 1. Annotation parameters tab in the plugin

Define and use a custom annotation

To create a custom annotation, do the following:

  1. On the Annotation parameters tab, click the + button to create a new annotation.
  2. In the new row, click on the Type column and select Add or update enum. As an example, you can make an enumeration for the game difficulty.

  3. Click the Add New Enum button after specifying the enum values.

    Figure 2. Add a new enum

  4. Select the new type in the Type column. Enter a name for the parameter in the Parameter name column.

    Figure 3. Select the new enum

  5. Click the Apply button to let the plugin regenerate the protocol buffer files and classes.

To set this annotation in your game, call SetCurrentAnnotation():

tuner.SetCurrentAnnotation(new Annotation
{
    Scene = Scene.AssetsScenesMainmenu,
    LoadingState = LoadingState.Loading
    GameDifficulty = Difficulty.Medium
});

Define loading annotations

Loading annotations mark frames that are part of the level-loading process. Use loading annotations so that slower frames, such as those that occur while the game is loading, do not affect your overall metrics.

Before loading starts, set the loading annotation:

tuner.SetCurrentAnnotation(new Annotation
{
    Scene = Scene.AssetsScenesMainmenu,
    LoadingState = LoadingState.Loading
    // And any other annotation
});

After loading finishes, set the not-loading annotation:

tuner.SetCurrentAnnotation(new Annotation
{
    Scene = Scene.AssetsScenesMainmenu,
    LoadingState = LoadingState.NotLoading
    // And any other annotation
});

Define fidelity parameters and quality levels

Fidelity parameters reflect the performance and graphical settings of your game. Quality levels are used to annotate sessions so that you can determine if devices are running on a quality level that is too high (resulting in lower performance) or too low (resulting in unnecessarily reduced fidelity).

Your game might already have different fidelity parameters such as the following:

  • Shadow quality
  • Texture resolution
  • Particle effects quality

These parameters can be regrouped into quality levels (for example "low", "medium", and "high"). To have these parameters properly reported by Android Performance Tuner, and then analyzed and visualized in the Google Play Console, you must expose the parameters to the plugin. Add your fidelity parameters in the Fidelity parameters tab.

Figure 4. Fidelity parameters tab in the plugin

Select Use custom parameters, and then define a set of parameters. Each parameter has a type, like annotations.

Use the SetFidelityParameters() function to set the fidelity parameters as appropriate in your game:

tuner.SetFidelityParameters(new FidelityParams
{
    ParticleDetails = 1.0f,
    ShadowQuality = ShadowQuality.High,
    TextureResolution = 2048,
});

Next, define different quality levels that will be used to group the data in the Google Play Console and give you better insights. Add your quality levels in the Quality levels tab.

Click the Add Level button to add your first level. Define multiple levels that follow a trend. For example, define levels for the lowest quality level to the highest.

Figure 5. Quality levels tab in the plugin