Unity Xr Agent Skill

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

• Run xr_check_setup.
• Create the rig with xr_setup_rig.
• Ensure XR UI input exists with xr_setup_event_system.
• 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

• Convert Canvas with xr_setup_ui_canvas
• Ensure xr_setup_event_system
• 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:

• XRGrabInteractable needs a Rigidbody.
• A grabbable collider must not be trigger.
• A direct interactor collider must be trigger.
• Dynamic mesh colliders must be convex.
• 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

• Scenes should normally have exactly one XRInteractionManager.
• Most locomotion skills assume an XROrigin already exists.
• Package installation or reconfiguration can trigger Domain Reload. Wait before retrying XR calls.
• Use InteractionLayerMask for interactor/interactable filtering.
• 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.