How to attach unity profiler to existing WebGL builds on Windows 11

readme.md

Attaching the Unity profiler to WebGL builds on Windows 11

One of the biggest pains in Unity when developing for WebGL is that if you want to profile it, you have to use the "Build and Run" menu option to do it, while it works, it can be very inconvenient and waste a lot of time recompiling everything, in this brief tutorial I present a way of attaching the profiler without having to recompile everything.

Click here to see the TL;DR (Too long; Didn't Read™) step-by-step if you are not patient enough to read everything

Note: This entire procedure was only tested with Unity 2021.3.29f1. The procedure might be the same in newer versions, but in case it's not, refer below for how I discovered it for this version.

As of 2023-09-28, the Unity documentation states:

WebGL
You can use the Unity Profiler in WebGL, but you cannot attach to a running player built with WebGL via the Editor. This is because WebGL uses WebSockets for communication, which does not allow incoming connections on the browser side. To attach to a running player, you need to enable the "Autoconnect Profiler" checkbox in Build Settings (menu: File > Build Settings). Unity cannot profile draw calls for WebGL.

Contrary to what the documentation says, it is possible to attach the profiler to WebGL, albeit not directly through the editor, but by launching specific programs with specific arguments.

Note: I'm going to assume that the "Autoconnect Profiler" build option(a) is enabled. Without this option, it might not be possible to attach the profiler at all.

Existing References

As suggested here(a) by some users, it is possible to manually launch the HTTP server that Unity uses when clicking on File -> Build and Run. However, this alone isn't sufficient if you want to attach the profiler.

I tried searching on the internet and even asking Chat-GPT, but it looks like nobody knows or have succeeded in attaching the profiler to WebGL builds in Unity, the procedure is relatively simple, though.

How Unity Attaches the Profiler to WebGL

When you click on File -> Build and Run, Unity launches two processes:

mono.exe

• The only parameter of mono.exe is the path to SimpleWebServer.exe, which receives three parameters:
  1. Root path folder containing the index.html file from the WebGL build (e.g., "C:/Projects/game-client/Builds/WebGL-custom").
  2. HTTP port where the HTML file will be served (e.g., when you access this in your browser at localhost:64046, it loads the WebGL build because it's served on port 64046).
  3. The PID of the Unity.exe process. These options can be seen if you run SimpleWebServer.exe without any parameters:

  C:\> "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport/BuildTools/SimpleWebServer.exe"
  usage: SimpleWebServer.exe source_directory [port] [pid]
  

• Full command-line example:

  C:\> "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/MonoBleedingEdge/bin/mono.exe" "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport/BuildTools/SimpleWebServer.exe" "C:/Projects/game-client/Builds/WebGL-custom" 64046 22176
  

node.exe

Unity uses its own node.exe binary.

• The first parameter is the path to websockify.js, e.g., "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport\BuildTools/websockify/websockify.js".
• The remaining parameters are passed to websockify.js (this might be inaccurate):
  1. Port to listen from.
  2. Port to proxy to.
• Full command-line example:

  C:\> "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport\BuildTools\Emscripten\node\node.exe" "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport\BuildTools/websockify/websockify.js" 54998 localhost:34999
  

The rest is magic

If you launch both command lines mentioned above (following the example command-lines) with Unity profiler open, it should autoconnect the profiler (if your build has the Autoconnect Profiler option enabled of course)

How did I discover this?

I opened System Informer and watched the process list on my secondary monitor, while on my primary monitor I clicked on Unity's "Build and Run" menu. From there on, I simply analyzed the command line arguments passed to the newly created processes and tried to reproduce it, and voilà, it worked.

Does it work with Unity's "Profiler (Standalone Process)"?

No. At least it didn't work when I tried

TL;DR

1. Open the Unity profiler
2. Make sure your game was built with Autoconnect Profiler option enabled
3. Run Unity's SimpleWebServer.exe passing the listening port and Unity.exe Process ID (PID) respectively as params:

C:> "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport/BuildTools/SimpleWebServer.exe" 8000 1234

4. Run node.exe with websockify.js with parameters similar to the example below:

C:\> "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport\BuildTools\Emscripten\node\node.exe" "C:/Program Files/Unity/Hub/Editor/2021.3.20f1/Editor/Data/PlaybackEngines/WebGLSupport\BuildTools/websockify/websockify.js" 54998 localhost:34999

5. Open the game in your browser (http://localhost:8000)
6. Wait Unity profiler to display "Autoconnected Player"
7. Profit

love u！thanks！

Thanks ! On Unity 2023.3 I had to change the port argument of SimpleWebServer to "http://localhost:64046/" to make it working

I made this batch file to launch it quick

start "C:\Program Files\Unity\Hub\Editor\2023.3.0b9\Editor\Data\MonoBleedingEdge\bin\mono.exe" "C:\Program Files\Unity\Hub\Editor\2023.3.0b9\Editor\Data\PlaybackEngines\WebGLSupport\BuildTools\SimpleWebServer.exe" . http://localhost:64046/ && start "C:\Program Files\Unity\Hub\Editor\2023.3.0b9\Editor\Data\PlaybackEngines\WebGLSupport\BuildTools\Emscripten\node\node.exe" "C:\Program Files\Unity\Hub\Editor\2023.3.0b9\Editor\Data\PlaybackEngines\WebGLSupport\BuildTools\websockify\websockify.js" 54998 localhost:34999 && start http://localhost:64046