トラブルシューティング

まずBasic Sampleを使用し、SDK通信とXR設定を切り分けてください。調査時はパッケージのリビジョン、Unity版、入力バックエンド、ホスト設定、診断値を記録します。認証情報はログや問い合わせ内容に含めないでください。

パッケージを導入・コンパイルできない見出しへのリンクをコピー

• セットアップに記載したパッケージIDとパスを確認します。
• Gitからの導入では、UnityからGitを実行でき、リポジトリにアクセスできるか確認します。リポジトリの権限エラーはSDK実行時の障害とは別です。
• ディスクからの導入では、Packages/com.melt-interface-technologies.contactglove.sdkv2/package.jsonを選択します。
• パッケージを追加する前に、Consoleの最初のエラーを解消します。Unity UI、Physics、IMGUI、ImageConversionはcoreに依存宣言があります。VR用のOpenXR／XR Handsと、必要に応じたInput Systemはプロジェクトへ別途導入します。

ConnectがTransportUnavailableを返す見出しへのリンクをコピー

Basic SampleではHost unavailableと表示され、ConsoleにTransportUnavailableの警告が出ます。別のプロセスやセッションが、指定した受信・送信ポートを使用している可能性があります。操作結果のDetailと診断のLastErrorを確認してください。競合するインスタンスを停止するか、異なるローカルポートを指定します。ReceivePort=0とSendPort=0は空いているポートの割り当てを要求します。起動後に実際の値を確認してください。

複数のEditorやPlayerは、同じ固定受信ポートを共有できません。DivingStation側のServerPortとSDK側のReceivePortを混同しないでください。

WaitingForDataのまま変わらない見出しへのリンクをコピー

1. 必要なバージョンのDivingStationが起動し、グローブが接続・有効化されているか確認します。
2. IpAddressとServerPortを確認します。127.0.0.1は両方のアプリケーションを同じコンピューターで実行する場合に使用します。
3. DivingStationでProtocol v2の状態を確認します。右上の歯車から設定 > SDK / Protocolを開き、SDK / DivingStationProtocol v2のSDK の状態を見ます。
   • 接続中にならない場合は、Unityからの登録がDivingStationに届いていないか、まだ承認されていません。手順2と手順4を確認してください。DivingStationがポートで待ち受けられない場合は、「SDK / Protocol の待受を開始できませんでした」と表示されます。
   • 接続中でもデータが届かない場合は、外部出力 > SDKに「SDKはContactGlove3 Pro専用機能です。」と表示されていないか確認します。この表示がある場合、データは配信されません。
4. LANではLAN接続の設定を確認します。DivingStationのSDK / Protocolで待受範囲をLAN に公開に変更した場合は、DivingStationを再起動してください。接続承認が必要な設定では保留中の接続要求を許可し、両方のPCの実際の受信ポートで必要なUDP通信が許可されているか調べます。
5. 診断値を確認します。UnexpectedSourcesの増加は設定ホスト以外のIPからの受信、ParseErrorsの増加は受信パケットの拒否を示唆します。
6. 保持しているクライアントでResumeまたは同じ設定のConnectを使用し、登録を再試行します。承認を待つ間に停止・開始を繰り返さないでください。

WaitingForDataだけでは、承認待ち、通信断、サーバー不在、配信データがない状態を区別できません。Connectのローカルな成功は承認の応答ではありません。ネットワーク公開範囲は、利用する信頼できる環境に限定してください。

Connectの再試行でInvalidArgumentになる見出しへのリンクをコピー

既存のHostIdに、異なる接続先や異なる設定ポートを指定している可能性があります。自動ポートには最初と同じ0を指定し、元の設定で再試行してください。意図的に接続情報を変える場合は、そのホストを切断して新たなセッションを作成します。Inspectorの値を変えても、実行中のHostOptionsのコピーは変わりません。

接続済みのグローブが選択されない見出しへのリンクをコピー

サンプルのHostIdと左右のIDを確認してください。同じ側に接続済みデバイスが複数ある場合、Autoは意図的に選択を行いません。IDを明示的に選択してください。選択したIDが切断された場合も、別のグローブを誤って操作しないように選択を保持します。

各ストリームも別々に確認してください。メタデータの到着やConnectedだけでは、Controller、Ergonomics、Skeletonの受信は確認できません。GetDataStatusとAgeSecondsを使用してください。

骨格や関節角度のパネルが空になる見出しへのリンクをコピー

選択したデバイス、Raw/Retargetedのストリーム、データの新しさを確認します。サンプルは未受信・期限切れのフレームを非表示にします。既定の鮮度閾値は0.5秒です。デモ用の方針なので、用途に応じて意図的に調整してください。

IK失敗フレームは診断表示に使用できますが、アプリケーションの制御には使用してはいけません。RawとRetarget済みの状態が異なる場合もあります。Profile情報のタイムアウトだけでは、骨格表示は停止しません。

骨格の位置や向きがおかしい見出しへのリンクをコピー

Basic SampleのSkeletonRendererを使う場合は、受信したスナップショットをApplyへそのまま渡します。独自に表示する場合は、UnityPoseConverterで受信値をUnityの座標へ一度だけ変換してください。

位置は手首を原点とするメートル値です。表示ルートの位置・回転・Scaleと、関節の配置方法を確認します。同じ表示ルートの子に関節を置く場合と、骨ごとに親子を作る場合では、設定するlocalPositionが異なります。19個の回転は親関節に対する値です。式と配置方法は座標系とUnityでの表示を参照してください。

F/Jや画面上のボタンが反応しない見出しへのリンクをコピー

• GameビューまたはPlayerをフォーカスします。
• その側で接続済みグローブを1台選択できているか確認します。
• 画面上の振動ボタンには、デバイスの振動対応が必要です。
• New-input-onlyの場合はInput Systemが導入され、EventSystemで対応するUIモジュールが使われているか確認します。サンプルは既存のUI action bindingを保持し、Active Input Handlingを変更しません。
• 操作結果欄とConsoleでコマンドが拒否されていないか確認します。

振動がSuccessでも実機が振動しない見出しへのリンクをコピー

Successはローカル送信の成功です。グローブの接続・振動対応、選択したID、DivingStationのクライアント承認、実機の状態を確認してください。周波数・振幅・時間は指定範囲内にします。SDKには実際の動作を確認する応答はなく、通信復帰時のコマンド再送もありません。

Profile問い合わせがタイムアウト・NotFoundになる見出しへのリンクをコピー

Retarget済みスケルトンから取得した実際のProfileUuidを指定します。NotFoundはサーバーからの応答、タイムアウトは対応する応答を受信しないままローカル期限が経過した状態です。通信と承認を確認し、必要に応じて、要求に対応しない応答の診断値も調べてください。Profileの表示名が取得できなくても、スケルトンの配信・表示は可能です。

コールバックが止まる・通知が欠落する見出しへのリンクをコピー

独自に所有するクライアントでは、1つのスレッドから毎フレームPumpNotificationsを呼びます。ContactGloveBehaviourを使用する場合は二重にpumpしないでください。購読トークンを保持し、明示切断やクライアント再作成後には購読し直します。

キュー長、通知欠落、コールバック例外を確認してください。SubscribeNotificationLossの通知後は保持している入力を解除し、新しい基準を取得します。容量を増やすと一時的な集中を吸収できますが、pumpしない所有側の問題は解消しません。UDPですべての入力変化を保証することはできません。

HandVisualizerで手が表示されない見出しへのリンクをコピー

1. OpenXR 1.17.1、XR Hands 1.8.1を使用しており、公式HandVisualizerを使用していることをご確認ください。
2. OpenXRとHand Tracking featureが有効か確認してください。Android側だけで有効にしてもPCには適用されません。Project ValidationとConsoleの最初のエラーを確認してください。
3. PCの有効なOpenXR runtimeとUnityのPlay Mode OpenXR Runtimeを確認します。SteamVRを使用する場合は、そのruntimeが起動し、HMDやトラッキング機器を認識しているか確認します。
4. Render pipelineを確認してください。特に、Unityの従来のレンダーパイプラインであるBuilt-in Render Pipelineでは、DirectX11に強制するなど特殊な設定を行わなければ手が表示されない場合がありました。Universal Render Pipeline (URP)の利用を推奨します。
5. Unity OpenXRの診断ログで、実際のruntime、拡張、featureを確認します。手のデータにはXR_EXT_hand_trackingが必要です。コントローラーposeの取得成功だけでは、手の関節データの提供を確認できません。
6. 第三者製OpenXR API layerを導入している場合は、その名前・バージョンとエラーを記録します。提供元の管理手順に従い、追加layerの有無による差を切り分けてください。レジストリの一括削除やセキュリティ警告の回避は行いません。元の設定を記録し、診断後に戻せる状態で試します。
7. 手は出るが位置がおかしい場合はXR Origin、tracking origin、装着オフセットを確認します。SDKとXR Handsの関節対応を確認します。XR HandsのposeはUnityの座標なので、そのまま使用してください。

設定を変えて原因を調べる場合は、1項目ずつ変更してください。描画API、Render Pipeline、Render Mode、時刻予測の設定を記録すると比較しやすくなります。

Windows Playerのビルドが失敗する見出しへのリンクをコピー

File > Build ProfilesでWindowsを選択し、ビルド対象のシーンを確認します。Consoleまたはビルドログの最初のエラーから調べてください。Windows向けのビルドモジュールが必要です。IL2CPPを選ぶ場合は、対応するUnityモジュールとC++ビルド環境も用意します。

ビルド後は対象PCで実行し、DivingStationとの接続、入力、本体振動を確認してください。VRではOpenXR runtimeとHMDを準備して、HandVisualizerの手表示も確認します。