Skip to main content

Controller Support

QWR SDK provides comprehensive controller support for a wide range of XR devices. This page explains how to use and customize controller input, visualization, and haptic feedback.

Controller Support Overview​

The controller system in QWR SDK includes:

  • Default input mappings for common controllers
  • Visual representation of controllers in VR
  • Haptic feedback system
  • Interaction with UI and objects
  • Custom input action configuration

QWRControllerManager​

The QWRControllerManager component is responsible for managing controller input, visualization, and interactions.

Accessing Controllers​

You can access controllers through the QWRControllerManager:

// Get references to controllers
QWRController leftController = QWRControllerManager.Instance.GetController(HandType.Left);
QWRController rightController = QWRControllerManager.Instance.GetController(HandType.Right);

// Check if controllers are active
bool isLeftControllerActive = QWRControllerManager.Instance.IsControllerActive(HandType.Left);

Input System​

QWR SDK uses Unity's Input System with a custom input action asset that maps physical controller inputs to actions.

Default Input Actions​

The SDK includes default input mappings for:

  • Trigger button and axis
  • Grip button and axis
  • Thumbstick/touchpad position and click
  • Primary and secondary buttons (A/B, X/Y)
  • Menu button

Reading Input Values​

You can read input values directly from the QWRInputManager:

// Get trigger and grip values (0-1 range)
float triggerValue = QWRInputManager.Instance.GetTriggerValue(HandType.Right);
float gripValue = QWRInputManager.Instance.GetGripValue(HandType.Left);

// Get thumbstick/touchpad position
Vector2 thumbstickPos = QWRInputManager.Instance.GetThumbstickValue(HandType.Right);

// Check button states
bool isPrimaryButtonPressed = QWRInputManager.Instance.IsPrimaryButtonPressed(HandType.Right);
bool isMenuButtonPressed = QWRInputManager.Instance.IsMenuButtonPressed(HandType.Left);

Input Events​

The QWRInputManager provides events for button presses and releases:

// Subscribe to button events
QWRInputManager.Instance.OnTriggerPressed += HandleTriggerPress;
QWRInputManager.Instance.OnGripPressed += HandleGripPress;
QWRInputManager.Instance.OnPrimaryButtonPressed += HandlePrimaryButtonPress;

// Subscribe to thumbstick events
QWRInputManager.Instance.OnThumbstickMoved += HandleThumbstickMove;
QWRInputManager.Instance.OnThumbstickClicked += HandleThumbstickClick;

// Example event handler
private void HandleTriggerPress(HandType handType)
{
    Debug.Log($"Trigger pressed on {handType} controller");
}

Customizing Input Actions​

You can customize the input actions to match your specific needs:

  1. In the Project window, locate com.qwr.core/Inputs/QWR XRI Default Input Actions
  2. Create a duplicate of this asset to customize it
  3. Modify the input mappings in the Input Action editor
  4. Assign your custom input actions to the QWRInputManager component

Controller Visualization​

QWR SDK includes visual models for common controllers that are displayed in VR.

Controller Models​

The SDK includes models for:

  • Oculus Touch controllers
  • Vive controllers
  • Windows Mixed Reality controllers
  • Generic XR controllers

Customizing Controller Appearance​

You can customize the appearance of controllers:

  1. In the scene hierarchy, select QWR XR Origin > Camera Offset > Left/Right Controller
  2. In the Inspector, find the QWRControllerVisualizer component
  3. Modify properties such as:
    • Controller Model: Change the model used for the controller
    • Controller Materials: Customize the materials
    • Visual Effects: Enable/disable button highlights, pointer rays, etc.

Using Custom Controller Models​

To use your own controller models:

  1. Create a controller model prefab with appropriate transforms
  2. In the scene hierarchy, select the Controller GameObject
  3. In the Inspector, find the QWRControllerVisualizer component
  4. Replace the Controller Model Prefab with your custom model

Haptic Feedback​

QWR SDK provides a haptic feedback system for controllers.

Triggering Haptic Feedback​

You can trigger haptic feedback on controllers:

// Simple haptic pulse
QWRInputManager.Instance.TriggerHapticFeedback(HandType.Right, amplitude: 0.5f, duration: 0.1f);

// Continuous haptic feedback
QWRInputManager.Instance.StartContinuousHapticFeedback(HandType.Left, amplitude: 0.3f);
QWRInputManager.Instance.StopHapticFeedback(HandType.Left);

// Haptic patterns
QWRInputManager.Instance.TriggerHapticPattern(HandType.Right, QWRHapticPatterns.Success);

Creating Custom Haptic Patterns​

You can define custom haptic patterns:

// Create a custom haptic pattern
QWRHapticPattern customPattern = new QWRHapticPattern(
    new QWRHapticPulse(amplitude: 0.7f, duration: 0.05f),
    new QWRHapticPulse(amplitude: 0.0f, duration: 0.05f),
    new QWRHapticPulse(amplitude: 0.7f, duration: 0.05f)
);

// Register and trigger the custom pattern
QWRHapticPatterns.RegisterPattern("MyCustomPattern", customPattern);
QWRInputManager.Instance.TriggerHapticPattern(HandType.Right, "MyCustomPattern");

Controller Interactions​

Controllers can interact with objects in the scene through the interaction system.

Ray Interaction​

Controllers have ray interactors for distance interaction:

// Get the current ray interactor
QWRRayInteractor rayInteractor = QWRControllerManager.Instance.GetRayInteractor(HandType.Right);

// Check if ray is hitting something
bool isHitting = rayInteractor.IsHitting;

// Get the current hit object
GameObject hitObject = rayInteractor.CurrentHitObject;

// Adjust ray properties
rayInteractor.MaxRayDistance = 10f;
rayInteractor.SetRayColor(Color.blue);

Direct Interaction​

Controllers can also interact with objects directly:

// Get the direct interactor
QWRDirectInteractor directInteractor = QWRControllerManager.Instance.GetDirectInteractor(HandType.Left);

// Check if currently interacting with something
bool isInteracting = directInteractor.IsInteracting;

// Get the current interacted object
QWRInteractable interactedObject = directInteractor.CurrentInteractable;

Controller Tracking​

The SDK automatically handles controller tracking through Unity's XR system.

Accessing Controller Transforms​

You can access controller transforms:

// Get controller transforms
Transform leftControllerTransform = QWRControllerManager.Instance.GetControllerTransform(HandType.Left);
Transform rightControllerTransform = QWRControllerManager.Instance.GetControllerTransform(HandType.Right);

// Get controller position and rotation
Vector3 controllerPosition = leftControllerTransform.position;
Quaternion controllerRotation = leftControllerTransform.rotation;

Controller Tracking Events​

You can subscribe to controller tracking events:

// Subscribe to tracking events
QWRControllerManager.Instance.OnControllerConnected += HandleControllerConnected;
QWRControllerManager.Instance.OnControllerDisconnected += HandleControllerDisconnected;

// Example event handler
private void HandleControllerConnected(HandType handType)
{
    Debug.Log($"Controller {handType} connected");
}

Switching Between Controllers and Hands​

QWR SDK supports seamless switching between hand tracking and controllers.

Automatic Mode Switching​

By default, the SDK automatically switches between hand tracking and controllers:

  • When controllers are detected, they take precedence over hand tracking
  • When controllers are put down, hand tracking is automatically enabled

Manual Mode Control​

You can manually control which input mode is active:

// Force controller mode
QWRInputManager.Instance.SetInputMode(InputMode.Controllers);

// Force hand tracking mode
QWRInputManager.Instance.SetInputMode(InputMode.Hands);

// Set automatic mode switching
QWRInputManager.Instance.SetInputMode(InputMode.Auto);

Platform-Specific Considerations​

Different XR platforms have varying controller capabilities:

  • Oculus/Meta: Full support for Touch controllers
  • SteamVR: Support for Vive, Index, and other SteamVR controllers
  • Windows Mixed Reality: Support for WMR controllers
  • Mobile VR: Limited support for 3DOF controllers

Troubleshooting​

Controllers Not Detected​

If controllers aren't being detected:

  • Ensure controllers are powered on and paired with your device
  • Check that the correct interaction profiles are enabled in OpenXR settings
  • Verify that controller support is enabled in the XR Plugin Management

Input Not Registering​

If controller input isn't registering:

  • Check that the input action mappings match your controller type
  • Verify that the QWRInputManager is properly initialized
  • Ensure the controller is properly tracked and connected

Haptic Feedback Not Working​

If haptic feedback isn't working:

  • Check that your controllers support haptic feedback
  • Verify that the correct XR plugin is enabled
  • Ensure the amplitude values are in the correct range (0-1)

Next Steps​

Now that you understand controller support, you can explore: