はじめに
概要
このドキュメントは、Interhaptics Unity SDK を使用してカスタムハプティックフィードバックを統合するためのガイドです。ハプティクスは、既製のコンポーネントまたは API を通じて組み込むことができます。利用可能なメソッドの一覧は以下のとおりです。
記事
- ハプティクスの再生方法
- シンプルなハプティック効果: シンプルなパターンを記述して再生します。
- 高度なハプティック効果: 感覚を変調し、ハプティックパターンを再生します。
- ハプティック効果アセットの再生: .haps アセットの再生を行い、その再生を定義します。
- ハプティックプリセット: Apple のガイドラインに従ったライブラリからハプティック効果を再生します。
- Unity コンポーネント: ハプティクスのソース、ターゲット、および再生を完全に制御します。
- HapticBodyPart コンポーネント
- HapticSource コンポーネント
- 強度制御
互換性
Core SDK
- Razer Sensa™ HD ハプティクス
- iOS
- Android
- Razer Sensa HD ハプティクス
- Meta Quest
- OpenXR
- Xinput/GameInput PC コントローラー
パートナー向けプラットフォーム拡張
- PlayStation®5
- PlayStation®4
- Nintendo Switch®
必要要件とセットアップ
- Unity 2019.4 LTS 以降
Unity Package Manager を使用して Interhaptics SDK を Unity にインポートするには、以下の手順に従ってください。
- Unity Package Managerを開き、ツールバーの「+」ボタンをクリックします。メニューから「Add package from git URL」を選択します。
- 表示されるテキストボックスに URL「https://github.com/Interhaptics/Unity_CoreSDK.git」を入力し、Add をクリックします。
インストールが成功すると、Interhaptics パッケージが git タグとともにパッケージリストに表示されます。
以前のバージョンが必要な場合は、git フラグを使用できます (例: https://github.com/Interhaptics/Unity_CoreSDK.git#v1.2.3 -- 例えば PS5 アドオンには必要です)。プラットフォーム固有のセットアップについてはドキュメントを参照してください。
ハプティクスの再生方法
このセクションでは、Interhaptics Core Unity SDK がセットアップされていることを前提としています。Interhaptics Core Unity SDK の関数はターゲットプラットフォームに依存せず、すべてのターゲットデバイスに対して 1 度だけ実装すれば済みます。
このセクションでは、ハプティクスをトリガーするための基礎を扱います。コードを書きたくない場合は、既製の Unity コンポーネントが用意されています。
開始するには、スクリプトでハプティクス関数を使用するために Interhaptics.Core 名前空間をインクルードしてください。
using Interhaptics.Core;
シンプルなハプティック効果
1. コンスタント効果の再生
コンスタントなハプティック効果を再生します。通知やハプティクスの学習に便利です。
- HAR.PlayConstant() を使用して、一定の振幅でハプティック効果を再生します。
- パラメータ: Amplitude* (0 から 1 の間)、duration (秒単位)。
- 使用方法:
HAR.PlayConstant(1.0, 0.5); // 100% の振幅でコンスタントなハプティック効果を 0.5 秒間再生します。
* ハプティクスにおける Amplitude (振幅) は、音の音量のようなものです。それは振動がどれだけ強く、または力強く感じられるかを表します。音量を上げると音楽が大きくなるのと同じように、振幅を上げるとハプティックフィードバック (感じる振動) が強くなります。
2. トランジェントの再生*
ハプティックショックを再生します。クリックや機関銃のような迅速な効果に使用します。
- HAR.PlayTransient() を使用して、ゲームイベントに基づいた迅速なハプティックフィードバックを行います。
- パラメータ: Time, Amplitude, Pitch**
- 使用方法:
HAR.PlayTransient(); // トランジェント効果を即座に再生します
HAR.PlayTransient(0.5, 1.0, 1.0); // 0.5 秒に最高ピッチで単一のトランジェントを再生します。ピッチの説明は高度なハプティクスを参照してください。慣れるために 1 を使用してください。
* ハプティクスにおけるトランジェントとは、振動パターンの突然の変化やスパイクのことです。テーブルを指で素早くタップしたり、ボタンをクリックしたりすることを想像してください。それは短くて明確な振動であり、より一定で継続する振動パターンとは対照的です。
** ピッチの説明については高度なハプティック効果を参照してください。慣れるために 1.0 を使用し始めることをお勧めします。
高度なハプティック効果
配列構造の理解
高度なハプティック効果は、配列構造にコード化されたパラメータに基づいています。配列構造には 2 つのタイプがあります。
振幅およびピッチ* 配列: 「時間-値-時間-値」のパターンに従います。各ペアは秒単位で表される時間ポイントと、対応する 0 から 1 の間で表される振幅またはピッチを表します。
トランジェント配列: 「時間-振幅-ピッチ-時間-振幅-ピッチ」のパターンを使用します。各トリプレットは秒単位で表される時間、振幅値、ピッチ値で構成されます。振幅およびピッチ値は 0 から 1 の間です。
* ピッチとは、最小および最大周波数の間で正規化された振動周波数です。ピッチはハプティクス体験の感覚を形作ります。低いピッチはランブルし深く感じられ、高いピッチはシャープに感じられます。
1. シンプルなハプティックパターン
一定のピッチで振動の強度を変調します。爆発のような長めの効果を変調するために使用します。
- HAR.Play() を使用して基本的なハプティックパターンを再生します。
- パラメータ: Amplitude array、[オプション: transient array、intensity、loops、controller side]
- 使用方法
HAR.Play(new double[] {0, 1, 1, 0.5, 2, 1}); // 最大振幅で開始し、1 秒で 0.5 に減少し、2 秒で 1 に戻る振動を再生します。
2. トランジェントの再生
トランジェントのパターンを再生します。鍵を開けるような迅速なパターンを作成するのに便利です。
- HAR.PlayTransients() を使い、提供された時間、振幅、ピッチのトリプレットに基づいて複数のトランジェントハプティック効果を再生します。
- パラメータ: トランジェント配列 [オプション: 強度、ループ、コントローラー側]
- 使用方法:
// 振幅が減少し、ピッチが一定のトランジェントの連続
double[] transient = {
0.0, 1.0, 0.5,
0.25, 0.75, 0.5,
0.5, 0.5, 0.5,
0.75, 0.25, 0.5
};
HAR.PlayTransients(transient);
3. 複雑なパターン
振幅とトランジェントのパターンを組み合わせます。例えば、振動するテールを伴う爆発ショックを作成するために使用します。
- 振幅とトランジェントの配列を HAR.Play() と組み合わせて、複雑なハプティックパターンを再生します。基本パターンで使用したのと同じ関数を使用し、振幅配列の後にトランジェント配列を追加します。
- パラメータ: Amplitude array、transient array [オプション: intensity、loops、controller side]
- 使用方法:
// 「時間-振幅」のペアとしての振幅配列
double[] amplitude = {
0.0, 0.5,
2.0, 0.5,
};
// 「時間-振幅-ピッチ」のトリプレットとして表されるトランジェント
double[] transient = {
0.5, 1, 0.5,
1.5, 0.75, 0.5
};
HAR.Play(amplitude, transient, 1.0, 1, LateralFlag.Left); //配列で記述された複雑なパターンを、強度 1 で左側で 2 回再生します。強度制御を参照してください
4. パラメトリックハプティック効果
振幅とトランジェントのパターンを組み合わせ、効果のピッチを変調します。これにより、ハプティクスの感覚を低い振動（ゴロゴロした感触）から鋭い感触へと変化させたり、効果にバリエーションを持たせたりすることができます。
- HAR.PlayAdvanced() を使用して、振幅、ピッチ、トランジェントのパラメータを微調整します。
- パラメータ Amplitude array、Pitch array、Transient array、[オプション: Frequency Min/Max*、Intensity、Loops、controller side]
- 使用方法:
// 0秒から2秒の間で振幅が0.5
double[] amplitudes = {
1.0, 0.5,
3.0, 0.5
};
//0から1の間のピッチ
double[] pitch = {
1.0, 1.0,
3.0, 0.0
};
HAR.PlayAdvanced(amplitudes, pitch); //低めのうなりのある振動から鋭い感触へと、ピッチが徐々に上昇する一定のハプティック効果を再生します。
*周波数の最小値と最大値の宣言されていない場合のデフォルト値は、それぞれ 65 Hz と 300 Hz であり、これは iPhone の可変周波数範囲に対応しています。
使用方法 2: より長いテールを伴う振幅の上昇と下降。ピッチは最大から最小、再び最大へとスワイプされ、2 つのティックを伴う「爆弾の急降下」効果を作成します。周波数範囲は、DualSense のような特定のコントローラーのハプティック機能を活用するために拡張されています。
// 振幅配列
double[] amplitudes = {
0.0, 0.0,
1.0, 1.0,
2.0, 0.5,
3.0, 0.25,
4.0, 0.25
};
// ピッチ配列
double[] pitch = {
0.0, 1,
2.0, 0,
4.0, 1
};
// トランジェント配列
double[] transients = {
0.5, 1, 0.5,
3.5, 0.5, 0.5
};
double _fmin = 30;
double _fmax = 400;
HAR.PlayAdvanced(amplitudes, pitch, _fmin, _fmax, transients);
ハプティック効果アセットの再生
PlayHapticEffect() メソッドは、ハプティック効果アセット (haps ファイル) で定義されたハプティック効果を再生するために設計されています。この関数は、強度、効果が発生するコントローラー側、効果のループ回数など、haps ファイルに含まれるハプティックフィードバックの再生詳細を指定できます。
Haps ファイルは、複数の振動パターンを組み合わせてタイムラインを定義できるため、高度なハプティック効果と比較してより大きな表現能力を備えています。Haps ファイルは Haptic Composer で編集できます。
基本的な使用方法:
- 以下のようなスクリプトを作成します。
- Unity Editor で、スクリプトを GameObject にアタッチします。
- Inspector で myHapticMaterial フィールドにハプティック効果アセットを割り当てます。Interhaptics SDK\Assets\HapticMaterials フォルダにある既製のハプティック効果のライブラリを利用するか、Haptic Composer アプリを使用して独自のものを作成できます。
- シーンを実行/ビルドします。
- シーンが開始するか、トリガーされると、定義されたとおりにハプティック効果が再生されます。
using UnityEngine;
using Interhaptics.Core;
public class HapticEffectPlayer : MonoBehaviour
{
public HapticMaterial myHapticMaterial; // Unity Inspector で割り当ててください
void Start()
{
// 開始時にハプティック効果を再生
PlayMyHapticEffect();
}
void PlayMyHapticEffect()
{
if (myHapticMaterial != null)
{
HAR.PlayHapticEffect(myHapticMaterial);
Debug.Log("Haptic effect played successfully!");
}
else
{
Debug.LogError("Haptic material is not assigned!");
}
}
}
ハプティックプリセット
- HapticPreset.Play() を活用して、SDK に含まれる定義済みのパターンを再生します。
- Interhaptics.Utils 名前空間を必ずインクルードしてください (
using Interhaptics.Utils;) - パラメータ: PresetType は Apple の Human Interface ガイドラインに基づいています。これらの各プリセット (Selection、Light、Medium、Heavy、Rigid、Soft、Success、Failure、Warning) は、触覚を定義する特定のハプティックパラメータのセットに対応しています。これらのプリセットは、シンプルなアプリケーションでハプティックフィードバックを実装するプロセスを簡素化するように設計されています。これにより、軽いタップ (Light)、より強い振動 (Heavy)、または成功を示すパターンなど、特定の触覚体験を簡単に呼び起こすことができます。
using Interhaptics.Utils;
void Start()
{
HapticPreset.Play(HapticPreset.PresetType.Success); // 'Success' ハプティックパターンを再生します
}
Unity コンポーネント
以下の章では、主要な Unity コンポーネントの構成プロセスについて詳しく説明します。
SDK には、Controllers、Mobile、XR 用に既にセットアップされたサンプルシーンが含まれています。チュートリアルセクションをご確認ください。
Unity コンポーネントは Interhaptics Engine の完全な制御を可能にし、前述の方法では不十分な場合に使用するべきです。これには以下が含まれます。
- HapticManager：ハプティック再生を管理するプロセス。(1.3.0 以降は不要、Core SDK 1.2.3 までは必須)
- HapticBodyParts：ハプティック効果を再生するターゲット。これらはハプティックデバイスやコントローラーの側を表すコンポーネントです。
- HapticSources：HapticBodyParts にアタッチできるハプティック効果のエミッター。
- GlobalHapticIntensityController：全体的なハプティック強度を管理するコンポーネント。
Haptic Manager の構成
SDK バージョン 1.3.0 以降 (11.2023)
このセクションをスキップして HapticBodyPart コンポーネント に進みます。
このバージョンから、ランタイム強度管理やループのような再生機能のセットを含むため、HapticManager コンポーネントは MonoBehaviour から静的クラスに変更されます。そのわけ、HapticManager コンポーネントを追加しないでください。
SDK バージョン 1.2.3 まで
まず Unity で空の GameObject を作成します。この GameObject にハプティックフィードバックを管理するための HapticManager コンポーネントを追加します。HapticManager は、必要に応じて異なるシーンにわたって永続化するように構成できます。
HapticBodyPart コンポーネント
HapticBodyPart コンポーネントは、コントローラーまたはターゲットのハプティックデバイスのさまざまな部分にハプティックフィードバックを割り当てて管理するために不可欠です。
- Debug Mode と Target Intensity の値は実行時に変更できます。
- Target Intensity は、ターゲットのハプティック強度を変調できるようにします。強度は、再生中のハプティック効果のゲインとして機能します。Target intensity は、トリガー/コリジョンのインタラクション中に Spatial Haptic Sources に適用できます。
特定の構成
PC コントローラー (GameInput / XInput)、下の画像を参照
- Body Parts を Hand、Palm、または Index として定義します。
- Side の向きを Left、Right、または Global に設定します。
- 必要に応じて HapticBodyPart をプレイヤーリグにアタッチします。Spatial Haptic Sources の場合、コントローラーに Box Collider と重力を無効にした Rigidbody があることを確認してください。
モバイルデバイス (Android / iOS)、下の画像を参照
- Body Part は Hand に、Side は Global に設定する必要があります。
OpenXR/Meta Quest VR コントローラー、下の画像を参照
- PC コントローラーと同様のセットアップで、適切に XR リグにアタッチします。
PS5 DualSense コントローラー、下の画像を参照
- 唯一のHaptic Body Partとして Hand が使用されます。
- アダプティブトリガーは、スティフネスパーセプションを介して管理されます。
HapticSource コンポーネント
Haptic Sources の概要
Haptic Sources は、Interhaptics Unity SDK 内のコアコンポーネントであり、ゲームワールド内のイベントに応じてタッチや振動の感覚を生成します。これらのソースは、仮想インタラクションとユーザーの触覚との橋渡しとなり、豊かなハプティック体験を作成するためのさまざまなオプションを提供します。
Haptic Source の作成
ハプティックソースを作成するには、
- ハプティックフィードバックのエミッターとして Unity で標準の GameObject を作成します。
- この GameObject に HapticSource コンポーネントを割り当てます。
- ハプティック効果 (haps ファイル) をドラッグするか、Use Streaming Assets をチェックして StreamingAssets フォルダ内の haps ファイルのフルパスを割り当てて、ハプティック効果ファイルを割り当てます。
- HapticSource コンポーネントには 4 つの主要なタイプがあり、それぞれ異なるハプティックフィードバックのシナリオに合わせて調整されています。
HapticSource タイプ
各 HapticSource コンポーネントは、特定のタイプのハプティックフィードバックに対応しており、ゲーム内の特定のインタラクション向けに設計されています。
EventHapticSource
EventHapticSource は、ボタンを押す感覚など、離散的なイベントによってトリガーされるハプティック効果を再生するために使用されます。
通常、Unity Inspector 内のイベントに接続され、効果をアクティブ化するために PlayEventVibration() メソッドを使用します。
SpatialHapticSource
SpatialHapticSource は、コリジョンやトリガーゾーンへのオブジェクトの侵入など、空間的なイベントに応じてハプティックフィードバックをアクティブ化します。
ParametricHapticSource
ParametricHapticSource は、既製のハプティック効果や高度なプログラミングを必要としない、より複雑なハプティックパターンを可能にします。
このコンポーネントは、連続的なハプティクスや/およびトランジェントの振幅とピッチなどのパラメータを時間経過とともに解釈し、ハプティック効果を再生できます。
ハプティック効果パラメータ
連続的なハプティックパラメータ (時間経過に伴う振幅やピッチなど) を定義して、繊細なものから強いものまでさまざまな感覚を作成します。
トランジェントハプティックパラメータを調整して、突然の衝撃や振動のバーストをシミュレートします。これは、「時間-振幅-ピッチ」のトリプレットをコンポーネントに追加することで行われます。
例については、Player Control API メソッドを参照してください。
AudioHapticSource
AudioHapticSource は、オーディオシグナルとハプティックフィードバックを同期するのに役立ちます。サウンドとハプティクスをリンクさせることで、ユーザーの没入感を高めます。
AudioHapticSource は、オーディオクリップとの直接的な関連付けのために AudioSource コンポーネントも統合しています。
HapticSource コンポーネントの構成
各 HapticSource は、アプリケーションのニーズに合わせて構成できるさまざまな設定を提供します。
ハプティック効果ファイル
既存のハプティックファイル (.haps) のライブラリからハプティック効果を選択するか、Haptic Composer アプリを使用してカスタムハプティック効果を作成します。(ダウンロード | ドキュメント)
カスタム効果は、ゼロから設計することも、Haptic Composer 内でオーディオファイルをインポートしてハプティックパターンに変換することもできます。
その他の構成オプション
Vibration Offset: ゲーム内イベントに合わせてハプティック効果の開始を遅延させます。
Source Intensity: ハプティックフィードバックの強度を管理します。値は 0 (強度なし) から 2 (最大強度) の間で調整可能です。この設定は、ゲームのダイナミクスに応答してリアルタイムで変更できます (モバイルでは新しい再生の開始時に更新されます)。
Debug Mode: デバッグ目的でコンソールにリアルタイムログを提供し、ハプティックフィードバックの開始と停止を示します。
Looping: ハプティック効果を繰り返すかどうかを決定し、最大ループ数やループ時間値などのループ条件を設定します。最大ループ数またはループ時間のうち最小のものが考慮されます。
Play At Start: Haptic Source を含む GameObject がアクティブになると同時にハプティック効果を開始するかどうかを指定します。Spatial Haptic Sources については特別に考慮します (false に設定)。
Haptic Body Parts Array: HapticBodyPart 設定で定義された特定のコントローラー領域 (Palm、Index、または Hand など) にハプティックソースをリンクし、効果のターゲットサイド (left、right、または global) を決定します。
強度制御
GlobalHapticIntensityController クラス/コンポーネントは、ハプティックフィードバックの強度を調整するために使用されます。
このクラスは、ハプティックソースの強度を制御する Source Intensity と、ボディパーツのハプティック強度を制御する target intensity を補完します。
GameObject に統合された GlobalHapticIntensityController は、ハプティックフィードバックを管理する集中型システムを提供します。
Global Intensity Adjustment (グローバル強度の調整): ゲーム全体でハプティック効果の強さを変更します。
UI Integration (UI 統合): プレイヤーが UI コンポーネントを介して、ハプティック強度を好みに応じてカスタマイズできるようにします。
Debugging Support (デバッグサポート): ハプティックフィードバックに関する問題の特定と解決のためのログを提供します。
Pause/Resume Functionality (一時停止/再開機能): public メソッド StopAllHaptics() および ResumeAllHaptics() を介して、ゲームの中断中のハプティックフィードバックの制御を可能にします。
Suspend or keep the haptic playback if the app is not in focus (アプリがフォーカスにない場合のハプティック再生の中断または継続) -- チェック (デフォルトで true)
