Unity Xr

Unity XR Interaction Toolkit Skills

Requirements

• com.unity.xr.interaction.toolkit (≥ 3.4). Recipes target XRI 3 API only. If missing, install via Unity_PackageManager_ExecuteAction with operation=Add, package=com.unity.xr.interaction.toolkit, version=3.4.1.

When to Use

Use this module for XR Interaction Toolkit setup and configuration.

Hard rule: Read this file before the first xr_* call in a session. Wrong property names can fail silently because the bridge is reflection-based.

Common Mistakes

DO NOT (common hallucinations):

• XRHand, XRPlayer, XRTeleporter, GrabInteractor, VRController, XRLocomotion, and XRManager are not the runtime classes you want here
• interactable.OnGrab() / OnRelease() are not the XRI event model -> use selectEntered / selectExited
• controller.vibrate() is not the documented route here -> configure haptics through xr_configure_haptics
• Do not assume physics Layer or Tag replaces InteractionLayerMask
• Do not guess component property names — they are set via reflection. Use the skill parameters directly

Correct class names to anchor on:

• XRInteractionManager
• XROrigin
• XRRayInteractor
• XRDirectInteractor
• XRSocketInteractor
• XRGrabInteractable
• XRSimpleInteractable
• TeleportationProvider
• TeleportationArea
• TeleportationAnchor
• ContinuousMoveProvider
• SnapTurnProvider
• ContinuousTurnProvider
• TrackedDeviceGraphicRaycaster
• XRUIInputModule
• TrackedPoseDriver

Routing:

• For non-XR Canvas UI creation -> use ui

Quick Reference

Setup and Diagnostics

Interactors and Interactables

Locomotion and XR UI

Feedback and Filtering

Workflow Summary

Rig Setup

1. Run xr_check_setup.
2. Create the rig with xr_setup_rig.
3. Ensure XR UI input exists with xr_setup_event_system.
4. Add at least one interactor per controller.

Grab Setup

• Direct hand grab: xr_add_direct_interactor + xr_add_grab_interactable
• Distance grab: xr_add_ray_interactor + xr_add_grab_interactable
• Socket placement: xr_add_socket_interactor + grabbable object

movementType defaults matter:

• VelocityTracking: best general-purpose physical grab
• Kinematic: use for handles/tools that should not get stuck
• Instantaneous: best for precise remote grab

Locomotion Setup

• Teleport: xr_setup_teleportation + xr_add_ray_interactor + xr_add_teleport_area/xr_add_teleport_anchor
• Continuous locomotion: xr_setup_continuous_move
• Turn: xr_setup_turn_provider

Comfort default: snap turn + moderate move speed (~2.0 m/s).

XR UI

1. Convert Canvas with xr_setup_ui_canvas
2. Ensure xr_setup_event_system
3. Add a ray interactor on the controller that should click UI

Events and Haptics

Event types for xr_add_interaction_event: selectEntered, selectExited, hoverEntered, hoverExited, firstSelectEntered, lastSelectExited, activated, deactivated.

Haptic defaults: selectIntensity=0.5, selectDuration=0.1, hoverIntensity=0.1, hoverDuration=0.05.

Collider Configuration Matrix

This is the most important XR anti-hallucination table.

Critical rules:

1. XRGrabInteractable needs a Rigidbody.
2. A grabbable collider must not be trigger.
3. A direct interactor collider must be trigger.
4. Dynamic mesh colliders must be convex.
5. Socket colliders should be trigger-only overlap zones.

Version Compatibility

C# Templates

Recipe path rule: ../../recipes/xr/<command>.md

See ../../recipes/xr/<command>.md for C# templates.

Important Notes

1. Scenes should normally have exactly one XRInteractionManager.
2. Most locomotion skills assume an XROrigin already exists.
3. Package installation or reconfiguration can trigger Domain Reload. Wait before retrying XR calls.
4. Use InteractionLayerMask for interactor/interactable filtering.
5. For custom XR scripts, prefer XRI lifecycle hooks and events over Update() polling when possible.