unity-xr

**调用此模块中的任何技能之前：**如果你正准备根据技能名称或描述猜测参数后调用技能，请先停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获得参数定义，则可以直接进行 dryRun。

触发条件

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

Unity XR Interaction Toolkit 技能

使用此模块设置和配置 XR Interaction Toolkit。所有 xr_* 技能都基于反射，并支持 Unity 2022 上的 XRI 2.x 和 Unity 6+ 上的 XRI 3.x。

需要：com.unity.xr.interaction.toolkit。 **硬性规则：**在会话中首次调用 xr_* 之前，请先阅读此文件。由于桥接基于反射，错误的属性名称可能会静默失败。

护栏

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

• Approval（默认）：查询/列表/信息类技能（xr_check_setup、xr_get_scene_report、xr_list_interactors、xr_list_interactables）直接运行。创建/修改类技能为 FullAuto——在 MODE_RESTRICTED 下运行授权流程；成功调用 /permission/grant 后，技能会在服务端执行，并在同一响应中返回结果。
• Auto / Bypass：SemiAuto 和 FullAuto 直接运行。
• 此模块不包含任何 Delete / PlayMode / Reload / 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

技能

设置与诊断

技能	用途	关键参数
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 状态	无

交互器和可交互对象

技能	用途	关键参数
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	列出场景中的所有可交互对象	无

移动和 XR UI

技能	用途	关键参数
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

反馈和筛选

技能	用途	关键参数
xr_configure_haptics	设置悬停／选择时的振动	name、强度、时长
xr_add_interaction_event	将交互回调连接到目标方法	name、eventType、targetName、targetMethod
xr_configure_interaction_layers	设置 InteractionLayerMask	name、layers、isInteractor

快速开始

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")

工作流概要

Rig 设置

1. 运行 xr_check_setup。
2. 使用 xr_setup_rig 创建 Rig。
3. 使用 xr_setup_event_system 确保 XR UI 输入已就绪。
4. 为每个控制器至少添加一个交互器。

抓取设置

• 直接手部抓取：xr_add_direct_interactor + xr_add_grab_interactable
• 远距离抓取：xr_add_ray_interactor + xr_add_grab_interactable
• 插槽放置：xr_add_socket_interactor + 可抓取对象

movementType 的默认值很重要：

• VelocityTracking：最适合通用物理抓取
• Kinematic：适用于不应卡住的把手／工具
• Instantaneous：最适合精准的远距离抓取

移动设置

• 传送：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

1. 使用 xr_setup_ui_canvas 转换 Canvas
2. 确保已运行 xr_setup_event_system
3. 在需要点击 UI 的控制器上添加射线交互器

碰撞体配置矩阵

这是此仓库中最重要的 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	点射线投射目标

关键规则：

1. XRGrabInteractable 需要 Rigidbody。
2. 可抓取物体的碰撞体不能是触发器。
3. 直接交互器的碰撞体必须是触发器。
4. 动态网格碰撞体必须为凸面。
5. Socket 碰撞体应仅用作触发器重叠区域。

版本兼容性

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

重要说明

1. 场景通常应当恰好包含一个 XRInteractionManager。
2. 大多数移动技能都假定 XROrigin 已存在。
3. 安装或重新配置软件包可能会触发 Domain Reload。请等待后再重试 XR 调用。
4. 使用 InteractionLayerMask 筛选交互器和可交互对象。
5. 编写自定义 XR 脚本时，尽可能优先使用 XRI 生命周期钩子和事件，而不是通过 Update() 轮询。

最小示例

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)

精确签名

精确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。 在详细配置 XR 组件属性前，请加载 API_REFERENCE.md。XR 属性名称对反射敏感。