追踪的偏移方式。选择 Unbond 和 Device 时，下方出现 YOffsetValue，可手动输入数据；选择 Floor 时YoffsetValue 隐藏。如果选择为 Floor，且设备开启了安全边界，则以设备离地面高度作为当前视角高度（暂时只支持 quest2 ）；如果选择为Device，则偏移的高度为输入的高度。

YOffset Value

设备数值偏移量。手动输入偏移的值，米为单位，默认为1.36144m。如果为固定值，则OffsetObject选中的对象Transform属性的Y值为当前填入的值。

HMDCtrl

HMD（Head Mounted Display）头戴显示设备控制器，可以认为所有具备双目立体绘图能力的XR眼镜设备都属于HMD的大范畴，因此此组件定义了XR眼镜的图像渲染输出相关参数。

属性

说明

Per Eye Camera

开启单眼显示功能；勾选 PerEyeCamera 后下方出现 Sync With Main Camera 选项；XR HMD 下的两个子节点 LeftEye 和 RightEye 由隐藏变为显示

IPDOffset

调整瞳间距。下拉列表中选择 Manual 时下方出现 OffsetValue 输入框；在 PerEyeCamera 开启的情况下，调整 Manual 的参数可让 LeftEye 和 RightEye 的 TransForm 属性 X 值变化（变化的值为 ±IPDOffset/2）

PoseTracker

位姿追踪组件。

属性

说明

Tracking Source

选择需要追踪的设备源

Tracking Type

追踪模式。选择 POSITION_AND_ROTATION 时追踪设备的平移 + 旋转；选择 POSITION 时只追踪平移的量；选择 ROTATION 时只追踪旋转的量。

TargetEye

指定接受渲染相机的组件。

属性

说明

Target Eye

指定渲染的目镜。Both 为左右眼都显示，left 为左眼，right 为右眼。

XRController

控制器抽象组件。

属性

说明

InputDevice

绑定输入手柄设备。

SelectAction

将 Select 行为映射到手柄的对应实体按键

ActivateAction

将 Activate 行为映射到手柄的对应实体按键

UIPressAction

将交互 UI 行为映射到手柄的对应实体按键

AxisToPressThreshold

行为触发时的阈值

Model

用于指定手柄的模型对象。

ARCameraMgr

移动端手持设备摄像头AR属性

属性

说明

Auto Focus

开启或关闭相机自动对焦功能。关闭时，使用固定对焦模式。自动对焦功能是否可用取决于设备相机。

Light Estimate（实验性）

开启后，运行时估计环境光各项属性并实时调整场景光照，让虚拟物体具有与真实场景相同的光照效果（光照一致性）。

交互组件

一次交互操作需要有两种对象协调完成：交互主体和被交互物，对应的交互组件由此也分为两类：Interactor（交互器）和 Interactable（可交互对象）。

RayInteractor

射线交互器组件。

属性

说明

AttachTransform

用此 AttachTransform 的位置作为抓取的物体最终落到的位置，如果为空就用当前 Interactor 的位置

ForceGrab

远距离抓起；开启时被抓对象吸附到 Attach Transform、关闭后抓取挂载在交互点的位置

RayOriginTransform

可以改变发出 Ray 的起始位置，为空就默认是当前 Interactor 的位置

LineType

改变射线检测和射线样式；StraightLine 是直线；Projectile Line 是抛物线；Bezier Line 是贝塞尔曲线

MaxRayDistance

射线交互可以触发的最远距离

ReferenceNode

LineType为ProjectileLine和BezierLine时出现此项。用曲线的参考系来定义地平面和向上向量。如果在启动时没有设置，它将尝试找到XR Agent，如果没有引用，它将默认使用全局的上向量和原点。

Velocity

LineType为ProjectileLine时出现此项。初始速度。增加这个值将使曲线延伸的更远。

Acceleration

LineType为ProjectileLine时出现此项。重力加速度。

Additional Ground Height

LineType为ProjectileLine时出现此项。在地平面以下的额外高度，射线超过地平线会继续向下投射。增加这个值将使终点的位置高度下降。

Additional Flight Time

LineType为ProjectileLine时出现此项。在落地后的额外飞行时间，射线超过地平线会继续向下投射。增加这个值将使投射的飞行时间延长。

End Point Distance

LineType为BezierLine时出现此项。增加这个值的距离会使曲线的末端离起始点更远。

End Point Height

LineType为BezierLine时出现此项。降低这个值将使曲线的末端相对于起点下降得更低。

Control Point Distance

LineType为BezierLine时出现此项。增加这个值将使曲线的峰值离起点更远。

Control Point Height

LineType为BezierLine时出现此项。增加这个值将使曲线的峰值相对于起点更高。

Sample Frequency

LineType为ProjectileLine和BezierLine时出现此项。用于近似曲线路径的采样点的数目。数目越多近似效果越好，但性能越低。

RaycastMask

只能和此 Layer 类型的交互物发生交互

SelectActionTrigger

Select 行为触发机制，详情见交互功能介绍

注：抛物线和贝塞尔曲线的功能需要扩展版本>=v1.1.0，编辑器版本>=3.7.1。

DirectInteractor

直接交互器组件。

属性

说明

AttachTransform

用此 AttachTransform 的位置作为抓取的物体最终落到的位置，如果为空就用当前 Interactor 的位置

SelectActionTrigger

Select 行为触发机制，详情见交互功能介绍

XRGazeInteractor

属性

说明

Gaze Pointer Offset

凝视点竖直方向偏移（单位米）

Max Ray Distance

射线最远投射距离（单位米）

Gaze Default Distance

凝视点UI默认距离（单位米）

Gaze Timer Duration

凝视交互触发时间（单位秒）

Gaze Reticle Outer Ring

凝视点外环UI

注：此功能需要扩展版本>=v1.1.0，编辑器版本>=3.7.1。

ScreenTouchInteractor

屏幕手势交互器

行为

属性

说明

Select Action

选择行为相关配置

Gesture

允许用户操作虚拟物体的可选收拾类型。

Double Tap Gap

Gesture选择为DoubleTap时出现此项，当两次点击的时间间隔小于此值时，判定为双击

Hold Touch Duration

Gesture选择为HoldTouch时出现此项，当触碰屏幕时间大于此值时，判定为长按

Move Action

移动行为相关配置

Gesture

绑定移动行为的手势

Rotate Action

旋转行为相关配置

Gesture

绑定旋转行为的手势

Drag Degree

Gesture选择为2FingersDrag时出现此项，双指拖动速率

Twist Degree

Gesture选择为2FingersRotate时出现此项，双指旋转速率

Scale Action

放缩行为相关配置

Gesture

绑定放缩行为的手势

Sensitivity

放缩的灵敏度

Place Action

放置行为相关配置

Gesture

绑定放置行为的手势

Calculation Mode

当将物体放置在AR表面时，用于计算命中点位置的方法。

Placement Prefab

引用挂载Placeable组件的预置体

GrabInteractable

可抓取交互对象组件。

属性

说明

AttachTransform

用此 AttachTransform 的位置作为触碰点的位置，如果为空就用当前 node 的位置

AttachEaseInTime

对象被抓取到 AttachTransform 位置过程的时间（在该时间内，被抓取对象会有一个拖尾的效果，持续时间越久效果越不明显）

GrabTrigger

两种方式用于触发抓取：当 Select 的行为触发时/当 Activate 行为触发时

RayReticle

当交互器与此交互物发生交互碰撞计算时，在碰撞点会显示此属性所引用的对象

HideController

开启时，此物体被抓取后会隐藏 XR Controller 所引用的 Model

ThrowOnDetach

开启后，允许模拟抛物的动作。

ThrowSimulationMode

选择为 InheritRigidbody 时，物体抛出时继承刚体的速度；选择为 CurveComputation 时，出现下列两项ThrowSmoothingDuration、ThrowSmoothingCurve，允许自定义抛出速度的计算

ThrowSmoothingDuration

速度计算的采样时间段。使用此值作为采样区间，用于计算物体被抛出前的速度的加权平均值，作为物体抛出时的初速度

ThrowSmoothingCurve

速度采样曲线。根据绘制的曲线进行抛出时初速度的加权平均值计算

ThrowVelocityScale

初速度的权重系数。权重越大，抛物瞬时速度所乘的系数也越大，在继承或者加权计算出的初速度基础上乘以一个系数

ThrowAngularVelocityScale

初角速度的权重系数。权重越大，抛物瞬时角速度所乘的系数也越大，在继承或者加权计算出的初始角速度基础上乘以一个系数

Teleportable

可传送对象组件。

属性

说明

TeleportableType

传送点的类型。选择为Area时，传送到射线与传送区域交互点的位置；选择为 Anchor 时，不受射线与传送区域的交互点的限制，之间传送到区域的固定位置。

Teleport Anchor Node

TeleportableType 选择为 Anchor 时出现此项，用于标定传送的落点。此项为空时传送到传送区域的默认中心区域；此项引用了其他对象就传送到引用的对象的位置

RayReticle

当交互器与此交互物发生交互碰撞计算时，在碰撞点会显示此属性所引用的对象

TeleportTrigger

触发传送行为的事件：OnSelectExited 表示 Select 行为结束的时刻（按钮抬起）执行传送；OnSelectEntered 表示Select触发的时刻（按钮按下）

Teleporter

指定需要被传送的主体（一般为XR Agent），主体需挂载 Teleporter

Selectable

挂载此组件的对象可以被选中，且可以在选中状态下发生位移、旋转或放缩行为。

属性

说明

Allowed Actions

选择此对象后允许进行的操作。

Selection Events

选择行为的回调，它将在特定事件发生时被触发。

Selected Visualization

对象被选中时将激活的可视化效果。

Placeable

挂载此组件的对象可以使用某种方式放置于空间、AR Plane或AR Mesh上。

属性

说明

Preview Placement Prefab

在放置物生成之前要放置的预放置对象。

Placement Offset

偏移由交互器放置的预制件的位置。

Placement Events

放置行为的回调，它将在特定事件发生时被触发。

事件

在项目开发过程中用户会遇到很多依赖于 XR 组件的信号来触发的逻辑。为了方便用户专注于逻辑开发而不用关心两者之间的通知关系，Cocos CreatorXR 基于传统的事件系统在一部分常被事件依赖的交互组件中封装好了一部分事件信号，用户只需要在特定的信号上绑定一系列想要触发的对象和方法即可。

事件信号

事件信号分为以下三种：

● Hover：指的是 XR 的输入设备的射线覆盖到物体上时触发

● Select：当在输入设备上按下 Select 映射的按键时触发

● Active：当在输入设备上按下 Active 映射的按键时触发

其交互行为描述如下：

交互行为

事件信号

说明

Hover

OnHoverEntered

Hover 行为执行的时刻

OnHoverExited

Hover 行为退出的时刻

OnHoverCanceled

Hover 行为取消的时刻

Select

OnSelectEntered

Select 行为执行的时刻

OnSelectExited

Select 行为退出的时刻

OnSelectCanceled

Select 行为取消的时刻

Active

OnActivated

激活的时刻

OnDeactivated

取消激活的时刻

这些事件信号，可以在下列组件中选择，用于处理特定情形下的输入状态。

交互事件组件

交互组件分为：

● InteractorEvents：交互器事件组件。

● InteractableEvents：可交互对象事件组件。

其属性描述如下：

InteractorEvents

属性

说明

AudioEvents

开启后可以绑定事件触发时播放的音频

HapticEvents

开启后可以绑定事件触发时控制器的震动反馈

InteractorEvents

开启后可以绑定任意回调函数

● Audio Events：

Audio Events 可以根据事件信号选择不同类型的事件触发，触发后可以播放特定的音频。

选中事件信号右侧的单选框可启用/禁用该事件信号，启用后可以通过 AudioClip 属性右侧的下拉菜单选择不同的音频资源。

● Haptic Events（要求扩展版本>=v1.1.0，编辑器版本>=3.7.1）：

选中事件信号右侧的单选框后，可以调整控制器的震动反馈，通过震动可以给与用户更真实的触感反馈。

○ Haptic Intensity：震动的灵敏度 [0,1]

○ Duration：持续的时长

● Interactor Events：

在右侧的输入框内，输入任意整数值，可在 Interactor Events 数组内添加元素。

● 添加完成后，可对事件回调进行配置：

○ Node：回调接收节点

○ 组件：回调组件

○ 方法：回调方法

○ CustomEventData：自定义事件的数据，这些数据会被当做回调方法的参数，传入到上述的回调方法中。

InteractableEvents

该组件的事件使用方式和 InteractorEvents 组件的 Interactor Events 属性类似，也可以通过在右侧输入框修改整数值的方式修改事件的数组的长度，并配置响应的回调。

交互限制组件

对于挂载了Selectable组件的交互物，可以使用交互限制组件限制他的交互效果。

MinMaxScaleConstrain

属性

说明

Min Scale

可被缩小的最小尺寸比例。

Max Scale

可被放大的最大尺寸比例。

RotationAxisConstrain

属性

说明

Axis Flag

限制交互物只能按所选旋转轴进行旋转。屏幕交互器最多只能控制双轴(x,y)旋转。

Use Local Space

是否按本地坐标轴进行旋转。默认关闭，以世界坐标轴做旋转。

虚拟移动组件

在绝大多数的 VR 项目中，用户会用第一人称的角色视角在虚拟场景中进行移动。这种移动行为一般不会依赖于用户在真实空间的移动反馈，因为位姿的追踪会受到现实世界物理空间的限制。因此我们需要一种类似传统 3D 游戏中那种利用接受控制器输入信号的方式来驱动移动行为的组件，称之为虚拟移动组件（Locomotion Component）。

LocomotionChecker

运动检查器。

属性

说明

XR Agent

指定需要进行运动的XR Agent（或其他对象）。添加该组件时，默认绑定遍历当前场景得到的第一个挂载了TrackingOrigin的节点，通常是XR Agent；用户也可以自行指定需要进行locomotion操作的对象

Teleporter

传送驱动组件。

属性

说明

Checker

添加该组件时，默认绑定遍历当前场景得到的第一个挂载Locomotion Checker组件的节点用户也可以自己拖入需要指定的Locomotion Checker

SharpTurner

瞬间转向驱动。

属性

说明

Checker

添加该组件时，默认绑定遍历当前场景得到的第一个挂载Locomotion Checker组件的节点用户也可以自己拖入需要指定的Locomotion Checker

InputDevice

绑定挂载了XRController的控制器对象

TurnAngle

转动角度

EnableTurnAround

开启后按下摇杆允许旋转180°（点击摇杆的按钮）

ActivationTimeout

执行连续的转弯时需要等待的时间

ContinuousTurner

连续转弯驱动。

属性

说明

Checker

添加该组件时，默认绑定遍历当前场景得到的第一个挂载Locomotion Checker组件的节点用户也可以自己拖入需要指定的Locomotion Checker

InputDevice

绑定挂载了XRController的控制器对象

InputControl

绑定接受输入的摇杆

TurnSpeed

转动的角速度

ContinuousMover

平移运动驱动。

属性

说明

Checker

添加该组件时，默认绑定遍历当前场景得到的第一个挂载Locomotion Checker组件的节点用户也可以自己拖入需要指定的Locomotion Checker

InputDevice

绑定挂载了XRController的控制器对象

InputControl

绑定接受输入的摇杆

MoveSpeed

移动速度

ForwardSource

选择一个物体，用该物体节点的朝向作为移动的正方向

XR UI

传统的生成 UI 控件的方式都是把 UI 画在画布（Canvas）上，而画布本身不具有深度信息(位置属性不可更改)，导致了画布是贴在屏幕上的，只有与屏幕进行交互才能反馈作用于 UI 控件。由于 XR 设备的摄像头是两个目镜，不支持交互，这明显不满足于 XR 项目的需求。所以我们需要将 UI 的交互方式改为在空间中用交互器进行交互，因此需要将 UI 控件剥离出画布而能够单独存在于空间中，具有完整的位置属性并具有碰撞检测功能。

XR UI 是基于 2D UI 扩展而来，关于如何使用 2D/UI 组件可参考 2D 对象概述。

新建 UI

在层级管理器 -> 创建 -> XR -> XR UI 可以添加 XRUI。

相比于传统的 UI 控件，XR UI 会新增一些组件用于计算碰撞检测以触发交互，如图示，RaycastChecker 和 BoxCollider 可使其能够接收 XR 输入：

注意：对于 3D 空间上的 UI，其根节点上需要 RenderRoot2D 组件才可以正常渲染。

存量 UI 转换

如 UI 已制作完成，也参考下面的步骤将原本的 2D Canvas 下的 UI，转化为 XR 的 UI。

方法一：

● 在层级管理器右键创建一个空节点（如命名为 UIRoot，下文均使用 UIRoot），为节点添加组件 RenderRoot2D 组件，同时节点会自动添加 UITransform 组件：

● 将原有的2D UI控件分离出Canvas，移动至UIRoot层级下。修改 Button 位置和 Layer 属性。同时将 Button 及其子节点的 Layer 属性，都修改为和 Camera 的 Layer 属性一致（此处均为DEFAULT）。

● 给 Button 及其子节点添加材质。在资源管理器中点击 xr-plugin -> xr -> res -> default_materials，选择 xr-3dui-sprite-material 拖拽至 Sprite 组件的 CustomMaterial 属性中。

● 给 Button 添加射线交互组件 RaycastChecker。点击 Button 节点，在属性检查器下方，点击添加组件按钮，选择 XR -> UI -> RaycastChecker。

● 在属性检查器中出现 RaycastChecker 组件和 BoxCollider 组件，且 BoxCollider 组件的 Size 属性的 xy 值与节点的 UITransfrom 的 Content Size 值一致，如下图：（此处可以将 BoxCollider 替换为其他所需 3D 碰撞体，能够贴合 UI 组件即可）。