Unreal Engine 5 ドキュメントは Epic Developer Community に移動しました

PlayerInput オブジェクトは、プレイヤーからの入力をアクタ (PlayerController や Pawn など) が認識および 利用することができるデータ形式へ変換します。プレイヤーからのハードウェア入力をゲームイベント、 PlayerInput マッピングや InputComponent を使用した動作へ変換する、入力処理フローの一部です。

ハードウェアへの入力

プレイヤーからのハードウェアへの入力は非常に分かりやすいです。キー入力、マウスクリックやマウス動作、そしてコントローラーボタン入力かジョイスティックによる入力が最も一般的です。標準的な軸やボタンのインデックスに従わない特殊な入力デバイスや、通常の入力範囲を超えたものを持つ場合は、 RawInput プラグイン を使って手動で設定することができます。

PlayerInput

PlayerInput (プレイヤー入力) はプレイヤー入力を管理する PlayerController クラス内の UObject です。PlayerInput はクライアント側でのみスポーンされます。2 つの構造体が PlayerInput 内に 定義されます。まず、 FInputActionKeyMapping が「ActionMapping」を定義します。次に FInputAxisKeyMapping が「AxisMapping」を定義します。 「ActionMappings」と「AxisMappings」の両方で使用するハードウェアの入力定義は InputCoreTypes で設定します。

ActionMappings

後にイベント駆動の動作と結合する「フレンドリーネーム」へ、ディスクリート ボタンかキー入力をマッピングします。最終的な効果としては、キー、マウスボタン、またはキーパッドボタンを押す (または解放する) と、特定のゲーム動作が直接トリガーされます。

AxisMappings

ゲーム内の移動など、後に継続的なゲーム動作と結合する「フレンドリーネーム」へ、キーボード、コントローラーまたはマウスの入力をマッピングします。AxisMapping でマッピングされた入力値は、単に入力値が現在 0 である旨の報告の場合でも、そのままポーリングされます。ActionMapping への入力でトリガーされる別個のゲームイベントではなく、移動や他のゲーム動作のスムーズな遷移を有効にします。

入力マッピングの設定

入力マッピングはコンフィギュレーション ファイルに格納されていますが、[Project Settings (プロジェクト設定)] の [Input (入力)] セクションで簡単に設定できます。

1. レベルエディタで、 [Edit (編集)] > [Project Settings] の順に選択します。

2. 表示される [Project Settings] タブで [Input] をクリックします。

このウィンドウで、以下の設定を行うことができます。

(ハードウェア) 軸入力のプロパティの変更

ActionMapping の追加または編集

AxisMapping の追加または編集

InputComponent

InputComponent は通常ポーンやコントローラに作成されますが、必要に応じて別のアクタやレベル スクリプトに設定することも出来ます。InputComponent は、ユーザープロジェクトの AxisMapping と ActionMapping をゲームアクションとリンクさせます。 通常は関数として、C++ コードかブループリントグラフに設定します。

InputComponent による入力処理のプライオリティ スタックは、以下の通りです (優先順位の高い順から)

1. 「Accepts input」が有効となったアクタは、直前に有効となったものから最も長時間有効となっている順番で処理されます。

   入力処理で特定のアクタを常に優先したい場合、そのアクタの「Accepts input」を再び有効にして、スタックのトップに移動させることができます。

2. コントローラ

3. レベルスクリプト

4. ポーン

ある InputComponent が入力を受け取ると、そのコンポーネントはその後スタックでは利用できません。

入力処理の手順

例 - 前進

この例は、UE4 に同梱される First Person テンプレートからのものです。

1. ハードウェアへの入力: プレイヤーが W を押します。

2. PlayerInput Mapping: AxisMappingは W を値 1 のスケーリングで「MoveForward」へ変換します。

3. InputComponent Priority Stack: InputComponent のプライオリティ スタックを通過した「MoveForward」入力が最初に結合するものは、AFirstPersonBaseCodeCharacter クラス内にあります。このクラスは現在のプレイヤーのポーンであるため、その InputComponent は最後にチェックされます。

   void AFirstPersonBaseCodeCharacter::SetupPlayerInputComponent(class UInputComponent* InputComponent)
       {
           // set up gameplay key bindings
           check(InputComponent);
           ...
           InputComponent->BindAxis("MoveForward", this, &AFirstPersonBaseCodeCharacter::MoveForward);
           ...
       } 

   この手順はキャラクターのイベントグラフに InputAxis MoveForward ノードを設定することで、ブループリントで実現することも出来ます。このノードと接続されている値が、 W キーがクリックされると実行されます。

4. Game Logic: AFirstPersonBaseCodeCharacter の MoveForward 関数を実行します。

   void AFirstPersonBaseCodeCharacter::MoveForward(float Value)
       {
           if ( (Controller != NULL) && (Value != 0.0f) )
           {
               // find out which way is forward
               FRotator Rotation = Controller->GetControlRotation();
               // Limit pitch when walking or falling
               if ( CharacterMovement->IsMovingOnGround() || CharacterMovement->IsFalling() )
               {
                   Rotation.Pitch = 0.0f;
               }
               // add movement in that direction
               const FVector Direction = FRotationMatrix(Rotation).GetScaledAxis(EAxis::X);
               AddMovementInput(Direction, Value);
           }
       }

   Blueprint Implementation:

タッチ インターフェース

タッチ デバイス上で動作するゲームには、デフォルトで 2 つのバーチャル ジョイスティックがあります (例えばコンソール コントローラー)。この設定は、 [Project Settings] の [Input] セクションから、 [Default Touch Interface] プロパティを 選択して変更できます。これは Touch Interface Setup アセットを示します。デフォルトのインターフェース、 DefaultVirtualJoysticks は、共有エンジン コンテンツ( /Engine/MobileResources/HUD/DefaultVirtualJoysticks.DefaultVirtualJoysticks )に格納されています。 またカメラの回転を必要としないゲームのために、 Left Stick 専用バージョンの LeftVirtualJoystickOnly もあります。

これらを見るには、オブジェクト ピッカーの [View Options (表示オプション)] 設定で、 [Show Engine Content (エンジンのコンテンツを表示)] チェックボックスをオンにしなくてはいけません。

バーチャル ジョイスティックを使用しない場合、Default Touch Interface] プロパティの値をクリアします。また [Always Show Touch Interface (タッチインターフェースを常に表示)] にチェックを入れると、動作しているプラットフォームとは関係なくゲームでタッチ インターフェースを強制的に使用することも出来ます (または、「-faketouches」で PC ゲームを実行)。

Enhanced Input プラグイン

複雑な入力処理やランタイム制御の再マッピングなど、より高度な入力機能を必要とするプロジェクトの場合、実験的機能の 拡張入力プラグイン により、開発者は簡単なアップグレードパスとエンジンのデフォルト入力システムとの下位互換性を利用できます。このプラグインには、放射状のデッドゾーン、コード化されたアクション、コンテキスト入力と優先順位付け、アセットベースの環境での生の入力データの独自のフィルタリングと処理を拡張する機能などの機能が実装されています。

操作を開始する

拡張入力を使用するようにプロジェクトを設定するには、Enhanced Input プラグインを有効にします。これには、エディタの [Edit (編集)] ドロップダウン メニューを開き、 [Plugins (プラグイン)] を選択します。[Plugin] リストの [Input] セクションで [Enhanced Input] プラグインを見つけて有効にし、エディタを再起動します。

エディタを起動すると、プラグインが有効になります。

エディタが再起動したら、デフォルトの UE4 入力ハンドラの代わりに Enhanced Input プラグインのクラスを使用するようにプロジェクトを設定できます。 [Edit (編集)] ドロップダウン メニューに移動して、 [Project Settings (プロジェクト設定)] を選択します。[Project Settings] の [Input ] セクション ( [Engine] という見出しの下にある) を特定して、 [Default Classes (デフォルト クラス)] 設定を見つけます。これには、最初、標準の PlayerInput クラスと InputComponent クラスが指定されています。

拡張入力を使用するには、これらの設定をそれぞれ EnhancedPlayerInput と EnhancedInputComponent に変更します。

主要概念

拡張入力システムには、次の 4 つの主要な概念があります。

• 入力アクション (Input Actions) は拡張入力システムとプロジェクトのコードの間の通信リンクです。入力アクションは、ジャンプしたりドアを開けたりするなど、インタラクティブなキャラクターが実行する可能性のあるあらゆるアクションに相当します。また、それだけでなく、歩行動作をランに変更するボタンの長押しなど、ユーザーの入力状態を示すためにも使用できます。入力アクションは raw 入力とは異なるものです。入力アクションはそのアクションをトリガーした特定の入力には認識しないものの、その入力の現在の状態は認識しており、最大 3 つの独立した浮動小数点軸で入力値を報告することができます。例えば、「アイテムを拾う」アクションでは、ユーザーが何かを拾おうとしているかどうかを示すオン/オフの状態のみが必要で、「歩行」アクションでは、ユーザーが歩いていこうとしている方向と速度を指定するために 2 つの軸が必要です。

• 入力マッピング コンテキスト (Input Mapping Contexts) は、ユーザー入力をアクションにマッピングします。また、入力マッピング コンテキストはユーザーごとに動的に追加、削除したり、優先順位を付けることができます。また、拡張入力ローカル プレイヤー サブシステム (Enhanced Input Local Player Subsystem) を使用してローカル プレイヤーに 1 つ以上のコンテキストを適用し、適用したコンテキストに優先順位を付けることで、同じ入力を消費しようとする複数のアクション間の競合を解決することができます。一般的な例としては、キャラクターがワールドを歩き回りながらドアを開けたり、キャラクターのバックパックを確認しながらアイテムを選択したりできる単一のボタンが挙げられます。キャラクターがバックパックを開くときは必ず、「ドアを開く」コンテキストを優先順位から除外し、キャラクターがバックパックを閉じると「アイテムを選択する」コンテキストを削除する「アイテムを選択する」入力マッピング コンテキストを追加することができます。入力マッピング コンテキストにより、ユーザーの入力がキャラクターの状況に基づいて正しく解釈されることが保証され、ドアとバックパックのシステムを意識して、入力処理レベルでコードをプログラミングする必要がなくなります。 モディファイアは、ユーザーのデバイスから受け取る raw 入力の値を調整します。入力マッピング コンテキストは、入力アクションのそれぞれの raw 入力に関連付けられたモディファイアをいくつでも含むことができます。プラグインには、デッド ゾーン、複数フレームにわたる入力のスムージング、ローカル空間からワールド空間への入力ベクターの変換をはじめとする一般的なモディファイアが含まれています。また、デベロッパーが独自のモディファイアを作成することもできます。

• トリガー (Triggers) はポストモディファイア入力の値、または他の入力アクションの出力の大きさを使用して、入力アクションを有効にする必要があるかどうかを決定します。入力マッピング コンテキスト内の入力アクションは、入力ごとに 1 つ以上のトリガーを含むことができます。例としては、写真を撮るには、カメラの照準を合わせるための別の入力アクションが有効であるときに、ユーザーが左マウス ボタンを 1/4 秒押す必要がある場合などが挙げられます。

以上の概念を組み合わせることで、デベロッパーはシンプルな入力システムから複雑な入力システムまで素早くセットアップし、プロジェクト コードを変更することなく入力システムを調整することができます。

入力アクション

入力アクション (Input Action) は、システムとユーザーのプロジェクトのコードを関連付けます。入力アクションを作成するには、 コンテキスト ブラウザ で右クリックして、 [Input (入力)] オプションを展開し、 [Input Action (入力アクション)] を選択します。入力アクションをトリガーするには、その入力アクションを入力マッピング コンテキストに設定し、その入力マッピング コンテキストをローカル プレイヤーの Enhanced Input Local Player Subsystem (拡張入力ローカル プレイヤー サブシステム) に追加する必要があります。

トリガーされた入力アクションに Pawn クラスを応答させるには、 SetupPlayerInputComponent で適切なタイプの トリガー イベント にバインドする必要があります。次のサンプル コードでは、SetupPlayerInputComponent をオーバーライドして、2 つの入力アクション MyInputAction および MyOtherInputAction をハンドラ関数にバインドしています。

// There are ways to bind a UInputAction* to a handler function and multiple types of ETriggerEvent that may be of interest.

// This calls the handler function on the tick when MyInputAction starts, such as when pressing an action button.
if (MyInputAction)
{
    PlayerEnhancedInputComponent->BindAction(MyInputAction, ETriggerEvent::Started, this, &AMyPawn::MyInputHandlerFunction);
}

// This calls the handler function (a UFUNCTION) by name on every tick while the input conditions are met, such as when holding a movement key down.
if (MyOtherInputAction)
{
    PlayerEnhancedInputComponent->BindAction(MyOtherInputAction, ETriggerEvent::Triggered, this, TEXT("MyOtherInputHandlerFunction"));
}

入力アクションを Enhanced Input プラグインにバインドすると、ビルトインの入力システムのアクションおよび軸のバインディングが置き換えられます。Enhanced Input プラグインを使用する場合は、入力アクションのみをバインドする必要があります。 入力アクションをバインドする場合、以下の 4 種類のハンドラ関数シグネチャから選択できます。

入力アクションにはブループリント スクリプティングに入力アクションを公開するビルトイン イベントが含まれているので、C++ のデベロッパーは、ブループリント スクリプティングのデベロッパーが入力アクションのイベントにアクセスできるように、パススルー関数を作成する必要はありません。 一般的なハンドラ関数は次の形式を取ります。

// Debug log output to confirm that the handler function is running.
UE_LOG(LogTemp, Warning, TEXT("%s called with Input Action Value %s (magnitude %f)"), TEXT(__FUNCTION__), *Value.ToString(), Value.GetMagnitude());
// Use the GetType() function to determine Value's type, and the [] operator with an index between 0 and 2 to access its data.

ほとんどのユース ケースで、void (const FInputActionValue&) シグネチャを使用することが推奨されます。 入力アクションをハンドラ関数にバインディングすることで、ポーンは入力アクションがトリガーされた特定の方法に応じて、入力アクションに応答することができます。 最も一般的なトリガー タイプは、ボタンを押した直後に 1 回実行されるアクションでは Started で、入力を保持している間にフレームごとに実行される連続的なアクションでは Triggered である可能性があります。ただし、完全なリストについては、ETriggerEventETriggerEvent の API リファレンス ページを参照してください。

入力マッピング コンテキスト

入力マッピング コンテキスト (Input Mapping Context) は、1 つ以上の入力アクションをトリガーするためのルールを記述します。基本的な構造は、最上位レベルに入力アクションのリストを持つ階層になっています。入力アクション レベルの下には、キー、ボタン、および移動軸などの各入力アクションをトリガーできるユーザー入力のリストがあります。 最下位レベルには、各ユーザー入力の入力トリガーと入力モディファイアのリストがあります。このリストを使用すると、入力の raw 値のフィルタリングまたは処理方法、および階層の最上位にある入力アクションを制御するために満たす必要のある制約事項を決定することができます。 どの入力にも複数の入力モディファイアと入力トリガーを設定できます。このような入力モディファイアおよび入力トリガーは、ユーザーが作成するリストに表示される順に評価されます。

入力マッピング コンテキストを作成するには、 コンテキスト ブラウザ を右クリックして、 [Input] オプションを展開し、 [Input Mapping Context] を選択します。

入力マッピング コンテキストには関連するすべての入力アクションを設定します。シンプルなプロジェクトでは、すべての入力アクションを 1 つの入力マッピング コンテキストにまとめることができることがあります。複雑なプロジェクトでは、入力アクションを複数の入力マッピング コンテキストに設定すると適切に機能する可能性があります。これは、ローカル プレイヤーが一度に複数のアクティブな入力マッピング コンテキストを持つことができるためです。 たとえば、泳いだり、歩いたり、車を運転したりできるキャラクターは、常に利用することができ、常に同じユーザー入力にマップされる一般的なアクションの入力マッピング コンテキストと、それぞれの移動モード用の個別の入力マッピング コンテキストを持つ場合があります。 デベロッパーは、車両関連の入力アクションを別の入力マッピング コンテキストに設定することができます。これにより、車両に乗車したときにローカル プレイヤーに車両関連の入力アクションを追加し、車両から出たときにローカル プレイヤーからこれらのアクションを削除することができます。こうすることで、不適切な入力アクションが実行されない (CPU サイクルを無駄にしない) ようにし、ユーザー入力が相互に排他的な入力マッピング コンテキストによって異なる入力アクションに使用された場合の入力の衝突を回避することで、バグを低減できます。詳細については、「モディファイア」および「トリガー」のセクションを参照してください。

この入力マッピング コンテキストでは、ラン (走行) 用の入力アクションを示しています。これは、ゲームパッドの左サムスティックの偏位を含む複数の入力によってアクティブにすることができ、両方の軸を 1 つの入力にまとめることができます。 その入力の raw 値は、[Dead Zone (デッド ゾーン)] 入力モディファイアで処理され、結果の値が [Hold (長押し)] 入力トリガーに送信され、「RunAction」入力アクションを制御します。

このドロップダウン リストには多くの入力バインディングがあります。入力バインディングをより素早く選択するには、ドロップダウンの左にある小さなボタンを押してから、バインドしたいキーまたはボタンを押します。

このシンプルな入力マッピング コンテキストは、ランとジャンプの入力アクションをサポートしています。 入力マッピング コンテキストの設定が完了したら、それをポーンのプレイヤー コントローラーに関連付けられているローカル プレイヤーに追加できます。これを行うには、PawnClientRestart 関数をオーバーライドして以下のようなコード ブロックを追加します。

// Get the Enhanced Input Local Player Subsystem from the Local Player related to our Player Controller.
if (UEnhancedInputLocalPlayerSubsystem* Subsystem = ULocalPlayer::GetSubsystem<UEnhancedInputLocalPlayerSubsystem>(PC->GetLocalPlayer()))
{
    // PawnClientRestart can run more than once in an Actor's lifetime, so start by clearing out any leftover mappings.
    Subsystem->ClearAllMappings();

    // Add each mapping context, along with their priority values.Higher values take priority over lower values.
    Subsystem->AddMappingContext(MyInputMappingContext, MyInt32Priority);
}

入力マッピング コンテキストが追加されると、ポーンは SetupPlayerInputComponent またはユーザーが設定したブループリント スクリプティングで、バインドした入力アクション イベントに応答できるようになります。使用可能な入力マッピング コンテキストのセットの変更を保証するイベントがゲームプレイ中に発生する場合、ClearAllMappings、AddMappingContext、および RemoveMappingContext を使用して使用可能なコマンドのセットを動的に更新することができます。 詳細については、Plugins/EnhancedInput/IEnhancedInputSubsystemInterfaceIEnhancedInputSubsystemInterface API リファレンス ページを参照してください。

入力モディファイア

入力モディファイアは、UE4 が受け取る raw 入力の値を、入力トリガーに送信する前に変更するプリプロセッサーです。Enhanced Input プラグインは、軸の順序を変更したり、「デッド ゾーン」を実装したり、軸入力をワールド空間に変換したり、その他のタスクを実行するための様々な入力モディファイアを備えてリリースされています。入力マッピング コンテキスト内の入力アクションに関連付けられた各入力は、その入力の 1 つまたは複数の入力トリガーに進む前に、ユーザー定義の一連の入力モディファイアによって調整されます。入力モディファイアはリストされている順に適用され、各入力モディファイアからの出力値が次の入力値になります。 Enhanced Input プラグインに装備されている入力モディファイアのコンプリート リストについては、Plugins/EnhancedInput/UInputModifierUInputModifier API リファレンス ページを参照してください。自分のプロジェクトでまだ提供されていない入力モディファイアが必要な場合は、独自の UInputModifier クラスを作成することができます。

入力トリガー

入力トリガーは、ユーザー入力が入力モディファイアのオプション リストで調整された後、その入力マッピング コンテキスト内で対応する入力アクションをアクティブにするかどうかを決定します。ほとんどの入力トリガーは入力自体を分析します。つまり、最小有効化値を確認して、短いタップ、長押し、または通常の「押す」または「離す」イベントなどのパターンを検証します。このルールの 1 つの例外として、[Chorded Action (コード アクション)] 入力トリガーがあります。デフォルトでは、入力に対するユーザー アクティビティは、ティックごとにトリガーされます。 Enhanced Input プラグインに装備されている入力トリガーの完全なリストについては、Plugins/EnhancedInput/UInputTriggerUInputTrigger API リファレンス ページを参照してください。Enhanced Input プラグインで提供されていない入力トリガーが必要な場合は、独自の UInputTrigger クラスを作成することができます。