SteamVR Utils

A Unity package containing useful tools and scripts for SteamVR projects, including tracker management, UI utilities, and data recording capabilities.

Created by: Alex van den Berg - 2025-06-10
With contributions from: Nicolas Wenk

For more information visit our website: mlnlab.nl, or our wiki page.

Features

• Tracker Configuration System - Reliable tracker assignment based on serial IDs
• ViveTrackersUI - Interactive UI for managing tracker configurations
• SteamVR Event System - Easy trigger and button press event handling
• Data Recording - Optional UXF integration for experiment data collection
• Utility Scripts - Smooth following, jitter monitoring, rig alignment, and more

Installation

Method 1: Import Unity Package

1. Download the files in this repo.
2. Just drag them into your Unity assets.

Method 2: Git URL (Package Manager)

1. Open Unity Package Manager (Window > Package Manager)
2. Click the + button and select Add package from git URL
3. Enter the repository URL

Important: StreamingAssets Setup

After importing the package, you must copy the contents of the SteamingAssets folder to your project's StreamingAssets folder:

1. Navigate to Assets/SteamVR Utils/SteamingAssets/
2. Copy tracker_config.txt to your project's Assets/StreamingAssets/ folder
3. If your project doesn't have a StreamingAssets folder, create one in your Assets directory first

Dependencies

Required Dependencies

SteamVR Plugin

This package only works with the SteamVR Plugin.

Installation:

1. Get the SteamVR Plugin from: https://assetstore.unity.com/packages/tools/integration/steamvr-plugin-32647
2. Add it to your Unity assets first
3. Open Package Manager → My Assets → Import SteamVR Plugin
4. Last tested version: 2.8.0 (SDK 2.0.10)

Optional Dependencies

UXF (Unity Experiment Framework)

For advanced data recording and experiment management capabilities.

Installation:

• Repository: https://github.com/immersivecognition/unity-experiment-framework
• Follow the UXF installation instructions from their repository

Enable UXF Support:

1. Go to Project Settings > Player > Scripting Define Symbols
2. Add UXF to the symbols list
3. Scripts with UXF integration will now be fully functional

VIVE OpenXR Plugin

For OpenXR compatibility with VIVE devices.

Installation:

1. Download VIVE OpenXR Plugin UnityPackage from: https://github.com/ViveSoftware/VIVE-OpenXR-Unity
2. Import the unitypackage file in Unity
3. Select VIVE/OpenXR Installer from the Unity menu
4. Press "Install or Update latest version"

VIVE Input Utility

For enhanced VIVE controller input handling.

Installation:

1. Go to Project Settings > Package Manager > Scoped Registries
2. Add the following registry:
   • Name: VIVE
   • URL: https://npm-registry.vive.com
   • Scope(s): com.htc.upm
3. Open Window > Package Manager > My Registries > VIVE
4. Install "Vive Input Utility"

Enable VIU Support:

1. Go to Project Settings > Player > Scripting Define Symbols
2. Add VIU to the symbols list
3. VIU-dependent scripts will now be fully functional

Usage Guide

TrackerConfigurationLoader

The TrackerConfigurationLoader ensures trackers are consistently assigned based on their serial IDs rather than connection order.

Setup:

1. Add the TrackerConfigurationLoader component to any GameObject that should be tracked by a VIVE tracker
2. Set the Configured Name field to match a name from tracker_config.txt (e.g., "VR-17", "VR-19", etc.)
3. When the scene starts, the tracker will automatically assign based on its ID from the config file

Configuration File Format: The StreamingAssets/tracker_config.txt file uses the format:

TrackerName;TrackerSerialID
VR-17;LHR-F806079D
VR-19;LHR-481B26F5

ViveTrackersUI

Interactive UI system for managing tracker configurations in real-time.

Setup:

1. Drag the ViveTrackersUI prefab into your scene
2. Unity will prompt to import TMP Essentials - click "Import" (you don't need examples & extras)
3. If your scene doesn't have an Event System:
   • Right-click in Hierarchy
   • Go to UI > Event System
   • Add the Event System (required for UI button functionality)

Usage:

1. Start the scene - the UI will automatically detect trackers with TrackerConfigurationLoader components
2. Set New Tracker IDs: Change the text field next to any tracker name and click "Submit" to assign a new tracker ID
3. Save Configuration: Submitting changes automatically saves the configuration to a CSV file in StreamingAssets
4. Load from File: Click "Load from File" to restore previously saved configurations
5. Get from Scene: Click "Get from Scene" to refresh the UI with current TrackerConfigurationLoader settings

Event System Scripts

SteamVRTriggerEvent

Attach to a controller to easily handle trigger button events.

Usage:

1. Add to any SteamVR controller GameObject
2. Configure trigger events in the inspector
3. Assign methods to run on trigger press/release

VIUButtonPressEvent (Requires VIU)

Advanced button press event handling for VIVE controllers.

Usage:

1. Add to any GameObject
2. Configure controller role and button type
3. Assign UnityEvents to trigger on button press

Data Recording (Requires UXF)

UXFSteamVRTracker

Advanced data logging for SteamVR devices integrated with UXF.

Features:

• Records position and rotation data for all tracked devices
• Thread-safe recording for high-frequency data capture
• Integrates seamlessly with UXF experiment framework

Tracker Following Scripts

RelativeSmoothTrackedFollower

Smoothly tracks a raw tracker relative to a reference tracker and applies it to a reference frame.

Setup:

1. Create a GameObject for your smooth tracker (e.g., "SmoothHandTracker")
2. Add the RelativeSmoothTrackedFollower component
3. Assign:
   • Raw Tracker: Your raw tracker (e.g., Vive tracker with TrackerConfigurationLoader)
   • Reference Tracker: The reference tracker (e.g., tabletop tracker)
   • Reference Frame: The frame to apply the smoothed pose to
4. Adjust smoothing values (0 = instant, 1 = very slow)

Usage:

• This script outputs a smoothed tracker position/rotation
• Use this as input for ObjectTrackerConnector to connect any object

ObjectTrackerConnector

Connects any object to a smooth tracker with manual offsets.

Setup:

1. Attach this component to any GameObject (hand, tool, etc.)
2. Assign the Smooth Tracker (output from RelativeSmoothTrackedFollower)
3. Adjust Position Offset and Rotation Offset to align the object correctly

Usage:

• Simple two-step workflow:
  1. Use RelativeSmoothTrackedFollower to create a smooth tracker
  2. Use ObjectTrackerConnector to connect any object to that smooth tracker

Utility Scripts

SmoothFollower

Smooth camera following with configurable damping.

JitterMonitor

Monitor and debug tracking jitter issues.

RigAlignment

Tools for aligning VR rigs and tracked objects.

AxisGizmo

Visual debugging aids for coordinate systems.

Troubleshooting

Compile Errors

• UXF-related errors: Add UXF to Scripting Define Symbols or ensure UXF is properly installed
• VIU-related errors: Add VIU to Scripting Define Symbols or install VIVE Input Utility
• SteamVR errors: Ensure SteamVR Plugin is properly imported and up to date

Tracker Issues

• Trackers not assigning: Check that tracker_config.txt is in your StreamingAssets folder
• Wrong tracker assignments: Verify serial IDs in the config file match your physical trackers
• UI not working: Ensure you have an Event System in your scene and TMP Essentials imported

Performance Issues

• High CPU usage: Check recording frequency settings in data recording components
• Frame drops: Consider reducing tracking update rates or using threaded recording options

Package Contents

Scripts

• TrackerConfigurationLoader.cs - Core tracker assignment system
• ViveTrackerUIManager.cs - UI management for tracker configuration
• TrackerInputRow.cs - UI component for individual tracker rows
• UXFSteamVRTracker.cs - UXF-integrated data recording
• VIUButtonPressEvent.cs - VIU button event handling
• SteamVRTriggerEvent.cs - Basic trigger event handling
• RelativeSmoothTrackedFollower.cs - Smooth relative tracking with reference frames
• ObjectTrackerConnector.cs - Connect any object to smooth tracker with offsets
• SmoothFollower.cs - Smooth following utility
• JitterMonitor.cs - Tracking quality monitoring
• RigAlignment.cs - VR rig alignment tools
• AxisGizmo.cs - Visual coordinate system debugging

Prefabs

• ViveTrackersUI.prefab - Complete tracker management UI
• TrackerInputRow.prefab - Individual tracker UI component
• Recorder.prefab - Data recording setup
• Replayer.prefab - Data playback system

Configuration Files

• tracker_config.txt - Tracker serial ID mapping

License

See LICENSE file for details.

Support

For more information visit our website: mlnlab.nl, or our wiki page.