Unity Xr

Unity XR Interaction Toolkit Skills

Requires: com.unity.xr.interaction.toolkit (2.x or 3.x). If not installed, all skills return an install prompt. Cross-version: All API calls use reflection — compatible with XRI 2.x (Unity 2022) and 3.x (Unity 6+) without recompilation.

MANDATORY: Read this document BEFORE calling any xr_* skill. It contains verified property names, Collider rules, and class name references extracted from XRI source code. Using incorrect property names causes silent failures (reflection returns false, no error). The "Guardrails" section at the bottom lists common hallucinated class names that DO NOT EXIST in XRI.

Skills Overview

Quick Start: Complete VR Scene in 5 Steps

import unity_skills as u

# Step 1: Validate project
u.call_skill("xr_check_setup")

# Step 2: Create XR rig
u.call_skill("xr_setup_rig", name="XR Origin")

# Step 3: Add interactors to controllers
u.call_skill("xr_add_ray_interactor", name="Right Controller")
u.call_skill("xr_add_direct_interactor", name="Left Controller")

# Step 4: Set up locomotion
u.call_skill("xr_setup_teleportation")
u.call_skill("xr_setup_turn_provider", turnType="Snap", turnAmount=45)

# Step 5: Make objects interactive
u.call_skill("xr_add_grab_interactable", name="MyCube", movementType="VelocityTracking")

Workflow 1: XR Rig Setup (Project Initialization)

When to use

Starting a new VR/AR project, or converting an existing scene to XR.

Step-by-step

# 1. Check current state — identifies missing components
result = u.call_skill("xr_check_setup", verbose=True)
# Returns: xriVersion, interactionManagerCount, xrOriginCount, mainCamera, issues[]

# 2. Create the XR Origin rig (Camera + Controllers hierarchy)
u.call_skill("xr_setup_rig", name="XR Origin", cameraYOffset=1.36)
# Creates:
#   XR Origin (XROrigin + XRInteractionManager)
#   ├── Camera Offset (y=1.36)
#   │   └── Main Camera (Camera + AudioListener + TrackedPoseDriver)
#   ├── Left Controller (TrackedPoseDriver)
#   └── Right Controller (TrackedPoseDriver)

# 3. Ensure EventSystem has XR input
u.call_skill("xr_setup_event_system")
# Replaces StandaloneInputModule with XRUIInputModule

# 4. Add interactors to controllers
u.call_skill("xr_add_ray_interactor", name="Right Controller", maxDistance=30)
u.call_skill("xr_add_direct_interactor", name="Left Controller", radius=0.1)

Checklist after setup

• xr_check_setup returns 0 issues
• Scene has exactly 1 XRInteractionManager
• Scene has exactly 1 XR Origin with MainCamera
• Both controllers have at least one interactor
• EventSystem has XRUIInputModule

Common Issues

Workflow 2: Grab Interaction

Basic Direct Grab (close range)

# On the controller — add direct interactor
u.call_skill("xr_add_direct_interactor", name="Left Controller", radius=0.1)

# On the object — make it grabbable
u.call_skill("xr_add_grab_interactable", name="MyCube",
    movementType="VelocityTracking",
    throwOnDetach=True,
    useGravity=True)

Remote Ray Grab (point and grab from distance)

# On the controller — add ray interactor
u.call_skill("xr_add_ray_interactor", name="Right Controller",
    maxDistance=30, lineType="StraightLine")

# On the object — same grab setup
u.call_skill("xr_add_grab_interactable", name="DistantObject",
    movementType="Instantaneous")

Socket Interaction (snap-to-slot placement)

# Create a socket on a shelf/holder
u.call_skill("xr_add_socket_interactor", name="ItemSlot",
    showHoverMesh=True, recycleDelay=1.0)

# Make the item grabbable (it will snap into the socket when released near it)
u.call_skill("xr_add_grab_interactable", name="KeyItem",
    movementType="VelocityTracking")

movementType Selection Guide

Attach Point Configuration

# Offset where the hand grips the object (local space)
u.call_skill("xr_add_grab_interactable", name="Sword",
    movementType="VelocityTracking",
    attachTransformOffset="0,-0.3,0")  # grip near the handle base

Advanced: Fine-tune grab physics

u.call_skill("xr_configure_interactable", name="HeavyBox",
    movementType="VelocityTracking",
    smoothPosition=True,
    smoothPositionAmount=5,
    smoothRotation=True,
    smoothRotationAmount=5,
    throwOnDetach=True)

Workflow 3: Teleportation

Basic Setup

# 1. Add teleportation provider to the XR Origin
u.call_skill("xr_setup_teleportation")

# 2. Add a teleport ray to one controller
u.call_skill("xr_add_ray_interactor", name="Right Controller",
    lineType="ProjectileCurve")  # curved ray for natural aiming

# 3. Mark surfaces as teleportable
u.call_skill("xr_add_teleport_area", name="Floor",
    matchOrientation="WorldSpaceUp")

Teleport Areas vs Anchors

# Area: player can land anywhere on this floor
u.call_skill("xr_add_teleport_area", name="MainFloor",
    matchOrientation="WorldSpaceUp")

# Anchor: player teleports to this exact spot, facing the specified direction
u.call_skill("xr_add_teleport_anchor",
    name="Desk Seat", x=2, y=0, z=3, rotY=180,
    matchOrientation="TargetUpAndForward")

matchOrientation Options

Workflow 4: Continuous Locomotion

Joystick Movement + Snap Turn

# Smooth movement on left stick
u.call_skill("xr_setup_continuous_move",
    moveSpeed=2.0, enableStrafe=True, enableFly=False)

# Snap turn on right stick
u.call_skill("xr_setup_turn_provider",
    turnType="Snap", turnAmount=45)

Smooth Movement + Smooth Turn

u.call_skill("xr_setup_continuous_move",
    moveSpeed=2.0, enableStrafe=True)

u.call_skill("xr_setup_turn_provider",
    turnType="Continuous", turnSpeed=90)

Comfort Considerations

Recommendation: Default to Snap Turn + moderate moveSpeed (2.0). Offer smooth turn as an option in settings.

Workflow 5: XR UI

Make existing Canvas work in VR

# Convert Canvas to World Space + add XR raycaster
u.call_skill("xr_setup_ui_canvas", name="MyCanvas")
# - Sets renderMode = WorldSpace
# - Removes GraphicRaycaster, adds TrackedDeviceGraphicRaycaster
# - Sets scale to 0.001 for readable size

# Ensure XR event system
u.call_skill("xr_setup_event_system")

# Player needs a Ray Interactor to interact with UI
u.call_skill("xr_add_ray_interactor", name="Right Controller")

World Space Canvas Best Practices

Workflow 6: Interaction Events & Haptic Feedback

Wire up events

# When player grabs the lever, call a method on the door
u.call_skill("xr_add_interaction_event",
    name="Lever",
    eventType="selectEntered",
    targetName="Door",
    targetMethod="Open")

Available Event Types

Haptic Feedback

# Strong click on grab, light buzz on hover
u.call_skill("xr_configure_haptics", name="Right Controller",
    selectIntensity=0.7, selectDuration=0.15,
    hoverIntensity=0.1, hoverDuration=0.05)

XR Component Dependency Map

Understanding which components must coexist:

Scene Requirements:
  XRInteractionManager (exactly 1)     ← required by ALL interactors/interactables
  EventSystem + XRUIInputModule        ← required for UI interaction

XR Origin Rig:
  XROrigin                             ← required for locomotion
  ├── Camera (TrackedPoseDriver)       ← required for head tracking
  ├── Left Controller (TrackedPoseDriver)
  │   └── Interactor (Ray/Direct)      ← needs Collider (trigger)
  └── Right Controller (TrackedPoseDriver)
      └── Interactor (Ray/Direct)      ← needs Collider (trigger)

Grabbable Object:
  XRGrabInteractable                   ← needs Rigidbody + Collider
  ├── Rigidbody                        ← physics simulation
  └── Collider (non-trigger)           ← interaction detection

Teleport Target:
  TeleportationArea/Anchor             ← needs Collider for ray detection
  └── Collider                         ← raycast target surface

XR UI Canvas:
  Canvas (WorldSpace)
  ├── TrackedDeviceGraphicRaycaster    ← replaces GraphicRaycaster
  └── UI Elements (Button, etc.)

Locomotion (on XR Origin):
  TeleportationProvider                ← for teleport
  ContinuousMoveProvider               ← for joystick movement
  SnapTurnProvider / ContinuousTurnProvider  ← for rotation

Interaction Layer Configuration

Interaction layers control which interactors can interact with which interactables. Use them to separate concerns:

# Example: Teleport ray should only interact with teleport surfaces
u.call_skill("xr_configure_interaction_layers",
    name="TeleportRay", layers="Teleport", isInteractor=True)

u.call_skill("xr_configure_interaction_layers",
    name="Floor", layers="Teleport", isInteractor=False)

# Grab interactor only interacts with grabbable layer
u.call_skill("xr_configure_interaction_layers",
    name="Left Controller", layers="Default", isInteractor=True)

Version Compatibility Notes

All XR skills handle this automatically via XRReflectionHelper — no manual version handling needed. The helper tries 3.x namespaces first, then falls back to 2.x.

Important Notes

1. Package required: All XR skills require com.unity.xr.interaction.toolkit. Install via Package Manager.
2. XR Origin required: Most locomotion skills auto-find the XR Origin. If none exists, they prompt to create one.
3. Colliders are essential: Interactors need trigger Colliders to detect targets. Interactables need Colliders for ray/overlap detection. Skills auto-add appropriate Colliders when missing.
4. One InteractionManager: The scene should have exactly one XRInteractionManager. Multiple managers cause undefined behavior.
5. TrackedPoseDriver: Controllers need TrackedPoseDriver for position/rotation tracking. xr_setup_rig adds these automatically.
6. Domain Reload: Installing the XRI package may trigger a Domain Reload. Wait for Unity to finish compiling before calling XR skills.
7. Reflection safety: If a type is not found (wrong XRI version or missing sub-package), skills return a clear error message instead of crashing.
8. Undo support: All modification skills register with Unity Undo and Workflow tracking.

API Reference: XRRayInteractor (Complete Properties)

Anti-hallucination: These are the REAL property names from XRI source code. Do NOT invent properties.

Core Properties

Line Configuration

Hit Detection

UI & Selection

API Reference: XRInteractorLineVisual

API Reference: XRGrabInteractable (Complete Properties)

Critical: These property names are verified from source. Using wrong names causes silent failures via reflection.

Movement

Smoothing (reduce jitter)

Throw Physics

Attach

Selection

Grab Transformers

API Reference: XRSocketInteractor (Complete Properties)

API Reference: XRDirectInteractor

Collider requirement: XRDirectInteractor MUST have a trigger Collider on the same GameObject. Use SphereCollider with isTrigger=true, radius 0.1–0.25m.

Collider Configuration Matrix (CRITICAL)

Most common XR setup error: Wrong Collider trigger setting. This table is authoritative.

Critical Rules

1. XRGrabInteractable requires Rigidbody — without it, physics-based movementType won't work
2. XRGrabInteractable Collider must NOT be trigger — trigger colliders cannot participate in physics simulation
3. XRDirectInteractor Collider MUST be trigger — it uses OnTriggerStay to detect interactables
4. MeshCollider on grabbables must be convex=true — non-convex MeshCollider cannot be Dynamic Rigidbody
5. Socket Collider must be trigger — overlap detection, not physics blocking

Common Mistakes

❌ GrabInteractable + Collider(isTrigger=true) → Object cannot be grabbed
❌ GrabInteractable without Rigidbody → VelocityTracking silently fails
❌ DirectInteractor + Collider(isTrigger=false) → Cannot detect any targets
❌ MeshCollider(convex=false) on Rigidbody → Unity error, physics broken
❌ Socket Collider(isTrigger=false) → Objects bounce off instead of snapping

API Reference: Event System (Complete)

Interactable Events (on XRBaseInteractable / XRGrabInteractable)

Event Args Properties

// SelectEnterEventArgs
args.interactorObject   // IXRSelectInteractor — who grabbed
args.interactableObject // IXRSelectInteractable — what was grabbed

// SelectExitEventArgs
args.interactorObject   // IXRSelectInteractor
args.interactableObject // IXRSelectInteractable
args.isCanceled         // bool — was it force-canceled (not natural release)

// HoverEnterEventArgs / HoverExitEventArgs
args.interactorObject   // IXRHoverInteractor
args.interactableObject // IXRHoverInteractable

// ActivateEventArgs / DeactivateEventArgs
args.interactorObject   // IXRActivateInteractor
args.interactableObject // IXRActivateInteractable

Usage Pattern (from XRI source examples)

// CORRECT pattern — subscribe in OnEnable, unsubscribe in OnDisable
protected override void OnEnable()
{
    base.OnEnable();
    selectEntered.AddListener(OnGrab);
    selectExited.AddListener(OnRelease);
}

protected override void OnDisable()
{
    selectEntered.RemoveListener(OnGrab);
    selectExited.RemoveListener(OnRelease);
    base.OnDisable();
}

// CORRECT — use ProcessInteractable for continuous updates
public override void ProcessInteractable(XRInteractionUpdateOrder.UpdatePhase updatePhase)
{
    base.ProcessInteractable(updatePhase);
    if (updatePhase == XRInteractionUpdateOrder.UpdatePhase.Dynamic)
    {
        if (isSelected)
        {
            // Track hand position, update slider/knob/etc.
            var attachPos = m_Interactor.GetAttachTransform(this).position;
        }
    }
}

UpdatePhase Values

API Reference: TrackedPoseDriver

Namespace: UnityEngine.InputSystem.XR.TrackedPoseDriver (Input System package) Legacy fallback: UnityEngine.SpatialTracking.TrackedPoseDriver

Typical Bindings

Camera:           <XRHMD>/centerEyePosition, <XRHMD>/centerEyeRotation
Left Controller:  <XRController>{LeftHand}/devicePosition, deviceRotation
Right Controller: <XRController>{RightHand}/devicePosition, deviceRotation

API Reference: Input Action Map (XRI Default)

Source: XRI Default Input Actions.inputactions (from Starter Assets)

XRI LeftHand / RightHand Interaction

XRI LeftHand / RightHand Locomotion

Standard Controller Layout

Left Controller:                    Right Controller:
┌──────────────────┐               ┌──────────────────┐
│   [Thumbstick]   │ ← Move       │   [Thumbstick]   │ ← Turn/Teleport
│                  │               │                  │
│ [Grip] ← Select │               │ [Grip] ← Select  │
│                  │               │                  │
│ [Trigger]←Activate              │ [Trigger]←Activate│
└──────────────────┘               └──────────────────┘

Guardrails: Preventing AI Hallucination

Mode: Full-Auto required (requires com.unity.xr.interaction.toolkit package)

DO NOT assume these exist (they don't in XRI)

❌ XRHand                    → Use XRController or ActionBasedController
❌ XRPlayer                  → Use XR Origin (XROrigin)
❌ XRTeleporter              → Use TeleportationProvider + TeleportationArea/Anchor
❌ GrabInteractor            → Use XRDirectInteractor or XRRayInteractor
❌ XRButton                  → Use XRSimpleInteractable + custom script
❌ VRController              → Use ActionBasedController
❌ XRLocomotion              → Use ContinuousMoveProvider / TeleportationProvider
❌ interactable.OnGrab()     → Use selectEntered event
❌ interactable.OnRelease()  → Use selectExited event
❌ controller.vibrate()      → Use haptic properties on interactor
❌ XRManager                 → Use XRInteractionManager

Correct class names (verified from source)

✅ XRInteractionManager      (exactly 1 per scene)
✅ XROrigin                   (from Unity.XR.CoreUtils)
✅ XRRayInteractor            (remote interaction)
✅ XRDirectInteractor          (close-range interaction)
✅ XRSocketInteractor          (snap-to placement)
✅ XRGrabInteractable          (grabbable object)
✅ XRSimpleInteractable        (basic hover/select)
✅ TeleportationProvider       (on XR Origin)
✅ TeleportationArea           (surface teleport target)
✅ TeleportationAnchor         (point teleport target)
✅ ContinuousMoveProvider      (joystick movement)
✅ SnapTurnProvider             (snap rotation)
✅ ContinuousTurnProvider      (smooth rotation)
✅ TrackedDeviceGraphicRaycaster (XR UI raycast)
✅ XRUIInputModule              (XR event system)
✅ ActionBasedController        (Input System controller)
✅ TrackedPoseDriver            (position/rotation tracking)
✅ XRInteractorLineVisual       (ray line rendering)

Script writing rules for XR

1. Inherit from XRBaseInteractable for custom interactive objects, NOT MonoBehaviour
2. Use ProcessInteractable(UpdatePhase.Dynamic) for continuous tracking, NOT Update()
3. Use selectEntered/selectExited events, NOT OnTriggerEnter/OnCollisionEnter
4. Use GetAttachTransform(this).position to get hand position, NOT controller.transform.position
5. Use isSelected / isHovered readonly properties, NOT custom flags
6. Always call base.OnEnable() / base.OnDisable() when overriding in interactable subclasses
7. Use InteractionLayerMask for filtering, NOT physics Layer or Tag

Load Related Advisory Modules When Needed

• Architecture & module design: see ../architecture/SKILL.md
• Performance review (Update, allocations): see ../performance/SKILL.md
• Script quality (coupling, naming): see ../scriptdesign/SKILL.md
• Async & lifecycle (coroutine vs UniTask in XR): see ../async/SKILL.md
• Design patterns (Observer for XR events, State Machine for locomotion modes): see ../patterns/SKILL.md