Immersive Debugger
Updated: Nov 26, 2024
Immersive Debugger is an experimental tool
Immersive Debugger is currently an experimental tool and we’re keen to gather your feedback for making it an official release. The features provided are complete but may be improved in the future; APIs and other functionalities might change in future versions based on your feedback.Immersive Debugger for Unity is a tool that lets you monitor, visualize, troubleshoot, and iterate your application’s gameplay from your headset. It comes with:
A UI panel for in-headset debugging
An optional Unity Editor framework that lets you customize the in-headset debugging experience
The debugger can be customized with the scripting attribute [DebugMember]
or Inspector component DebugInspector
.
With Immersive Debugger, you can do the following without having to remove your headset:
- View Unity logs from the Console Log panel
- Watch specified application variables in the Inspector panel
- Tweak specified float/int/boolean variables from the Inspector panel
- Invoke any Action for the specified function from the in-headset Inspector panel
- Visualize specified application data in 3D space via Gizmo drawings
These tools can speed up your development process by letting you:
- Iterate quickly within the headset for spatial and visual elements
- Debug a Mixed Reality experience that relies on features like Scene
- Monitor state changes (especially upon ephemeral events) and identify issues via console logs
From the bottom right corner of the Editor window, select the Meta icon > Immersive Debugger.
The Project Settings window opens to the Immersive Debugger tab. Select Enable.
Add debug options from Unity Editor Note: If you enable the Immersive Debugger while you add the [DebugMember] attributes, Immersive Debugger can incrementally cache the members to track upon compilation. Then, you can go ahead and tailor your Immersive Debugger experience by adding your own debug options to the in-headset inspector panel.
You can add programming elements of your interest with either or both of the following:
Scripting attributes
Add a [DebugMember]
attribute to any of your properties, fields, action functions and customize them through the parameters of the attribute.
Add a DebugInspector
component to any game object and configure the debug options.
Use Immersive Debugger in the headset This tool works with Link and can also be deployed within an apk build in headset. For the apk build, we used
OVROverlay compositor layer to make the text sharper.
Before deploying the build to the headset, go to File > Build Settings > Android and select Development Build.
Functionalities in detail
This section provides more detailed information on the elements of Immersive Debugger.
When Immersive Debugger is enabled, you can see a control bar in the game world automatically (if Display at Startup is enabled in Project Settings) or when you use the selected Toggle Display Input Button.
The top left of the panel displays how long you’ve been running the app.
From left to right, the icons on the bottom let you:
- Make the panel transparent/opaque
- Anchor the panel to a fixed position or make it move with the headset
- Enable or disable rotating the panel with head yaw
- Change the panel distance
The buttons on the right toggle the Inspector panel and the Console panel.
This panel shows all the console logs from Unity and allows you to toggle severity, clear logs, and collapse or expand identical logs.
Click a specific entry in the log to show a full stack trace panel and turn it off from the top right corner.
This panel lets you:
- Watch the variables’ runtime value
- Click the button to call functions
- Select the eye icon to show/hide gizmos
- Tweak variables’ runtime values
The left sidebar shows item categories. You can specify your item’s category within the DebugMember
attribute or Inspector panel. A selection of pre-configured Meta XR debugging items are also available out of the box, which you can turn off in Settings.
Here are the debug functionalities and the support status for each of them:
Function | Support status |
---|
Watch | Supports everything that supports ToString() . Vectors have a special UI to show separate fields. |
Action | Supports parameter-less functions only. |
Gizmos | Supports various DebugGizmoTypes that can be checked in GizmoTypesRegistry class. All gizmos except Axis can take additional Color parameters in [DebugMember] to draw with that color. |
Tweak | Supports tweaking float/int with a slider UI via [DebugMember(Tweakable = true, Min = xxx, Max = xx)] . Also supports tweaking boolean with a UI toggle. |
Scripting attributes example When Immersive Debugger is enabled, our framework will automatically collect the symbols with annotations in the Editor upon compilation and pipe them to the in-headset panel at runtime. To not overwhelm runtime perf to find those symbols, we pre-bake the debug member classes in the project with a Scriptable Object located at Assets/Resource/ImmersiveDebuggerSettings.asset
.
using Meta.XR.ImmersiveDebugger;
public class ExampleClass : MonoBehaviour
{
// gizmo drawing, specifying a category
[DebugMember(GizmoType = DebugGizmoType.Axis, Category = "MyDebugCategory")]
private Pose _gameObjectPos;
[DebugMember(GizmoType = DebugGizmoType.Line, Color = DebugColor.Red)]
private Tuple<Vector3,Vector3> _direction;
// just watch
[DebugMember]
private bool _gameState;
// tweak the value
[DebugMember(Tweakable = true, Min = 0.0, Max = 1.0)]
private float _param;
// action / call function
[DebugMember]
private void SpawnObject() {/* some code here */}
private void Update()
{
// Update and consume all the debug options, e.g.:
_gameObjectPos = new Pose(transform.position, transform.rotation);
}
}
This section provides instructions for more specific use cases.
Use Immersive Debugger in a production build To use the tool in a production build rather than a development build, add IMMERSIVE_DEBUGGER_ALLOW_USE_IN_PROD
as a Scripting Preprocessor Define in the project settings. The tool can then be used in non-development builds.
Use your own camera/controller instead of OVRCameraRig We have provided a custom integration config to expose overrides for the camera and controllers used by Immersive Debugger. To provide a script, override the CustomIntegrationConfigBase
(check out the ExampleCustomIntegrationConfig
) and fill the mono script in the settings section with Use Custom Integration Config enabled. To find this setting, open the Project Setup Tool, from the left navigation panel, click Meta XR > Immersive Debugger > Advanced > Integration > Use Custom Integration Config.

Issue | Explanation |
---|
OVRManager dependency (OVROverlay) | Immersive Debugger makes use of OVROverlay compositor layer to make the text sharper, which relies on your project using OVRManager. |
Unity OpenXR Plugin not supported yet | Our integration doesn’t fully support Unity OpenXR Plugin, only the Oculus OpenXR Plugin. |
HDR (in camera and device graphics settings) not supported yet | There may be some visual glitches in the Immersive Debugger panels when using HDR. |
Hands only partially supported | Immersive Debugger relies on the input provided by the project and doesn’t add any input mechanism of its own. We have observed that hands can be used to interact with the Immersive Debugger panels in the headset, but some buttons can be hard to interact with. |