버전: 3.5.x

3.5로 마이그레이션

이 페이지는 Inverse Service 3.5에 대한 통합 업그레이드 가이드입니다. 이 가이드는 서비스에 여전히 남아 있는 모든 비추천 기능, 즉 레거시 3.0 다음에 삭제될 예정인 와이어 형식 4.0, 더 이상 사용되지 않는 HTTP 엔드포인트, 그리고 더 이상 사용되지 않는 세션 채널 시뮬레이션 명령어 — 이와 함께 하나 새로움 3.5 버전에서 도입된 마이그레이션: 선택적 적용 방식의 Wireless Verse Grip 출력 형상.

여기에 나열된 모든 비추천 기능은 하위 호환성을 위해 여전히 네트워크 상에서 허용됩니다. 업그레이드 시에도 아무런 문제가 발생하지 않으므로, 편하신 때에 마이그레이션을 진행하시기 바랍니다.

`3.0` vs `3.x` API 버전

이 서비스는 두 가지 병렬 JSON 형식을 제공합니다: 레거시 3.0 형식 포트에서 10000 그리고 현재 3.x 포트의 형식 10001. 두 가지 모두 이전 버전과의 호환성을 위해 계속 제공됩니다 — 3.0 업그레이드 후에도 통합 기능은 변함없이 계속 실행됩니다.

경고

3.0 다음에 대한 API 버전 지원이 중단됩니다. 4.0.

3.0 API
- 전체 문서는 3.0.x 문서 페이지.
- HTTP on http://localhost:10000/3.0/.
- Websockets 항구에서 10000.
3.x API
- 전체 문서는 3.x 문서 페이지.
- HTTP on 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 (또는 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" } } } }

축 표기 규칙이 변경되었습니다

두 명령어의 축-기호 해석 방식은 서로 다릅니다. 다음 조건 하에서 올바른 매핑을 생성한 순열은 session.set_basis ~을 생성할 수 있다 역변환 아래 session.configure.basis — 마이그레이션 시 하나 이상의 축에 대해 부호를 반전해야 할 수도 있습니다.

예: 다음 명령어로 정상적으로 실행된 세션 session.set_basis + "permutation": "X-ZY" 일반적으로 다음이 필요합니다 "permutation": "XZ-Y" 아래 session.configure.basis. 마이그레이션을 배포하기 전에 항상 결과 변환을 다시 확인하십시오.

Wireless Verse Grip 출력 형태 (3.5mm, 선택 사항)

서비스 버전 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 페이로드 버전은 변경되지 않았으며 — 다음 항목 아래의 네 가지 런타임 설정에 의해 전적으로 제어됩니다. serialization/wireless_verse_grip/. 3.5 이전 버전의 사운드를 원하는 사용자는 자동으로 해당 사운드를 적용받으며, 새로운 사운드를 선택한 사용자는 세 가지 추가 조절 기능을 통해 출력 사운드를 세밀하게 조정할 수 있습니다.

누가 이주를 원할까요?

다음 내용을 파싱하는 모든 클라이언트는 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 새 모양을 활성화하려면. 두 가지 방법이 있습니다:

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`
리눅스	`/etc/haply-inverse-service/haply-inverse-service-config.json`

변경 사항을 적용하려면 서비스(또는 Haply )를 다시 시작하십시오.

한 번 legacy_mode = false, 나머지 노브들 (explicit_custom, extended_data/raw_data, extended_data/custom_fields)가 활성화됩니다. 참조 노브 매트릭스 아래.

새로운 모양은 어떤 모습인가요?

가입을 선택하면 (legacy_mode = false), 페이로드는 이전에 얽혀 있던 축들을 배열합니다:

config.type 모 가족입니다항목당 — "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 버튼 등)로 변환해야 합니다. 전용 고급 플래그 extended_data/custom_fields 서비스 내에서 미리 번역된 필드를 출력할 수는 있지만, 이는 아니 권장 마이그레이션 경로의 일부입니다. 이 설정을 활성화하기 전에 해당 설정에 대한 설명을 확인하십시오.

기존 방식(기본값) 대 선택적 참여 방식 예시

스타일러스가 하나 있다고 가정하면 (1615)와 루코 한 명 (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]
      }
    }
  ]
}

이 예시에서는 나머지 세 개의 노브가 모두 기본값으로 설정되어 있습니다 (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 로 하드웨어 식별 정보 그리고 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 플래그, 하지만 해당 플래그는 극히 특정된 내부 클라이언트만을 대상으로 하며, 현재 서비스 중인 번역 기능은 향후 릴리스에서 서비스에서 완전히 제거될 예정입니다. 추후 또 다른 마이그레이션을 피하기 위해 처음부터 클라이언트 측에서 바이트 디코더를 구축하십시오.

기존 방식 유지 (별도 조치 불필요)

3.5 버전의 기본 설정은 레거시 모드입니다. 업데이트할 수 없는 고정된 클라이언트가 있거나, 아직 새로운 형식이 필요하지 않다면 아무 조치도 취하지 마십시오. 3.5 버전으로 업그레이드하더라도 페이로드에는 변화가 없습니다.

레거시 모드는 과도기적인 모드입니다

legacy_mode = true 이는 3.5 버전의 기본 설정으로, 내부 Haply (Hub 포함) 및 자사 통합 기능이 마이그레이션될 시간을 주기 위함입니다. 이는 더 이상 사용되지 않는 기능이 아님 오늘이지만, 기본 설정은 다시 false 향후 소폭 업데이트에서 변경될 예정이며, 해당 설정 자체는 4.0 버전으로의 주요 업데이트 전에 제거될 것으로 예상됩니다. 부담 없이 편한 시기에 마이그레이션하시기 바랍니다. 꼭 지켜야 할 마감 기한을 기다리지 마세요.

전체 노브 매트릭스

네 개의 노브는 모두 serialization/wireless_verse_grip/ 또한 실행 중에 설정 HTTP API를 통해 토글할 수 있습니다.

손잡이: `legacy_mode`

유형: bool
기본값: true (3.5 버전은 레거시 모드가 활성화된 상태로 제공됩니다)

~할 때 true, 페이로드가 3.5 이전 버전의 형식과 바이트 단위로 일치하면 다른 설정 항목들은 아무런 동작을 하지 않게 됩니다. false, 새로운 모양이 활성화되고 아래에 있는 세 개의 노브가 적용됩니다. 참조 동의하기.

손잡이: `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; 네 가지 조합은 아래 표를 참조하십시오.

일반 스타일러스 하위 유형(확장 채널 없음)에서는 아무 작업도 수행하지 않습니다.

손잡이: `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 전혀.

참조

설정 안내 — 네 명 serialization/wireless_verse_grip/* 키를 입력합니다.
WebSocket 프로토콜 — 전체 스냅샷 및 스트리밍 프레임 레이아웃.
AsyncAPI 참조 — 모든 v3.1 페이로드에 대한 기계 가독형 스키마.
HTTP API 참조 — 위에서 언급된 현재 HTTP 경로 및 더 이상 사용되지 않는 엔드포인트에 대한 대체 경로를 확인할 수 있는 Swagger UI.

3.0 vs 3.x API 버전​

사용 중단된 HTTP 엔드포인트​

사용 중단된 세션 채널 명령어​

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

session.set_basis → session.configure.basis​

Wireless Verse Grip 출력 형태 (3.5mm, 선택 사항)​

누가 이주를 원할까요?​

동의하기​

새로운 모양은 어떤 모습인가요?​

기존 방식(기본값) 대 선택적 참여 방식 예시​

파서 조정하기​

기존 방식 유지 (별도 조치 불필요)​

전체 노브 매트릭스​

손잡이: legacy_mode​

손잡이: explicit_custom​

손잡이: extended_data/raw_data​

손잡이: extended_data/custom_fields​

통합 매트릭스 (옵트인 모드)​

프로토타입 하위 유형​

참조​