Enhanced Input に関数は沢山ありますが、調べても日本語の情報があまり見つからなかったので私なりに検証した内容をまとめています。
相変わらずですが間違ったことを書いてる可能性がございますのでご注意下さいませ。
C++(ヘッダ/ソース)ファイルの場所
UE5.0 のデフォルトのインストール先：
C:\Program Files\Epic Games\UE_Version\Engine\Plugins\Experimental\EnhancedInput\Source\EnhancedInput
UE5.1 以降のデフォルトのインストール先：
C:\Program Files\Epic Games\UE_Version\Engine\Plugins\EnhancedInput\Source\EnhancedInput
(UE5.1 以降で Experimental でなくなったためファイルパスが変更されています)
上記ファイルパスまで移動し
「Private」に ".cpp"
「Public」に ".h" が入ってました。
その中の EnhancedInputSubsystemInterface.h(.cpp)、EnhancedInputLibrary.h(.cpp) にこの先出てくる関数が確認できました。
IMC の大事な仕様(2023-12-07 文面を修正)
個人的に結構大事な仕様だなと思ったのと、マニュアルに書いてなさそうだったので追記しました。
IMC を開くと一番上に Mappings という項目があり、その横の [+] ボタンをクリックすることで入力アクションやキー入力の割り当てが出来るようになっています。
この情報は IMC の「Get Mappings」から配列で取得でき、型は Enhanced Action Key Mapping構造体 になっています。
この IMC に対して例えば「Unmap All(後述)」を使うと IMC の中に割り当てた Mappings を全て削除することができますが、Blueprint からIMC を直接書き換えた場合、上書き保存を示すマーク「*」が付きません。
そのためプロジェクトを再起動する時に保存が聞かれることもないですし、プロジェクトを再起動後は「Unmap All」する前の状態に戻っています。これはパッケージ化したゲームでも同じ挙動になっています。
この挙動はバグではなく仕様とのこと。
Unreal Engine Issues にて「ゲームプレイ中に行われたInputMappingContextへの変更は、エンジンを再起動すると以前の状態に戻ります」という報告があります。
By Design と記載されており仕様のようです。
IMC を直接書き換えた後、起動中は問題ないですが、ゲームを起動し直す時には注意が必要ということになります。
以前アップロードした動画でキーコンフィグを実装する際、IMC を直接書き換える方法で紹介しましたが、上記理由から IMC を書き換えるキーコンフィグはやめておいた方がいいかなと思いました。
そのため、Enhanced Input でキーコンフィグを実装する場合は、SaveGameObject で割り当てたキーを保存するようにしておき、ゲーム起動時にその情報をロード＞ 後述の「Add Player Mapped Key」を使って表面上キーを置き換える方がいいかなと思います。
※UE5.3で非推奨な機能となり利用できなくなっています
以降は過去に検証などを行った関数をまとめたものです。
Has Mapping Context
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/MappingQueries/HasMappingContext/
Enhanced Inbput Local Player Subsystem に "Mapping Context" で指定した IMC が追加されているかを確認する関数です。
True でその IMC は追加されていて、
False でその IMC は未追加であることが分かります。
「Add Mapping Context」されているか確認したい時に利用できそうです。
Query Keys Mapped to Action
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/MappingQueries/QueryKeysMappedtoAction/
"Action" で指定した「入力アクション」のキーすべてが "Return Value" の Key構造体の配列で返ってきます。
例えば "Action" に IA_Jump を設定し、IMC に割り当てた IA_Jump が、画像のように三つのキーで設定されていた場合は "Return Value" の Key構造体の配列には下記のように割り当てた順番で返ってきます。
Key構造体[0]：「スペースバー」
Key構造体[1]：「マウスの右ボタン」
Key構造体[2]：「T」
この関数には IMC の指定はなく、入力アクションのみ指定しています。
IA_Jump を利用している複数の IMC があると配列の中身がどうなるか気になります。
そこで「IMC_A」「IMC_B」と二つの IMC を用意してみました。
検証1：Priority で優先順位を与えた場合
IMC_A と IMC_B に画像のような "Priority" を与えています。(「Add Mapping Context」する時の "Priority" のことです)
- 「Print String」で配列の中身を出力したところ、Priority の高い IMC から先に配列に格納されていることが確認できました。(「Print String」の出力は下の方が先に処理されています)
- IA_Jump で設定した順番で配列に格納されていることも確認できます。また、IMC_B の4キーとKキーの位置を入れ替えた場合は配列の中身もそれに合わせて出力されていました。
- 重複したキー(スペースバー)が見つかった場合、2回目は出力されていないことも確認できます。
重複したキーがあった場合、Priority の高い方が先に配列に入り、低い方は無視されるといった結果になっていました。
検証2：同じ Priority の場合
- 後から「Add Mapping Context」した方が先に配列に格納されたことが確認できました。
- こちらも同じく重複したキーがあった場合2回目は無視されます。
IMC_A だけ「Add Mapping Context」した場合は IMC_B の結果は配列に入りませんでした。「Has Mapping Context」が True を示すもの(現在有効な IMC) のみに対して作用するということです。
Query Map Key in Active Context Set(2023-03-20追記)
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/MappingQueries/QueryMapKeyinActiveContextSet/
何を行うための関数なのか分かりませんでした...
一応リストに載せてたのでそのまま残しています。
Query Map Key in Context Set(2023-03-20追記)
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/MappingQueries/QueryMapKeyinContextSet/
何を行うための関数なのか分かりませんでした...
一応リストに載せてたのでそのまま残しています。
Break Input Action Value
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/BreakInputActionValue/
Input Action Value 構造体("In Action Value")を、X, Y, Z に分解する。サポートされてない値(軸)は 0 が返ってきます。
軸を扱う入力を分解するようなので
「Break Vector」に似たような扱いでしょうか。
Make Input Action Value
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/MakeInputActionValue/
XYZ の値を使って Input Action Value構造体を作成します。
"Match Value Type" が参照渡しになっており、接続しないと有効なインプットが必要とエラーが出ます。
利用されてない軸には 0 が設定(無視)されるようです。
既存の Input Action Value を変更することを目的としているようです。後述の「Inject Input for Action」「Inject Input Vector for Action」などと組み合わせて使ったりできそうでした。
Inject Input for Action(2023-01-19追記)
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/InjectInputforAction/
"Action" に繋いだ指定の入力アクションへのトリガーを "Raw Value" の値に応じてシミュレートするような使い方になりそうです。
"Modifiers" や "Triggers" も考慮したシミュレートをしたい場合は必要に応じて設定できます。
例えば "Action" に IA_Jump を設定し、"Raw Value" に前述の「Make Input Action Value」を使って Input Action Value構造体を渡します。
これでプレイしてみると1キーを押した時に入力アクション IA_Jump がトリガーされジャンプしたことになります。
この関数に IMC を指定するところはありませんが、「Has Mapping Context」が True を示すもの(現在有効な IMC) が対象になります。
この入力アクションを何らかの理由でトリガーしたことにしたい時に使えそうな気はしましたが、そういうシチュエーションを思いつかなかったので例を挙げることができませんでした。
Inject Input Vector for Action(2023-01-19確認)
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/InjectInputVectorforAction/
上記「Inject Input for Action」の Vector 入力が取れるバージョンです。
これも入力アクションのシミュレートをしたりなどに使えるんだと思いますが、そういうシチュエーションが想定できず...
Request Rebuild Control Mappings(2023-05-31修正)
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/RequestRebuildControlMappings/
"Rebuild Type" で指定した内容に沿って IMC の再構築を行います。
この関数は「Add Mapping Context」「Remove Mapping Context」「Clear All Mappings」などの、IMC を更新する関数で利用されてました。
そのため、IMC 自体をなんらかの手段で変更する場合は、この関数を使って更新する必要があります。
一例ですが、ゲーム中のキーコンフィグでユーザが入力したキーに変更するといった処理を実装したとします。
IMC に登録している Mappings(Enhanced Action Key Mapping構造体)を参照で取得してメンバ内を直接書き換える実装をした場合、IMC のファイル上は変更されますが、「Request Rebuild Control Mappings」が呼ばれないとゲーム内では反映されませんでした。
先程挙げたような Blueprint に公開されている関数内で「Request Rebuild Control Mappings」が呼ばれているものを使った場合は問題ないですが、特に手動で IMC を触ることをした場合は、ゲーム内だけで見ると反映してないように感じるので注意が必要です。
再構築を行う対象は「Enhanced Input Local Player Subsystem」が持つ IMC すべてに実行されます(前述の「Has Mapping Context」が True を示すものが対象です)
"Options" は「Add Mapping Context」などに出てきた "Modify Context Options 構造体" です。
ピンを分割(もしくはBreak)して表示される "Ignore All Pressed Keys Until Release" は True にしておく方がいいかもしれません。
"Options" については 以前の検証記事(Ignore All Pressed Keys Until Release) をご覧ください。
"Rebuild Type" は EInputMappingRebuildType という Enum 値を指定します。
Rebuild：一般的な再構築ならこれでいいと思います。各入力アクションの Triggers/Modifiers などの情報がそのまま保持されます。
キーコンフィグでは一般的にユーザが入力したキーを入れ替えるだけで良さそうなのでメインはこれになりそうな気がします。
RebuildWithFlush：
「入力アクション」自体の Triggers/Modifiers など変更を加えた場合、上記 Rebuild だけでは再構築されないようです。
一度フラッシュを行い、そこから再構築という流れを取ってる感じがします。キー以外の変更を伴う場合のオプションではないかと思います。
Map Key
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Mapping/MapKey/
”ターゲット” に指定した IMC 内で、"Action" に指定した入力アクションを対象に "To Key" で指定したキーの割り当てを追加します。
例えばこの画像の場合 ”ターゲット” で指定した IMC の中にある IA_Jump に対して Bキーを追加するという挙動になります。
「Map Key」の注意点は、割り当てるキー("To Key")に関しては重複チェックはされていないようで、「Map Key」を呼ぶたびに上の画像のようにキーが追加され続けるので注意です。
キーが追加されるだけなので Triggers/Modifiers のようなオプションなどは考慮されません。
Unmap Action
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Mapping/UnmapAction/
”ターゲット” に指定した IMC 内で、"Action" に指定した入力アクションを丸ごと削除します。
例えばこの画像のような設定で "Action" に IA_Jump を指定した場合、入力アクション(IA_Jump)ごと消えていることが確認できます。
Undo(Ctrl + Z) が効かないみたいなので、動作確認する時はファイルコピー推奨です。
Unmap Key
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Mapping/UnmapKey/
”ターゲット” に指定した IMC 内で、"Action" に設定した入力アクションを対象に、"Key" で指定したキーと同じキーの割り当てがあった場合それだけ削除します。
上記「Unmap Action」に、追加でキーを指定できるバージョンです。
例えばこの画像の場合、"Action" に IA_Jump、"Key" にスペースバーを指定した場合、スペースバーだけが削除されます。
"Action" や "Key" を指定しない場合は、対象の入力アクションやキーがないため削除されませんでした(何も起こらない)
Undo(Ctrl + Z) が効かないみたいなので、動作確認する時はファイルコピー推奨です。
Unmap All
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Mapping/UnmapAll/
”ターゲット” に指定した IMC のマッピングを全てクリアする。
入力の割り当てを綺麗にする効果です。
Undo(Ctrl + Z) が効かないみたいなので、動作確認する時はファイルコピー推奨です。
Clear All Mappings(2023-07-07追記)
▼ 公式ドキュメント
https://docs.unrealengine.com/5.1/en-US/BlueprintAPI/Input/ClearAllMappings/
「Add Mapping Context」で追加された IMC を全て削除する。
例えばゲーム中にリトライや、タイトル画面からやり直すなどした場合に、実装によっては余分な IMC が追加されている可能性があるため、一度すべて削除して必要な IMC だけ再登録するような処理などに使えそうです。
Add Player Mapped Key(2023-05-31修正)
※UE5.3で非推奨な機能となり利用できなくなっています
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/PlayerMappable/AddPlayerMappedKey/
"Mapping Name" に指定した名前と一致する名前を探し、見つかった場合そのキーを "New Key" に置き換えます。
実行中、一時的にキーを変更したい時に利用する関数みたいです。
一致する名前が複数ある場合、そのキー全てが置き換えられます。
"Mapping Name" の名前というのは IMC で割り当てた各入力アクションの中にある Player Mappable Options 内の "Name" がここに該当します。
上記二つの画像が示す挙動は、有効な IMC に "JumpMappable" という名前があるかを確認し、一致した名前があった場合、その名前をすべてチェックします。
そして、IA_Jump に割り当たっているスペースバーに "JumpMappable" という名前が見つかったので、"New Key" に指定した「5キー」がジャンプのキーに置き換わります。
例えば IA_Jump にスペースバーと左クリックが割り当たっていて、両方 "JumpMappable" という名前にしていた場合、この二つのキーが両方「5キー」になります。
入力アクションを跨いでも同じ効果があるため IA_Shoot に "JumpMappable" という名前を設定したらこれも置き換わります。
"Mapping Name"に同じ名前を指定するケースがあるのか分かりませんが、もし同じ名前にした場合は「Add Mapping Context」で指定する Priority が高い方が優先される挙動になっていました。
また、IMC 自体を直接編集している訳ではないみたいです。
(IMC を開いたままゲーム中の挙動を確認しても IMC 自体には何の変化もありませんでした)
前述の「Request Rebuild Control Mappings」を使ったあと、ゲームを起動し直しても IMC 自体は書き換わっていませんでしたので置き換えると表現しています。
キーコンフィグに利用する場合は、Save Game Object を利用してキーコンフィグしたキーを保存し、ロード時にその情報を使ってこの関数で置き換えるような実装でキーコンフィグが実現できそうです。
戻り値の "Return Value" は置き換えられたマッピングの数を Intger型で返すそうですが、複数あっても1しか返ってこなかったためよく分かりませんでした。
"Options" は Modify Context Options構造体です。
Options については 以前の検証記事(Ignore All Pressed Keys Until Release) をご覧下さい。
Get Player Mapped Key(2023-05-31追記)
▼ 公式ドキュメント
＜見つからず＞
前述の「Add Player Mapped Key」にて置き換えられたキーを取得する関数で、この関数だけ単体で使っても(多分)None しか返ってこないです。
ここで指定する "Name" は前述の「Add Player Mapped Key」の引数にある "Mapping Name" と同じ名前を指定します。
「Add Player Mapped Key」で置き換えたあと、そのキーだけ取得したい場合に利用できます。
Add Player Mappable Config(2023-03-20追記)
▼ 公式ドキュメント
https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/Input/PlayerMappable/AddPlayerMappableConfig/
"Config" に指定の "Player Bindable Input Config" を追加します。
UE5.1 だと名称が変更されており、Player Mappable Input Config になっています。
"Player Bindable Input Config" / "Player Mappable Input Config" についてどういうファイルなのかは別記事で簡単にまとめました。
Get All Player Mappable Action Key Mappings(2023-05-31追記)
▼ 公式ドキュメント
＜見つからず＞
"Is Player Mappable" が ON になっているキーだけを取得出来る関数ですが、取得可能な範囲は「Has Mapping Context」が True を示すもの(現在有効な IMC) が対象になります。
キーコンフィグ可能なキーだけ取得できる凄い関数ですが、前述の通り現在有効な IMC に設定された "Is Player Mappable" のキーのみ取得されます。
例えば乗り物に乗った時だけそれ用のキーを割り当てた IMC を追加するような実装をしていた場合は、キーコンフィグ時に乗り物に乗ってないと「Add Mapping Context」されていないのでそのキーが取得できない状態が予想されます。
これを解決できるアセットが用意されています。
別記事にて紹介している"Player Bindable Input Config" / "Player Mappable Input Config" に簡単な使い方をまとめています。
"Is Player Mappable" というフラグは IMC を開き、各入力のキー割り当てを展開すると出てくるフラグのことです。
このフラグにチェックを入れたあと保存してエラーが出た場合、"Player Mappable Options" を展開すると出てくる "Name" に好きな名前を入れておきます。
例えば移動キーで使われる WASD のキーで A と D だけ "Is Player Mappable" にチェックを入れ、上記の画像のように1キーを押してこの情報を出力した結果がこれです。
「Add Mapping Context」で複数の IMC が有効になっている場合はそれらも含まれます。
ややこしすぎるって...
