Profile CPU performance with Superluminal

1. Overview

While the Unity Profiler is the best choice for initial, coarse-grained performance profiling, developers may require greater granularity than the Unity Profiler provides.

Superluminal is a CPU profiler that can be used on Windows to do sampling and instrumentation profiling of applications running on Windows (as well as on certain game consoles, which we will not cover in this guide). Superluminal is a great tool to determine CPU usage bottlenecks and better understand thread contention and synchronization issues.

One of the strengths of Superluminal is that when it is used to profile a Unity Windows build that uses Mono as a scripting backend or the Unity Editor running on Windows, it can capture and display mixed mode call stacks. This means that both native (C++) and managed (C#) stack frames of a call stack are shown in the profiler.

2. Before you begin

Technical requirements

This tutorial assumes that you already have a completed Windows-based project in Unity that you are ready to profile. In addition, this tutorial assumes that you are working with the following software and hardware:

• Windows 7+

• A supported Unity version:

• 2019.4.23+

• 2020.3.2f1+

• 2021.2.1f1+

• 2022.1.0a15+

• Unity Hub 3.0+

• Superluminal

Set up Superluminal and your Unity project

To set up your Unity project for this tutorial, complete the following steps:

1. Download and install Superluminal. Superluminal offers a 14-day free trial but requires a paid license otherwise. We suggest that you review the application’s pricing page for more information concerning licensing.

2. Once Superluminal is downloaded and installed it will need to be activated using a license. Please refer to the Licensing and Activation section of Superluminal’s documentation for more details.

3. Open your Unity project and ensure that it’s in a state that is ready to be published and profiled.

Now you’re ready to prepare a profileable build and attach to that build from Superluminal.

3. Profile a Windows build

Superluminal can be used to profile a Windows Unity Player. Reviewing Build Settings will ensure that your build is connectable and profileable in Superluminal with as little overhead as possible. To format your settings, complete the following steps:

1. Select File > Build Settings to open the Build Settings window.

2. Under Platform, select Windows, Mac, Linux. Select Switch Platform at the lower-right of the window if the target platform is not already set to Windows, Mac, Linux.

3. Select Windows as the Target Platform.

4. Enable Copy PDB files.

5. Disable Development Build.

6. Disable Autoconnect Profiler.

7. Disable Deep Profiling Support.

8. Disable Script Debugging.

9. Select Build. Once this process is complete, you will have a folder containing your executable Windows Player on disk.

4. Launch a Windows build from Superluminal

To launch a Windows build from Superluminal:

1. In the leftmost tab, select the Run button.

2. In the Application field, select the executable file of your build.

3. If you want to start profiling from the moment the application is launched, enable Start profiling immediately. If you want to profile a section of a playthrough that occurs at a later time, do not enable this setting.

4. Select Run to run your application.

5. Attach Superluminal to a running Windows build

To attach Superluminal to a running Windows build, complete the following steps:

1. For users using a version of the Unity Editor prior to the following versions:

• 2020.3.38f1

• 2021.3.9f1

• 2022.1.1f1

• 2022.2.0a12

Before you can attach to a running Unity Player, you must copy the DLL found at c:\Program Files\Superluminal\Performance\Unity\ (path for a default installation) into the folder containing the Unity Player that you wish to profile.

2. Run your build. If your build uses the Mono scripting backend and was built using a version of Unity previous to Unity 2022.2.0f1, you must launch the build with the -monoProfiler superluminal command-line argument.

3. With the build running, open Superluminal.

4. In the leftmost tab, select Attach and choose your running application from the list of available processes.

Note: The command line parameter string should be showing the correct command-line arguments mentioned in the above if you are profiling a build using the Mono scripting backend.

5. If you want to start profiling immediately, enable Start profiling immediately. If you want to profile a section of a playthrough that occurs at a later time, do not enable this setting.

6. Select Attach to attach to your running application.

6. Launch the Unity Editor from Superluminal

You can also use Superluminal to profile the Unity Editor itself. To prepare the Unity Editor to be profiled using Superluminal:

1. In Superluminal, select Run and then select the Unity Editor executable that you want to profile in the Application field.

2. If you want to start profiling immediately, enable Start profiling immediately. If you want to profile a section of Unity Editor processing that occurs at a later time, do not enable this setting.

3. Select Run to run the Unity Editor.

7. Attach Superluminal to a running instance of the Unity Editor

You can also attach Superluminal to a running instance of Unity Editor. To do this:

1. For users using a version of the Unity Editor prior to the following versions:

• 2020.3.38f1

• 2021.3.9f1

• 2022.1.1f1

• 2022.2.0a12

Before you can attach to a running Unity Editor, you must copy the DLL found at c:\Program Files\Superluminal\Performance\Unity\ (path for a default installation) into the folder containing the Unity Editor that you wish to profile. If you have several versions of the Unity Editor installed on your workstation, ensure that the DLL is placed in the correct Unity Editor folder containing the Unity Editor executable that you wish to profile.

2. Launch Unity Hub and ensure that the project you want to profile is ready to be opened.

3. Select More (…) next to the project you wish to profile and then select Add command line arguments.

4. Add the -monoProfiler superluminal command line arguments to the large command arguments field.

5. Select Save and then select your project in Unity Hub to launch the Unity Editor.

6. With the Unity Editor loading or running, open Superluminal. In the leftmost tab, select Attach and then select the Unity Editor from the list of available processes.

Note: The command line parameter string should show the correct command-line arguments mentioned above.

7. If you want to start profiling immediately, enable Start profiling immediately. If you want to profile a section of Unity Editor processing that occurs at a later time, do not enable this setting.

8. Select Attach to attach to the Unity Editor.

8. Capture data

If you select Run, or Attach with the Start profiling immediately option disabled, Superluminal will not begin profiling the application immediately. You can:

• Select Start Recording to begin the profiling session.

• Select Start Analyzing to end the profiling session.

If the Start profiling immediately option is enabled, the profiling session will begin as soon as you attach or run your application. Select Start Analyzing to end the profiling session.

9. Inspect data

The Working with Sessions section of Superluminal’s official documentation explains the different UI panels shown when a session document is open and covers how to navigate and interpret the captured data.

10. Next steps

In this tutorial, you learned how to profile CPU usage using Superluminal to track down CPU performance issues at runtime. You can now use this to provide more detailed profiling than the Unity Profiler supports, including determining CPU usage bottlenecks and identifying thread contention and synchronization issues.

For further guidance on profiling with Superluminal, refer to the Superluminal documentation.