リファレンス

BhapticsKit クラスは、Swift から bHaptics ハプティックデバイスを制御する関数を提供します。ハプティックデバイスの接続、ハプティックパターンの再生、デバイスモーターの直接制御、ハプティック再生の管理を行えます。

import BhapticsPlugin

let kit = BhapticsKit()

ハプティックを再生する関数は リクエスト ID を返します。これを使用して再生の確認や停止を行えます。

---

ライフサイクル

init

init()
init(delegate: BhapticsKitDelegate?)

SDK インスタンスを作成します。インスタンスを 1 つだけ作成し、アプリのライフタイム全体を通して保持してください。

iOS と visionOS では、インスタンスを作成すると Bluetooth が起動し、システムがユーザーに Bluetooth の権限を求めます。

パラメーター

• delegate（任意）: Bluetooth とデバイスの状態変化を受け取ります。BhapticsKitDelegate を参照してください。

initialize

func initialize(appId: String, apiKey: String, defaultSetting: String) async -> Bool
func initialize(appId: String, apiKey: String, defaultSetting: String)

ハプティック環境を初期化します。この関数は、イベント関連の関数を使用する前に呼び出す必要があります。

• iOS と visionOS では、ハプティックアプリのハプティックイベントをサーバーからダウンロードします。
• macOS では、bHaptics Player に接続します。bHaptics Player がインストールされているものの実行されていない場合は、bHaptics Player を起動します。

非 async 版は同じ初期化をバックグラウンドで実行し、結果を返しません。

パラメーター

• appId: bHaptics Developer Portal で作成したアプリケーション ID。
• apiKey: bHaptics Developer Portal で作成した API キー。
• defaultSetting: 空の文字列（""）を渡します。

戻り値

初期化の成功状態。

例

let result = await kit.initialize(appId: "your_app_id", apiKey: "your_api_key", defaultSetting: "")
print("Initialization result: \(result)")

delegate

var delegate: BhapticsKitDelegate?

Bluetooth とデバイスの状態変化を受け取ります。BhapticsKitDelegate を参照してください。

イベントベースのハプティック再生

特定のイベントにバインドされたハプティックパターン（bHaptics Designer/Portal でデザイン）を再生します。ほとんどのアプリケーションで推奨される関数です。

play

func play(eventId: String) -> Int

あらかじめ定義されたハプティックイベントを再生します。

パラメーター

• eventId: ハプティックイベントの名前。

戻り値

リクエスト ID。再生の停止に使用できます。

例

let requestId = kit.play(eventId: "heartbeat")
print("Playback request ID: \(requestId)")

playParam

func playParam(
    eventId: String,
    requestId: Int? = nil,
    intensity: Float,
    duration: Float,
    angleX: Float,
    offsetY: Float
) -> Int

ハプティックの強さ、Duration、方向を調整して、ハプティックイベントを再生します。

パラメーター

• eventId: ハプティックイベントの名前。
• requestId（任意）: この再生に使用するリクエスト ID。省略した場合は、ランダムな ID が割り当てられます。
• intensity: ハプティック Intensity の倍率。有効範囲: [0.0 - 2.0]（デフォルト: 1.0）
• duration: Duration の倍率。（デフォルト: 1.0）
• angleX: ハプティックを反時計回りに回転します。有効範囲: [0.0 - 360.0]（デフォルト: 0.0）
• offsetY: ハプティックを上または下に移動します。有効範囲: [-0.5 - 0.5]（デフォルト: 0.0）

戻り値

リクエスト ID。再生の停止に使用できます。

例

let requestId = kit.playParam(eventId: "pistol_r", intensity: 1.0, duration: 1.0, angleX: 0.0, offsetY: 0.0)

playLoop

func playLoop(
    eventId: String,
    intensity: Float,
    duration: Float,
    angleX: Float,
    offsetY: Float,
    interval: Int,
    maxCount: Int
) -> Int

ハプティックイベントをループ再生します。

パラメーター

• eventId: ハプティックイベントの名前。
• intensity: ハプティック Intensity の倍率。有効範囲: [0.0 - 2.0]（デフォルト: 1.0）
• duration: Duration の倍率。（デフォルト: 1.0）
• angleX: ハプティックを反時計回りに回転します。有効範囲: [0.0 - 360.0]（デフォルト: 0.0）
• offsetY: ハプティックを上または下に移動します。有効範囲: [-0.5 - 0.5]（デフォルト: 0.0）
• interval: ループ間の時間間隔（ミリ秒単位）。
• maxCount: ループの回数。

戻り値

リクエスト ID。再生の停止に使用できます。

例

let requestId = kit.playLoop(eventId: "heartbeat", intensity: 0.8, duration: 1.0, angleX: 90, offsetY: 0, interval: 150, maxCount: 5)

playWithStartTime

func playWithStartTime(
    eventId: String,
    startMillis: Int,
    intensity: Float,
    duration: Float,
    angleX: Float,
    offsetY: Float
) -> Int

ハプティックイベントを特定の時点から再生します。すでに再生中のメディアとハプティックを同期させる場合に使用します。

パラメーター

• eventId: ハプティックイベントの名前。
• startMillis: 再生の開始時間。イベントの先頭からの経過時間をミリ秒単位で指定します。
• intensity: ハプティック Intensity の倍率。有効範囲: [0.0 - 2.0]（デフォルト: 1.0）
• duration: Duration の倍率。（デフォルト: 1.0）
• angleX: ハプティックを反時計回りに回転します。有効範囲: [0.0 - 360.0]（デフォルト: 0.0）
• offsetY: ハプティックを上または下に移動します。有効範囲: [-0.5 - 0.5]（デフォルト: 0.0）

戻り値

リクエスト ID。再生の停止に使用できます。

例

// Start from 1.5 seconds into the event.
let requestId = kit.playWithStartTime(eventId: "music_video", startMillis: 1500, intensity: 1.0, duration: 1.0, angleX: 0, offsetY: 0)

playWithoutResult

func playWithoutResult(eventId: String, intensity: Float, duration: Float, angleX: Float, offsetY: Float)

リクエスト ID を返さずにハプティックイベントを再生します（fire-and-forget）。

パラメーター

• eventId: ハプティックイベントの名前。
• intensity: ハプティック Intensity の倍率。有効範囲: [0.0 - 2.0]（デフォルト: 1.0）
• duration: Duration の倍率。（デフォルト: 1.0）
• angleX: ハプティックを反時計回りに回転します。有効範囲: [0.0 - 360.0]（デフォルト: 0.0）
• offsetY: ハプティックを上または下に移動します。有効範囲: [-0.5 - 0.5]（デフォルト: 0.0）

例

kit.playWithoutResult(eventId: "heartbeat", intensity: 0.8, duration: 1.0, angleX: 90, offsetY: 0.25)

ハプティックの直接再生

イベントを使わずにハプティックを再生したい場合は、これらの関数を使用してください。

position は他の bHaptics SDK と共通の Int 値です。値を取得するには BhapticsPosition.index を使用してください。BhapticsPosition を参照してください。

playDot

@discardableResult
func playDot(position: Int, durationMillis: Int, arr: [Int]) -> Int

特定のハプティックアクチュエーターでハプティックフィードバックを再生します。

パラメーター

• position: 再生するハプティックデバイスのタイプ。詳細については こちら を参考にしてください。

  値	デバイス	モーター数
  0	TactSuit Pro	32
  1	TactSleeve(Left)	3
  2	TactSleeve(Right)	3
  3	TactVisor	4
  4	Tactosy for Hands(Left)	3
  5	Tactosy for Hands(Right)	3
  6	Tactosy for Feet(Left)	3
  7	Tactosy for Feet(Right)	3
  8	TactGlove(Left)	8
  9	TactGlove(Right)	8

• durationMillis: ハプティックの Duration（ミリ秒単位）。100 以上を推奨します。
• arr: 配列の長さをデバイスのモーター数に合わせて指定します。配列の値はモーターの Intensity を意味します。配列の各値の有効範囲: [0 - 100]

戻り値

リクエスト ID。再生の停止に使用できます。

例

// Sequentially activate 32 motors
let motorsCount = 32

for i in 0..<motorsCount {
    var motors = [Int](repeating: 0, count: motorsCount)
    motors[i] = 50
    kit.playDot(position: BhapticsPosition.Vest.index, durationMillis: 500, arr: motors)
    try await Task.sleep(nanoseconds: 500_000_000)
}

playPath

@discardableResult
func playPath(position: Int, durationMillis: Int, x: [Float], y: [Float], intensity: [Int]) -> Int

特定の座標の周辺でハプティックを再生します。各ハプティックアクチュエーターのハプティック Intensity を個別に指定する playDot 関数とは異なり、このメソッドは 特定の座標 に対するハプティック Intensity を指定します。

ハプティックの位置を指定する際、playDot は離散的な制御を提供するのに対し、playPath はより連続的です。playDot は個々のアクチュエーターに Intensity を割り当てるのに対し、playPath は特定の座標（X 軸と Y 軸の両方で 0 と 1 の間）に対する Intensity の指定が可能で、周辺のアクチュエーターがそれに応じて振動します。

複数の座標と複数の Intensity をまとめて指定できます。配列内のこれらの座標の周辺のすべてのアクチュエーターは、順次ではなく 同時に（同じタイミングで） 作動する点に注意してください。さらに、すべての配列のサイズは同じである必要があります。

値を徐々に変化させながらこの関数を継続的に呼び出すことで、ハプティックポイントが移動するエフェクトを実現できます。

パラメーター

• position: 再生するハプティックデバイスのタイプ。playDot の表を参照してください。
• durationMillis: ハプティックの Duration（ミリ秒単位）。100 以上を推奨します。
• x: ハプティックエフェクトの X 座標の配列。各値の範囲: [0.0 - 1.0]
• y: ハプティックエフェクトの Y 座標の配列。各値の範囲: [0.0 - 1.0]
• intensity: 各座標に対する Intensity 値の配列。長さは座標の数と一致する必要があります。各値の範囲: [0 - 100]

戻り値

リクエスト ID。再生の停止に使用できます。

例

// Path of point #1
let x1: [Float] = [0.738, 0.723, 0.709, 0.696, 0.682, 0.667, 0.653]
let y1: [Float] = [0.680, 0.715, 0.749, 0.782, 0.816, 0.852, 0.885]
// Path of point #2
let x2: [Float] = [0.061, 0.072, 0.102, 0.184, 0.254, 0.310, 0.363]
let y2: [Float] = [0.632, 0.587, 0.542, 0.498, 0.411, 0.366, 0.301]

for i in 0..<x1.count {
    // Point #1 and #2 will vibrate at the same time.
    kit.playPath(position: BhapticsPosition.Vest.index, durationMillis: 250, x: [x1[i], x2[i]], y: [y1[i], y2[i]], intensity: [20, 60])
    try await Task.sleep(nanoseconds: 250_000_000)
}

playGlove

@discardableResult
func playGlove(position: Int, points: [GlovePoint], frequency: Int, repeatCount: Int) -> Int

TactGlove 専用。 TactGlove でハプティックを再生します。playDot を使用する場合とは異なり、ハプティックの Duration や振動 Intensity の変化を細かく調整できます。これにより、ハプティックフィードバックをさらに詳細に表現できます。

作動させたいモーターごとに GlovePoint を渡します。動作させるには少なくとも 1 個のポイントが必要です。

struct GlovePoint {
    var index: Int
    var intensity: Int
    var shape: Int
    var playTime: Int

    init(index: Int, intensity: Int, shape: Int = 0, playTime: Int = 0)
}

パラメーター

• position: 再生するハプティックデバイスのタイプ。8 または 9 のみ使用してください。

  値	デバイス
  8	TactGlove(Left)
  9	TactGlove(Right)

• points: GlovePoint の配列。

  • index: モーターのインデックス。

    インデックス	モーターの位置
    0	親指の先
    1	人差し指の先
    2	中指の先
    3	薬指の先
    4	小指の先
    5	手首
    6	手のひら（親指側）
    7	手のひら（小指側）

  • intensity: モーターの Intensity。有効範囲: [0 - 100]

  • playTime: 作動の時間間隔。

    Value	Playtimes
    1	5ms
    2	10ms
    4	20ms
    6	30ms
    8	40ms

  • shape: 時間に応じたハプティック Intensity 変化の形態。

    Value	波形
    0	Duration の間、一定の Intensity
    1	指定した Intensity から始まり、半分まで減少
    2	指定した Intensity の半分から始まり、指定した Intensity まで増加

• frequency: 手首モーターの振動周波数（Hz 単位）。TactGlove DK3 にのみ適用されます。デフォルト（80）を使用するには 0 を渡します。

• repeatCount: 繰り返しの回数。

戻り値

リクエスト ID。再生の停止に使用できます。

例

let points = (0..<8).map { GlovePoint(index: $0, intensity: 100, shape: 2, playTime: 8) }

// Left hand
kit.playGlove(position: BhapticsPosition.GloveL.index, points: points, frequency: 0, repeatCount: 1)

// Right hand
kit.playGlove(position: BhapticsPosition.GloveR.index, points: points, frequency: 0, repeatCount: 1)

再生制御

stopByRequestId

func stopByRequestId(_ requestId: Int)

リクエスト ID でハプティック再生を停止します。

パラメーター

• requestId: ハプティック再生関数が返したリクエスト ID。

例

let requestId = kit.play(eventId: "shoot")
try await Task.sleep(nanoseconds: 2_000_000_000)
kit.stopByRequestId(requestId)

stopByEventId

func stopByEventId(_ eventId: String)

特定のイベント名に対するすべてのハプティック再生を停止します。

パラメーター

• eventId: 停止したいハプティックイベントの名前。

stopAll

func stopAll()

現在再生中のすべてのハプティックを停止します。

pause

func pause(_ eventId: String)

特定のイベントの再生を一時停止します。

パラメーター

• eventId: 一時停止したいハプティックイベントの名前。

resume

func resume(_ eventId: String)

一時停止した特定のイベントの再生を再開します。

パラメーター

• eventId: 再開したいハプティックイベントの名前。

turnOffMotors

func turnOffMotors()

接続されたすべてのデバイスのモーターを直ちにオフにします。

状態確認

isPlaying

func isPlaying() -> Bool

ハプティック全体の再生状態を確認します。イベントベースの再生と直接再生の両方で動作します。

isPlayingByRequestId

func isPlayingByRequestId(_ requestId: Int) -> Bool

特定のリクエスト ID の再生状態を確認します。イベントベースの再生と直接再生の両方で動作します。

isPlayingByEventId

func isPlayingByEventId(_ eventId: String) -> Bool

特定のイベントの再生状態を確認します。

getEventList

func getEventList() -> [String]

ハプティックアプリに含まれるハプティックイベントの名前を返します。このリストは initialize の完了後に使用できます。

デバイス管理

iOS と visionOS では、SDK が Bluetooth LE を介してハプティックデバイスをスキャンし、接続します。macOS ではデバイスは bHaptics Player によって管理されます。スキャン関数とペアリング関数は効果がありませんが、getDevices と ping は bHaptics Player に接続されたデバイスに対して動作します。

scan

func scan()

近くの bHaptics デバイスのスキャンを開始します。検出されたデバイスは deviceStateUpdated に通知されます。ペアリング済みのデバイスは、検出されると自動的に再接続されます。

スキャンは Bluetooth の準備が整っている場合にのみ開始されます。bleStateChange が true を通知した後に呼び出してください。

stopScan

func stopScan()

スキャンを停止します。ペアリングも接続もされていないデバイスは、デバイスリストから削除されます。

isScanning

func isScanning() -> Bool

SDK がスキャン中かどうかを確認します。

toggleScanning

func toggleScanning() -> Bool

SDK がスキャン中であればスキャンを停止し、そうでなければスキャンを開始します。

戻り値

呼び出し後に SDK がスキャン中かどうか。

pair

func pair(device: BhapticsDevice)

デバイスをペアリングして接続します。SDK はペアリングしたデバイスをアプリの起動をまたいで記憶します。

パラメーター

• device: ペアリングするデバイス。getDevices または deviceStateUpdated から取得します。

unpair

func unpair(device: BhapticsDevice)

デバイスのペアリングを解除し、接続を切断します。

パラメーター

• device: ペアリングを解除するデバイス。

getDevices

func getDevices() -> [BhapticsDevice]

検出されたデバイスとペアリング済みのデバイスを返します。BhapticsDevice を参照してください。

ping

@discardableResult
func ping(device: String) -> Bool

特定のデバイスに ping を送信します。デバイスが短く振動するため、ユーザーはデバイスを識別できます。

パラメーター

• device: BhapticsDevice の uuid。

戻り値

ping が送信されたかどうか。

例

if let device = kit.getDevices().first {
    kit.ping(device: device.uuid)
}

pingAll

@discardableResult
func pingAll() -> Bool

接続されたすべてのデバイスに ping を送信します。

戻り値

ping が送信されたかどうか。

getBluetoothState

func getBluetoothState() -> Int

Bluetooth の状態を返します。デバイスが見つからない原因を特定するために使用します。

値	状態
0	不明
1	リセット中
2	非対応
3	未許可（Bluetooth の権限が拒否されている）
4	電源オフ
5	電源オン

macOS 専用

isPlayerConnected

func isPlayerConnected() -> Bool

bHaptics Player との接続状態を確認します。iOS と visionOS では常に false を返します。

onPlayerConnectionChanged

var onPlayerConnectionChanged: ((Bool) -> Void)?

bHaptics Player との接続状態が変化したときに、メインスレッドで呼び出されます。macOS でのみ使用できます。

例

#if os(macOS)
kit.onPlayerConnectionChanged = { connected in
    print("bHaptics Player connected: \(connected)")
}
#endif

型

BhapticsKitDelegate

protocol BhapticsKitDelegate {
    func bHapticsKit(_ kit: BhapticsKit, bleStateChange state: Bool)
    func bHapticsKit(_ kit: BhapticsKit, deviceStateUpdated devices: [BhapticsDevice])
    func bHapticsKit(_ kit: BhapticsKit, didConnect device: BhapticsDevice)
    func bHapticsKit(_ kit: BhapticsKit, didDisconnect device: BhapticsDevice)
}

iOS と visionOS で、Bluetooth とデバイスの状態変化を受け取ります。

• bleStateChange: Bluetooth が使用可能になった（true）、または使用できなくなった（false）。
• deviceStateUpdated: デバイスリストが変更された。デバイスが検出、ペアリング、ペアリング解除、接続、または切断されたときに呼び出されます。
• didConnect: デバイスが接続された。
• didDisconnect: ペアリングされていないデバイスが切断された。

BhapticsDevice

SDK が検出したハプティックデバイス。

プロパティ	型	説明
name	String	デバイスの名前。
uuid	String	デバイスの一意の識別子。id としても使用できます。
position	PositionType	デバイスを装着する身体部位。
battery	Int	バッテリー残量（パーセント）。不明な場合は -1。
connected	Bool	デバイスが接続されているかどうか。
paired	Bool	デバイスがペアリングされているかどうか。

BhapticsPosition

ハプティックデバイスのタイプ。playDot、playPath、playGlove などの関数に渡すには index を使用します。

ケース	index	デバイス
.Vest	0	TactSuit
.ForearmL	1	TactSleeve(Left)
.ForearmR	2	TactSleeve(Right)
.Head	3	TactVisor
.HandL	4	Tactosy for Hands(Left)
.HandR	5	Tactosy for Hands(Right)
.FootL	6	Tactosy for Feet(Left)
.FootR	7	Tactosy for Feet(Right)
.GloveL	8	TactGlove(Left)
.GloveR	9	TactGlove(Right)

let position = BhapticsPosition.GloveL.index  // 8