跳过至主要内容

导航

使用导航模块，Inverse3 ，您可以通过光标在应用程序的工作区中移动。这有时也被称为“速率控制移动”或“游戏手柄式漂移”。 光标在到达物理工作区边缘时，不会撞上坚硬的墙壁，而是进入一个“软壳”区域——该区域内，光标与虚拟中心的距离会被转换为推动整个工作区滑动的速度。 光标被推得越远，场景滚动得就越快。

目前主要（也是唯一）的支持功能是“气泡导航”（Bubble Navigation）。气泡的形状 使用 SDF 基元来定义。关于相关概念， 请参阅“什么是 SDF？”。

气泡导航 — 概述​

虚拟气泡以设备安装空间内的中心点为基准进行定位。 光标将经过以下三个同心圆区域：

┌──────────────────────────────────────────┐
│              WALL ZONE                   │  cursor beyond outer shell
│  ┌────────────────────────────────────┐  │
│  │         VELOCITY ZONE              │  │  soft shell → scene moves
│  │  ┌──────────────────────────────┐  │  │
│  │  │       DEAD ZONE (inside)     │  │  │  no scene movement
│  │  │                              │  │  │
│  │  │         ● centre             │  │  │
│  │  │                              │  │  │
│  │  └──────────────────────────────┘  │  │
│  │       bubble surface               │  │
│  └────────────────────────────────────┘  │
│       outer boundary                     │
└──────────────────────────────────────────┘
区域光标位置动作
死区（不感带）泡沫的内部不会进行导航。会施加轻微的阻尼。您可以自由操作场景。
限速区表面与外侧边界之间根据从距离到速度的曲线，工作区将朝光标方向移动。
壁区位于外侧边界之外的位置硬弹簧将光标向内推回，导航速度达到上限后便不再增加。

在所有三个区域中，弹簧-减震器式的触觉力都在起作用，您可以感受到表面、漂移壳体以及外侧壁。

快速入门 — 启用气泡导航​

导航设置为永久性的一次性设置。一旦发送，该设置将保持有效，直到您明确停止该设置、重新启动服务或关闭会话为止。

开始（最小配置 — 默认的圆角矩形气泡）​

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": { "mode": "bubble" }
      }
    }
  ]
}

停止​

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": { "mode": "disabled" }
      }
    }
  ]
}

其他 HTTP 端点​

方法通关用途
GET/{type}/{id}/config/navigation?session=<expr>当前的导航设置和状态
POST/{type}/{id}/config/navigation?session=<expr>开始或更新导航
DELETE/{type}/{id}/config/navigation?session=<expr>停止导航

气泡形状一览​

气泡的“死区”（不敏感区）由带符号距离函数（SDF）的形状来定义。 不同的形状会带来不同的导航手感。舒适的矩形静止区应使用圆角矩形（默认）；各向同性的漂移应使用球体；优先特定轴向的情况应使用椭球体；通道则应使用胶囊。

圆角框（默认）​

默认的死区是一个平坦的、高度略大于深度的体积。它经过调整，旨在让玩家在Inverse3 和MInverse 两种模式下都能感到舒适：

{
  "shape": {
    "primitive": "rounded_box",
    "parameters": { "b": { "x": 0.05, "y": 0.02, "z": 0.03 }, "r": 0.01 }
  }
}

球——等方性漂移​

{
  "shape": {
    "primitive": "sphere",
    "parameters": { "r": 0.05 }
  }
}

椭圆体 — X/Z 方向比 Y 方向更宽​

当希望水平方向的漂移感觉比垂直方向更平缓时，请使用此设置：

{
  "shape": {
    "primitive": "ellipsoid",
    "parameters": { "a": { "x": 0.06, "y": 0.03, "z": 0.06 } }
  }
}

胶囊 — 狭长的通道​

两个端点 a/b 和半径 r 指定：

{
  "shape": {
    "primitive": "capsule",
    "parameters": {
      "a": { "x": 0.0, "y": -0.03, "z": 0.0 },
      "b": { "x": 0.0, "y": 0.03, "z": 0.0 },
      "r": 0.04
    }
  }
}

一个关于自定义尺寸和动作手感的完整示例：

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": {
          "mode": "bubble",
          "bubble": {
            "shape": {
              "primitive": "ellipsoid",
              "parameters": { "a": { "x": 0.06, "y": 0.03, "z": 0.06 } }
            },
            "velocity_zone_width": 0.025,
            "max_velocity": 1.0,
            "velocity_ease": "quadratic_in"
          }
        }
      }
    }
  ]
}

速度曲线​

速度区域的距离在转换为工作区速度之前，会先通过缓动曲线进行映射。请根据用户向壳体内部按压时希望场景以何种方式加速，选择相应的缓动曲线。

velocity_ease感悟适用场景
linear一定的坡度易于预测，适合作为标准选项
quadratic_in起始阶段较为平缓，随后推进速度较快在表面附近进行精密操作，长距离移动则高速进行
cubic_in上升趋势非常缓慢精度极高，长距离移动时会逐渐加速
sine_out起速平顺且迅速，在外侧附近达到极限响应迅速，且平稳地达到上限
quadratic_out起步迅猛，长途行驶也舒适敏捷的微调、舒适的巡航
{ "velocity_ease": "quadratic_in", "max_velocity": 1.5 }

中心的运作​

泡沫的中心呈嵌套状 center 通过对象进行设置。该对象包含四个字段—— position、relative、follow、speed — 拥有，以前的 center、center_enabled、center_mode、center_drift_speed 这是对由……构成的扁平化布局的一种替代方案。

{
  "center": {
    "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
    "relative": true,
    "follow":   false,
    "speed":    0.02
  }
}

中心的基准位置​

position 和 relative 用于控制启用时的中心初始位置：

relativeposition 的意思
true（默认）position 是 相对于光标的偏移量 是。早期的核心是 cursor + position 将变为。默认的 (0, 0, 0) 在这种情况下，气泡会正好生成在光标所在的位置。
falseposition 是 应用程序空间中的绝对点 。由于在输入时会被转换为挂载空间，在输出时又会转换回应用程序空间，因此往返的值是相同的。

该中心此后的动向​

气泡生效后，每帧的操作是 follow 和 speed 由……控制：

followspeed动作传统等效设置
false（默认）无视中心将保持在初始化位置——即固定中心。center_mode: "fixed"
true> 0当光标位于内部时，中心是 speed 以 m/s 为单位，向光标方向漂移。center_mode: "auto_follow"（center_drift_speed （使用）
true0.0中心会随着每次点击自动对准光标——感觉就像是瞬间传送一样。center_mode: "track_cursor"
在 3.5 版本中，默认设置发生了变化

默认的中心行为目前是 固定（follow = false）です。在以前的版本中，默认情况下光标会朝该方向漂移（auto_follow）。若要恢复到旧的漂移操作， center.follow = true 设置为，center.speed 与之前的 center_drift_speed 请根据该值进行调整。

follow = true 当光标处于该状态并超出外侧边界时，speed 无论该值为何，中心都会跟随光标移动。这样，气泡就会始终停留在光标周围，从而防止光标向外移出。

冲突时的响应​

泡沫是，collision_detection.force_threshold 会对超过该值的来自外部的光标力作出反应：

  • 限速区将暂时 膨胀 将（最多 collision_detection.inflate_ratio 倍的 velocity_zone_width （……）。这样，用户就能有足够的余地来避开障碍物。
  • collision_detection.enabled 但 true（默认）情况下，气泡中心不会沿碰撞力的方向漂移。 这样可以防止用户将工作区拖入坚硬的墙壁中。

在冲突检测中，为了避免阈值附近出现闪烁， 滞后 使用： 一旦冲突生效，|ext_force| が积 collision_detection.force_threshold × collision_detection.exit_ratio 该状态将持续有效，直至低于该数值为止。 exit_ratio 当该值减小时，滞后带的宽度会增大（碰撞状态更容易持续），1.0 若将该选项设置为，即可禁用迟滞并使用单一阈值。

{
  "collision_detection": {
    "enabled":         true,
    "force_threshold": 0.5,
    "inflate_ratio":   2.0,
    "exit_ratio":      0.7
  }
}

参数参考​

常被调整的参数​

参数默认说明
shape{rounded_box, r=0.01, b=(0.05,0.02,0.03)}定义死区的SDF形状
velocity_zone_width0.03 m流量控制壳体的厚度
max_velocity0.5 m/s导航的最高速度
velocity_ease"quadratic_in"从距离到速度的缓和曲线
center.followfalse中心是否跟随光标移动
center.speed0.02 m/sfollow = true 时的漂移速度

所有参数列表​

字段型预设值说明
center.positionvec3(0, 0, 0)初期中心 — relative = true 此时为相对于光标的偏移量，false 此时为应用空间的绝对坐标
center.relativebooltruetrue: position 是相对于光标的偏移量。false: 以应用空间的绝对坐标表示，在边界处转换为挂载空间
center.followboolfalsefalse: 中心将保持在初始化位置不变。true: 中心会跟随光标移动
center.speedfloat0.02follow = true 时的跟随速度（m/s）。0.0 在这种情况下，会每 tick 一次将光标定位到该位置
shape形状{rounded_box, r=0.01, b=(0.05,0.02,0.03)}“死区” SDF 格式
velocity_zone_widthfloat0.03速度控制壳体的宽度（米）
max_velocityfloat0.5导航最大速度（m/s）
velocity_ease字符串"quadratic_in"从距离到速度的缓入效果
reset_velocity_on_entrybooltrue当光标再次进入限速区时，将累计速度清零
bump_widthfloat0.005表面触觉凸起（m）
bump_stiffnessfloat200.0表面凸点的弹簧常数
spring_innerfloat0.0气泡中心的弹簧
spring_surfacefloat10.0表面弹簧
spring_outerfloat15.0外侧边界的弹簧
wall_stiffnessfloat700.0用于跨越外侧边界后的硬壁的弹簧
damping_innerfloat0.1中心阻尼
damping_surfacefloat4.0表面阻尼
damping_outerfloat7.0外侧边界的阻尼
rotation_enabledboolfalse将工作区旋转应用于导航方向
scale_enabledboolfalse将工作区的缩放比例应用于导航速度
collision_detection.enabledbooltrue阻止向冲突方向导航
collision_detection.force_thresholdfloat1.0进入碰撞所需的外力大小（N）
collision_detection.inflate_ratiofloat2.0针对冲突中速度区宽度的乘数（必须大于等于1.0）
collision_detection.exit_ratiofloat0.7滞后比。|ext_force| < force_threshold × exit_ratio 将保持冲突状态，直到……为止。范围为 (0, 1]。1.0 以禁用磁滞效应
3.5 中隐藏的字段

在针对 3.6 版本重新设计实现期间，以下两个功能组已被从 3.5 版的 JSON 模式中移除：

  • 《阿凡达：边界》的夹具: avatar_boundary_enabled、avatar_boundary、avatar_boundary_hysteresis 的各个字段。
  • 工作区的边界: workspace_bounded、workspace_transition_speed、workspace_transition_ease 的各个字段。

tick 处理代码仍会继续编译并使用默认值执行，但客户端无法通过 HTTP 或 WebSocket 读写这些字段。在 3.6 版本中，化身边界与具有完整布局变换的 bubble 对象处于同一层级的顶级 bounds 预计将恢复该功能。工作区的边界限制功能预计将在完成中心抖动调查后恢复。

验证规则​

  • velocity_zone_width > 0
  • 0 ≤ bump_width < velocity_zone_width
  • max_velocity > 0
  • bump_stiffness ≥ 0
  • spring_inner ≥ 0 而且 spring_inner ≤ spring_surface ≤ spring_outer
  • wall_stiffness ≥ 0
  • damping_inner ≥ 0 而且 damping_inner ≤ damping_surface ≤ damping_outer
  • collision_detection.force_threshold > 0
  • collision_detection.inflate_ratio ≥ 1.0
  • collision_detection.exit_ratio 但 (0, 1] 范围内
  • center.speed ≥ 0

指定了无效的参数 POST 或者 configure.navigation 被拒绝，invalid-value 将触发该事件。之前的设置仍保持有效。

活动​

活动名称点火时机
navigation-started当设备启用了导航功能时
navigation-updated当导航功能已启用且设置被更新时
navigation-stopped当导航被停止时（显式禁用、DELETE、或会话结束）
invalid-value当导航设置在验证过程中被拒绝时

已知的限制事项​

  • 3.5 中隐藏的工作区边界和虚拟形象边界：虽然这两个功能组正在为 3.6 版本进行重新设计，但它们未包含在 JSON 模式中。请参阅上述参数参考中的注释。
  • 非均匀尺度 + 旋转: rotation_enabled 和 scale_enabled 当两者均启用时，速度方向会略有偏差。旋转不会应用于缩放轴。
  • 按设备调整大小：气泡的大小（半径、区域宽度）不会根据设备的物理缩放系数进行调整。由于MInverse 和Inverse3 使用相同的绝对尺寸，因此在不同设备上的显示效果可能会有所不同。