跳转至正文

导航

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

默认（目前唯一的）操作是气泡导航。气泡的形状使用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>停止导航

气泡形状列表​

气泡的“死区”以带符号距离函数（signed-distance-function，SDF）的形式定义。 根据形状的不同，导航的体验也会有所不同。在舒适的矩形休止区域中使用圆角矩形（默认值）；在各向同性漂移中使用球体（sphere）；若需优先考虑特定轴，则使用椭球体（ellipsoid）；在通道中则使用胶囊（capsule）。

圆角矩形（默认值）​

默认死区是一个略高于深度、形状略扁平的区域，经过调整后可在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"
          }
        }
      }
    }
  ]
}

速度曲线​

速度范围距离经由缓动（easing）曲线映射后，将转换为工作区速度。请根据用户向壳体内部推得越深时，希望场景如何加速的情况，选择相应的缓动曲线。

velocity_ease感觉使用时机
linear稳定增长可预测且稳妥的默认值
quadratic_in慢热，快攻在靠近地表时精度高，长距离移动速度快
cubic_in开局非常缓慢精度极高，长距离移动时会逐渐加速
sine_out起始阶段柔和而迅猛，在接近外围时逐渐平缓反应迅速，且上限会逐渐触发
quadratic_out起步迅猛，长途驾驶舒适快速微调，舒适巡航
{ "velocity_ease": "quadratic_in", "max_velocity": 1.5 }

核心动作​

气泡的中心由四个区域（position, relative, follow, speed由……组成的嵌套结构 center 通过对象进行设置。这是 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用于控制每个 tick 的操作：

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会对超过该值的外部向心力作出反应：

  • 速度区间暂时 膨胀합니다（最大 velocity_zone_width的 collision_detection.inflate_ratio（直到腹部）。 这样一来，用户在障碍物周围进行操作的余地就更大了。
  • collision_detection.enableda 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速率控制（rate-control）壳体的厚度
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当光标再次进入速度区域时，将累积速度重置为0
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 版本中，Avatar 边界与 Bubble 对象同级，属于顶级 bounds 将作为项目重新提供，并具有完整的布局变换（placement transform）。工作区边界将在中心抖动（centre-jitter）调查完成后重新提供。

验证规则​

  • 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 使用相同的绝对大小，因此在不同设备上可能呈现出不同的视觉效果。