KAT Unreal ユニバーサルSDKマニュアル
UE版SDK １．３．２を対象 2025/03/06
1. はじめに
1.1 SDK の概要
KAT Unreal ユニバーサルSDK は、KAT VR が製造するトレッドミル型デバイス（KAT Walk mini S、KAT Walk 3DT、C2 シリーズなど）を Unreal Engine 上で制御するための統合開発キットです。
· 歩行状態（回転・移動速度・バッテリーなど）を取得して、ゲームキャラクターの移動に反映
· キャリブレーション（腰方向と HMD の正面向きを一致させる）
· デバイスの振動・LED 制御
· 拡張データ（C2 系列であれば左右足速度や接地状態、LocoS 系列であれば脚のピッチ/ロール等）
· デバイスロスト（切断）時のハンドリング
Unreal Engine の BP（Blueprint） から簡単に呼び出せるように、UFUNCTION(BlueprintCallable) で公開されているのが特徴です。C++ レベルでさらに細かい制御を行うことも可能です。
対象デバイスの例
· KAT Walk mini S / 3DT
· KAT Walk C2 / C2+
· KAT LocoS / MiniS
※ 機種やファームウェアによって、振動や拡張データ機能に差があります。
1.2 必要要件
· Unreal Engine: 4.24 以降（4.27 や 5.x も可）
· Windows 10 以上（標準的には 64bit）
· KAT デバイス本体 が PC に接続・正常動作していること
o Gateway or Device Driver をインストールし、KAT Device Simulator などでデバイスを認識できる状態
2. SDK の導入手順
2.1 Unreal Engine のインストール
1. Epic Games Launcher を入手し、インストール
2. Launcher 内で Unreal Engine → 好みのバージョン（4.27 / 5.1 等）を Install
3. VR/AR を利用する場合、OpenXR または SteamVR / Oculus / Pico などのプラットフォーム SDK をセットアップ
2.2 プロジェクト作成
1. Unreal エディタ起動 → 「ゲーム」などのテンプレートを選択 → 例: First Person / Third Person
2. 「プロジェクト名」と「保存先」を指定
3. 「BluePrint プロジェクト」か「C++ プロジェクト」かを選び、Create
注意: プロジェクト名や保存先に日本語（2バイト文字・特殊文字）が含まれると問題が起きやすいため、使用しないようにしてください。
2.3 SDK パッケージのコピー
1. 取得した KATVRUniversalSDK フォルダを、[YourProject]/Plugins/ 下に配置
o 例: C:\UnrealProjects\MyKatProject\Plugins\KATVRUniversalSDK\...
2. Unreal エディタを再度起動し、コンテンツドロワ（コンテンツブラウザ）右下にある 「表示オプション」 → 「プラグインの候補を表示」 をオン
3. 左パネルに KATVRUniversalSDK フォルダが表示されれば、正常にインポート完了
2.4 UE バージョンの差異
· SDK はデフォルトで UE 4.24 向けにビルドされているケースが多いです
· UE5 の場合、UE_SDK_Update.bat などを通じてバージョンを変換する手順が推奨されます
· 「BUILD SUCCESSFUL」と表示されれば変換完了
最新版では、UE5系のリビルド済みのものが準備されています
3. プロジェクト設定とモジュール概要
3.1 モジュール構成
SDK がインポートされると、プロジェクト内に以下のようなファイル群が展開されます:
MyProject
└─ Plugins
└─ KATVRUniversalSDK
├─ KATVRUniversalSDK.uplugin
├─ Source
│ ├─ KATVRUniversalSDK
│ │ ├─ KATVRUniversalSDK.cpp (モジュール開始/終了)
│ │ └─ KATVRUniversalSDK.h
│ ├─ KATVRUniversalSDKBPLibrary
│ │ ├─ KATVRUniversalSDKBPLibrary.cpp (BPCallable 関数実装)
│ │ └─ KATVRUniversalSDKBPLibrary.h
│ └─ ThirdParty
│ └─ KAT (DLL 本体など)
└─ (Resources, etc.)
3.1.1 KATVRUniversalSDK.cpp / .h
· StartupModule() / ShutdownModule() を通じて Unreal エンジンのプラグインライフサイクルにフック
· IMPLEMENT_MODULE(FKATVRUniversalSDKModule, KATVRUniversalSDK) がエントリポイント
3.1.2 KATVRUniversalSDKBPLibrary.cpp / .h
· Blueprint Function Library
· UFUNCTION(BlueprintCallable) で DeviceCount() や GetWalkStatus(...) などを公開
· BP からノードを呼ぶと、内部で KATSDKWarpper を介して DLL 関数を呼び出す仕組み
3.1.3 KATSDKWarpper.h
· DLL ローダー の本体
· FPlatformProcess::GetDllExport(...) を使い、DeviceCount(), VibrateOnce(), などを取得
· TreadMillData, KATTreadMillMemoryData などの構造体定義を含む
4. 主要クラス・関数
4.1 Blueprint 用関数
UKATVRUniversalSDKBPLibrary 内に定義される関数の例:
DeviceCount()
接続している KAT デバイス数を返す (int 型)
GetDevicesDesc(int index)
FKATDeviceDesc を返す: デバイス名 (device), シリアル番号 (serialNumber), デバイス種別 (deviceType) 等
GetWalkStatus(FString sn = "")
FKATTreadMillMemoryData を返す: treadMillData (回転, 速度, 接続状態) などが詰まった構造体
sn を空にすると、最初に見つかったデバイスの状態を取得
VibrateInSeconds(float amplitude, float duration)
バイブレーションを指定秒数 (duration 秒) 継続 (0 <= amplitude <= 1.0)
一部機種のみ有効
LEDInSeconds(float amplitude, float duration)
LED を指定秒数点灯 (同じく一部機種のみ)
GetLastCalibratedTimeEscaped()
直近のキャリブからの経過秒数を取得
キャリブ実行後、この値が 0 に近い間は新たなキャリブを控える等に使う
4.1.1 Blueprint ノード化
Unreal Editor で Blueprint を開いて 右クリック → ノード追加 メニューを開くと、「KATVRUniversalSDK」や「KATVRExtensionSDK」カテゴリに上記関数がリストアップされます。
たとえば「Vibrate In Seconds」ノードをドラッグし、amplitude と duration を繋げば簡単にバイブを起動できます。
5. キャリブレーションと歩行制御
5.1 キャリブレーションの意義
KAT デバイスは腰センサーを基準とした回転を出力します。一方、ゲーム内で “前方” として扱う軸はキャラクターの Yaw、あるいは HMD (VRヘッドセット) の回転が基準になることも多いです。
キャリブレーション では、この 体 (腰) と HMD の向きの差を計算し、移動方向が自然になるよう補正します。
5.2 実装例（Blueprint）
1. Calibration イベント
キーボードFキー or コントローラ操作 or “キャリブレーションボタン押下” で呼び出す
2. GetWalkStatus で bodyRotationRaw を取得
3. bodyRotationRaw の Yaw を取り出し、HMD のカメラ Yaw との差分を YawCorrection 変数に格納
4. 後述する Apply Movement や Apply Rotation 時に、(bodyYaw - YawCorrection) でキャラの最終Yawを求める
5.2.1 サンプルフロー
(1) OnPressCalibrationKey/Event
↓
(2) data = GetWalkStatus("")
float deviceYaw = ExtractYaw(data.treadMillData.bodyRotationRaw)
float cameraYaw = CameraActor.GetActorRotation().Yaw
YawCorrection = deviceYaw - cameraYaw
(完了)
Blueprint ノード Set YawCorrection → 次の Apply Movement や Apply Rotation で用いる。
5.3 移動制御
Apply Movement では、デバイスから返る移動速度 (moveSpeed) と補正後の Yaw を組み合わせて、AddMovementInput (Character) や SetActorLocation などを行います。
注意: 頭 (HMD) を自由に動かして周囲を見回したい場合は、「体の前方＝腰」「視線＝HMD」を意識して分離する設計が必要です。付属の KATDemoGameMode などのサンプルを見ると、その実装が理解しやすいです。
6. デバイスロストと再接続
6.1 ロスト検出
現時点の SDK には SetOnDeviceLostCallback 相当の仕組みがある場合とない場合があり、最新のリリースノートで異なることがあります。
もしコールバックが利用可能な SDK なら、C++ で以下のように登録するケースがあります（※サンプル抜粋）:
// Not an official sample, just conceptual
SetDeviceLostCallback([](const char* sn, const char* message, int reason) {
// On device lost
// Log or call blueprint event
});
6.2 再接続処理
ロスト時にはブループリントイベントで GUI に通知し、ForceConnect(sn)（もし存在すれば）を呼び出す形で再接続を試みる例があります。
注意: KAT Device Simulator モードでは再接続が不要な場合もあり、本番デバイスで要確認です。
7. 振動・LED 制御
7.1 関数詳細
· VibrateOnce(float amp)
o 単発バイブレーションを一瞬だけ起こす (amp=0〜1)
· VibrateInSeconds(float amp, float duration)
o 指定秒数だけ振幅 amp で振動
· VibrateConst(float amp)
o 連続振動 (amp=0.0 で停止)
· LEDOnce(float amp) / LEDInSeconds / LEDConst
o 同様に LED を点滅 or 連続点灯
7.2 実装例（BP）
// Vibrate for 2 seconds, amplitude=0.7
UKATVRUniversalSDKBPLibrary::VibrateInSeconds(0.7f, 2.0f);
// LED once
UKATVRUniversalSDKBPLibrary::LEDOnce(1.0f);
1. Blueprint でノード検索 → 「Vibrate In Seconds」「LED Once」など
2. amplitude は 0〜1.0、duration は秒数
3. MiniS / LocoS などバイブや LED が物理的にない機種では動作しない点に留意
注意: 急激な連続呼び出し（例: 30ms 未満の間隔）はデバイスに負荷をかける可能性があります。SDK ドキュメントでは最低 30ms の間隔推奨 (KAT PRO WALK MECHA)
8. エクストラデータ（C2, LocoS 等）
8.1 概要
extraData (128バイトの追加情報) が KATTreadMillMemoryData に含まれています。機種により内容が異なり、C2 系列なら左右足速度や接地状態が、LocoS 系列ならピッチ／ロールなどが入っている場合があります。
8.2 C2 系列の例
· WalkC2ExtraData.cs のような別ファイルで extraData を構造体にマッピング
· lFootSpeed, rFootSpeed, isLeftGround, motionType など取得
· BP 側でさらに解釈して、左右足の動きに応じたアニメーションを行うなど拡張が可能
8.3 LocoS 系列の例
· LocoSExtraData.cs で L_Pitch, L_Roll 等を取り出せる場合あり
· ただし「デバッグ用」領域であり、SDK バージョンやファームウェアで値が常に 0 の場合もある
· Byte レベルで再解釈 (BitConverter) するサンプルがあるが、公式サポート外のことも多い
9. アプリのデバッグとビルド
9.1 デバイスの接続確認
1. KAT Walk mini S などのデバイスを USB 3.0 で接続し、KAT Gateway / Driver ソフトウェアで正常に認識されていること
2. Unreal プロジェクトを開き、Play ボタンを押下 → 何らかのレベル内キャラクターで GetWalkStatus() を呼び出し、connected == true となるかチェック
9.2 Windows向けビルド
1. 「File → Package Project → Windows (64-bit)」
2. Blueprint ネイティブ化を Exclusive に設定推奨 (プロジェクト設定の Packaging タブ)
3. ビルド後、出力フォルダに exe が生成される
4. exe を起動し、デバイスが接続されていれば同様に歩行が反映されるはず
9.3 オールインワン VR (Oculus / Pico 等)
1. Android SDK / NDK を公式手順でセットアップ
2. Unreal Project Settings > Platforms > Android で各種パスを登録
3. VR プラットフォーム用プラグイン (OculusXR / PicoXR / OpenXR) をオンに
4. 同じく Package Project → Android (ASTC/ETC2 など)
5. ヘッドセットにビルドして、KAT デバイスの通信が可能な形であれば歩行を確認
10. よくある質問・トラブルシュート
10.1 キャリブを連打すると動きがおかしい
· 短時間に何度もキャリブボタンを押すと、Yaw補正が重複して挙動が乱れやすい
· 一定秒数のクールダウンを挟む or GetLastCalibratedTimeEscaped() を見て 1秒以内の再キャリブを制限する
10.2 振動が効かない / LED が点灯しない
· MiniS, LocoS 等には振動・LED 機構がない場合が多い
· deviceType やデバイス名をチェックして C2 系列か確認
· SDK で VibrateInSeconds を呼んでいるがデバイスが非対応であれば無反応
10.3 LocoS のピッチロールが常に 0
· ファームウェアが古い、またはデバッグ用フィールドが使われていない場合に起こる
· 通常の製品版では、公式サポート外のケースが多い
10.4 接続が切れた / ロスト検出したい
· 最新 SDK なら SetDeviceLostCallback が用意されていることがあります（バージョン差あり）
· ない場合は定期的に GetWalkStatus() で connected == false になったタイミングをチェックする方法も
11. まとめと今後
· KAT Unreal ユニバーサルSDK により、Unreal Engine 4/5 プロジェクトに KAT デバイスの歩行・回転・振動・拡張データをスムーズに統合可能
· Blueprint から “Get KAT Treadmill Walk Status” や “Vibrate In Seconds” などをノードとして呼び出せるため、VR 上のキャラクター制御ロジックを簡潔に組める
· キャリブレーション を取り入れることで、腰の向きと HMD の向きを自然にズレなくできる
· SDKバージョン / デバイスファームウェア による差分に注意し、リリースノートを都度チェック
· Android/オールインワン HMD や 拡張機能 (左右足検出など) を用いる場合は、さらに詳細なマニュアルも参照
以上が、KAT Unreal ユニバーサルSDK の詳細な導入・利用ガイドです。各機能を BP / C++ で呼び出し、KAT デバイスの歩行操作をゲームやシミュレーションに統合することで、より臨場感ある VR 体験を実現できます。デバッグやビルドを通じて実機テストを行い、安定した動作をご確認ください。
Unreal Engine向けKAT VRウォーカー実装ガイド
このガイドでは、Unity用KATXRWalkerサンプルに相当する機能をUnreal Engine環境に実装する方法を説明します。C++とBlueprintの両方の実装例を含みます。
キャリブレーション（による補正の）部分の参考としてください。
1. 概要
KAT VRデバイスのデータをキャラクター移動に反映するには、以下の主要な機能が必要です：
· デバイスからの歩行状態データの取得
· キャリブレーション処理（体の向きとHMDの向きの差分計算）
· 速度モードの設定（線形/一定）
· 適切な移動方法の実装
· XRリグとの連携