它是什么

NearFarInteractor 是一种同时使用近距离交互探测器和远距离交互探测器的 Interactor，在近距和远距之间做平滑切换，并把远距探测数据用来与 UGUI 交互。

设计上强调模块化和可扩展性。高级开发者可以自定义近距 / 远距探测器（分别实现 IInteractionCaster 和 ICurveInteractionCaster），以及自定义附着控制器 IInteractionAttachController。

一句话定位：

NearFarInteractor 不是那条"可见的线"，而是一整套"近距 + 远距 + UI + 附着控制"的交互总控。线的视觉通常由 CurveVisualController + LineRenderer 负责。

目前两个需要注意的能力缺口：

  • AR 设备的 AR 数据射线仍需要 XRRayInteractor，NearFarInteractor 暂不支持这个用例。
  • 官方文档写 NearFarInteractor 不支持用摇杆直接控制 attach transform——但 Starter Assets 3.4.x 中实际把操控能力下沉到了 InteractionAttachController，所以从工程实践仍可通过预制件实现远距离操控。

关键属性

属性作用实践建议
Interaction Manager通信的 XR Interaction Manager留空，让系统自动找
Interaction Layer Mask只允许与重叠层 Interactable 交互XR 自己的层，不是 Unity 物理 Layer
Select Action Trigger扳机如何触发选中（按住 / 切换 / 粘性）抓取类用 State，按钮类用 Toggle
Keep Selected Target Valid首次选中后是否保持选中抓取物体建议 true，传送建议 false
Allow Hovered Activate未选中时悬停是否触发 Activate次级动作开关，默认即可
Target Priority Mode追踪目标数量（性能排序）做复杂反馈时再调
Interaction Attach Controller附着控制器（手感）见下方"相关组件"
Enable Near Casting是否启用近距离探测首页可关；质量评价场景建议开
Enable Far Casting是否启用远距离探测首页与质量评价都需要
Enable UI Interaction是否允许点击 World Space UI要做 UI 交互必须开
UI Press Input点击 UI 按钮的输入绑定到扳机或 Grip
Far Attach Mode远距选中的附着模式（Near / Far）点云实验建议 Far

三个枚举

Region

由 selectionRegion 使用，表示当前选择发生在哪个区域：

  • None：当前没有选中。
  • Near：近距离选中。
  • Far：远距离选中。

做不同提示效果时这个状态很有用。

NearCasterSortingStrategy

近距探测发现多个候选目标时如何排序：

  • None：不排序。
  • SquareDistance：按 Interactor 与 Interactable 附着点的平方距离排序，性能最好。
  • InteractableBased：由 Interactable 自身策略排序。
  • ClosestPointOnCollider：按 Interactor 附着点与 Collider 最近点的平方距离排序，最精确。

InteractorFarAttachMode

远距选中时如何调整 attach transform：

  • Near：把 attach transform 重置到近处点位。物体被拉到手边。
  • Far：把 attach transform 移到远处命中点。物体留在原位，可远程操控。

实现了 IFarAttachProvider 的 XRGrabInteractable 可覆盖 Interactor 默认行为。对点云实验这类"展示而非抓物"场景，Far 通常更合适——避免模型突然飞到用户脸前。

InteractionAttachController

附着点运动规则执行器——决定"远距选中后物体的手感"：稳定、平滑、推拉、旋转、距离速度缩放。详情见《InteractionAttachController 中文注释版》。

CurveInteractionCaster

远距离探测器。真正把远程射线/曲线打出去，看打中了什么。支持 Raycast、SphereCast、ConeCast。Starter Assets 里通常配合柔和的交互曲线，不是死直的激光。

SphereInteractionCaster

近距离探测器。在手附近做球形检测，判断是否碰到附近可交互物体。"手靠近就抓"的体验靠它。

CurveVisualController

可视化控制器，只负责把线画好看。它根据命中状态、UI 状态、选中状态动态切换颜色、宽度、弯曲程度。

线在但点不到？先检查 NearFarInteractor / CurveInteractionCaster / Canvas / 输入动作，不要先去怪 CurveVisualController。

XR UI 链路

要让 XR 控制器与 Unity UI 正常交互，四条同时满足：

  1. Canvas.RenderMode = World Space（Screen Space - Overlay 不会按预期工作）
  2. Canvas 上挂 TrackedDeviceGraphicRaycaster（必须与 Canvas 同物体）
  3. 场景里有 EventSystem + XRUIInputModule（不要混用旧 StandaloneInputModule）
  4. NearFarInteractor.Enable UI Interaction = true 且 UI Press Input 绑定

场景配置建议

场景推荐配置
Home（首页）Enable UI Interaction = true，Enable Far Casting = true，近距可关；Canvas 用 World Space + TrackedDeviceGraphicRaycaster
质量评价Near Casting + Far Casting 都开；Far Attach Mode = Far；模型根对象有 Collider + XRGrabInteractable
JND沿用质量评价配置；优先保证 UI 点击与远距稳定选中

常见坑

  • 把 XR 交互层和 Unity 物理层混为一谈：射线碰到 Collider 但选不中 → 通常是 Interaction Layer Mask 不匹配；对象挂了 XRGrabInteractable 但射线像穿过去 → 物理 Raycast Mask 没包含该 Layer。
  • 只有线没有交互：可能 Canvas 不是 World Space、少了 TrackedDeviceGraphicRaycaster、没装 XRUIInputModule、Enable UI Interaction 未开启。
  • 3D 模型点不到：模型没 Collider、根对象没挂 XRGrabInteractable、Interaction Layer Mask 不匹配。
  • 远距抓取体验不对：物体突然飞到脸上 / 抖动 / 推拉肉 → 检查 Far Attach Mode 和 InteractionAttachController。

参考资料