Omniverse Spatial XR Settings Reference#

Note

Applies to: Spatial Extensions, Kit 109.0.3+, CloudXR 6

This document covers the key settings for configuring XR rendering, profiles, quality, and behavior in your Kit application.

Use defaults. — not persistent. — for XR profile settings in .kit files

# Correct — survives --reset-user, acts as app-level default
defaults.xr.profile.ar.anchorMode = "scene origin"

# Wrong — overwritten by user.config.json at startup, cleared by --reset-user
persistent.xr.profile.ar.anchorMode = "scene origin"

See Setting Prefixes below for details.

Settings can be configured in your .kit file, in an extension’s extension.toml, or at runtime through the Python API or command-line overrides.

Settings Hierarchy#

Kit XR settings follow a hierarchical path structure:

/persistent/
└── xr/
    └── profile/
        ├── vr/            # VR profile saved preferences
        ├── ar/            # AR profile saved preferences
        └── tabletar/      # TabletAR profile saved preferences

/xr/
├── defaults/              # System defaults (set in .kit or extension.toml)
└── profile/
    ├── vr/                # VR profile transient settings
    ├── ar/                # AR profile transient settings
    └── tabletar/          # TabletAR profile transient settings

Setting Prefixes#

Prefix	Behavior
`defaults.`	Applied at startup, overridden by user preferences
`persistent.`	Saved between sessions
(no prefix)	Transient, reset on restart

Choosing the right prefix in .kit files

Use defaults. when setting XR profile preferences in a .kit file or extension.toml.

# Correct: survives --reset-user, acts as app-level default
defaults.xr.profile.ar.anchorMode = "scene origin"

The XR system reads the active value from /persistent/xr/profile/<profile>/<setting> (the user’s saved preference). When no saved preference exists — for example after --reset-user clears user.config.json — the XR system falls back to /defaults/xr/profile/<profile>/<setting>, which is where defaults. writes.

Avoid persistent. in kit files for XR profile settings. Writing directly to the /persistent/ namespace in a kit file is immediately overwritten when user.config.json is loaded at startup, and is also cleared entirely when --reset-user is passed, removing your intended default.

Goal	Kit file TOML	Carb path written	Survives `--reset-user`?
App default (recommended)	`defaults.xr.profile.ar.anchorMode = "scene origin"`	`/defaults/xr/profile/ar/anchorMode`	Yes
Direct user preference	`persistent.xr.profile.ar.anchorMode = "scene origin"`	`/persistent/xr/profile/ar/anchorMode`	No

Accessing Settings#

import carb.settings
from omni.kit.xr.core import XRSettings, XRCore

# Method 1: carb.settings (most common)
settings = carb.settings.get_settings()
value = settings.get("/persistent/xr/profile/vr/renderQuality")

# Method 2: XRSettings
xr_settings = XRSettings.get_singleton()
value = xr_settings.get_setting("/persistent/xr/profile/vr/renderQuality")

# Method 3: Profile helper paths
xr_core = XRCore.get_singleton()
profile = xr_core.get_profile("vr")
persistent_path = profile.get_persistent_path()  # Returns "/persistent/xr/profile/vr"
value = settings.get(f"{persistent_path}/renderQuality")

XR Profiles#

Profiles configure rendering and interaction for different device types.

Profile Selection#

# In .kit file
[settings]
defaults.xr.activeProfile = "ar"      # "vr" or "ar"
defaults.xr.system.display = "OpenXR"  # "OpenXR" or "SimulatedXR"

# At runtime
import omni.kit.xr.core

xr_core = omni.kit.xr.core.XRCore.get_singleton()
xr_core.request_enable_profile("ar")  # "vr" or "ar"

Profile Comparison#

Setting	VR	AR
Blend mode	Opaque	Alpha-blended
Stereoscopic	Yes	Yes
Passthrough	No	Yes
Navigation	Controller-based	Controller / hand
Typical devices	Tethered HMDs	Vision Pro, Quest 3

Render Quality Presets#

Quality presets provide a convenient way to balance visual fidelity against performance:

defaults.xr.profile.ar.renderQuality = "balanced"

Preset	Resolution	Ray Tracing	Best For
`"performance"`	Low	Reduced	Low-end GPUs, large scenes
`"balanced"`	Medium	Standard	Most use cases
`"quality"`	High	Full	Showcases, small scenes
`"stage"`	Maximum	Maximum	Final-quality renders
`"off"`	Custom	Custom	Manual configuration

Resolution and Rendering#

Resolution#

# Resolution multiplier (0.1 - 2.0)
defaults.xr.profile.ar.render.resolutionMultiplier = 1.0

Foveated Rendering#

Foveated rendering reduces resolution at the periphery to improve performance:

# Foveation mode: "none", "inset", or "warped"
defaults.xr.profile.ar.foveation.mode = "warped"

# Warped foveation settings
defaults.xr.profile.ar.foveation.warped.resolutionMultiplier = 0.5
defaults.xr.profile.ar.foveation.warped.insetSize = 0.3

RTX Renderer Settings#

[settings]
# Disable eco mode for full XR performance
rtx.ecoMode.enabled = false

# Anti-aliasing (3 = DLAA)
rtx.post.aa.op = 3

# DLSS execution mode (1 = enabled)
rtx.post.dlss.execMode = 1

# Texture streaming (disable for XR to avoid pop-in)
rtx-transient.resourcemanager.enableTextureStreaming = false

# Opacity Micro-Map (improve ray tracing performance)
persistent.renderer.raytracingOmm.enabled = true

# Prevent duplicate AHS invocations
persistent.rtx.sceneDb.allowDuplicateAhsInvocation = false

AR Alpha Blending#

For AR profiles, configure how the virtual content blends with the real world:

# "vr" = opaque, "ar" = alpha-blended
defaults.xr.profile.ar.alphaBlend.mode = "ar"

# Request AR blend mode from device
defaults.xr.profile.ar.device.requestARBlendMode = true

Near Plane#

The near clipping plane affects minimum render distance. A lower value allows content closer to the user:

persistent.xr.profile.ar.render.nearPlane = 0.15

OpenXR Runtime Settings#

# OpenXR runtime selection: "system", "custom", or "cloudxr"
persistent.xr.system.openxr.runtime = "cloudxr"

# Use the CloudXR native data channel for bidirectional JSON messaging between client and server
xr.openxr.preferNVOpaqueDataChannel = true

SimulatedXR Settings#

For testing without hardware:

# Enable SimulatedXR
xr.simulatedxr.enabled = true
defaults.xr.system.display = "SimulatedXR"

UI Settings#

# Disable the default XR UI (for headless or custom UI)
xr.ui.enabled = false

Controller and Interaction Settings#

# Show controller models
defaults.xr.profile.vr.controllers.visible = true

# Show tooltips
defaults.xr.profile.vr.tooltips.visible = true

# Navigation controls
defaults.xr.profile.vr.enableNavigationControls = true
defaults.xr.profile.vr.navigation.speed = 5.0

# Dominant hand
persistent.xr.tools.dominantHand = "right"

Command-Line Overrides#

Any setting can be overridden from the command line using --/setting/path=value:

Linux

./repo.sh launch -- \
  --/persistent/xr/profile/ar/renderQuality="performance" \
  --/xr/system/display="OpenXR"

Windows

.\repo.bat launch -- `
  --/persistent/xr/profile/ar/renderQuality="performance" `
  --/xr/system/display="OpenXR"

Runtime Configuration Through Python#

import carb.settings

settings = carb.settings.get_settings()

# Read a setting
quality = settings.get("/persistent/xr/profile/ar/renderQuality")

# Write a setting
settings.set("/persistent/xr/profile/ar/renderQuality", "performance")

# Check XR state
import omni.kit.xr.core
xr_core = omni.kit.xr.core.XRCore.get_singleton()

if xr_core.is_xr_enabled():
    profile = xr_core.get_current_profile_name()
    print(f"XR active with profile: {profile}")

    systems = xr_core.get_system_names()
    print(f"Available systems: {systems}")

Recommended Settings by Use Case#

Apple Vision Pro

Goal: Product visualization with AR passthrough and high visual quality.

Warning

Use omni.kit.xr.bundle.apple_vision_pro for Apple Vision Pro applications, not omni.kit.xr.bundle.generic. The settings below marked AVP required are set automatically by that bundle. If you are not using the bundle, you must include them manually — omitting them causes glass rendering artifacts and texture pop-in over CloudXR streaming.

# Profile and display
defaults.xr.activeProfile = "ar"
defaults.xr.system.display = "OpenXR"
defaults.xr.system.openxr.runtime = "cloudxr"

# AR blend
defaults.xr.profile.ar.alphaBlend.mode = "ar"
defaults.xr.profile.ar.device.requestARBlendMode = true

# Render quality
defaults.xr.profile.ar.renderQuality = "quality"
rtx.ecoMode.enabled = false
rtx.post.aa.op = 3

# AVP required — 15 cm near plane for comfortable arm's-reach AR content
persistent.xr.profile.ar.render.nearPlane = 0.15

# AVP required — enable Opacity Micro-Map for correct transparency ray tracing
persistent.renderer.raytracingOmm.enabled = true

# AVP required — disable texture streaming to prevent pop-in over CloudXR
rtx-transient.resourcemanager.enableTextureStreaming = false

# AVP required — prevents glass rendering artifacts
persistent.rtx.sceneDb.allowDuplicateAhsInvocation = false

# AVP required — Fabric Scene Delegate for XR performance
app.useFabricSceneDelegate = true

Meta Quest 3

Goal: Large scene walkthrough with performance-balanced rendering.

defaults.xr.activeProfile = "ar"
defaults.xr.profile.ar.renderQuality = "balanced"
defaults.xr.profile.ar.foveation.mode = "warped"
rtx.ecoMode.enabled = false
rtx-transient.resourcemanager.enableTextureStreaming = false

Development / Testing

Goal: Iterate without a physical headset using SimulatedXR.

defaults.xr.system.display = "SimulatedXR"
xr.simulatedxr.enabled = true
defaults.xr.activeProfile = "ar"
defaults.xr.profile.ar.renderQuality = "performance"

Complete Settings Catalog#

The tables below provide an exhaustive reference of all XR settings. Replace <profile> with vr, ar, or tabletar.

General System Settings#

Setting	Type	Default	Description
`/xr/system/display`	string	`"OpenXR"`	Active XR system plugin (`"OpenXR"`, `"SimulatedXR"`)
`/xr/activeProfile`	string	`""`	Currently active profile name (`"vr"`, `"ar"`, `"tabletar"`)
`/xr/simulatedxr/enabled`	bool	`false`	Enable SimulatedXR for testing
`/xr/persistent/tools/dominantHand`	string	`"right"`	Dominant hand for controller layout (`"left"`, `"right"`)

Render Quality Settings#

Setting	Type	Default	Description
`/persistent/xr/profile/<profile>/renderQuality`	string	`"balanced"`	Quality preset (`"performance"`, `"balanced"`, `"quality"`, `"stage"`)
`/persistent/xr/profile/<profile>/render/resolutionMultiplier`	float	`1.0`	Resolution scale (0.1 - 2.0)
`/persistent/xr/profile/<profile>/render/nearPlane`	float	`0.1`	Near clipping plane (meters)
`/persistent/xr/profile/<profile>/render/farPlane`	float	`10000.0`	Far clipping plane (meters)

Foveated Rendering Settings#

Setting	Type	Default	Description
`/persistent/xr/profile/<profile>/foveation/mode`	string	`"none"`	Foveation mode (`"none"`, `"inset"`, `"warped"`)
`/persistent/xr/profile/<profile>/foveation/warped/resolutionMultiplier`	float	`0.5`	Resolution of peripheral area (warped mode)
`/persistent/xr/profile/<profile>/foveation/warped/insetSize`	float	`0.3`	Size of high-res area (0.0-1.0, warped mode)
`/persistent/xr/profile/<profile>/foveation/warped/horizontalOffset`	float	`0.0`	Horizontal offset of foveation center
`/persistent/xr/profile/<profile>/foveation/warped/verticalOffset`	float	`0.0`	Vertical offset of foveation center
`/persistent/xr/profile/<profile>/foveation/inset/fullResSize`	float	`0.3`	High-res area size (0.0-1.0, inset mode)
`/persistent/xr/profile/<profile>/foveation/inset/backgroundFactor`	float	`0.5`	Background resolution factor (inset mode)
`/persistent/xr/profile/<profile>/foveation/inset/horizontalOffset`	float	`0.0`	Horizontal offset (inset mode)
`/persistent/xr/profile/<profile>/foveation/inset/verticalOffset`	float	`0.0`	Vertical offset (inset mode)

Navigation & Anchoring Settings#

Setting	Type	Default	Description
`/persistent/xr/profile/<profile>/anchorMode`	string	`"scene origin"`	Anchor mode (`"scene origin"`, `"active camera"`, `"custom anchor"`)
`/xr/profile/<profile>/stage/customAnchor`	string	`""`	USD path for custom anchor
`/persistent/xr/profile/<profile>/enableNavigationControls`	bool	`true`	Enable keyboard/mouse navigation
`/persistent/xr/profile/<profile>/floorAlignedNavigation`	bool	`true`	Navigation along floor
`/persistent/xr/profile/<profile>/adjustForUserHeight`	bool	`true`	Adjust for user height
`/persistent/xr/profile/<profile>/navigation/speed`	float	`5.0`	Controller navigation speed
`/persistent/xr/profile/<profile>/teleport/arc/maxHeight`	float	`3.0`	Max teleport arc height (meters)

Controller Settings#

Setting	Type	Default	Description
`/persistent/xr/profile/<profile>/controllers/visible`	bool	`true`	Show controller models
`/xr/profile/<profile>/controllers/rotationOffset`	vec3	`(0,0,0)`	Controller model rotation offset
`/xr/profile/<profile>/controllers/translationOffset`	vec3	`(0,0,0)`	Controller model position offset
`/persistent/xr/profile/<profile>/inputSmoothing/enabled`	bool	`false`	Enable pose smoothing
`/persistent/xr/profile/<profile>/inputSmoothing/factor`	float	`0.3`	Smoothing factor (0.0-1.0)
`/persistent/xr/profile/<profile>/tooltips/visible`	bool	`true`	Show tooltips on controllers

Scaling Settings#

Setting	Type	Default	Description
`/xr/profile/<profile>/scale/string`	string	`"Scale 1:1"`	Scale preset name
`/xr/profile/<profile>/scale/value`	float	`1.0`	Scale multiplier
`/persistent/xr/profile/<profile>/scale/factor`	float	`1.0`	Persistent scale factor

AR-Specific Settings#

Setting	Type	Default	Description
`/persistent/xr/profile/ar/alphaBlend/overrideStage`	bool	`true`	When `true`, XR system automatically manages RTX composite settings when blend mode changes
`/persistent/xr/profile/ar/alphaBlend/mode`	string	`"alpha"`	Blend mode: `"opaque"` (fully virtual, no passthrough), `"alpha"` (AR composite), `"additive"` (holographic overlay)
`/persistent/xr/profile/ar/alphaBlend/translucencyAsOpacity`	bool	`true`	Render translucent materials as opaque for AR compositing, preventing passthrough bleed-through
`/persistent/xr/profile/ar/device/requestQuadviewMode`	bool	`false`	Request quad view rendering
`/persistent/xr/profile/ar/device/requestTabletMode`	bool	`false`	Request tablet form factor
`/persistent/xr/profile/ar/device/requestARBlendMode`	bool	`true`	Request AR blend mode from device

OpenXR Settings#

Setting	Type	Default	Description
`/xr/persistent/system/openxr/runtime`	string	`"system"`	OpenXR runtime (`"system"`, `"custom"`, `"cloudxr"`)
`/xr/persistent/system/openxr/activeRuntimeJSON`	string	`""`	Path to custom runtime JSON

SimulatedXR Settings#

Setting	Type	Default	Description
`/xr/simulatedxr/enabled`	bool	`false`	Enable SimulatedXR
`/xr/profile/<profile>/simulatedxr/refreshRate`	float	`90.0`	Simulated refresh rate (Hz)

Subscribing to Setting Changes#

from omni.kit.xr.core import XRSettings

xr_settings = XRSettings.get_singleton()

def on_quality_changed():
    quality = xr_settings.get_setting("/persistent/xr/profile/vr/renderQuality")
    print(f"Quality changed to: {quality}")

subscription = xr_settings.subscribe_to_change(
    "/persistent/xr/profile/vr/renderQuality",
    on_quality_changed
)

# Subscription auto-cleans up when reference is deleted
# To unsubscribe explicitly:
subscription = None

Setting Defaults in .kit Files#

# my_app.kit
[settings.xr.profile.vr.persistent]
renderQuality = "balanced"
render.resolutionMultiplier = 1.0
foveation.mode = "warped"
navigation.speed = 5.0
controllers.visible = true
tooltips.visible = true

Omniverse Spatial XR Settings Reference#

Settings Hierarchy#

Setting Prefixes#

Accessing Settings#

XR Profiles#

Profile Selection#

Profile Comparison#

Render Quality Presets#

Resolution and Rendering#

Resolution#

Foveated Rendering#

RTX Renderer Settings#

AR Alpha Blending#

Near Plane#

OpenXR Runtime Settings#

SimulatedXR Settings#

UI Settings#

Controller and Interaction Settings#

Command-Line Overrides#

Runtime Configuration Through Python#

Recommended Settings by Use Case#

Complete Settings Catalog#

General System Settings#

Render Quality Settings#

Foveated Rendering Settings#

Navigation & Anchoring Settings#

Controller Settings#

Scaling Settings#

AR-Specific Settings#

OpenXR Settings#

SimulatedXR Settings#

Subscribing to Setting Changes#

Setting Defaults in .kit Files#

See Also#