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

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` リスト内のすべてのパラメータの型を決定する 1 つのパラメータを示します。
`AutoCreateRefTerm="Parameter1, Parameter2, .."`	リストされているパラメータは参照によって渡されますが、ピンが未接続のままになっている場合は、デフォルトが自動的に作成されます。これはブループリントの便利な機能であり、配列ピンでよく使用されます。
`BlueprintAutocast`	ブループリント関数ライブラリの静的な `BlueprintPure` 関数によってのみ使用されます。関数の戻り値の型と最初のパラメータの型に対して、キャストノードが自動的に追加されます。
`BlueprintInternalUseOnly`	この関数は、別の関数またはノードを実装するために使用される内部実装の詳細です。ブループリントグラフでは直接公開されることはありません。
`BlueprintProtected`	この関数は、ブループリント内の所有オブジェクトに対してのみ呼び出すことができます。別のインスタンスでは呼び出すことができません。
`CallableWithoutWorldContext`	クラスが `GetWorld` 関数を実装していなくても関数を呼び出すことができることを示す、`WorldContext` ピンを持つ `BlueprintCallable` 関数に使用されます。
`CommutativeAssociativeBinaryOperator`	`BlueprintCallable` 関数が Commutative Associative Binary ノードを使用する必要があることを示します。このノードにはピン名がありませんが、追加の入力ピンを作成する [Add Pin (ピンの追加)] ボタンがあります。
`CompactNodeTitle="Name"`	`BlueprintCallable` 関数をコンパクト表示モードで表示することを示し、そのモードで表示する名前を提供します。
`CustomStructureParam="Parameter1, Parameter2, .."`	リストされているパラメータはすべてワイルドカードとして扱われます。この指定子には、`UFUNCTION` レベルの指定子 `CustomThunk` が必要です。これは、ユーザーに対してカスタム `exec` 関数の提供を求めます。この関数では、パラメータの型をチェックし、そのパラメータの型に基づいて適切な関数呼び出しを行うことができます。ベース `UFUNCTION` の呼び出しは避けてください。呼び出された場合は、アサートが発生するかエラーがログに記録されます。カスタム `exec` 関数を宣言するには、`MyFunctionName` が元の関数の名前である構文 `DECLARE_FUNCTION(execMyFunctionName)` を使用します。
`DefaultToSelf`	`BlueprintCallable` 関数の場合、これは、オブジェクトプロパティの名前付きデフォルト値がノードの self コンテキストである必要があることを示します。
`DeprecatedFunction`	この関数へのブループリント参照が発生すると、関数が非推奨であることをユーザーに通知するコンパイル警告が発生します。`DeprecationMessage` メタデータ指定子を使用して、非推奨の警告メッセージに追加することができます (たとえば、非推奨の関数を置き換える手順を提供するなど)。
`DeprecationMessage`="Message Text"	関数が非推奨の場合、それを使用するブループリントをコンパイルしようとしたときに、このメッセージが標準の非推奨警告に追加されます。
`DeterminesOutputType="Parameter"`	関数の戻り値の型は、名前付きパラメータピンに接続されている入力に合わせて動的に変更されます。パラメータは `TSubClassOf<X>` または `TSoftObjectPtr<X>` のようなテンプレート化された型である必要があります。ここで、関数の元の戻り値の型は `X`、または `TArray<X>` などの値の型として `X*` を持つコンテナです。
`DevelopmentOnly`	`DevelopmentOnly` としてマークされた関数は Development モードでのみ実行されます。これは、シッピングされた製品には存在しないことが予想されるデバッグ出力などの機能に対して役立ちます。
`DisplayName="Blueprint Node Name"`	ブループリント内のこのノードの名前は、コードによって生成された名前ではなく、ここで指定された値に置き換えられます。
`ExpandEnumAsExecs="Parameter"`	`BlueprintCallable` 関数で、パラメータによって使用される `enum` のエントリごとに 1 つの入力実行ピンを作成する必要があることを示します。パラメータは、`UENUM` タグを持つ列挙型である必要があります。
`ForceAsFunction`	イベントからの戻り値のない `BlueprintImplementableEvent` を関数に変更します。
`HidePin="Parameter"`	`BlueprintCallable` 関数で、パラメータピンをユーザーのビューから非表示にする必要があることを示します。この方法では、機能ごとに 1 つのピンのみを非表示にできます。
`HideSelfPin`	関数が呼び出されるオブジェクトを示す「self」ピンを非表示にします。呼び出し元のブループリントのクラスと互換性のある `BlueprintPure` 関数では、「self」ピンは自動的に非表示になります。`HideSelfPin` メタタグを頻繁に使用する関数では、`DefaultToSelf` 指定子も使用されます。
`InternalUseParam="Parameter"`	`HidePin` と同様に、これは名前付きパラメータのピンをユーザーのビューから非表示にし、関数ごとに 1 つのパラメータにのみ使用できます。
`KeyWords="Set Of Keywords"`	ブループリントグラフで関数を呼び出すノードを配置するときなど、この関数を検索するときに使用できるキーワードのセットを指定します。
`Latent`	潜在的なアクションを示します。潜在的なアクションには `FLatentActionInfo` 型のパラメータが 1 つあり、このパラメータは `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` 関数によって使用され、操作が行われるワールドを決定するパラメータを示します。
`ScriptName="DisplayName"`	このクラス、プロパティ、または関数をスクリプト言語にエクスポートするときに使用する名前。非推奨の名前を、セミコロンで区切った追加のエントリとして含めることができます。

関数パラメータ指定子

パラメータ指定子説明

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 回ダメージを与えたい場合があります。このようなアクションは、タイマーを使用することで実現できます。

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