API ReferenceGE Extensionsrender
OpenXR VR
Manages the OpenXR VR session lifecycle: toggling on/off, welcome dialog, debug ImGui panel, headset centering, state tracking, and error handling.
Manages the OpenXR VR session lifecycle: toggling on/off, welcome dialog, debug ImGui panel, headset centering, state tracking, and error handling.
Public API
| Function | Signature | Description |
|---|---|---|
M.toggle | () | Cycles through disabled → welcome → enabled → disabled |
M.center | (value) | Centers the VR headset; nil = one-shot, number = hold-and-release |
M.isSessionRunning | () → boolean | Returns whether an OpenXR session is currently active |
M.restart | () | Disables then re-enables OpenXR |
M.closeWelcome | (enable) | Closes welcome dialog; starts or cancels XR based on enable |
M.setStateUI | (stateString) | Transitions to "welcome", "enabled", or "disabled" |
M.stateChanged | (enabled, sessionRunning, ...) | C++ callback - updates all XR state fields |
M.updateUI | (forced) | Pushes state to UI via guihooks.trigger('OpenXRStateChanged', ...) |
M.errorDetected | (err) | Logs error and shows toast notification |
M.onInit | () | Sets manual unload mode, reads settings |
M.onSettingsChanged | () | Reloads settings; restarts XR if debug mode changed |
M.onUpdate | (...) | Handles centering countdown, runs ImGui debug panel |
M.state | - (function) | Returns current XR state table |
M.stateString | - (string field) | Current state: "disabled", "enabled", or "welcome" |
State Machine
disabled ──toggle──> welcome ──closeWelcome(true)──> enabled
▲ │ │
│ └──closeWelcome(false)────────────┘
└────────────────toggle/setStateUI("disabled")────────┘Key State Fields (M.state)
| Field | Type | Description |
|---|---|---|
enabled | bool | XR runtime active |
sessionRunning | bool | XR session in progress |
headsetActive | bool | Headset being worn |
controller0Active/1Active | bool | Controller tracking |
systemName | string | HMD system name |
renderedWidth/Height | number | Current render resolution |
recommendedWidth/Height | number | Recommended render resolution |
ipd | number | Inter-pupillary distance (meters) |
fov0hz/fov0vt/fov1hz/fov1vt | number | Per-eye field of view |
Internal State
| Field | Type | Description |
|---|---|---|
M.cefDialogOpen | bool/nil | Tracks whether the CEF welcome dialog is currently open |
Settings
| Setting Key | Type | Description |
|---|---|---|
openXRuiEnabled | bool | Show UI overlay in VR |
openXRuiMode | int | UI anchor mode (0=Room, 1=Head) |
openXRwindowViewMode | int | 2D window view (0=Empty, 1=Between eyes, 2=Left, 3=Right) |
openXRdebugEnabled | bool | Enable debug mode (lower framerate) |
openXRquadCompositionEnabled | bool | Use quad composition layer |
How It Works
- User triggers
toggle()or UI sends state change setStateUI("welcome")shows a confirmation dialog (checks Vulkan adapter)- On confirmation,
setStateUI("enabled")callsOpenXR.toggle()to start session - C++ calls
stateChanged(...)each frame with headset/controller state - State changes are pushed to UI via
guihooks.trigger('OpenXRStateChanged') center()sends recenter request to C++ OpenXR layersetStateUI("disabled")stops session and unloads extension
Usage Examples
-- Toggle VR on/off (bound to ctrl+numpad0)
extensions.render_openxr.toggle()
-- Center headset (bound to ctrl+numpad5)
extensions.render_openxr.center()
-- Check if VR is running
if extensions.render_openxr.isSessionRunning() then
-- VR is active
endSee Also
- Render HDR - Post-Effect Pipeline Initialization - Related reference
- Render Views - Offscreen Camera Screenshots - Related reference
- Render View Demo - Render View Usage Example - Related reference
- Game Engine Overview - Guide
HDR Post-Processing
Initializes the HDR post-processing chain (bright pass, downscale, luminance, combine) on first update. Creates engine-level PostEffect objects if they don't already exist.
Render Views
Provides a utility to create offscreen render views and save them to disk. Used for programmatic screenshots from arbitrary camera positions.