迁移到 3.5

本页是 Inverse Service 3.5 的综合升级指南。它涵盖服务仍然保留的全部弃用项：计划在 4.0 中移除的旧版 3.0 传输格式、已弃用的 HTTP 端点，以及已弃用的会话通道模拟命令。

此处列出的所有弃用项在传输层仍会为向后兼容而被接受。升级不会导致任何故障，请按您方便的时间规划迁移。

---

3.0 与 3.x API 版本

服务同时提供两种并行的 JSON 格式：端口 10000 上的旧版 3.0 格式，以及端口 10001 上的当前 3.x 格式。两者都将为向后兼容而保留，3.0 集成在升级后将继续无需修改地运行。

注意

3.0 API 版本支持将在 4.0 中停止提供。

• 3.0 API

  • 完整文档请参阅 3.0.x 文档页面。
  • HTTP 位于 http://localhost:10000/3.0/。
  • Websockets 位于端口 10000。

• 3.x API

  • 完整文档请参阅 3.x 文档页面。
  • HTTP 位于 http://localhost:10001/。
  • Websockets 位于端口 10001。
  • 功能更完善，并且可以更快速地与游戏引擎集成。

请按您方便的时间升级，不会影响现有工作流程。

---

已弃用的 HTTP 端点

以下端点仍被接受，但会发出弃用警告。它们将在 4.0 中移除，请改用替代路由。

已弃用路径	替代路径
POST /force_scale	POST /settings/devices/force_scale
POST /gravity_compensation	POST /{type}/{id}/config/gravity_compensation
POST /torque_scaling	POST /{type}/{id}/config/torque_scaling
POST /device_handedness	POST /{type}/{id}/config/handedness
POST /serial_enable	POST /settings/system/serial_enable
POST /experimental/features/grip_dropped_simulation_stopper	POST /settings/features/grip_hook/enabled
POST /experimental/features/screensaver_enable	POST /settings/features/screensaver/enabled

每个已弃用的路由都会在事件通道上触发 http-route-deprecated 事件，其中同时包含旧路由及其替代路由。

---

已弃用的会话通道命令

以下两个会话级模拟命令已被弃用，并将在未来的主版本中移除。它们在传输层仍会被接受；新的集成应改用替代列中列出的 configure 条目。

每个已弃用的命令都会在事件通道上触发 command-deprecated 事件。

session.set_coordinate_origin → inverse3[*].configure.preset

// Old — deprecated
{ "session": { "set_coordinate_origin": { "coordinate_origin": "workspace_center" } } }

// New — canonical
{ "inverse3": [ { "device_id": "…", "configure": { "preset": { "preset": "arm_front_centered" } } } ] }

取值映射：

旧 coordinate_origin	新预设
device_base	arm_front（或 defaults）
workspace_center	arm_front_centered

预设通过 inverse3[*].configure.preset（或 verse grip / 无线 verse grip 设备条目上的 configure.preset）按设备逐一应用，而不是作为会话级的全局开关。完整的预设名称列表请参阅仿真参考中的 Configure 章节。

session.set_basis → session.configure.basis

// Old — deprecated
{ "session": { "set_basis": { "basis": { "permutation": "X-ZY" } } } }

// New — canonical
{ "session": { "configure": { "basis": { "permutation": "XZ-Y" } } } }

坐标轴符号约定已更改

---

参考资料

• 设置参考
• WebSocket 协议 — 完整快照 与流式帧布局。
• AsyncAPI 参考 — 适用于所有 v3.1 载荷的 机器可读架构。
• HTTP API 参考 — 用于查看当前 HTTP 路由，以及上文所列 已弃用端点替代路由的 Swagger UI。