概要
この記事では、今年2023年に新卒ゲームプログラマとして働き始めた、Unreal Engine 初心者である筆者が UPROPERTY の一覧を見て、使ったことがない、もしくはあまりないけど、便利そうで今後使えそうだなと思った UPROPERTY をまとめて、紹介させていただきます。
この記事の主な対象者
- Unreal Engine の C++ 初心者の方
UPROPERTY
DisplayName
UPROPERTY( meta = (DisplayName = "[Blueprintエディタでの表示名]") )
Blueprintのイベントグラフや、詳細パネルで表示される変数名を、指定した名前にすることができます。
「プログラマのみが見るプログラムではより詳細な変数名にしておきたいけど、プログラマ以外の人が見るエディタでは、わかりやすさ重視の名前にしたい」というようなときに使えると思います。
// Playerの1秒間当たりの移動量
UPROPERTY( BlueprintReadWrite, EditAnywhere, meta = (DisplayName = "Player Speed") )
FVector PlayerVelocitySec = FVector::ZeroVector;
DisplayPriority
UPROPERTY( meta = (DisplayPriority = [表示の優先度]) )
エディタの詳細パネルにおける表示順の優先度をつけることができ、優先度の値が小さいほど、上に表示されます。
「DisplayPriority」をつけていない状態だと、ヘッダファイルで宣言した順番通りに表示されます。
例)
UPROPERTY( EditDefaultsOnly, meta = (DisplayPriority = 1) )
int NumPriority1 = 0;
UPROPERTY( EditDefaultsOnly, meta = (DisplayPriority = 0) )
int NumPriority0 = 0;
UPROPERTY( EditDefaultsOnly )
int NumPriorityNone1 = 0;
UPROPERTY( EditDefaultsOnly )
int NumPriorityNone0 = 0;
EditCondition
UPROPERTY( meta = (EditCondition = "[編集できるときの条件式]") )
「EditCondition」プロパティで指定した条件式を満たしていないときは、下図のように「EditCondition」プロパティをつけた変数をエディタ上で編集できない状態になります。
例)
// 攻撃力
UPROPERTY( EditAnywhere )
float AttackPower = 10.0f;
// 攻撃力が100以上ある場合、必殺技を使わせることもできる
UPROPERTY( EditAnywhere, meta = (EditCondition = "AttackPower >= 100.0") )
bool bCanUseSpecialAttack = false;
InlineEditConditionToggle
UPROPERTY( meta = (InlineEditConditionToggle) )
下のように「EditCondition」プロパティと組み合わせて使用します。
「InlineEditConditionToggle」プロパティをつけたbool変数を「EditCondition」プロパティに指定すると、「InlineEditConditionToggle」プロパティをつけたbool変数と「EditCondition」プロパティをつけた変数が結びつき、エディタ上では1行で表示されます。
例)
// 攻撃をできるならばtrue
UPROPERTY( EditAnywhere, meta = (InlineEditConditionToggle) )
bool bCanAttack = true;
// 攻撃できるなら、攻撃力を設定できるようにする
UPROPERTY( EditAnywhere, meta = (EditCondition = "bCanAttack") )
float AttackPower = 10.0f;
(上図の赤丸のチェックボックスが「bCanAttack」となっています。「bCanAttack」がtrueになっていないと、「AttackPower」は編集できません。)
Multiple
UPROPERTY( meta = (Multiple = [倍数の値]) )
エディタの詳細パネル上で、指定した倍数の値になるように補正がかかります。
例)
偶数の値だけが入るように、2の倍数の値になるようにします。
// 2の倍数、0以上の整数値
UPROPERTY( BlueprintReadWrite, EditAnywhere, meta = (ClampMin = 0, Multiple = 2) )
int EvenNum = 0;
下図のように、エディタの詳細パネル以外の場所からは、指定した倍数の値にするための補正はかからないので、注意します。
ForceUnits
UPROPERTY( meta = (ForceUnits = "[値の単位]") )
特定の単位の値になるように、補正を書けることができます。
使用できる単位については、株式会社ヒストリア様が下記の記事にまとめてくださっていたので、下記の記事を参考にされると良いと思います。
例)
// 走り続けられる時間の最大値(秒)
UPROPERTY( EditAnywhere, meta = (ClampMin = 0, ForceUnits = "s") )
float MaxRunningTime = 0;
変数名のsuffix(接尾語)に「Sec」などの単位をつけなくても、エディタ上に単位が表示されてわかりやすくなるので、変数名をすっきりさせることができるとともに、見やすくできそうと思いました。
MultiLine
UPROPERTY( meta = (MultiLine = true) )
「Shift + Enter」で、改行して入力することができるようになります。
UPROPERTY( EditAnywhere, meta = (MultiLine = true) )
FString TalkText = "";
TitleProperty
UPROPERTY( meta = (TitleProperty = "[タイトルとして使用する構造体の中の変数名]") )
構造体の配列などに使用します。
エディタ上の配列の要素の見出しに、指定した構造体の中の変数名に設定された値が表示されるようになります。
例)
USTRUCT( BluepritType )
struct FCharacterStatus
{
GENERATED_BODY()
public:
UPROPERTY( EditDefaultsOnly )
FString Name = "";
UPROPERTY( EditDefaultsOnly )
int HP = 10;
UPROPERTY( EditDefaultsOnly )
int AttackPower = 10;
}
UPROPERTY( EditAnywhere, meta = (TitleProperty = "Name") )
TArray<FCharacterStatus> StatusArray;
AllowPreserveRatio
UPROPERTY( meta = (AllowPreserveRatio) )
FVectorなどにおいて、ほかの入力できる項目との比率を保った状態で値を編集できるようになります。
例)
UPROPERTY( EditAnywhere, meta = (AllowPreserveRatio) )
FVector TestScale = FVector::ZeroVector;
BlueprintSetter、BlueprintGetter
UPROPERTY( BlueprintGetter = [値を取得するのに使用する関数名], BlueprintSetter = [値をセットするのに使用する関数名] )
例)
UPROPERTY( EditAnywhere, BlueprintReadWrite, BlueprintSetter = SetTalkText, BlueprintGetter = GetTalkText )
FString TalkText = "";
// イベントグラフ上でTalkText変数に文字列を代入するときに呼ばれる関数
UFUNCTION(BlueprintSetter)
void SetTalkText(FString text);
// イベントグラフ上でTalkText変数から文字列を取得するときに呼ばれる関数
UFUNCTION(BlueprintGetter)
FString GetTalkText();
void ATestActor::SetTalkText(FString text)
{
TalkText = "Hello " + text;
}
FString ATestActor::GetTalkText()
{
return TalkText + " !!";
}
(「ATestActor」クラスは、テスト用に作成したアクタのクラスです。)
上のような処理を実装したとき、下のようなノードを組むと、セットノードを呼んだときに SetTalkText 関数が呼ばれ、ゲットノードを呼んだときに GetTalkText 関数が呼ばれるので、下のように出力されます。
ExposeOnSpawn
UPROPERTY( meta = (ExposeOnSpawn = true) )
アクタをスポーンするノードに、入力ピンとして追加されるようになります。
「BlueprintReadOnly」か「BlueprintReadWrite」をつけないと、エラーが出るので注意しましょう。
UPROPERTY( EditAnywhere, meta = (ExposeOnSpawn = true) )
float LifeTime = 30.0f;
(上の変数を定義したクラスは、テスト用に作成した「ATestActor」クラスです。)
Categories
UPROPERTY( meta = (Categories = "表示したいGameplayTagのカテゴリ名") )
GameplayTagをエディタで指定するとき、指定したGameplayTagのカテゴリ以外のGameplayTagが表示されなくなります。
例)
// 「Categories」をつけない場合
UPROPERTY( EditAnywhere )
FGameplayTag TestTag = FGameplayTag::EmptyTag;
// 「Categories」をつけて、「Test1」カテゴリしか表示しないようにした場合
UPROPERTY( EditAnywhere, meta = (Categories = "Test1") )
FGameplayTag TestTagWithCategories = FGameplayTag::EmptyTag;
「Categories」をつけた変数の方は、下図の右のように指定したカテゴリのGameplayTagのみを表示し、不要なカテゴリを表示しないようにできます。
(GameplayTagはテスト用に適当に用意したものです。)
Interp
UPROPERTY( Interp )
シーケンサー内のタイムラインで、値を編集できるようになります。
参考文献
(1) ben🌱ui , "All UPROPERTY Specifiers · ben🌱ui", https://benui.ca/unreal/uproperty/, (参照 2023-12-11)
(2) 株式会社ヒストリア, [UE5]プロパティの数値入力欄に単位を追加しよう, https://historia.co.jp/archives/36394/, (参照 2023-12-12)