Unity build settings

Follow the steps here to ensure that your Android game can be profiled successfully with Arm Mobile Studio tools. 

  1. Check that you are using the Unity recommended Android SDK and Android NDK versions in the Unity editor.

    • On Windows and Linux, select Edit > Preferences > External Tools.
    • On macOS, select Unity > Preferences > External Tools.

    If the checkboxes are selected, they are installed. Otherwise, you can add them as modules. See https://docs.unity3d.com/Manual/android-sdksetup.html for more information.

  2. Select File > Build Settings, then select Player Settings.
  3. Under Identification, set Target API Level to the required Android version.
    By default, Target API Level is set to the latest version of the Android SDK tools that you have installed. If you change to a lower API level, ensure that you have the SDK tools for that version installed, and be aware that if you want to build for a higher API version later, you will need to change this setting accordingly.
  4. Under Configuration, set the following options to build a 64-bit application:
    1. Set the scripting backend in Unity to work with 64-bit targets. Set Scripting Backend to IL2CPP. For more information about IL2CPP, refer to the Unity documentation.
    2. Under Target Architectures, select ARM64.
      Unity Player Settings
      To build a 32-bit application:
      1. Leave the scripting backend at its default setting, Mono.
      2. Under Target Architectures, select ARM7.

        Note: You should aim to target 64-bit applications, as support for 32-bit will eventually be removed on most platforms. 

  5. Close the Player Settings. In the Build Settings, select the Development Build checkbox. This option ensures that your application is marked as debuggable in the Android application manifest. This is required, to enable the profiling tools to connect to the application.
  6. Select Build and Run to build your application and install it on your device in one step. Alternatively, select Build to build the application and then install it on your device using Android Debug Bridge:
    adb install -r YourApplication.apk
  7. Now you can take a capture with Streamline and generate a Performance Advisor report. This video walks you through how to do that. 

    Or you can work through the get started guides to learn how to take captures. 

Annotating games to add context with the Mobile Studio package for Unity

This package provides a simple way to add annotations to your game, which are then exposed within the Arm Mobile Studio profiling tools, Streamline and Performance Advisor. These annotations provide useful context when analyzing performance, showing when certain actions or events have taken place within a game, and enabling you to more easily identify the cause of any performance issues.

Full documentation for the package can be found here. Please try out the new package and give Arm your feedback. Arm and Unity continue to collaborate to create better integration for performance profiling tools on mobile, and your input is welcome and valued.

Install the Mobile Studio package for Unity

Install the Mobile Studio package for Unity via Unity's Package Manager:

  1. In Unity, open your project and then select Window > Package Manager.
  2. In the Package Manager, click the + icon and then select Add package from git URL...
  3. Enter the following URL and click Add

Adding markers to the timeline in Streamline

Markers are simple annotations that show along the top of the timeline in Streamline. To add markers to your Unity game, simply call into the Mobile Studio library. For example: 

private void Start()
{      MobileStudio.Annotations.marker("Game Started"); } 

This will emit a timestamped marker with the label "Game Started", which Streamline will show along the top of the timeline.

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

MobileStudio.Annotations.marker("Game Started", Color.green); 

Using markers to define regions in Performance Advisor

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

Mark regions of interest by adding markers with a unique name for the region, prefixed with “Region Start” and “Region End”, for example: 

MobileStudio.Annotations.marker("Region Start Times Square"); 
// Do work 
MobileStudio.Annotations.marker("Region End Times Square"); 

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.

Creating channels

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

To create a channel: 

private MobileStudio.Annotations.Channel channel; 
private void Start()  {      channel = new MobileStudio.Annotations.Channel("Spawner");  } 

Annotations can then be inserted into a channel easily: 

private void HandleNewWaveStartedEvent() 
    channel.annotate("Spawning Wave", Color.red); 
private void HandleWaveCompleted(object sender, EventArgs e) 
{      channel.end();  } 

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

Custom Activity Maps 

Custom Activity Maps (CAMs) are a global (not per-thread) set of timelines. Each CAM appears as its own view in the lower half of Streamline's UI, so each CAM has a name, and consists of several tracks, each of which appears as a named row in the CAM. Activity is logged into a track by registering jobs into it. 
To create and add tracks to the CAM: 

private MobileStudio.Annotations.CAM gameCAM; 
private MobileStudio.Annotations.CAM.CAMTrack waveTrack; 
private MobileStudio.Annotations.CAM.CAMTrack uiTrack;  
private void Start() 
{       //Create the CAM 
    gameCAM = new MobileStudio.Annotations.CAM("GameActivity"); 

    // Add tracks to the CAM 
   waveTrack = gameCAM.createTrack("Wave Activity"); 
    uiTrack = gameCAM.createTrack("UI Activity"); } 

After you have created a CAM and added tracks to it, register a job within a track using one of the following methods. The first is to create the job just as you start to undertake the activity you want to associate with it, and end the job when you are done, like you did with Annotations: 

private MobileStudio.Annotations.CAM.CAMJob waveJob; 
private void HandleNewWaveStartedEvent() 
{      waveJob = waveTrack.makeJob("Spawning Wave", Color.red);  } 
private void HandleWaveCompleted(object sender, EventArgs e) 
{      waveJob.stop(); } 

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

UInt64 startTime = MobileStudio.Annotations.getTime(); 
// Do work 
UInt64 endTime = MobileStudio.Annotations.getTime(); 
uiTrack.registerJob("UI Active", Color.blue, startTime, endTime); 

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

Switch to the CAM you have added in Streamline and see the tracks and jobs that have been added: 

Capturing a profile with Streamline and Performance Advisor 

When 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 now contain your annotations. This video walks you through how to do that. 

Exporting shader programs for analysis with Mali Offline Compiler

In order to run Mali Offline Compiler on your shader programs, you need to export a vertex or fragment shader from within Unity. Here's how to do that:

  1. In Unity, select the shader you want to analyze, either directly from your assets folder, or by selecting a material, clicking the gear icon and choosing Select shader.
  2. Choose Compile and show code in the Inspector. The compiled shader code will open in your default code editor. This file contains several shader code variants.
  3. Copy either a vertex or fragment shader variant from this file into a new file, and give it an extension of either .vert or .frag. Vertex shaders start with #ifdef VERTEX and fragment shaders start with #ifdef FRAGMENT. They end with their respective #endif. (Don’t include the #ifdef and #endif statements in the new file).
  4. In a command terminal, run Mali Offline Compiler on this file, specifying the GPU you want to test, for example:
    malioc –c Mali-G72 myshader.frag