バージョン: 3.5.x

バージョン3.5への移行

このページは、Inverse Service 3.5 の統合アップグレードガイドです。本サービスに残っているすべての非推奨機能――レガシー機能――について解説しています。 3.0 ワイヤー形式は、今後廃止される予定である 4.0、非推奨となったHTTPエンドポイント、および非推奨となったセッションチャネルシミュレーションコマンド — これらに加え、 1つ新着バージョン3.5で導入された移行機能：オプトイン式のWireless Verse Grip 出力形状。

ここに記載されている非推奨機能は、下位互換性を確保するため、引き続きネットワーク上で受け入れられます。アップグレードによって機能に支障が生じることはありません。ご都合の良いタイミングで移行してください。

`3.0` 対 `3.x` APIのバージョン

このサービスは、2つの並行するJSON形式を提供しています：レガシー 3.0 フォーマットポート上で 10000 そして現在の 3.x ポート上のフォーマット 10001. これらは両方とも下位互換性のために引き続き利用可能です — 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 イベントチャンネルでのイベントで、旧ルートとそれに代わるルートの両方を放送します。

非推奨となったセッション・チャネルコマンド

以下の 2 つのセッションレベルのシミュレーションコマンドは非推奨となっており、将来のメジャーバージョンで削除される予定です。これらはネットワーク上では引き続き受け入れられますが、新しい統合では 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 （または configure.preset （Verse Grip / ワイヤレスVerse Gripデバイスのエントリについて）、セッション全体の切り替え機能ではありません。詳しくはセクションの設定プリセット名の全リストについては、シミュレーションのリファレンスを参照してください。

`session.set_basis` → `session.configure.basis`

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

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

軸の符号の規則が変更されました

2つのコマンドでは、軸と符号の解釈が異なります。において正しい対応関係をもたらす置換は、 session.set_basis ～を生成できる 逆変換 ～の下 session.configure.basis — 移行の際、1つまたは複数の軸の符号を反転させる必要がある場合があります。

例：以下のように正常に実行されたセッション session.set_basis + "permutation": "X-ZY" 通常、必要となる "permutation": "XZ-Y" ～の下 session.configure.basis. マイグレーションをデプロイする前に、必ず変換結果を確認し直してください。

Wireless Verse Gripの出力形状（3.5、オプション）

サービスバージョン3.5では、v3.1シミュレーションチャネルのフルスナップショットおよびストリーミングフレームの両方において、 Wireless Verse Gripデバイス（RukoおよびKingfisherのカスタムバリエーションを含む）向けのオプトインJSONシェイプが追加されました。

この移行は任意です

3.5には以下が同梱されています serialization/wireless_verse_grip/legacy_mode = true （デフォルトでは）. バージョン3.5以前の既存のクライアントは、設定やコードを変更することなく引き続き動作します。つまり、既存の連携システムに手を加えることなく、サービスをアップグレードできます。

以下の場合にのみ移行してください ～したい 新しい形：よりすっきりとしたデザイン config.type / config.sub_type 分割し、カスタムグリップが全体に複製されるかどうかを明示的に制御する wireless_verse_grip そして custom_verse_grip 配列。有効にするには、次のように設定します。 serialization/wireless_verse_grip/legacy_mode = false そして、このセクションの残りの手順に従ってください。

変更点は ワイヤー上の添加剤 — v3.1のペイロードバージョンは変更されていません — そして、以下の4つのランタイム設定によって完全に制御されています serialization/wireless_verse_grip/. バージョン3.5以前のシェイプを希望するクライアントは自動的にそのシェイプが適用されます。新しいシェイプを選択したクライアントは、さらに3つのパラメータを調整して出力を調整することができます。

どのような人が移行を希望するでしょうか

以下の内容を解析するクライアントは、 wireless_verse_grip または custom_verse_grip v3.1ペイロードの配列は、新しい形状を活用できる可能性があります：

WVGエントリを読み込むUnityプラグインの統合 JsonUtility
WebSocketストリームを処理する TouchDesignerの統合機能
Python / C++ のサンプルコードを基にした config.type （例： "ruko" / "kingfisher")

解析のみを行うクライアント inverse3 または verse_grip 配列は 影響を受けない 設定にかかわらず。

参加する

裏返す legacy_mode への false 新しい形状を有効にするには、2つの方法があります：

HTTP（実行時）
設定ファイル（永続的）

curl -X POST http://127.0.0.1:10001/settings/serialization/wireless_verse_grip/legacy_mode \
     -H 'Content-Type: application/json' \
     -d 'false'

サービスは直ちに完全なスナップショットを再送信するため、ストリームを再生中のクライアントは次のフレームで新しい形状を確認できます。

キーを追加して haply-inverse-service-config.json:

{
  "serialization/wireless_verse_grip/legacy_mode": false
}

設定ファイルの保存場所（いずれか）：

プラットフォーム	パス
Windows	`C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json`
macOS	`/Library/Application Support/Haply/Inverse/haply-inverse-service-config.json`
Linux	`/etc/haply-inverse-service/haply-inverse-service-config.json`

変更を反映させるには、サービス（またはHaplyHaply ）を再起動してください。

一度 legacy_mode = false、その他のつまみ（explicit_custom, extended_data/raw_data, extended_data/custom_fields) が有効になります。参照ノブマトリックス以下。

新しい形状はどのようなものか

オプトインすると（legacy_mode = false)、ペイロードは、以前は絡み合っていた軸を解きほぐします：

config.type 親家族です1件あたり — "wireless_verse_grip" スタイラスの行については、 "custom_verse_grip" カスタム行（Ruko、Kingfisher、prototype）用。
config.sub_type 新しい分野です （オプトイン形式のみ）で、物理ハードウェアサブタイプを持つもの — "stylus", "prototype", "ruko"あるいは "kingfisher". これは wireless_verse_grip::subtype enum 直接、～とは区別して config.typeの device_type enum。以前はスタイラスとプロトタイプの両方が次のようにシリアライズされていました "wireless_verse_grip"; それぞれに独自の値が設定されています。レガシーモードでは ではない 放出する sub_type.
カスタムグリップの共有 wireless_verse_grip[] デフォルトでは 有効にすると、スタイラス配列にはカスタムバリエーションも含まれます。別の custom_verse_grip 配列は、反転させたときにのみ出力されます explicit_custom = trueその場合、その配列はカスタム専用となり（スタイラスはそこに表示されなくなります）。
カスタムグリップのペイロードは、生の拡張バイトとして保持されます。 extended_data/raw_data (デフォルト true) は生データを保持します state.extension_data: [...] カスタムグリップのエントリにおけるバイト配列 — 従来の形状に準拠しています。クライアントは、自身のコード内でこれらのバイトをサブタイプ固有のフィールド（Ruko wheel/trigger、Kingfisher buttons など）に変換する必要があります。専用の高度なフラグ extended_data/custom_fields サービス内で事前変換済みのフィールドを出力することは可能ですが、それは ではない 推奨される移行手順の一部です。有効にする前に、その設定項目に関する注意事項をご確認ください。

従来の方法（デフォルト）とオプトイン方式の比較例

1本のスタイラスを想定すると（1615) とルコが1人（1419）が接続されています。

レガシー（3.5版デフォルト）
オプトイン（legacy_mode = false、デフォルト設定）

{
  "wireless_verse_grip": [
    {
      "device_id": "1615",
      "config": { "type": "wireless_verse_grip", "…": "…" },
      "state": {
        "buttons": { "a": false, "b": false, "c": false },
        "hall": 16,
        "orientation": { "x": 0, "y": 0, "z": 0, "w": 1 }
      }
    },
    {
      "device_id": "1419",
      "config": { "type": "ruko", "…": "…" },
      "state": {
        "buttons": { "up": false, "down": false, "left": false, "right": false },
        "trigger": 7,
        "wheel": 4,
        "hall": 16,
        "orientation": { "x": 0, "y": 0, "z": 0, "w": 1 }
      }
    }
  ],
  "custom_verse_grip": [
    {
      "device_id": "1419",
      "config": { "type": "custom_verse_grip", "…": "…" },
      "state": {
        "buttons": { "a": false, "b": false, "c": false },
        "hall": 16,
        "orientation": { "x": 0, "y": 0, "z": 0, "w": 1 },
        "extension_data": [0, 6, 1, 183, 5, 6, 7, 8, 9, 10, 11, 12]
      }
    }
  ]
}

{
  "wireless_verse_grip": [
    {
      "device_id": "1615",
      "config": { "type": "wireless_verse_grip", "sub_type": "stylus", "…": "…" },
      "state": {
        "buttons": { "a": false, "b": false, "c": false },
        "hall": 16,
        "orientation": { "x": 0, "y": 0, "z": 0, "w": 1 }
      }
    },
    {
      "device_id": "1419",
      "config": { "type": "custom_verse_grip", "sub_type": "ruko", "…": "…" },
      "state": {
        "buttons": { "a": false, "b": false, "c": false },
        "hall": 16,
        "orientation": { "x": 0, "y": 0, "z": 0, "w": 1 },
        "extension_data": [0, 6, 1, 183, 5, 6, 7, 8, 9, 10, 11, 12]
      }
    }
  ]
}

この例では、他の3つのノブはすべてデフォルトの設定になっています (explicit_custom = false, raw_data = true, custom_fields = false)、そのため、税関は wireless_verse_grip 配列、個別の custom_verse_grip array は出力されず、ruko エントリには生のデータが格納されます extension_data クライアントがローカルで変換するためのバイト配列。

オプトインする際の主な違い：

側面	レガシー（3.5版デフォルト）	オプトイン (`legacy_mode = false`)
`config.type` 以下のカスタム行について `wireless_verse_grip`	サブタイプ名（例： `"ruko"`)	実家 `"custom_verse_grip"`
`config.sub_type`	不在	現在 — `"stylus"` / `"prototype"` / `"ruko"` / `"kingfisher"`
`custom_verse_grip` 配列が出力された	常に（カスタムグリップが接続されている場合）	～の場合に限り `explicit_custom = true`
カスタムグリップの状態スキーマ	生 `extension_data` バイト + `a/b/c` ボタン	同じ生データ `extension_data` デフォルトではバイト単位； `raw_data` 無効にすることができ、 `custom_fields` これは高度なオプトイン機能です — 詳細は以下をご覧ください
スタイラスの下 `custom_verse_grip`	決して	決して

パーサーの調整

登録したら、 config.sub_type として ハードウェアID そして config.type として 家族で楽しむ. 以前、これを基準としていたクライアント config.type == "ruko" …を基準にすべき config.sub_type == "ruko":

- const isRuko = entry.config.type === "ruko";
+ const isRuko = entry.config.sub_type === "ruko";

同じバイナリ内で、バージョン3.5以前のサービス（またはレガシーモードのままのバージョン3.5 サービス）と、オプトインモードのバージョン3.5サービスの両方をサポートする必要があるパーサーについては、いずれかのフィールドにチェックを入れてください：

const subtype = entry.config.sub_type ?? entry.config.type;
const isRuko = subtype === "ruko";

以前、以下に依存していたクライアントは翻訳サブタイプごとのフィールド RukoまたはKingfisherのエントリ内（buttons.{up,down,left,right}, trigger, wheel, buttons.{a..f}, …) は、生のデータを次のように変換する state.extension_data[] バイト側で。このサービスは、従来の稼働中翻訳を extended_data/custom_fields flag, ただし、このフラグはごく限られた特定の内部クライアントのみを対象としており、インサービス翻訳機能は今後のリリースでサービスから完全に削除される予定です。そのため、後々の移行作業を避けるために、最初からクライアント側でバイトデコーダを構築してください。

従来の設定のまま（何もする必要はありません）

3.5のデフォルト設定はレガシーモードです。更新できないように固定されたクライアントを使用している場合、あるいは新しいシェイプがまだ必要ない場合は、何もする必要はありません。3.5にアップグレードしても、ペイロードは変更されません。

レガシーモードは過渡的なものです

legacy_mode = true これは、内部Haply （Hubを含む）およびファーストパーティの統合機能に移行の時間を確保するため、3.5でのデフォルト設定となっています。これは 非推奨ではありません 今日はそうですが、デフォルト設定は再び false 今後のマイナーリリースで、この設定自体はバージョン4.0へのメジャーアップデート前に削除される予定です。都合の良いタイミングで移行するようにしてください。厳格な期限を待たずに進めてください。

ノブマトリックス全体

4つのノブはすべて serialization/wireless_verse_grip/ また、実行時に設定用HTTP APIを介して切り替えることができます。

つまみ： `legacy_mode`

タイプ: bool
デフォルト: true （3.5はレガシーモードが有効な状態で出荷されます）

いつ true、ペイロードはバージョン3.5以前の形式とバイト単位で一致し、その他の設定項目は機能しなくなります。 falseすると、新しい形状が有効になり、下にある3つのノブが機能します。参照参加する.

つまみ： `explicit_custom`

タイプ: bool
デフォルト: false
必要条件 legacy_mode = false 何らかの効果をもたらす。

カスタムグリップに専用の配列を割り当てるかどうかを制御します。

false (デフォルト) — 税関は wireless_verse_grip[] 配列スタイラスの入力と併せて；別途の custom_verse_grip 配列が出力されます。
true — 税関データも専用のシステムを通じて送信されます custom_verse_grip[] 配列（そして引き続き以下に表示される） wireless_verse_grip[] （も）。

前の merged_in_wireless これを反転表示：デフォルトでは true （税関が複製した wireless_verse_grip) であり、次のように設定する必要がありました false 明確な区別をつけるために。新しい名称は好ましい―― explicit_custom = true 「独自の配列の下で明示的にカスタムイベントを発行する」と読み替えられ、デフォルト設定が変更されたため、初期設定のオプトインモードでは単一の統合された wireless_verse_grip[] 配列化し、ティックごとのシリアライズコストを削減する。

つまみ： `extended_data/raw_data`

タイプ: bool
デフォルト: true
必要条件 legacy_mode = false 何らかの効果をもたらす。

いつ true （デフォルト）、カスタムグリップのエントリには生の state.extension_data: [...] バイト配列 — Unityのようなリフレクションベースのデシリアライザ向けの安定した形状 JsonUtility また、拡張チャネル上でカスタムバイナリプロトコルを伝送するクライアントについても。 false, バイト配列は省略されます。これとは別に custom_fields; 4つの組み合わせについては、以下の表を参照してください。

プレーン・スタイラス・サブタイプ（拡張チャネルなし）では何もしない。

つまみ： `extended_data/custom_fields`

タイプ: bool
デフォルト: false
必要条件 legacy_mode = false 何らかの効果をもたらす。

上級者向け — 推奨される移行手順には含まれません

custom_fields これは、未加工の拡張バイトをサブタイプ固有のフィールドに変換するために依然としてこのサービスに依存している、ごく一部の特定の内部クライアント向けに維持されています。サービス内での変換は、今後移行される予定です サービスから外れる 今後のリリースで、新しい連携機能は ではない このフラグを有効にします。保持 custom_fields = false （デフォルト）とし、クライアント側でバイトからフィールドへの変換を行います。

いつ true, カスタムグリップのエントリには、サブタイプごとの変換済みスキーマが適用されます — buttons.{up,down,left,right} + trigger + wheel ルコへ； buttons.{a..f} + trigger キングフィッシャー向け。いつ false (デフォルト)、汎用的なもののみ buttons.{a,b,c} が存在し、サブタイプ特異的な状態からデコードされなければならない state.extension_data[]. 独立して raw_data.

プレーン・スタイラス・サブタイプおよびプロトタイプ・サブタイプでは何もしない — プロトタイプには変換済みスキーマがなく、常に extension_data バイト（もし raw_data = true) またはプレーン a/b/c ボタンのみ（もし raw_data = false).

統合マトリックス（オプトインモード）

～とともに legacy_mode = false:

`explicit_custom`	`raw_data`	`custom_fields`	`wireless_verse_grip[]` を含む	`custom_verse_grip[]` を含む
`false` (既定値)	`true` (既定値)	`false` (既定値)	スタイラス（プレーン）＋カスタム（生データ）	（出力されません）
`false`	`false`	`true`	スタイラス（無地）＋カスタム（翻訳済み）	（出力されません）
`false`	`true`	`true`	スタイラス（プレーン）＋カスタム（生データ＋翻訳済み）	（出力されません）
`true`	`true`	`false`	スタイラス（プレーン）＋カスタム（生データ）	カスタム（生バイト）
`true`	`false`	`true`	スタイラス（無地）＋カスタム（翻訳済み）	税関（翻訳）
`true`	`true`	`true`	スタイラス（通常版）＋カスタム（未加工版＋翻訳版）	関税（原文＋翻訳）

（行に raw_data = false そして custom_fields = false は許可されていますが、一般的なもののみを出力します a/b/c ボタン — 通常は役に立たない。）

プロトタイプのサブタイプ

ルーティングの目的上、プロトタイプのカスタムグリップサブタイプはカスタムとして扱われます。これは wireless_verse_grip[]、および以下の項目でも custom_verse_grip[] いつ explicit_custom = true. プロトタイプ用の翻訳済みスキーマが存在しないため、 custom_fields プロトタイプのエントリに対しては何もしないそれらの状態は完全に extension_data バイト（とき raw_data = true) あるいは全く（～のときは raw_data = false).

オプトインモードでは、プロトタイプエントリが報告されます config.sub_type = "prototype" — 以下の値とは異なる専用の列挙型値 "stylus". 3.4 では、両方のサブタイプが次のようにシリアライズされます "wireless_verse_grip"; 3.5 オプトインモードでは、それぞれに独自の値が割り当てられます。レガシーモードでは、値は出力されません sub_type 全く。

参考

設定リファレンス — 4つ serialization/wireless_verse_grip/* キーだ。
WebSocketプロトコル— 完全なスナップショットおよびストリーミングフレームのレイアウト。
AsyncAPI リファレンス— すべての v3.1 ペイロード用の機械可読スキーマ。
HTTP API リファレンス— 上記の現在のHTTPルートおよび非推奨エンドポイントの代替ルートに関する Swagger UI。

3.0 対 3.x APIのバージョン​

非推奨のHTTPエンドポイント​

非推奨となったセッション・チャネルコマンド​

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

session.set_basis → session.configure.basis​

Wireless Verse Gripの出力形状（3.5、オプション）​

どのような人が移行を希望するでしょうか​

参加する​

新しい形状はどのようなものか​

従来の方法（デフォルト）とオプトイン方式の比較例​

パーサーの調整​

従来の設定のまま（何もする必要はありません）​

ノブマトリックス全体​

つまみ： legacy_mode​

つまみ： explicit_custom​

つまみ： extended_data/raw_data​

つまみ： extended_data/custom_fields​

統合マトリックス（オプトインモード）​

プロトタイプのサブタイプ​

参考​