unity-xr

name	unity-xr
description	Set up XR Interaction Toolkit (XRI) for VR/AR

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Building VR/AR interaction
• Setting up an XR rig
• Configuring grab/socket/ray interactors
• 构建 VR/AR 交互、搭建 XR rig、配置抓取/插槽/射线交互器

Unity XR Interaction Toolkit Skills

Use this module for XR Interaction Toolkit setup and configuration. All xr_* skills are reflection-based and support XRI 2.x on Unity 2022 and XRI 3.x on Unity 6+.

Requires: com.unity.xr.interaction.toolkit. 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.

Guardrails

Operating Mode (v1.9 three-tier):

• Approval (default): query/list/info skills (xr_check_setup, xr_get_scene_report, xr_list_interactors, xr_list_interactables) run directly. Create/modify skills are FullAuto — on MODE_RESTRICTED, run the grant protocol; a successful /permission/grant executes the skill server-side and returns the result in the same response.
• Auto / Bypass: SemiAuto and FullAuto run directly.
• This module contains no Delete / PlayMode / Reload / RiskLevel="high" skills, so nothing is auto-classified as forbidden — every skill is reachable via grant.
• When com.unity.xr.interaction.toolkit is missing, every xr_* skill returns the NoXRI() install instruction instead of executing.
• Reflection-sensitive: property names on XRI components must match XRI 2.x/3.x exactly. A wrong field name on xr_configure_interactable / xr_configure_haptics / xr_configure_interaction_layers is silently ignored. Load API_REFERENCE.md before issuing detailed property edits.

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. Load API_REFERENCE.md before setting detailed XR component properties

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
• For architecture or lifecycle decisions in XR gameplay code -> load advisory modules such as architecture, patterns, async, or scriptdesign
• For exact component property names and full workflow examples -> load API_REFERENCE.md

Skills

Setup and Diagnostics

Skill	Use	Key parameters
xr_check_setup	Validate XR package, rig, managers, and scene prerequisites	verbose?
xr_setup_rig	Create XR Origin + camera + controllers	name, cameraYOffset?
xr_setup_interaction_manager	Add or find manager	none
xr_setup_event_system	Replace/add XR UI input stack	none
xr_get_scene_report	Report scene-side XR status	none

Interactors and Interactables

Skill	Use	Key parameters
xr_add_ray_interactor	Remote pointing / ray interaction	name, maxDistance?, lineType?
xr_add_direct_interactor	Close-range hand grab	name, radius?
xr_add_socket_interactor	Snap-to slot	name, showHoverMesh?, recycleDelay?
xr_add_grab_interactable	Rigidbody + collider + grab config	name, movementType?, throwOnDetach?
xr_add_simple_interactable	Hover/select without grab	name
xr_configure_interactable	Fine-tune interactable behavior	target + changed fields only
xr_list_interactors	List all scene interactors	none
xr_list_interactables	List all scene interactables	none

Locomotion and XR UI

Skill	Use	Key parameters
xr_setup_teleportation	Add teleport provider to XR Origin	none
xr_add_teleport_area	Mark a surface as teleportable	name, matchOrientation?
xr_add_teleport_anchor	Create fixed teleport destination	name, x/y/z, rotY?, matchOrientation?
xr_setup_continuous_move	Add stick locomotion	moveSpeed?, enableStrafe?, enableFly?
xr_setup_turn_provider	Add snap or smooth turn	turnType, turnAmount?, turnSpeed?
xr_setup_ui_canvas	Convert Canvas for XR interaction	name

Feedback and Filtering

Skill	Use	Key parameters
xr_configure_haptics	Set hover/select vibration	name, intensities, durations
xr_add_interaction_event	Wire interaction callback to target method	name, eventType, targetName, targetMethod
xr_configure_interaction_layers	Set InteractionLayerMask	name, layers, isInteractor

Quick Start

import unity_skills as u

u.call_skill("xr_check_setup")
u.call_skill("xr_setup_rig", name="XR Origin")
u.call_skill("xr_add_ray_interactor", name="Right Controller")
u.call_skill("xr_add_direct_interactor", name="Left Controller")
u.call_skill("xr_setup_teleportation")
u.call_skill("xr_setup_turn_provider", turnType="Snap", turnAmount=45)
u.call_skill("xr_add_grab_interactable", name="MyCube", movementType="VelocityTracking")

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

Collider Configuration Matrix

This is the most important XR anti-hallucination table in the repo.

Component	Collider required	isTrigger	Recommended collider	Reason
XRDirectInteractor	Yes	True	SphereCollider (0.1-0.25)	Overlap detection
XRRayInteractor	No	-	None	Uses raycasts
XRSocketInteractor	Yes	True	SphereCollider (0.1-0.3)	Snap zone
XRGrabInteractable	Yes	False	BoxCollider or convex MeshCollider	Physics + ray target
XRSimpleInteractable	Yes	False	BoxCollider	Selection detection
TeleportationArea	Yes	False	MeshCollider or BoxCollider	Surface raycast target
TeleportationAnchor	Yes	False	Thin BoxCollider	Point raycast target

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

Topic	XRI 2.x	XRI 3.x
Main namespace style	root namespace	split sub-namespaces
Rig type	XROrigin	XROrigin
Locomotion core	LocomotionSystem	LocomotionMediator
Controller type	ActionBasedController	ActionBasedController
Bridge behavior	Reflection helper falls back automatically	Reflection helper prefers 3.x first

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.

Minimal Example

import unity_skills as u

u.call_skill("xr_setup_rig", name="XR Origin", cameraYOffset=1.36)
u.call_skill("xr_setup_event_system")
u.call_skill("xr_add_ray_interactor", name="Right Controller", maxDistance=30, lineType="StraightLine")
u.call_skill("xr_add_grab_interactable", name="Tool", movementType="VelocityTracking", throwOnDetach=True)
u.call_skill("xr_configure_haptics", name="Right Controller", selectIntensity=0.7, selectDuration=0.15)

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file. Before configuring XR component properties in detail, load API_REFERENCE.md. XR property names are reflection-sensitive.