导航
“导航”模块允许Inverse3 移动应用程序的 工作区——这有时被称为速率控制移动或“类似手柄的漂移”。 光标在物理工作区边缘不会撞上坚硬的墙壁， 而是进入一个柔性区域，其中光标与虚拟中心的距离会被映射为 一种速度，从而带动整个工作区滑动。光标推得越远， 场景滚动得就越快。
其主要（也是目前唯一的）行为是气泡导航。气泡的形状是通过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 │
└──────────────────────────────────────────┘
| 区域 | 光标位置 | 行为 |
|---|---|---|
| 死区 | 泡沫之中 | 无导航。光线衰减。您可以自由操作场景。 |
| 限速区 | 在表面与外边界之间 | “距离→速度”曲线会将工作区沿光标方向移动。 |
| 墙面区域 | 在越过外围边界 | 一个强力弹簧将光标推回原位，导航速度达到饱和。 |
弹簧阻尼触觉力作用于所有三个区域——你能感觉到 表面、漂移壳体以及外壁。
快速入门——启用气泡导航
导航配置是持久的、一次性配置——只需发送一次，它就会保持活跃状态，直到您明确停止它、重启服务或关闭会话。
开始（简约版——默认带圆角的方框气泡）
WebSocket 示例代码
{
"inverse3": [
{
"device_id": "04C3",
"configure": {
"navigation": { "mode": "bubble" }
}
}
]
}
超文本传输协定
curl -X POST "http://localhost:10001/inverse3/04C3/config/navigation?session=:0" -H "Content-Type: application/json" -d '{"mode": "bubble"}'
停止
WebSocket 示例代码
{
"inverse3": [
{
"device_id": "04C3",
"configure": {
"navigation": { "mode": "disabled" }
}
}
]
}
超文本传输协定
curl -X DELETE "http://localhost:10001/inverse3/04C3/config/navigation?session=:0"
其他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 控制激活时的初始中心位置：
| relative | 《语义学》 position |
|---|---|
| true (默认) | position 是 相对于光标的偏移量 — 初始中心是 cursor + position. 使用默认设置 (0, 0, 0)，气泡会精确地出现在光标位置。 |
| false | position 是 应用空间中的绝对点 — 它在进入时被转换为挂载空间，在退出时又被转换回应用程序空间，因此往返的数值保持一致。 |
中心随后如何行动
follow 和 speed 在气泡激活后控制每次帧的行为：
| follow | speed | 行为 | 之前的等效内容 |
|---|---|---|---|
| false (默认) | 被忽略 | 中心保持在初始化时的位置——固定中心。 | center_mode: 'fixed' |
| true | > 0 | 中心向光标方向偏移 speed 当光标位于其中时，按 m/s 键。 | center_mode: 'auto_follow' （附 center_drift_speed) |
| true | 0.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_width | 0.03 m | 速控壳的厚度 |
| max_velocity | 0.5 m/s | 最大航行速度 |
| velocity_ease | quadratic_in | 距离 → 速度缓动曲线 |
| center.follow | false | 中心是否跟踪光标 |
| center.speed | 0.02 m/s | 漂移速率当 follow = true |
完整参数列表
| 现场 | 类型 | 默认 | 说明 |
|---|---|---|---|
| center.position | vec3 | (0, 0, 0) | 初始中心 — 光标偏移量当 relative = true, 应用程序空间中的绝对坐标点，当 false |
| center.relative | bool | true | true: position 是相对于光标的偏移量。 false：绝对应用空间坐标，转换为边界处的挂载空间坐标 |
| center.follow | bool | false | false: 中心保持在初始位置。 true: 将光标居中 |
| center.speed | float | 0.02 | 漂移速度（米/秒）当 follow = true; 0.0 每帧自动对齐光标 |
| shape | 形状 | {rounded_box, r=0.01, b=(0.05,0.02,0.03)} | 死区 SDF 形状 |
| velocity_zone_width | float | 0.03 | 流量控制壳体的宽度（米） |
| max_velocity | float | 0.5 | 最大航行速度（米/秒） |
| velocity_ease | string | "quadratic_in" | 距离 → 速度缓动 |
| reset_velocity_on_entry | bool | true | 当光标再次进入速度区域时，将累积速度归零 |
| bump_width | float | 0.005 | 表面凸起（米） |
| bump_stiffness | float | 200.0 | 表面凸起弹簧常数 |
| spring_inner | float | 0.0 | 气泡中心的弹簧常数 |
| spring_surface | float | 10.0 | 地表的春天常数 |
| spring_outer | float | 15.0 | 外缘的春天常数 |
| wall_stiffness | float | 700.0 | 硬壁弹簧越过外边界 |
| damping_inner | float | 0.1 | 中心处的阻尼 |
| damping_surface | float | 4.0 | 表面阻尼 |
| damping_outer | float | 7.0 | 外边界处的阻尼 |
| rotation_enabled | bool | false | 将工作空间旋转应用于导航方向 |
| scale_enabled | bool | false | 将工作区缩放比例应用于导航速度 |
| collision_detection.enabled | bool | true | 在碰撞方向上阻挡导航 |
| collision_detection.force_threshold | float | 1.0 | 进入碰撞所需的外部力大小（N） |
| collision_detection.inflate_ratio | float | 2.0 | 碰撞期间速度区域宽度的倍数（必须≥1.0） |
| collision_detection.exit_ratio | float | 0.7 | 滞后比 — 保持碰撞状态直至 |ext_force| < force_threshold × exit_ratio. 范围 (0, 1]; 1.0 禁用滞后效应 |
在 3.5 中隐藏的字段
3.5 版 JSON 模式中省略了两个功能组，而其实现方案在 3.6 版中进行了调整：
- 化身边界钳位：字段 avatar_boundary_enabled, avatar_boundary和 avatar_boundary_hysteresis.
- 工作区边界：字段 workspace_bounded, workspace_transition_speed和 workspace_transition_ease.
使用默认设置时，Tick 代码仍可编译并运行，但客户端无法通过 HTTP 或 WebSocket 读取或写入这些字段。在 3.6 版本中，头像边界将作为顶级 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
A POST 或 configure.navigation 包含无效参数的请求将被拒绝，并返回一个 invalid-value 事件被触发；之前的配置仍保持有效。
活动
| 活动名称 | 何时被解雇 |
|---|---|
| navigation-started | 设备上已启用导航功能 |
| navigation-updated | 导航配置在已激活状态下被更新 |
| navigation-stopped | 导航已停止（显式禁用， DELETE（或会话结束） |
| invalid-value | 导航配置在验证过程中被拒绝 |
已知限制
- 在 3.5 版本中，工作区边界和虚拟角色边界已被隐藏：这两个功能组在 JSON 模式中均不存在，但在 3.6 版本中已重新设计。请参阅上文“参数参考”部分中的说明。
- 非均匀缩放 + 旋转: 当两者都 rotation_enabled 和 scale_enabled 启用时，速度方向会略有偏差——坐标轴未应用旋转。
- 按设备调整大小：气泡大小（半径、区域宽度）不会根据设备的物理缩放比例进行调整MInverse Inverse3 相同的绝对尺寸，因此在不同设备上显示效果可能有所不同。