---
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` is silently ignored; `xr_configure_interaction_layers` takes layer names or an integer mask and rejects undefined names. 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

```python
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

```python
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.