Get Started With Unreal Insights on Oculus Quest

Overview

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

1. 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.
2. 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
3. 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)
4. Copy your desired UE4CommandLine.txt file to your project’s root directory on device
• Adb push UE4CommandLine.txt /sdcard/UE4Game/<ProjectDir>/
5. Open UnrealInsights.exe and check the box for Auto-start analysis for LIVE trace sessions if desired
6. 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.

7. Push the updated UE4CommandLine.txt file to your project root directory on device
• Adb push UE4CommandLine.txt /sdcard/QuestUnrealDemo/
8. Launch Unreal Insights and check the Auto-start analysis for LIVE trace sessions checkbox if you wish.
9. 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
• Disable audio
• -NoTextureStreaming
• Isolate hitches
• -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

• Unreal Insights Overview⁠
• Collect, Analyze and Visualize Your Data With Unreal Insights - Unreal Fest Online 2020⁠
• Trace Recording Wiki⁠