Getting Started

このページでは、プラグインを有効にして、同梱の BasicExample から Hapbeat を 1 回再生するところまでを行います。Event Map の作成、Blueprint / C++ の実装、複数端末への送信は次のページへ分けています。

ヒント: AI に初期セットアップを任せる

ファイル操作と Unreal の build を実行できる AI には、次の依頼文を渡します。<ProjectRoot> は対象プロジェクトの絶対パスに置き換えます。

Unreal Engine 5.6 の C++ プロジェクト <ProjectRoot> に Hapbeat Unreal SDK を導入してください。
https://github.com/hapbeat/hapbeat-unreal-sdk.git を <ProjectRoot>/Plugins/HapbeatSDK に clone し、project files を再生成して Editor target を build してください。
Hapbeat SDK を有効化し、Plugin Content の BasicExample マップを開いてください。
PIE、Test Play、実機への触覚送信は実行しないでください。

動作環境

• Unreal Engine 5.3 以上で動作する想定です（動作確認済み: 5.6.1、5.4）。特にこだわりがなければ、Hapbeat のデモ制作で使っている 5.6.1 がおすすめです。
• C++ プロジェクトのビルド環境（Windows は Visual Studio）が必要です。Blueprint のみのプロジェクトでも、プラグインのために 1 回ビルドします。

1. プロジェクトへ追加する

1. .uproject があるフォルダでターミナルを開き、次を実行します（Plugins/HapbeatSDK フォルダは自動で作られます）。

   git clone https://github.com/hapbeat/hapbeat-unreal-sdk.git Plugins/HapbeatSDK

2. Plugins/HapbeatSDK/HapbeatSDK.uplugin が存在することを確認します。

3. project files を再生成して、プロジェクトの Development Editor / Win64 を build します。ビルド手順

補足: ZIP で入れる場合・更新・複数プロジェクト

• ZIP で入れる場合: Plugins/HapbeatSDK/ フォルダを作成し、ZIP を解凍したフォルダの中身をコピーします。Plugins/HapbeatSDK/hapbeat-unreal-sdk-main/HapbeatSDK.uplugin のように 1 階層深くなる配置は誤りです。
• パスを指定して clone する場合: パスにスペースが含まれるときは "..." で囲みます。囲まないと Too many arguments で失敗します。
• 更新: Plugins/HapbeatSDK で git pull（リリースに固定するなら git checkout vX.Y.Z）を実行し、build し直します。
• 複数プロジェクト: プロジェクトごとに clone します。プロジェクトを Git で管理しているなら git submodule add でも構いません。
• 1 つの clone をリンクで複数プロジェクトから共有しないでください。 build 成果物がプラグインのフォルダ内に作られるため、プロジェクト間で DLL が上書きされます。

2. プラグインを有効にする

1. Unreal Editor の Edit → Plugins で Hapbeat SDK を有効にします。
2. Tools → Hapbeat → Hapbeat Settings を開きます。Project Settings の Plugins → Hapbeat で、Connection > Port を Hapbeat と同じネットワークで使う UDP port と一致させます。既定値は 7700 です。

音と触覚のタイミング

音声出力の遅延は環境ごとに異なるため、触覚が音より先に感じられることがあります。Haptic Delay Seconds に少量の遅延を足し、音と触覚のタイミングを合わせます。

3. BasicExample を再生する

1. Content Browser の Settings から Show Plugin Content を有効にします。
2. Plugins/HapbeatSDK/Content/HapbeatSamples/BasicExample/Maps/BasicExample を開きます。
3. PIE を開始し、Space を押します。

100 Hz の StreamClip が再生されれば、SDK の導入とネットワーク送信は完了です。この操作はデバイスへの Kit 配布を必要としません。

Fire（Command）を試す

1. Hapbeat Studio で Plugins/HapbeatSDK/Content/HapbeatSamples/BasicExample/Kit/basic-exam-kit/ の Kit を開きます。
2. 接続済みの Hapbeat を選び、Deploy で basic-exam-kit を Hapbeat へデプロイします。Kit 内の install-clips/sine_200hz_1s.wav がデバイスに配置されます。
3. BasicExample の PIE に戻り、F を押します。

F は Fire（Command）として basic-exam-kit.sine_200hz_1s を再生します。Space のストリーミング再生を先に確認してから、Kit に含めた install-clip の再生を確認する順序です。

反応しない場合は、Hapbeat の電源・同一ネットワーク・UDP port と、OS のファイアウォールが Unreal Editor の UDP 通信を許可しているかを確認してください。Output Log の LogHapbeat で PONG・エラーを確認できます。

同梱サンプル

レベル	確認できること
BasicExample	最小構成の Stream / Fire（Command）再生
Showcase	Z1〜Z5 のゲーム内イベントと触覚再生の接続例
VR Config Example	VR コントローラーでの Address Override 設定と Test 再生

次に読むもの

• Event Map と再生 — Event Map を作り、Blueprint / C++ から再生する
• C++ API — Event Map 再生と直接送信を C++ で呼ぶ
• Blueprint ノード — 全 Blueprint node と component のリファレンス
• Showcase — Z1〜Z5 のゲーム内イベントと触覚再生の接続例
• ターゲティング — Target と Address Override