unity-xr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

调用本模块中的任何技能之前： 如果您打算根据技能名称或描述猜测参数来调用技能，请停止操作——先阅读本文档（或通过
GET /skills/recommend?includeSchema=true
获取其 schema）。如果您已经从推荐/schema中获取了参数定义，则可以直接进行dryRun。

Triggers

触发场景

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

构建VR/AR交互
搭建XR rig
配置抓取/插槽/射线交互器
构建 VR/AR 交互、搭建 XR rig、配置抓取/插槽/射线交互器

Unity XR Interaction Toolkit Skills

Unity XR Interaction Toolkit 技能

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.

本模块用于XR Interaction Toolkit的设置与配置。所有

xr_*

技能均基于反射实现，支持Unity 2022上的XRI 2.x版本以及Unity 6+上的XRI 3.x版本。

依赖要求：
com.unity.xr.interaction.toolkit
。 硬性规则：在会话中首次调用
xr_*
技能前，请阅读本文档。由于桥接层基于反射实现，错误的属性名称可能会导致静默失败。

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

运行模式（v1.9 三层模式）：

审批模式（默认）：查询/列表/信息类技能（
```
xr_check_setup
```
、
```
xr_get_scene_report
```
、
```
xr_list_interactors
```
、
```
xr_list_interactables
```
）可直接运行。创建/修改类技能为FullAuto模式——在
```
MODE_RESTRICTED
```
模式下，需执行授权协议；成功调用
```
/permission/grant
```
后，技能将在服务器端执行，并在同一响应中返回结果。
自动模式/绕过模式：SemiAuto和FullAuto模式的技能可直接运行。
本模块不包含删除/播放模式/重载/
```
RiskLevel="high"
```
类技能，因此没有技能会被自动归类为禁用——所有技能均可通过授权访问。
当缺少
```
com.unity.xr.interaction.toolkit
```
包时，所有
```
xr_*
```
技能将返回
```
NoXRI()
```
安装指引，而非执行操作。
反射敏感：XRI组件的属性名称必须与XRI 2.x/3.x版本完全匹配。
```
xr_configure_interactable
```
/
```
xr_configure_haptics
```
/
```
xr_configure_interaction_layers
```
技能中使用错误的字段名将被静默忽略。在进行详细的组件属性编辑前，请加载
```
API_REFERENCE.md
```
文档。

请勿执行以下操作（常见错误认知）：

XRHand

、

XRPlayer

、

XRTeleporter

、

GrabInteractor

、

VRController

、

XRLocomotion

和

XRManager

并非此处所需的运行时类

interactable.OnGrab()

OnRelease()

并非XRI的事件模型，请使用

selectEntered

selectExited

```
controller.vibrate()
```
并非此处的官方调用方式，请通过
```
xr_configure_haptics
```
配置触觉反馈
请勿假设物理层（Layer）或标签（Tag）可以替代
```
InteractionLayerMask
```
请勿猜测组件属性名称。在设置XR组件的详细属性前，请加载
```
API_REFERENCE.md
```
文档

应参考的正确类名：

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

路由指引：

若要创建非XR的Canvas UI，请使用
```
ui
```
模块
若要进行XR游戏代码的架构或生命周期决策，请加载
```
architecture
```
、
```
patterns
```
、
```
async
```
或
```
scriptdesign
```
等咨询模块
若要获取准确的组件属性名称和完整工作流示例，请加载
```
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

技能	用途	关键参数
`xr_check_setup`	验证XR包、Rig、管理器及场景前置条件	`verbose?`
`xr_setup_rig`	创建XR Origin + 相机 + 控制器	`name` , `cameraYOffset?`
`xr_setup_interaction_manager`	添加或查找管理器	无
`xr_setup_event_system`	替换/添加XR UI输入栈	无
`xr_get_scene_report`	报告场景端XR状态	无

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

技能	用途	关键参数
`xr_add_ray_interactor`	远程指向/射线交互	`name` , `maxDistance?` , `lineType?`
`xr_add_direct_interactor`	近距离手部抓取	`name` , `radius?`
`xr_add_socket_interactor`	吸附插槽	`name` , `showHoverMesh?` , `recycleDelay?`
`xr_add_grab_interactable`	刚体 + 碰撞器 + 抓取配置	`name` , `movementType?` , `throwOnDetach?`
`xr_add_simple_interactable`	无需抓取的悬停/选择	`name`
`xr_configure_interactable`	微调可交互对象行为	目标对象 + 仅需修改的字段
`xr_list_interactors`	列出场景中所有交互器	无
`xr_list_interactables`	列出场景中所有可交互对象	无

Locomotion and XR UI

移动系统与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`

技能	用途	关键参数
`xr_setup_teleportation`	为XR Origin添加传送提供者	无
`xr_add_teleport_area`	将表面标记为可传送区域	`name` , `matchOrientation?`
`xr_add_teleport_anchor`	创建固定传送目标点	`name` , `x/y/z` , `rotY?` , `matchOrientation?`
`xr_setup_continuous_move`	添加摇杆移动	`moveSpeed?` , `enableStrafe?` , `enableFly?`
`xr_setup_turn_provider`	添加快速转向或平滑转向	`turnType` , `turnAmount?` , `turnSpeed?`
`xr_setup_ui_canvas`	转换Canvas以支持XR交互	`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`

技能	用途	关键参数
`xr_configure_haptics`	设置悬停/选择时的振动反馈	`name` , intensities, durations
`xr_add_interaction_event`	将交互回调绑定到目标方法	`name` , `eventType` , `targetName` , `targetMethod`
`xr_configure_interaction_layers`	设置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")

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

Rig搭建

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.

运行
```
xr_check_setup
```
。
使用
```
xr_setup_rig
```
创建Rig。
通过
```
xr_setup_event_system
```
确保XR UI输入系统存在。
为每个控制器添加至少一个交互器。

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

手部直接抓取：

xr_add_direct_interactor

xr_add_grab_interactable

远程抓取：

xr_add_ray_interactor

xr_add_grab_interactable

插槽放置：
```
xr_add_socket_interactor
```
+ 可抓取对象

movementType

的默认值非常重要：

```
VelocityTracking
```
：最佳通用物理抓取方式
```
Kinematic
```
：适用于不应被卡住的手柄/工具
```
Instantaneous
```
：最适合精准远程抓取

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_setup_teleportation

xr_add_ray_interactor

xr_add_teleport_area

xr_add_teleport_anchor

连续移动：
```
xr_setup_continuous_move
```
转向：
```
xr_setup_turn_provider
```

舒适默认设置：快速转向 + 中等移动速度（

~2.0 m/s

）。

XR UI

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

使用
```
xr_setup_ui_canvas
```
转换Canvas
确保已设置
```
xr_setup_event_system
```
在用于点击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.

这是本仓库中最重要的XR错误认知规避表格。

组件	是否需要碰撞器	`isTrigger`	推荐碰撞器	原因
`XRDirectInteractor`	是	True	SphereCollider（ `0.1-0.25` ）	重叠检测
`XRRayInteractor`	否	-	无	使用射线检测
`XRSocketInteractor`	是	True	SphereCollider（ `0.1-0.3` ）	吸附区域
`XRGrabInteractable`	是	False	BoxCollider或凸面体MeshCollider	物理交互 + 射线目标
`XRSimpleInteractable`	是	False	BoxCollider	选择检测
`TeleportationArea`	是	False	MeshCollider或BoxCollider	表面射线检测目标
`TeleportationAnchor`	是	False	薄BoxCollider	点射线检测目标

关键规则：

```
XRGrabInteractable
```
需要添加
```
Rigidbody
```
组件。
可抓取对象的碰撞器不能设置为触发器。
直接交互器的碰撞器必须设置为触发器。
动态网格碰撞器必须设置为凸面体。
插槽碰撞器应设为仅触发的重叠区域。

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

主题	XRI 2.x	XRI 3.x
主命名空间风格	根命名空间	拆分的子命名空间
Rig类型	`XROrigin`	`XROrigin`
移动系统核心	`LocomotionSystem`	`LocomotionMediator`
控制器类型	`ActionBasedController`	`ActionBasedController`
桥接层行为	反射助手自动回退	反射助手优先使用3.x版本

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.

场景通常应仅包含一个
```
XRInteractionManager
```
。
大多数移动系统技能假设
```
XROrigin
```
已存在。
包安装或重新配置可能会触发域重载。重试XR调用前请等待。
使用
```
InteractionLayerMask
```
进行交互器/可交互对象的过滤。
编写自定义XR脚本时，尽可能优先使用XRI生命周期钩子和事件，而非
```
Update()
```
轮询。

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)

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

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.

精确的名称、参数、默认值和返回值由

GET /skills/schema

或

unity_skills.get_skill_schema()

定义，而非本文档。在详细配置XR组件属性前，请加载

API_REFERENCE.md

文档。XR属性名称对反射敏感。