Overview
Unreal Insights is a great new profiling and analysis tool that allows you to quickly find bottlenecks, performance spikes, threading patterns and much more. Any Unreal Engine developer building a game or app for Oculus Quest should have Unreal Insights in their toolbelt. The set-up process takes a short amount of time and after you do it once, it's set up forever and you’ll wonder how you ever lived without it. Let’s get started.
Requirements:
Unreal Engine version 4.24+
Tracing enabled in built development app (on by default)
Unreal Insights Executable built or downloaded (<CloneDir>\UnrealEngine\Engine\Binaries\Win64\UnrealInsights.exe and Solution ‘UE4’ > Programs > UnrealInsights in solution explorer)
Steps
Install the development app and verify the existence of /sdcard/UE4Game/<ProjectName>. You might need to launch the game for the first time for the binary to create its associated UE4 project directory.
Instruct adb to pass through TCP connections made on the device over USB (Unreal Insights listens on TCP port 1980): adb reverse tcp:1980 tcp:1980
Edit your UE4CommandLine.txt file to do what you want
Locate the template file in <CloneDir>\UnrealEngine\Engine\Build\Android\UE4Game
Find UE4CommandLine.txt.template & copy/paste it, then remove the .template extension at the end
Modify this file however you like. (See the format just below these steps as a guide)
Copy your desired UE4CommandLine.txt file to your project’s root directory on device
Adb push UE4CommandLine.txt /sdcard/UE4Game/<ProjectDir>/
Open UnrealInsights.exe and check the box for Auto-start analysis for LIVE trace sessions if desired
Go in your headset and run the map! You should see the trace being filled out in the Unreal Insights window.
Notes on each dir/flag shown above:
<ProjectName>
Just the name of the Unreal project - this will match the entry in /sdcard/UE4Game/<ProjectName>
<UProjectName>
The UProjectName will match the output binary (dictated by the engine) so you can just use the APK name or find the .uproject file in your game’s directory.
<MapName>
This one is optional, but it allows you to customize launch arguments on a per-map basis. If you know the map name, you can just put it here.
Pro Tip: if you have a benchmarking scene that you are using, you can set up tracing for only that map so that the tracing overhead doesn’t affect other profiling on regular maps. This is nice because you can keep that launch arg file in the same location without having to remove or rename it between play types.
-trace
Allows you to define the channels to tap into for the trace. Here are the combinations that I use when profiling:
Most Detail/Most Overhead: log,counters,cpu,frame,bookmark,file,loadtime,
gpu,rhicommands,rendercommands,object
Decent Detail/Minimal Overhead: counters,cpu,frame,bookmark,gpu
Additional:
Stats (experimental statstrace in 4.26 (Enable in code with #define EXPERIMENTAL_STATSTRACE_ENABLED 1 in Engine/Source/Runtime/Core/Public/Stats/StatsTrace.h)
LoadTime - includes ‘Loading - Main Thread’ and ‘Loading - Async Thread’ tracks
-statnamedevents
When combined with -trace=cpu option this will activate even more CPU timing events
-tracehost
IP address of the host machine with the Unreal Insights instance running that you want to connect to (127.0.0.1)
-tracefile
Can define a local path on the device that you want to dump the .trace file to as an alternative to live analysis. I keep mine in a static location and just overwrite it each time to always keep a most recent trace.
Just ‘adb pull /sdcard/UE4Game/MostRecentTraceCapture.utrace’ to grab it. Can also just put it in project dir so you can keep most recent for each UE title you’re working on
Example Project
As an example, I built a quick project called QuestUnrealDemo based on the VR Template and set the default map to MotionControllerMap.The uproject is the same, QuestUnrealDemo. The full package name is com.YourCompany.QuestUnrealDemo.
Push the updated UE4CommandLine.txt file to your project root directory on device
Adb push UE4CommandLine.txt /sdcard/QuestUnrealDemo/
Launch Unreal Insights and check the Auto-start analysis for LIVE trace sessions checkbox if you wish.
Launch your game! The live trace will start on launch within the Unreal Insights window.
Tips:
Default PushCommandLine.bat file may push to the wrong location - you can edit it to push to where you want if you don’t want to type the adb push command every time you make a change. This is helpful if you want to frequently change your text file. I edited mine to automatically push and reload the app for quick iteration - script just includes:
%ANDROID_HOME%\platform-tools\adb.exe push UE4CommandLine.txt /mnt/sdcard/UE4Game/QuestUnrealDemo/UE4CommandLine.txt
%ANDROID_HOME%\platform-tools\adb.exe shell am force-stop com.YourCompany.QuestUnrealDemo
%ANDROID_HOME%\platform-tools\adb.exe shell am start -n com.YourCompany.QuestUnrealDemo/com.epicgames.ue4.GameActivity
Additional Useful Launch Flags for Profiling:
-NoSound
-NoTextureStreaming
-NoVerifyGC
Avoids hitching in development builds
-Benchmark
Run game at fixed-step in order to process each frame without skipping
-ResX/ResY
Set the x and y resolution for the game to render at. Can force bottleneck to CPU this way
-Dumpmovie
Dump rendered frames to files using the current resolution of the game. Useful to share a benchmark video for context
Resources for Further Learning
