By the end of this post, you will understand all the tools at your disposal for debugging your Unity-based Oculus Quest application, including one currently under-utilized tool: connecting a debugger directly to your headset.
Currently, Unity is one of the most frequently used engines on the Oculus Quest platform. For Unity developers, the most common development workflow looks like this:
Connect a Quest to your PC with a Link cable, and enable Oculus Link in-headset.
Iterate on your application using Unity play-in-editor, which performs computation and rendering on your development PC, and sends the output frame to your Quest through Oculus Link.
Occasionally generate an Android build in Unity, disable Oculus Link, and sideload the Android build to your Quest headset. This performs computation and rendering on the Quest itself.
While sideloading Android builds accurately represents the user experience of playing your application, prototyping through Oculus Link provides shorter iteration times, use of more powerful hardware before you tackle performance optimizations, and well-documented, simple debugging pipelines for Unity.
Of course, you might run into issues that only occur in-headset, and can’t be reproduced via play-in-editor. Or, you may be implementing features that are only available when running natively on the Quest headset, like
hand tracking or
power management.
While you’re tracking down issues or implementing features that only occur in your Android builds for the Quest headset, there are some well-documented tools for you to use:
GPU issues (i.e. unexpected shader output, or GPU time causing you to miss a frame) can be profiled with
RenderDoc for OculusCPU performance issues (CPU time causing you to miss a frame) can be profiled with the
Unity ProfilerYou can also instrument your app to get system-wide performance data with
Perfetto
That said, sometimes you just want to place a breakpoint in code and examine your application’s state when you trigger it on the Quest headset. The following information outlines the necessary steps to enable this process.
Prerequisites
A Unity development environment setup for Quest, including the Android SDK and NDK, as discussed
hereA Quest headset in Developer mode, with a Link cable and ADB drivers allowing it to communicate with your PC, as discussed
hereAn installation of
Visual Studio 2019 (free Community edition is fine) with the “Game Development for Unity” package
If you already have Visual Studio 2019, you can launch the “Visual Studio Installer” application and click “Modify” next to your Visual Studio 2019 install to make sure you’ve installed the package.
Visual Studio .sln and .csproj files generated for your Unity application
These will be automatically created if Visual Studio is your default external script editor.
If it isn’t your default external script editor, you can generate these files in Unity by going to Edit > Preferences > External Tools, and clicking the “Regenerate Project Files” button.
Steps
In Unity, generate an Android build for your application with both “Development Build” and “Script Debugging” boxes checked, as seen below:
Open the Unity-generated .sln for your application in Visual Studio 2019 and place breakpoints where desired.
In Visual Studio 2019, select Debug > Attach Unity Debugger.
In the menu that shows up, you should see an entry with the machine “Oculus Quest” (or “Oculus Quest 2”). Select it and click ‘OK.’
Wait for Visual Studio to connect successfully. You’ll know you’re connected when the status bar at the bottom of Visual Studio turns orange, and your breakpoint markers have become filled-in red.
Perform actions in-headset to hit your breakpoints, and debug!
By using this pipeline, your on-headset debugging experience will be much closer to parity with your in-editor debugging experience. Enjoy your development!
FAQ
Why isn’t my headset showing up in Visual Studio’s “Select Unity Instance” window?
For your headset to appear, both of the following must be true:
Your headset must appear in the output of
adb devices in a command prompt. Follow
these steps to ensure this occurs.
You are currently running your application in-headset, and you checked “Development build” and “script debugging”. Unless both of these are true, the process that listens for a debug connection from Visual Studio won’t be running on your headset.
What if I need to debug something that occurs on frame 1 of my application?
Unfortunately, we don’t currently support the “Wait for Managed Debugger” toggle in Unity builds for Quest. Instead, we’d recommend modifying your application with a starting scene that waits for a predetermined signal before launching the rest of the application.
Can I use ADB over Wi-Fi to debug my application wirelessly?
Yes! As long as you see 192.168.x.y:z in your adb devices output, the pipeline for debugging your headset wirelessly is exactly the same.
If you have any questions, please join the conversation in our
Developer Forum.
