Unreal Engine のデバイスプロパティ | Unreal Engine 5.7 ドキュメンテーション

デバイスプロパティ は入力デバイスの物理プロパティを表し、ライトカラーの表示やハプティックトリガーの抵抗などのプロパティが含まれます。デバイスプロパティは次の方法で有効にできます。

入力デバイスサブシステム を使用する。
既存のフォースフィードバックアセットを [Device Properties (デバイスプロパティ)] カテゴリに追加する。
Burst Gameplay Cue Notify (バーストゲームプレイキュー通知) ブループリント を使用する。

デバイスのリストはコンフィグファイルによってエントリされるため、サードパーティベンダーはそれぞれ独自のデバイスを任意のオプションとして追加できます。Unreal ではデフォルトでコンソールをサポートしています。これらのコンフィグ設定をエディタで確認するには、[Project Settings (プロジェクト設定)] > [Input (入力)] > [Platform Settings (プラットフォーム設定)] > (対象のプラットフォーム) > [Hardware (ハードウェア)] に移動します。

例として、PlayStation5 では DualSense または DualShock4 を任意のオプションとして設定できます。

使用する武器のタイプに応じて入力トリガーにハプティックの抵抗を加えたり、特殊なエフェクトを出すために時間の経過とともにライトカラーを変化させたりと、さまざまなゲームプレイを演出することができます。

入力デバイスサブシステムはブループリントまたは C++ で使用できます。このシステムには次の機能が含まれています。

「最近使用したハードウェアデバイス」を取得するなど、コントローラーインプット機能を作成する機能。
OnInputHardwareDeviceChanged デリゲートへのリスナー。ユーザーがキーボードからコントローラーなどへと入力デバイスを変更した場合に向けて、Common UI プラグインを使用することなく、それに対応するユーザーインターフェースを PC またはコンソール上で作成できます。

デバイスプロパティの存続期間

デバイスプロパティには、公開された仮想関数を使ってカスタマイズできるシンプルな存続期間が含まれます。それぞれのデバイスプロパティには、フォースフィードバックエフェクトの持続期間属性と同じように機能する期間が設定されます。プロパティは有効になって評価されて適用され、その後、その期間が完了した際にリセットされます。

関数	説明
`Evaluate Device Property`	`EvaluateDeviceProperty()` 関数をオーバーライドして、デバイスプロパティのデータを変更します。この関数はティックごとに呼び出されて、現在の持続期間を提供するため、時間の経過に伴うカーブタイプの値といったステートの変更を取得できます。 C++ の例については `UColorInputDeviceCurveProperty::EvaluateDeviceProperty` クラス実装を、ブループリントの例については Lyra ゲームサンプルの `B_TeamColor_DeviceProperty` ブループリントを参照してください。
`Apply Device Property`	プロパティの内部構成をプラットフォームコードにパスする方法を変更するには、この関数をオーバーライドします。
`Reset Device Property`	デバイスプロパティの持続期間が完了した際に呼び出されます。この関数は、ライトカラーを最初に適用した際の設定にリセットして戻すなど、デバイスプロパティに適用したステートの変更をリセットするために使用できます。

入力デバイスの使用方法

使用する入力デバイスプロパティを決定したら、入力デバイスサブシステム を使ってそのプロパティを有効にできます。デバイスプロパティを有効にすると、入力デバイスのプロパティハンドル が提供されます。このハンドルを使用して、プロパティの現在のステートを入力デバイスサブシステムから取得したり、必要に応じて削除またはリセットしたりすることができます。

プロパティを有効にする際は、FActivateDevicePropertyParams 構造体で設定可能ないくつかのオプションがあります。

構造体のプロパティ	説明
User Id	設定対象の入力デバイスを所有するプレイヤーのプラットフォームユーザー ID です。
Device Id	このプロパティを有効にする入力デバイスの ID です。これが明示的に設定されていない場合は、当該のユーザー ID のデフォルトデバイスが使用されます。
Looping	True の場合は、存続期間が終了したときにこのプロパティがループします。
Ignore Time Dilation	True の場合は、このプロパティの評価時にすべての時間拡張が無視されます。
Play while paused	このプロパティをゲームの一時停止中にも適用するかどうかを指定します。

C++

入力デバイスプロパティは、C++ で入力デバイスサブシステムを使って手動で有効にできます。

ManualExample.h

	| // ヘッダ ファイル内...
	// インスタンス化されたデバイス プロパティ。プロパティを [Details (詳細)] パネルで編集したい場合は、これを使用します
	UPROPERTY(EditDefaultsOnly, Instanced, BlueprintReadOnly, Category = "Input Devices")
	TObjectPtr<UInputDeviceProperty> DevicePropertyInstance;
	 
	// もしくは、[Details (詳細)] パネルで変更したいプロパティがない場合は、サブクラスを使用できます。
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Input Devices")
	TSubclassOf<UInputDeviceProperty> DevicePropertyClass; |

ManualExample.cpp

	| // cpp ファイル内...
	#include "GameFramework/InputDeviceSubsystem.h"
	#include "GameFramework/InputDeviceProperties.h"
	 
	**void** ApplyProperties()
	{
		**const** FPlatformUserId UserId = GetOwningUserId();
	 
		**if** (UserId.IsValid())
		{
			**if** (UInputDeviceSubsystem* InputDeviceSubsystem = UInputDeviceSubsystem::Get())
			{    
					FActivateDevicePropertyParams Params = {};
					Params.UserId = UserId;
	 
					// デバイス プロパティは、デフォルトでプラットフォーム ユーザーのプライマリ入力デバイスで再生されます。
					// これをオーバーライドして特定のデバイスを指定したい場合は、DeviceId パラメータを設定できます。
					// Params.DeviceId = <特定のデバイス ID>;
				 
					// 特定のインスタンス化されたプロパティを使用して、それを変更します。使用する際は注意してください
					FInputDevicePropertyHandle Handle = InputDeviceSubsystem->ActivateDeviceProperty(DeviceProp, Params);
	 
					// このデバイス プロパティ クラスの新しいインスタンスをスポーンして、それを使用します
					FInputDevicePropertyHandle Handle = InputDeviceSubsystem->ActivateDevicePropertyOfClass(DeviceProp, Params);    
		 } 
		}
	}
	 |

武器として適用されたデバイスプロパティを装備/装備解除する例については、Lyra ゲームサンプルの「LyraWeaponInstance.cpp」を参照してください。

ブループリント

デバイスプロパティを使って独自のブループリントを作成することで、カスタム仕様のゲームプレイエクスペリエンスを作成できます。たとえば、Lyra ゲームサンプルの B_TeamColor_DeviceProperty 変数を使用して、コントローラーのライトカラーをあなたのチームカラー (赤色や青色) と一致するように設定したりできます。

ブループリントスクリプトを使用したデバイスプロパティシステムの Lyra ゲームサンプルの例。

ブループリントコードでは、悪影響を及ぼすオブジェクト参照を避けるためにサブクラスタイプのみを使用できます。これは、こういったユースケースでは、特定のデバイスプロパティブループリントを作成しなければならないことを意味します。

入力デバイスプロパティを手動で削除したい場合は、サブシステム上で RemoveDevicePropertyHandles() 関数を呼び出します。

フォースフィードバックアセット

デバイスプロパティは、プレイヤーに適用する既存のフォースフィードバックアセットに追加することで有効にできます。これは [Details (詳細)] パネルの [Device Properties (デバイスプロパティ)] カテゴリで設定できます。

バーストゲームプレイエフェクトキュー

Gameplay Cue Notify Burst (ゲームプレイキュー通知バースト) の適用時に有効にしたいと思っていた入力デバイスプロパティを指定するには、[Details (詳細)] パネルの [GCN Effects (GCN エフェクト)] > [Burst Effects (バーストエフェクト)] > [Burst Device Property Effect (バーストデバイスプロパティエフェクト)] > [Device Properties (デバイスプロパティ)] カテゴリに行きます。

デバッグ

現在有効なデバイスプロパティに関する情報を画面上に表示するには、チルダキー (~) を押してコンソールを開き、次のコンソールコマンドを使用します。


	| showdebug DeviceProperty |

コンソールに「showdebug deviceproperty」コマンドを入力します。

このコマンドにより、現在有効なデバイスプロパティに関するデバッグ情報がビューポートに表示されます。表示されるのは、デバイスが有効であった際に使用されたフラグ、適用先の入力デバイス ID、有効になっている期間の情報です。

ハードウェアプロパティを新規作成する

Engine モジュールの UInputDeviceProperty では、ApplicationCore モジュールで宣言された下位レベルの FInputDeviceProperty 構造体の抽象化が提供されます。各プロパティの実装が処理されるプラットフォームコードに FInputDeviceProperty がパスされます。

新しい開発キットがリリースされた際には、対象となるハードウェアの IInputDevice または IInputInterface にある SetDeviceProperty() 関数をオーバーライドすることで、さまざまな入力デバイスプロパティを使ってその開発キットのサポートを追加できます。

FInputDeviceProperty の新しいサブクラスを追加する場合は、それがデバイス特有ではないことと、あらゆる NDA (機密保持契約) に準拠しつつ、エンジン内のあらゆる場所で参照できることを確認してください。プロジェクト特有のハードウェア構成要素を使用している場合は、プロジェクトコード内でそれを宣言します。

デバイス プロパティの存続期間