Profiling mods

Written by Marioalexsan
You will need to have Unity Editor 2022.3.62f2 installed, and a project of any kind available (a blank project will do).

Creating the Profiler

To profile the game, you will first need to switch to the debug mode runner. The steps to do that are:

1. Go to ATLYSS's install path, and backup your current ATLYSS.exe and UnityPlayer.dll - for example into an UnityReleasePlayer folder.
2. Go to your Unity Editor install path, for example D:\Program Files\Unity Editors\2022.3.62f2\Editor.
3. Go to Data\PlaybackEngines\windowsstandalonesupport\Variations\win64_player_development_mono.
4. Copy WindowsPlayer.exe and UnityPlayer.dll into ATLYSS's install path, and rename WindowsPlayer.exe into ATLYSS.exe.
5. Go to ATLYSS's install path, then to ATLYSS_Data/boot.config.
6. Add player-connection-debug=1 as a new line to the configuration.
7. (Optional) Backup the debug mode runner (i.e. the renamed ATLYSS.exe, UnityPlayer.dll and the modified boot.config) into a separate folder like UnityDebugPlayer for easy access - Steam will try to replace the runner whenever the game updates, so you'll have to repeat these steps whenever that happens.

Starting the Profiler

You should now be able to connect a debugger (VS / Rider) or a profiler to the game when it runs. To start the profiler:

1. Open Unity Editor with any project (for example a blank project).
2. Go to Window => Analysis => Profiler (Standalone Process); this will launch the profiler in a separate window.
3. Launch the game.
4. In the profiler's target selection next to the record button, select Local => WindowsPlayer => the game instance identified by the device name, local IP and port.
5. Stop / start again the recording by pressing Record.

If you've done everything right, you should see something like this. The profiler will be able to show you the time spent within the various lifecycle callbacks of the game's scripts, and other data such as GUI processing, memory usage, etc.

Configuring the Profiler

This gives you a high level overview of CPU usage, it can't go deeper than that since the profiler can't do deep instrumentation for a finished build. However, in some cases you'll want to use markers to segment your code into chunks and analyze each of them separately. To do so, you'll need to do the following:

• Add to your mod's .csproj the following conditional definition, this allows profiler markers to actually work and not be skipped by the compiler due to ConditionalAttribute. If you want, you can make it apply both to Debug and Release builds by removing the Condition:

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <DefineConstants>
    <!--
    -->ENABLE_PROFILER;<!-- For Unity's ProfileMarkers to actually emit calls
    -->
  </DefineConstants>
</PropertyGroup>

Example usage: ModAudio.csproj

• In your code, declare a new marker somewhere. For example:

private static readonly ProfilerMarker _executeUpdate = new ProfilerMarker("ModAudio Update() execute script updates");

• Surround a code block you want to segment with Begin() and End(). For example:

 if (!string.IsNullOrEmpty(pack.Config.PackScripts.Update) && pack.Script != null)
{
  _executeUpdate.Begin();
  pack.Script.ExecuteUpdate();
  _executeUpdate.End();
}

Example usage: ModAudio/AudioEngine.cs

• Recompile and install the mod, then launch the game and attach the profiler.

All available development runner counters as provided by ProfilerRecorderHandle.GetAvailable().
debug_mode_counters_available.txt