Skip to main content

Quick Start Tutorial

This tutorial will guide you through setting up a basic XR project using the QWR SDK. By the end, you'll have a working XR scene with hand tracking and basic interactions.

Prerequisites​

Before starting this tutorial, make sure you have:

  • Unity 2022.3 or newer installed
  • Basic knowledge of Unity development
  • QWR SDK downloaded from the GitHub repository

Step 1: Create a New Unity Project​

  1. Open Unity Hub
  2. Click "New Project"
  3. Select the "3D Core" template
  4. Name your project (e.g., "QWR-Tutorial")
  5. Click "Create Project"

Step 2: Install QWR SDK​

  1. Download the QWR SDK from the GitHub repository
  2. In your Unity project, go to Window > Package Manager
  3. Click the "+" button and select "Add package from disk..."
  4. Navigate to the downloaded SDK and select the com.qwr.utilities/package.json file
  5. Once the QWR Utilities package is installed, repeat the process for the QWR Core package by selecting com.qwr.core/package.json

Step 3: Install Required Dependencies​

The QWR SDK requires several Unity packages to function properly. Install them through the Package Manager:

  1. Go to Window > Package Manager
  2. Click the "+" button and select "Add package by name..."
  3. Add the following packages one by one:
    • com.unity.xr.management (version 4.5.1 or newer)
    • com.unity.xr.interaction.toolkit (version 3.2.1 or newer)
    • com.unity.xr.openxr (version 1.15.1 or newer)
    • com.unity.inputsystem (version 1.14.2 or newer)

Step 4: Configure XR Settings​

  1. Go to Edit > Project Settings > XR Plugin Management
  2. Click "Install XR Plugin Management" if prompted
  3. In the XR Plugin Management tab, enable "OpenXR" under "Plugin Providers"
  4. Click on "OpenXR" in the left sidebar
  5. Under "Interaction Profiles", enable the profiles for your target devices (e.g., "Oculus Touch Controller Profile")
  6. Under "Features", ensure "Hand Tracking" is enabled if you plan to use it

Step 5: Create a Basic XR Scene​

  1. Create a new scene (File > New Scene)
  2. Save the scene (File > Save As...) and name it "QWRTutorial"

Step 6: Add QWR XR Origin​

  1. In the Project window, navigate to Packages/QWR Core/Prefabs/QWR_XROrigin
  2. Drag and drop the QWR XR Origin prefab into your scene
  3. Position it at (0, 0, 0)

Step 7: Add a Ground Plane​

  1. Right-click in the Hierarchy and select 3D Object > Plane
  2. Set its position to (0, 0, 0)
  3. Set its scale to (5, 1, 5) to make it larger

Step 8: Add Interactable Objects​

Let's add some simple objects that can be grabbed:

  1. Right-click in the Hierarchy and select 3D Object > Cube

  2. Position it at (0, 1, 2)

  3. Add a Rigidbody component (Add Component > Physics > Rigidbody)

  4. Add a QWRInteractable component (Add Component > QWR > Interaction > QWRInteractable)

  5. In the QWRInteractable component settings:

    • Set "Grab Type" to "Both"
    • Enable "Snap To Hand"
    • Set "Physics Grab Mode" to "Kinematic"

  6. Repeat steps 1-5 to create more objects with different shapes (Sphere, Cylinder) at different positions

Step 9: Add UI Elements​

Let's add a simple UI panel:

  1. Right-click in the Hierarchy and select UI > Canvas

  2. Add a QWRUICanvas component to the Canvas (Add Component > QWR > UI > QWRUICanvas)

  3. In the QWRUICanvas component settings:

    • Set "Interaction Mode" to "Both"
    • Set "Follow Type" to "BodyLocked"
    • Set "Follow Distance" to 1.0

  4. Right-click on the Canvas in the Hierarchy and select UI > Panel

  5. Set the Panel's RectTransform to:

    • Width: 300
    • Height: 200
    • Position: (0, 0, 0)

  6. Right-click on the Panel in the Hierarchy and select UI > Button

  7. Set the Button's RectTransform to:

    • Width: 160
    • Height: 40
    • Position: (0, 0, 0)

  8. Select the Text child of the Button and change the text to "Press Me"

Step 10: Add Button Functionality​

  1. Create a new C# script named "ButtonHandler" in your project
  2. Add the following code to the script:
using UnityEngine;
using UnityEngine.UI;
using QWR.Core.UI;

public class ButtonHandler : MonoBehaviour
{
    [SerializeField] private Button button;
    [SerializeField] private GameObject targetObject;
    [SerializeField] private Color newColor = Color.red;
    
    private Color originalColor;
    private Renderer targetRenderer;
    
    private void Start()
    {
        if (button == null)
            button = GetComponent<Button>();
            
        if (targetObject == null)
            targetObject = GameObject.Find("Cube");
            
        if (targetObject != null)
        {
            targetRenderer = targetObject.GetComponent<Renderer>();
            if (targetRenderer != null)
                originalColor = targetRenderer.material.color;
        }
        
        button.onClick.AddListener(OnButtonClick);
    }
    
    private void OnButtonClick()
    {
        if (targetRenderer != null)
        {
            // Toggle color
            if (targetRenderer.material.color == originalColor)
                targetRenderer.material.color = newColor;
            else
                targetRenderer.material.color = originalColor;
        }
    }
}
  1. Add this script to the Button GameObject
  2. In the Inspector, drag the Cube object into the "Target Object" field

Step 11: Configure Input Actions​

  1. In the Project window, navigate to Packages/QWR Core/Inputs
  2. Find the QWR XRI Default Input Actions asset
  3. Double-click to open it in the Input Actions editor
  4. Review the default input mappings for hands and controllers
  5. Close the editor when done (no changes needed for this tutorial)

Step 12: Test Your Scene​

  1. Save your scene
  2. Click the Play button to enter Play Mode
  3. You should now be able to:
    • Look around using your HMD
    • See your hands or controllers
    • Grab and manipulate the cubes
    • Interact with the UI button using ray interaction

If you don't have an XR device connected, you can still test basic functionality using Unity's XR Device Simulator:

  1. Go to Window > Package Manager
  2. Find and select "XR Interaction Toolkit"
  3. In the details panel, find "Samples" and import "XR Device Simulator"
  4. In your scene, add the XR Device Simulator prefab
  5. Press Play and use the keyboard/mouse to simulate XR input

Step 13: Build and Deploy​

To build your application for an XR device:

  1. Go to File > Build Settings
  2. Add your current scene to the build
  3. Select your target platform (e.g., Android for Quest devices)
  4. Click "Switch Platform"
  5. Configure platform-specific settings if needed
  6. Click "Build" or "Build And Run"

Next Steps​

Congratulations! You've created your first XR application with QWR SDK. Here are some suggestions for next steps:

Troubleshooting​

Hand Tracking Not Working​

  • Ensure your device supports hand tracking
  • Check that hand tracking is enabled in OpenXR settings
  • Verify that your hands are within the tracking volume of your device

Objects Not Grabbable​

  • Ensure objects have both a Collider and Rigidbody component
  • Check that the QWRInteractable component is properly configured
  • Verify that the grab type matches your input method (Hand, Controller, or Both)

UI Not Interactable​

  • Ensure the Canvas has a QWRUICanvas component
  • Check that the interaction mode is set correctly
  • Verify that the Canvas is within reach or visible