a0b6c24a-b49d-5c36-b8a5-62387d236033:undefined

Superluminal documentation

Overview

Before you begin

Profile a Windows build

Launch a Windows build from Superluminal

Attach Superluminal to a running Windows build

Launch the Unity Editor from Superluminal

Attach Superluminal to a running instance of the Unity Editor

Capture data

Inspect data

Next steps

Profile CPU performance with Superluminal

While the Unity Profiler is the best choice for initial, coarse-grained performance profiling, developers may require greater granularity than the Unity Profiler provides. In this tutorial, you will learn how to profile CPU usage using Superluminal to track down CPU performance issues at runtime.

Important: Superluminal is a profiling tool for Windows builds and the Windows version of Unity Editor only.

Create an ML2 app with Scene Comprehension

ML2 case study: scene localization

Internal Training Resources

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.

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:

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.

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.


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

The Build Settings fully configured, with Copy PDB files enabled.

The folder containing the Windows builds made from Unity Editor being shown in Windows Explorer.

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.

Superluminal showing the Run panel selected and the Application and Commandline Arguments fields correctly filled out to profile a 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:

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.

Command Prompt showing the -monoProfiler superluminal command-line arguments being passed to the build.

Superluminal with the running Unity build selected in the Attach panel. The command line parameters column shows that the build was run correctly.

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.

Superluminal showing the Run panel selected and the Application field correctly filled out to profile 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:

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.

Unity Hub with the Unity project ready to be launched.

Unity Hub with More (...) selected and the Add command line arguments highlighted.

Unity Hub’s Command line arguments modal dialog with the correct command line arguments entered

Superluminal with the running Unity Editor selected in the Attach panel. The command line parameters column shows that the Editor was run correctly.

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.

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.

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.

Profile CPU performance with Superluminal

1. Overview

2. Before you begin

3. Profile a Windows build

4. Launch a Windows build from Superluminal

5. Attach Superluminal to a running Windows build

6. Launch the Unity Editor from Superluminal

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

8. Capture data

9. Inspect data

10. Next steps

Complete this tutorial