Search Unity

Enhanced mobile performance analysis with Arm’s new Mobile Studio package for Unity

June 1, 2021 in Games | 10 min. read
Mobile Studio Unity Plugin Hero Image
Mobile Studio Unity Plugin Hero Image
Topics covered
Share

Arm Mobile Studio is a free suite of analysis tools for mobile game developers to manage their content and ensure that it runs smoothly across mobile devices powered by Arm CPUs and Mali GPUs. It helps identify and eliminate various performance issues. With the introduction of the new Mobile Studio plug-in for Unity, it’s now easier to perform mobile optimizations on your mobile game. 

This package provides a simple way to incorporate annotations into your project, which are then accessible within the Arm Mobile Studio profiling tools, Streamline and Performance Advisor. These annotations provide useful context for analyzing performance, so you can see when certain actions or events take place within a game, in addition to their corresponding performance impact.

For instance, you can see your annotations along the timeline in Streamline. This example shows a set of markers that highlight where a wave of enemies is spawning:

Mobile Studio Unity Plugin 1

By defining regions of your game with a start and end marker, Performance Advisor can report analytics separately for each region. In this example, you can see performance information on the ‘Battle’ region:

Mobile Studio Unity Plugin 2

Install the package

The Mobile Studio package is supported with the Unity Editor version 2018.4 LTS and later. Install the package through the Unity Package Manager, as such:

1. Open your Unity project and go to Window > Package Manager to open the Package Manager.

Mobile Studio Unity Plugin 3

2. From within the Package Manager, click the ‘+’ icon and then select Add package from git URL...

Mobile Studio Unity Plugin 4

3. Enter the following URL into the box and click Add:

https://github.com/ARM-software/mobile-studio-integration-for-unity.git

The package should be imported into your project and automatically appear in your list of packages:

Mobile Studio Unity Plugin 5

Adding annotations to your code

Now that you have the package up and running, let's look at the various types of annotations and the ways they can be used.

Markers

Markers are simple annotations at the top of the timeline in Streamline. To add markers, simply call into the Mobile Studio library. For example:

Mobile Studio Unity Plugin 6

You can also specify the color of the marker within Streamline by passing an optional Color object, such as:

Regions

You can specify a pair of markers prefixed with “Region Start” and “Region End” to define regions of interest within the game. These regions are shown on the frame rate analysis chart in the Performance Advisor report, and serve to generate dedicated charts for each region at the end of the report.

Mobile Studio Unity Plugin 7

Mark regions of interest by adding markers prefixed with “Region Start” and “Region End” – for example:

Note: Performance Advisor cannot capture frame data from devices running Android 9 for apps built with Unity 2021.2 or later. Refer to this Q&A topic for more information.

Channels

Channels are custom event timelines associated with a thread. Once a channel has been created, you can place annotations within it. Like a marker, an annotation has a text label and a color – but unlike markers, annotations span a range of time.

To create a channel:

To see this channel in Streamline, select the Core Map view, where you can find any added channels under the UnityMain thread:

Mobile Studio Unity Plugin 8

Custom Activity Maps

Custom Activity Maps (CAMs) are a global set of timelines (not per-thread). Each CAM appears as its own view, with a name, in the lower half of Streamline’s UI, and consists of several tracks, which appear as named rows in the CAM. Activity is logged into a track through registered jobs.

To create and add tracks to the CAM:

Once you have created a CAM and added tracks to it, you can register a job within a track through one of the following methods: The first method is to create the job just as you start to undertake the activity you want associated with it, and then end the job as soon as you’re done, just as you did with Annotations. See below:

The other method is to store the start and end times of your work, and then add them to the track later:

The advantage of this second approach is that the getTime() method is cheap in terms of CPU cycles. It can also be safely invoked from jobs running within the Unity Job Scheduler.

You can switch to the CAM you have added in Streamline to view all the tracks and jobs that have been added:

Mobile Studio Unity Plugin 9

Capturing a profile with Streamline and Performance Advisor

Once you’ve annotated your game, generate a development build and deploy it to a device. Then take a capture with Streamline and generate a Performance Advisor report, which will contain your annotations. This video walks you through the process:

This content is hosted by a third party provider that does not allow video views without acceptance of Targeting Cookies. Please set your cookie preferences for Targeting Cookies to yes if you wish to view videos from these providers.

Remove the package from release builds

You can also set up a preprocessor definition so that you can easily remove the package from any release builds without having to make code changes or risking errors in your code from package usage:

1. If you do not already have an Assembly Definition file for scripts that reference the Mobile Studio API, create one. Go to the folder where you wish to create the file, then right-click in the Project View and select Create > Assembly Definition.

2. Edit the asmdef file to add the following:

    a. Under Assembly Definition References, add MobileStudio.Runtime.

    b. Under Version Defines, add a rule:

  • Set Resource to com.arm.mobile-studio
  • Set Define to MOBILE_STUDIO
  • Set Expression to 1.0.0 

This rule makes Unity define MOBILE_STUDIO if the com.arm.mobile-studio package is present in the project, and if its version is greater than 1.0.0

3. In your code, wrap MOBILE_STUDIO around the Mobile Studio API:

#if MOBILE_STUDIO // Package usage #endif

 

With the new Mobile Studio package for Unity, you can take full advantage of the tools in Arm Mobile Studio, and gain further insight into the performance of your mobile apps to optimize your game.

Full documentation for the package is available here. If you haven’t tried Arm Mobile Studio tools before, they are free to use and come with starter guides to help you get going. 

As Arm and Unity continue to collaborate and create better integration for performance profiling tools on mobile, your ongoing input is welcome and valued.

June 1, 2021 in Games | 10 min. read
Topics covered