<<<<<<< HEAD

Creating Custom XR Bundles#

Note

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

This custom bundles reference covers creating custom XR bundle extensions to package dependencies and settings for reuse across applications.

What is an XR Bundle?#

An XR bundle is a Kit extension that:

Bundles dependencies: Groups related XR extensions
Applies settings: Configures XR system with custom defaults
Provides no code: Pure configuration extension
Enables reusability: Share configurations across projects

Use Cases:

Organization-specific XR configurations
Platform-specific bundles (Vision Pro, Quest, HoloLens)
Project-specific XR setups
Testing configurations

Bundle Extension Structure#

my_company.xr.bundle.custom/
├── config/
│   └── extension.toml        # Extension configuration
├── docs/
│   ├── README.md              # Documentation
│   ├── CHANGELOG.md           # Version history
│   └── OVERVIEW.md            # Overview (optional)
└── data/
    └── icon/
        ├── icon.png           # 256x256 icon
        └── preview.png        # Preview image (optional)

Creating a Bundle: Step-by-Step#

Step 1: Create Directory Structure#

mkdir -p my_company.xr.bundle.custom/config
mkdir -p my_company.xr.bundle.custom/docs
mkdir -p my_company.xr.bundle.custom/data/icon

Step 2: Create extension.toml#

# my_company.xr.bundle.custom/config/extension.toml

[package]
# Basic metadata
version = "1.0.0"
title = "My Company XR Bundle"
description = "Custom XR configuration for My Company applications"
category = "XR"
keywords = ["xr", "vr", "ar", "bundle"]
readme = "docs/README.md"
changelog = "docs/CHANGELOG.md"
preview_image = "data/icon/preview.png"
icon = "data/icon/icon.png"

# Authors
authors = ["My Company <xr-team@mycompany.com>"]

# Repository (optional)
repository = "https://github.com/mycompany/xr-bundles"

[dependencies]
# Core XR extensions (required)
"omni.kit.xr.core" = {}
"omni.kit.xr.system.openxr" = {}
"omni.kit.xr.system.simulatedxr" = {}

# UI extensions
"omni.kit.xr.ui.stage" = {}
"omni.kit.xr.ui.window.profile" = {}
"omni.kit.xr.ui.window.viewport" = {}

# Optional: Additional extensions for your use case
# "omni.kit.xr.teleport" = {}
# "omni.kit.xr.grab" = {}

[settings]
# ============================================================================
# XR System Configuration
# ============================================================================

# Default XR system
defaults.xr.system.display = "OpenXR"

# Default active profile
defaults.xr.activeProfile = "vr"

# ============================================================================
# VR Profile Settings
# ============================================================================

# Render quality preset (performance, balanced, quality, stage)
defaults.xr.profile.vr.renderQuality = "balanced"

# Resolution multiplier (0.1 to 2.0)
defaults.xr.profile.vr.render.resolutionMultiplier = 1.0

# Clipping planes
defaults.xr.profile.vr.render.nearPlane = 0.1
defaults.xr.profile.vr.render.farPlane = 10000.0

# ============================================================================
# Foveated Rendering
# ============================================================================

# Foveation mode (none, inset, warped)
defaults.xr.profile.vr.foveation.mode = "warped"

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

# ============================================================================
# Navigation & Anchoring
# ============================================================================

# Anchor mode (scene origin, active camera, custom anchor)
# Use defaults. (not persistent.) so this survives --reset-user
defaults.xr.profile.vr.anchorMode = "scene origin"

# Enable navigation controls (keyboard/mouse)
defaults.xr.profile.vr.enableNavigationControls = true

# Floor-aligned navigation
defaults.xr.profile.vr.floorAlignedNavigation = true

# Navigation speed
defaults.xr.profile.vr.navigation.speed = 5.0

# ============================================================================
# Controllers
# ============================================================================

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

# Dominant hand (left, right)
persistent.xr.tools.dominantHand = "right"

# Input smoothing
defaults.xr.profile.vr.inputSmoothing.enabled = true
defaults.xr.profile.vr.inputSmoothing.factor = 0.3

# ============================================================================
# UI & Tooltips
# ============================================================================

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

# ============================================================================
# AR Profile Settings (if supporting AR)
# ============================================================================

# Alpha blending
defaults.xr.profile.ar.alphaBlend.mode = "ar"
defaults.xr.profile.ar.alphaBlend.overrideStage = true

# ============================================================================
# OpenXR Configuration
# ============================================================================

# OpenXR runtime (system, custom, cloudxr)
persistent.xr.system.openxr.runtime = "system"

# ============================================================================
# Simulator Configuration (for testing)
# ============================================================================

# SimulatedXR refresh rate
defaults.xr.profile.vr.simulatedxr.refreshRate = 90.0

[documentation]
# Documentation pages to include
pages = [
    "docs/README.md",
    "docs/CHANGELOG.md",
]

Step 3: Create Documentation#

# my_company.xr.bundle.custom/docs/README.md
# My Company XR Bundle

Custom XR configuration optimized for My Company's applications.

## Features

- Pre-configured VR profile with balanced quality
- Warped foveation enabled for performance
- Navigation enabled by default
- Tooltips visible
- Controller smoothing enabled
- OpenXR system runtime

## Supported Platforms

- Windows 10/11 with OpenXR-compatible HMDs
- Linux (Ubuntu 22.04+) with OpenXR
- Testing with SimulatedXR

## Usage

Add to your application's `.kit` file:

\`\`\`toml
[dependencies]
"my_company.xr.bundle.custom" = {}
\`\`\`

Then enable XR in your Python code:

\`\`\`python
import omni.kit.xr.core
xr_core = omni.kit.xr.core.XRCore.get_singleton()
xr_core.request_enable_profile("vr")
\`\`\`

## Settings

### Quality Preset
Default: `balanced`

To change:
\`\`\`python
import carb.settings
settings = carb.settings.get_settings()
settings.set("/persistent/xr/profile/vr/renderQuality", "performance")
\`\`\`

### Navigation Speed
Default: `5.0`

To adjust:
\`\`\`python
settings.set("/persistent/xr/profile/vr/navigation/speed", 3.0)
\`\`\`

See [Settings Documentation](SETTINGS.md) for complete list.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## Support

Contact: xr-team@mycompany.com

# my_company.xr.bundle.custom/docs/CHANGELOG.md
# Changelog

All notable changes to this bundle will be documented in this file.

## [1.0.0] - 2024-01-15

### Added
- Initial release
- VR profile configuration
- Foveated rendering enabled
- Navigation and controller settings
- Tooltip support

### Settings
- Quality preset: balanced
- Foveation: warped mode
- Input smoothing: enabled
- Navigation speed: 5.0

## [Unreleased]

### Planned
- AR profile configuration
- TableAR support
- Custom quality presets

Step 4: Add Icon (Optional)#

Create a 256x256 PNG icon:

my_company.xr.bundle.custom/data/icon/icon.png

Platform-Specific Bundles#

Apple Vision Pro Bundle Example#

Warning

Use omni.kit.xr.bundle.apple_vision_pro — not omni.kit.xr.bundle.generic — for Apple Vision Pro applications. The generic bundle omits renderer settings that are required for AVP: without them, transparent surfaces render with glass artifacts and texture streaming causes visible pop-in during CloudXR streaming. If you are creating a custom bundle that targets AVP, you must include the critical renderer settings shown below.

# my_company.xr.bundle.apple_vision_pro/config/extension.toml

[package]
version = "1.0.0"
title = "My Company - Apple Vision Pro Bundle"
description = "XR configuration for Apple Vision Pro via CloudXR"
category = "XR"
keywords = ["xr", "ar", "visionpro", "cloudxr"]

[dependencies]
"omni.kit.xr.core" = {}
"omni.kit.xr.system.openxr" = {}
"omni.kit.xr.system.simulatedxr" = {}  # Hard dependency for AVP — not optional
"omni.kit.xr.ui.stage" = {}
"omni.kit.xr.ui.window.profile" = {}
"omni.kit.xr.ui.window.viewport" = {}

[settings]
# Enable SimulatedXR for local development
xr.simulatedxr.enabled = true

# Default to AR profile
defaults.xr.activeProfile = "ar"

# Use OpenXR with CloudXR
defaults.xr.system.display = "OpenXR"
defaults.xr.system.openxr.runtime = "cloudxr"

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

# Request tablet form factor
defaults.xr.profile.ar.device.requestTabletMode = false
defaults.xr.profile.ar.device.requestARBlendMode = true

# Quality optimized for streaming
defaults.xr.profile.ar.renderQuality = "balanced"

# -------------------------------------------------------------------------
# Critical AVP renderer settings — required to avoid glass artifacts and
# streaming pop-in. These are NOT set by omni.kit.xr.bundle.generic.
# -------------------------------------------------------------------------

# Enable Opacity Micro-Map for correct ray tracing through transparent surfaces
persistent.renderer.raytracingOmm.enabled = true

# Disable texture streaming — AVP streaming is latency-sensitive;
# streaming textures cause visible pop-in over CloudXR
rtx-transient.resourcemanager.enableTextureStreaming = false

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

# Prevent duplicate AHS invocations — eliminates glass rendering artifacts
persistent.rtx.sceneDb.allowDuplicateAhsInvocation = false

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

Quest 3 Bundle Example#

# my_company.xr.bundle.quest3/config/extension.toml

[package]
version = "1.0.0"
title = "My Company - Quest 3 Bundle"
description = "XR configuration for Meta Quest 3"
category = "XR"
keywords = ["xr", "vr", "quest", "meta"]

[dependencies]
"omni.kit.xr.core" = {}
"omni.kit.xr.system.openxr" = {}
"omni.kit.xr.system.simulatedxr" = {}
"omni.kit.xr.ui.stage" = {}
"omni.kit.xr.ui.window.profile" = {}
"omni.kit.xr.ui.window.viewport" = {}

[settings]
# Default to VR profile
defaults.xr.activeProfile = "vr"
defaults.xr.system.display = "OpenXR"

# Performance-focused quality
defaults.xr.profile.vr.renderQuality = "performance"
defaults.xr.profile.vr.render.resolutionMultiplier = 0.9

# Aggressive foveation for performance
defaults.xr.profile.vr.foveation.mode = "warped"
defaults.xr.profile.vr.foveation.warped.resolutionMultiplier = 0.4
defaults.xr.profile.vr.foveation.warped.insetSize = 0.25

# Controllers
defaults.xr.profile.vr.controllers.visible = true
defaults.xr.profile.vr.tooltips.visible = true

Testing Bundles#

Local Testing#

# Place bundle in local extension directory
my_project/
├── apps/
│   └── my_app.kit
└── exts/
    └── my_company.xr.bundle.custom/
        └── config/
            └── extension.toml

# Reference in .kit file

# apps/my_app.kit
[dependencies]
"my_company.xr.bundle.custom" = {}

[settings.app.exts]
folders.'++' = [
    "${app}/../exts"  # Include local extensions
]

Run and Verify#

# Launch application
./kit/kit --enable apps/my_app.kit

# Or using Kit App Template
./repo.sh launch --config=apps/my_app.kit

Verify Settings#

import carb.settings

settings = carb.settings.get_settings()

# Check quality preset
quality = settings.get("/persistent/xr/profile/vr/renderQuality")
print(f"Quality: {quality}")  # Should be your bundle's default

# Check foveation
fov_mode = settings.get("/persistent/xr/profile/vr/foveation/mode")
print(f"Foveation: {fov_mode}")

Versioning and Distribution#

Semantic Versioning#

[package]
version = "1.2.3"
#         │ │ └─ Patch: Bug fixes
#         │ └─── Minor: New features (backwards compatible)
#         └───── Major: Breaking changes

Publishing to Extension Registry#

# Package extension
./repo.sh package --ext my_company.xr.bundle.custom

# Publish to registry (configure in repo.toml)
./repo.sh publish --ext my_company.xr.bundle.custom

Git Repository Structure#

xr-bundles/
├── .gitignore
├── README.md
├── exts/
│   ├── my_company.xr.bundle.custom/
│   ├── my_company.xr.bundle.quest3/
│   └── my_company.xr.bundle.apple_vision_pro/
└── repo.toml

Bundle Comparison Table#

Bundle	Platform	Profile	Quality	Foveation	Use Case
custom	Cross-platform	VR	Balanced	Warped	General purpose
apple_vision_pro	Vision Pro	AR	Balanced	None	CloudXR streaming
quest3	Quest 3	VR	Performance	Aggressive	Mobile VR
desktop_high	PC VR	VR	Quality	Inset	High-end desktop

Advanced: Override Patterns#

User Preferences#

Users can override bundle settings:

import carb.settings

settings = carb.settings.get_settings()

# Override quality (takes precedence over bundle default)
settings.set("/persistent/xr/profile/vr/renderQuality", "quality")

Application-Specific Overrides#

Override bundle settings in your .kit file:

[dependencies]
"my_company.xr.bundle.custom" = {}

[settings.xr.profile.vr.persistent]
# Override bundle's default
renderQuality = "quality"
navigation.speed = 7.0

Best Practices#

Bundle Design#

Focused Purpose: One bundle per platform or use case
Documented Defaults: Clearly document all setting changes
Semantic Versioning: Version bundles properly
Minimal Dependencies: Only include necessary extensions

Settings#

Conservative Defaults: Start with safe, balanced settings
Test on Target: Verify on actual hardware
Document Changes: Explain why each setting is set
Allow Overrides: Do not lock settings

Documentation#

README: Clear usage instructions
CHANGELOG: Track all changes
Settings List: Document all configured settings
Support Contact: Provide support information

Troubleshooting#

Bundle Not Loading#

Issue: Bundle extension not found

Solution:

# In .kit file, add extension folder
[settings.app.exts]
folders.'++' = [
    "${app}/../exts",
    "/path/to/bundle/folder"
]

Settings Not Applied#

Issue: Bundle settings not taking effect

Check:

# Verify bundle is loaded
import omni.kit.ext

ext_manager = omni.kit.ext.get_manager()
if ext_manager.is_extension_enabled("my_company.xr.bundle.custom"):
    print("Bundle loaded")
else:
    print("Bundle NOT loaded")

# Check setting value
import carb.settings
settings = carb.settings.get_settings()
value = settings.get("/persistent/xr/profile/vr/renderQuality")
print(f"Current value: {value}")

Conflicting Bundles#

Issue: Multiple bundles fighting over settings

Solution: Only enable one platform-specific bundle at a time:

# Don't do this:
"my_company.xr.bundle.quest3" = {}
"my_company.xr.bundle.apple_vision_pro" = {}  # Conflict!

# Do this:
"my_company.xr.bundle.quest3" = {}  # For Quest build
# OR
"my_company.xr.bundle.apple_vision_pro" = {}  # For AVP build

Next Steps#

Kit App Integration – Integrate bundles into apps
Settings Reference – Complete settings list
Getting Started – Usage examples

Key Takeaways

Bundles package dependencies and settings
Pure configuration - no code required
extension.toml defines everything
Platform-specific bundles for different hardware
Semantic versioning for updates
Document all settings and changes

=======