The GameBench Unity Package

Latest Version: 0.7.4
Status: This version should be considered Alpha quality and should not be included into release or release candidate games.

Table of contents

  1. What is the GameBench Unity Package?
  2. Installation
  3. Configuration
  4. Metrics
  5. The API
  6. Overhead
  7. Uninstallation

1. What is the GameBench Unity Package?

The GameBench Unity Package enables the capture and remote analysis of performance data for games developed with the Unity game engine. Performance data is uploaded to GameBench servers and may be browsed in the GameBench Web Dashboard or accessed programmatically via the GameBench Session Data API.

Supported platforms

  • iOS 10.0 or above
  • Android 6.0 or above (armeabi-v7a and arm64-v8a)
  • We’ve tested this package with many devices, see our device list.

Supported Unity versions

  • Unity 2018, 2019, 2020. (NB: 2017 is unsupported but should be usable with special install instructions)
  • Unity Scripting Backend: IL2CPP and Mono
  • Unity Scripting Runtime Version: All stable .NET versions

2. Installation


IMPORTANT

If upgrading from version 0.6.1 or older, you should first manually remove all GameBench files from your project assets. Versions before 0.7 were in the older ‘asset package’ format where GameBench code and plugins got imported/copied into your project. Build 0.7 onwards uses the newer Package Manager package form.


Once you’ve obtained the package file (GameBench.tgz) perform the following steps:

  1. Open your game project in Unity.
  2. Open the ‘Package Manager’ (which is found under ‘Window’ in Unity’s menu).
  3. In Package Manager, click the ‘+’ button in the top left corner and select ‘Add package from tarball…’ :
    sdk_package_manager
  4. In the file browser select your GameBench.tgz from wherever you saved it. Package installation will proceed automatically.
  5. When the package installation completes you will be prompted to configure it with your GameBench account details.

Unity 2018 users: Tarball packages aren’t supported in Unity 2018 so you will need to unpack the .tgz first and use “Add package from disk…” and browse to the package.json in the package root.

3. Configuration

3.1 Configuring with the Editor UI

GameBench must be configured with some account details before use. This is easily done with the Editor UI which is accessed from “GameBench -> Configure” in the Unity menu:

sdk_config

Account
  • Upload URL - Base URL of the server where performance data will be stored.
  • Email - We recommend using a dedicated email account to store GameBench sessions.
  • Token - API token (a hex string). See the API token documentation for more details.
Other Settings
  • Enable GameBench - Controls whether GameBench will be included in your project builds.
  • Disable automatic capture - Session captures are automatic by default, i.e. a session starts when the app launches and stops when the app is backgrounded. Use this option to disable automatic capture and capture sessions through the C# API instead.

3.2 SDKConfig.txt

GameBench configuration is currently stored as JSON in the file Assets/Resources/GameBenchSDK/SDKConfig.txt.

{
    "serverendpoint":"https://web.staging.gamebench.net/v1/sessions/import",
    "emailaddress":"you@yourcompany.com",
    "sdktoken":"0123456789ABCDEF0123456789ABCDEF",
    "sdkEnable":true,
    "sdkAPIControlEnable":false,

    "markSceneChanges":true,
    "verboseSDK":true,
    "tags": "foo=bar,baz=bat"
}

As well as the settings that are visible in the Editor UI the following may be directly set in this file:

markSceneChanges

When set, scene changes will be automatically recorded as marker events. Default is ‘true’.

verboseSDK

This boolean flag is useful for troubleshooting, set it to ‘true’ for GameBench to log what it’s doing.

tags

Tags are an unordered set of name/value string pairs that are useful for identifying sessions or groups of sessions in the web dashboard.

This is a comma-delimited list of key=value pairs that may be used to identify sessions or sets of related sessions in the Analysis area of the Web Dashboard.

4. Metrics

GameBench captures the following measurements:

Metric Notes
FPS See FPS analysis.
CPU usage See CPU metrics and analysis. Android CPU measurements are normalized and agree with the Android Studio profiler, while iOS CPU are not normalised and agree with the debug gauges in Xcode.
GPU usage GameBench captures GPU usage on Android devices with Mali GPUs and iOS devices targeting Metal. Support is not available for OpenGLES. List of GPU supported processors and devices.. More information on GPU analysis.
Memory See Memory metrics and analysis.
Battery See Battery metrics and analysis.

5. The API

GameBench can be used without writing any code at all. By default, performance data will be automatically captured from app launch until the app is backgrounded, at which point the captured data will be automatically uploaded. But if you need finer control over data capture - to limit it to particular scenes or events in your game, say - then GameBench offers full control through an API.

NB: Before using the API it is strongly recommended that you disable automatic capture via the option in the configuration UI (pictured above).

All APIs are static methods of the Gamebench class in the GamebenchLib.Runtime namespace. You do not need to instantiate anything.

5.1 Sessions

Method Notes
Gamebench.Start() Starts a new capture session.
Gamebench.Stop() Stops the current capture session.
Gamebench.Upload(UploadCallback) Uploads any outstanding sessions to the endpoint configured in the UI. After successful upload the session data will be removed from the device. Must be called without an active session.
Gamebench.Reset() Deletes all GameBench data on the device. Must be called without an active session.

5.2 Metrics selection

By default all metrics are captured at preset intervals. These APIs allow control over which metrics are captured as well as the interval between captures.

Method Notes
Gamebench.MetricEnable(MetricType, float) Enable and set the capture interval in seconds for the given metric type. Can be called with or without an active capture session.
Gamebench.MetricDisable(MetricType) Disable capture of the given metric type.

5.3 Markers

To isolate specific areas of gameplay such as levels or battles, GameBench provides markers functionality.. For example, if you want to isolate performance data during a particular game level, you can set “in” marker when the level begins and “out” marker when the level is completed.

Method Notes
Gamebench.MarkStart(string) Record a ‘start’ marker with the given name.
Gamebench.MarkStop(string) Record a ‘stop’ marker with the given name.
Gamebench.MarkLaunchComplete() Record a special ‘launch complete’ marker.

NB: Markers for scene changes are recorded automatically by default.

5.4 Configuration

All of the configuration values documented in section 3 may also be set from code. Note that these values must be set before calling Start(), also that values set with these APIs are transient and do not persist beyond process exit.

Method Notes
Gamebench.ConfigSetURL(string) Sets the URL for uploading session data
Gamebench.ConfigSetEmail(string) Sets the email address (GameBench account name) to use
Gamebench.ConfigSetToken(string) Sets the token to use for authenticating during session data uploads
Gamebench.ConfigTagSet(string, string) Set a tag in the tags collection
Gamebench.ConfigTagRemove(string) Remove a tag from the tags collection
Gamebench.ConfigMarkSceneChanges(bool) Enables or disables automatic record of ‘start’ and ‘stop’ markers at each scene change. The marker name is taken from the scene name. Defaults to ‘true’.
Gamebench.ConfigEnableLogging(bool) Enables GameBench logging which may be useful in troubleshooting. Defaults to ‘false’.

6. Overhead

6.1 Executable size

GameBench will add around 0.9MB to your Android .apk and 1.5MB to your iOS .ipa.

6.2 RAM usage

GameBench performs very little dynamic allocation and it’s impact on RAM usage is reasonably constant at around ~200KB on both iOS and Android.

6.3 CPU and Power usage

To measure the impact of GameBench on CPU and Power usage we profiled game demos on common devices to measure the difference once GameBench was enabled. Each game demo required no user input and therefore performed the same path each time, each ran a minimum of 3 times and for the same duration each time.

CPU
iPhone 11 Samsung Galaxy S20 Ultra
CPU 0.17% 0.12%
Power
Device Without SDK (3 mins) With SDK
Huawei P40 Pro (Run1) 247.6 248
Huawei P40 Pro (Run2) 247.5 248.8
Huawei P40 Pro (Run3) 247.5 248.6
Avg - 247.5 mA Avg - 248.5 (~1 mA overhead)
iPhone 11 Pro Max (Run1) 191 191.87
iPhone 11 Pro Max (Run2) 199 199.28
iPhone 11 Pro Max (Run3) 190.6 191
Avg - 193.5 mA Avg - 194.05 (~0.6 mA overhead)

Storage and upload size overhead - 10Kb for 10 mins session

7. Uninstallation

To uninstall:

  1. Open the Package Manager window in Unity.
  2. Set the ‘Packages’ filter at the top of the window to ‘In Project’.
  3. Select GameBench from the package list.
  4. Click the “Remove” button in the bottom right corner. Uninstall will proceed automatically.