Unreal Engine の UFunctions | Unreal Engine 5.2 ドキュメンテーション

UFunction の宣言

UFunction は、Unreal Engine リフレクションシステムで認識される C++ 関数です。UObject またはブループリント関数ライブラリは、ヘッダファイルの関数宣言の上の行に UFUNCTION マクロを入れることにより、メンバー関数を UFunction として宣言することができます。このマクロは、Unreal Engine の関数の解釈と使用方法を変更するために 関数指定子 をサポートします。

	UFUNCTION([specifier1=setting1, specifier2, ...], [meta(key1="value1", key2, ...)])
	ReturnType FunctionName([Parameter1, Parameter2, ..., ParameterN1=DefaultValueN1, ParameterN2=DefaultValueN2]) [const];

関数指定子を使用すると、UFunctions をブループリントビジュアルスクリプティンググラフに公開することができ、デベロッパーは C++ コードを変更せずにブループリントアセットから UFunctions を呼び出したり、拡張したりすることができます。

UFunctions はクラスのデフォルトプロパティでデリゲートにバインドすることができ、アクションをユーザー入力に関連付けるタスクなどを実行させることができます。また、ネットワークコールバックとしても機能することができます。つまり、UFunction を使って通知を受け取り、任意の変数がネットワーク更新の影響を受けるたびにカスタムコードを実行することができます。

さらに、開発ビルドでゲームコンソールから呼び出すことができる独自の「コンソールコマンド」(「デバッグ」コマンド、「構成」コマンド、「チートコード」コマンドなどと呼ばれます) を作成したり、レベルエディタでカスタム機能のあるボタンをゲームオブジェクトに追加したりすることも可能です。

関数指定子

関数を宣言する場合に、エンジンおよびエディタの様々な部分で関数がどのように動作するのかを制御する 関数指定子 を宣言に追加することができます。

関数指定子	効果
`BlueprintAuthorityOnly`	ネットワーク権限を持つマシン上で (サーバー、Dedicated サーバー、シングルプレイヤーゲーム) 実行されている場合、この関数はブループリントのコードからのみ実行されます。
`BlueprintCallable`	この関数はブループリントあるいは Level ブループリントグラフで実行可能です。
`BlueprintCosmetic`	この関数は表面上のもので、Dedicated サーバー上では実行されません。
`BlueprintImplementableEvent`	この関数はブループリントあるいは Level ブループリントグラフで実行可能です。
`BlueprintNativeEvent`	この関数はブループリントによってオーバーライドされる設計となっていますが、デフォルトのネイティブの実装もあります。メインの関数と同じ名前の関数を追加で宣言しますが、最後に `_Implementation` が付加されます。これは、どこにコードが書き込まれるかを示しています。自動生成されたコードは、ブループリントのオーバーライドが見つからなければ、`_Implementation` メソッドを呼び出します。
`BlueprintPure`	この関数は所有するオブジェクトに決して影響することはなく、ブループリントあるいは Level ブループリントグラフで実行可能です。
`CallInEditor`	この関数は、 [Details(詳細)] パネルのボタンを使ってエディタで選択したインスタンス上で呼び出すことができます。
`Category = "TopCategory\\|SubCategory\\|Etc"`	ブループリント編集ツールに表示されるときの関数のカテゴリを指定します。\| 演算子を使用してネストされたカテゴリを定義します。
`Client`	この関数は、関数が呼び出されるオブジェクトを所有するクライアント上でのみ実行されます。メインの関数と同じ名前の関数を追加で宣言しますが、最後に `_Implementation` が付加されます。自動生成されたコードは、必要に応じて、`_Implementation` メソッドを呼び出します。
`CustomThunk`	`UnrealHeaderTool` のコードジェネレーターはこの関数に対してサンクを生成しません。`DECLARE_FUNCTION` または `DEFINE_FUNCTION` マクロを使って指定するかはユーザー次第です。
`Exec`	この関数は、インゲームのコンソールから実行することができます。特定クラス内で宣言される場合のみ、実行コマンドが機能します。
`NetMulticast`	この関数は、アクタの `NetOwner` に関わらず、サーバー上でローカルで実行、および全てのクライアントにレプリケートされます。
`Reliable`	この関数はネットワーク上でレプリケートされ、帯域幅やネットワークエラーに関係なく届くことが保証されます。`Client` または `Server` と併用時のみ有効です。
`SealedEvent`	この関数はサブクラスでオーバーライドできません。`SealedEvent` キーワードはイベントでのみ使用可能です。イベントではない関数では、 `static` または `final` と宣言してシールします。
`ServiceRequest`	この関数は RPC (リモートプロシージャコール) サービス要求です。これは `NetMulticast` と `Reliable` を暗示します。
`ServiceResponse`	この関数は RPC サービス応答です。これは `NetMulticast` と `Reliable` を暗示します。
`Server`	この関数はサーバー上でのみ実行されます。メインの関数と同じ名前の関数を追加で宣言しますが、最後に `_Implementation` が付加されます。これは、どこにコードが書き込まれるかを示しています。自動生成されたコードは、必要に応じて、`_Implementation` メソッドを呼び出します。
`Unreliable`	この関数はネットワーク上でレプリケートされますが、帯域幅の制約やネットワークエラーが原因で失敗することがあります。`Client` または `Server` と併用時のみ有効です。
`WithValidation`	メインの関数と同じ名前の関数を追加で宣言しますが、最後に `_Validate` が付加されます。この関数は同じパラメータを取り、`bool`を戻して、メイン関数への呼び出しを続行するかどうかを示します。

メタデータ指定子

クラス、インターフェイス、構造体、列挙型変数、列挙型変数の値、関数、プロパティを宣言するときに、メタデータ指定子 を宣言に追加して、エンジンやエディタの様々な側面でどのようにインタラクタするかを制御することができます。データ構造またはメンバのそれぞれの型には、固有のメタデータ指定子のリストがあります。

メタデータはエディタのみに存在しています。メタデータにアクセスするゲームロジックを書かないでください。

関数メタタグ	効果
`AdvancedDisplay="Parameter1, Parameter2, .."`	コンマで区切られたパラメータのリストが詳細ピンとして表示されます (UI の展開が必要)。
`AdvancedDisplay=N`	`N` を数字で置き換えて、N 番めより後のすべてのパラメータが詳細ピンとして表示されます (UI の展開が必要)。たとえば、'AdvancedDisplay=2' は、最初の 2 つのパラメータを除いて advanced としてマーク付けします)
`ArrayParm="Parameter1, Parameter2, .."`	`BlueprintCallable` 関数で Call Array Function ノードを使用し、リストされているパラメータをワイルドカード配列のプロパティとして扱うかを示します。
`ArrayTypeDependentParams="Parameter"`	`ArrayParm` を使用する場合、この指定子は `ArrayParm` リストにあるすべてのパラメータの型を決めるパラメータを示します。
`AutoCreateRefTerm="Parameter1, Parameter2, .."`	リストされているパラメータは参照によって渡されますが、ピンが接続されていなければ自動作成されるデフォルトを持ちます。これは配列ピンで使用されるブループリントの便利な機能です。
`BlueprintAutocast`	ブループリント関数ライブラリから静的な `BlueprintPure` 関数によってのみ使用されます。Cast ノードが自動的に戻り型と関数の最初のパラメータの型に追加されます。
`BlueprintInternalUseOnly`	この関数は内部実装の詳細です。他の関数やノードを実装するために使われます。グラフ内で直接公開されることはありません。
`BlueprintProtected`	この関数は、ブループリントで所有しているオブジェクトでのみ呼び出し可能です。他のインスタンス上での呼び出しはできません。
`CallableWithoutWorldContext`	`WorldContext` ピンを持つ `BlueprintCallable` 関数のために使われ、そのクラスが `GetWorld` 関数を実装していなくても呼び出し可能であることを示します。
`CommutativeAssociativeBinaryOperator`	`BlueprintCallable` 関数が、Commutative Associative Binary ノードを使用すべきであることを示します。このノードにはピン名がありませんが、追加の入力ピンを作成する Add Pin ボタンがあります。
`CompactNodeTitle="Name"`	`BlueprintCallable` 関数をコンパクト表示モードで表示することを示し、モード内で表示する名前を指定します。
`CustomStructureParam="Parameter1, Parameter2, .."`	リストされているパラメータはすべてワイルドカードとして扱われます。この指定子は `UFUNCTION`-レベル指定子、`CustomThunk` を必要とし、カスタム `exec` 関数をユーザーが指定する必要があります。この関数では、パラメータの型をチェック可能で、型に基づき適切な関数呼び出しを行うことができます。ベースとなる `UFUNCTION` は呼び出されません。呼び出された場合はアサートするかエラーを出力します。カスタム `exec` 関数を宣言するには、`DECLARE_FUNCTION(execMyFunctionName)` 記述を使用します (`MyFunctionName` は元の関数名)。
`DefaultToSelf`	`BlueprintCallable` 関数では、オブジェクトのプロパティの名前付けしたデフォルト値は、ノードの self コンテキストになります。
`DeprecatedFunction`	ブループリントでこの関数を参照すると、関数が非推奨であることを示すコンパイルに関する警告が出ます。`DeprecationMessage` メタデータ指定子を使って非推奨の警告メッセージに追加することができます (例、非推奨の関数を置き換える旨の指示を表示)。
`DeprecationMessage`="Message Text"	関数が非推奨であると、それを使用するブループリントをコンパイルしようとすると、このメッセージが標準の非推奨の警告に追加されます。
`DeterminesOutputType="Parameter"`	関数の戻り値の型は、指定されたパラメーターピンに接続されている入力に一致するように動的に変更されます。パラメータは `TSubClassOf<X>` または `TSoftObjectPtr<X>` のようなテンプレートタイプでなければなりません。関数の元の戻り値は `X`、または値の型として `X` を持つコンテナです (`TArray<X*>` など)。
`DevelopmentOnly`	`DevelopmentOnly` とマーク付けされている関数は Development モードでのみ実行します。出荷する製品には存在しないデバッグ出力のような機能で役立ちます。
`DisplayName="Blueprint Node Name"`	ブループリント内のこのノード名は、コードが生成する名前の代わりにここで指定する値で置き換えられます。
`ExpandEnumAsExecs="Parameter"`	`BlueprintCallable` 関数で、ある入力実行ピンがパラメータが使用する `enum` で各エントリに対して作成されることを示します。パラメータは、`UENUM` タグを持つ列挙型である必要があります。
`HidePin="Parameter"`	`BlueprintCallable` 関数で、このパラメータピンをユーザーから見えないようにします。この方法では、機能ごとに 1 つのピンのみを非表示にできます。
`HideSelfPin`	"self" ピンを隠します。"self" ピンは関数が呼び出されているオブジェクトを示すために使われます。"self" ピンは `BlueprintPure`関数で自動的に非表示になり、これはブループリントのクラスを呼び出すのに相当します。`HideSelfPin`メタタグを使用する関数は、 `DefaultToSelf`指定子も頻繁に使用します。
`InternalUseParam="Parameter"`	`HidePin` に類似していますが、これは名前付けしたパラメータピンをユーザーから見えなくし、ひとつの関数につきひとつのパラメータに対してのみ使用可能です。
`KeyWords="Set Of Keywords"`	ブループリントグラフで関数を呼び出すノードを配置する場合など、この関数を検索するときに使用可能なキーワード一式を指定します。
`Latent`	潜在的 (latent) アクションを示します。潜在的アクショには、`FLatentActionInfo` 型のパラメータをひとつ持ち、このパラメータは `LatentInfo` 指定子で名前付けされます。
`LatentInfo="Parameter"`	Latent `BlueprintCallable` 関数では、どれが LatentInfo パラメータであるかを示します。
`MaterialParameterCollectionFunction`	`BlueprintCallable` 関数では、マテリアルオーバーライドノードを使わないことを示します。
`NativeBreakFunc`	`BlueprintCallable` 関数では、標準の Break Struct ノードと同じように表示されることを示します。
`NotBlueprintThreadSafe`	ブループリント関数ライブラリでのみ有効です。この関数は、所有しているクラスの一般的な `BlueprintThreadSafe` メタデータの例外として扱われます。
`ShortToolTip="Short tooltip"`	親クラスのピッカーダイアログなどフルツールチップでは長すぎる場合に短いツールチップを使います。
`ToolTip="Hand-written tooltip`	コードコメントから自動的に生成されたツールチップをオーバーライドします。
`UnsafeDuringActorConstruction`	この関数はアクタの構築中には安全に呼び出すことはできません。
`WorldContext="Parameter"`	`BlueprintCallable` 関数によって使用され、オペレーションが起こるワールドをどのパラメータが決めるかを示します。

関数パラメータ指定子

パラメータ指定子説明

Out パラメータを参照渡しとして宣言することで、関数による修正を可能にします。

Optional 任意のキーワードを使用すると、呼び出し元が使いやすいように特定の関数パラメータをオプションにすることができます。呼び出し元が指定しないオプションパラメータの値は、関数によって異なります。たとえば、SpawnActor 関数は任意の位置と回転を取りますが、デフォルトでそれがスポーンしているアクタのルートコンポーネントの位置と回転になります。オプションの引数のデフォルト値は、= [value] を追加することにより指定できます。たとえば、function myFunc(optional int x = -1) です。オプションパラメータに何も値が渡されない場合は、変数タイプのデフォルト値またはゼロ (0, false, "", none など) を使用するケースがほとんどです。

パラメータ指定子	説明
Out	パラメータを参照渡しとして宣言することで、関数による修正を可能にします。
Optional	任意のキーワードを使用すると、呼び出し元が使いやすいように特定の関数パラメータをオプションにすることができます。呼び出し元が指定しないオプションパラメータの値は、関数によって異なります。たとえば、`SpawnActor` 関数は任意の位置と回転を取りますが、デフォルトでそれがスポーンしているアクタのルートコンポーネントの位置と回転になります。オプションの引数のデフォルト値は、`= [value]` を追加することにより指定できます。たとえば、`function myFunc(optional int x = -1)` です。オプションパラメータに何も値が渡されない場合は、変数タイプのデフォルト値またはゼロ (0, false, "", none など) を使用するケースがほとんどです。

デリゲート

デリゲート は、汎用的かつ型安全な方法で C++ オブジェクトでメンバー関数を呼び出すことができます。デリゲートを使用すると、呼び出し元がオブジェクトのタイプを知らない場合でも、任意のオブジェクトのメンバー関数に動的にバインドされ、未来の時間でオブジェクト上に関数を呼び出すことができます。

リファレンスおよび使用方法に関する情報は、「デリゲート」ページを参照してください。

タイマー

タイマー は、アクションを遅らせたり、ある期間にわたってアクションを実行するためのスケジュールを設定できます。たとえば、パワーアップアイテムを取得するとプレイヤーは無敵になり、10 秒後に無敵状態を解除したい場合があります。あるいは、プレイヤーが毒ガスの満ちた部屋を移動する間、毎秒 1 回ダメージを与えたい場合があります。このようなアクションは、タイマーを使用することで実現できます。

リファレンスおよび使用方法に関する情報は、「ゲームプレイタイマー」ページを参照してください。