猫でもわかるUE5のActor Coloration機能

猫でもわかる UE5のActor Coloration機能 Unreal Engine Meetup Connect - Vol.2 - UETipsLT編 #UEMConnect スクワッドスターズ株式会社 岡田 和也

• https://twitter.com/hashtag/UEMConnect?src=hashtag_click

自己紹介 スクワッドスターズ株式会社 シニアプログラマー 岡田 和也 兼 おかず( @pafuhana1213 ) 2023年10月まで Epic Games Japan で サポートエンジニアしてました 今は現職でゲーム開発中！ 仲間募集中です！ご興味のある方はぜひ！ https://squadstars.jp/recruit/

• https://squadstars.jp/
• https://twitter.com/pafuhana1213
• https://squadstars.jp/recruit/

お品書き 1. Actor Colorationってなに？ 2. Actor Colorationの使い方について 3. Custom Actor Colorationプラグインについて

Actor Coloration（カラーレーション） ってなに？

Actor Coloration機能ってなに？ Actorが持つプロパティが 条件を満たしているか否かを 一目で分かるように着色する機能

実は、UE3 ( UDK ) の頃からある機能 https://docs.unrealengine.com/udk/Three/ViewModesJP.html#Property%20Coloration%20(%E3%83%97 %E3%83%AD%E3%83%91%E3%83%86%E3%82%A3%20%E5%BD%A9%E8%89%B2)

• https://docs.unrealengine.com/udk/Three/ViewModesJP.html

突然ですがクイズの時間です！ 次のページにて 「他と何かが異なるActor」が 1つだけあります どれでしょう？

このActorだけ…

Naniteが無効になってました！

こんなん 分かるか！！！

この無理ゲーが求められる場面もある…！ 例：特定のレベルだけ何故か… ● ● ● ● 処理負荷が急に上がる！ 壁を貫通するなどのコリジョン抜けが発生する！ メモリが足りなくてクラッシュする！ などなど どのActor・設定に原因があるのか を 探す旅が始まる…

標準機能である程度「見える化」やプロファイリング可能 ViewMode・ShowFlag Unreal Insights

かゆいところに手が届かないことがしばしば… ● 標準のViewMode・ShowFlagがサポートしていない プロパティに関しては、一目で分かる「見える化」はできない ● Unreal Insightsなどの学習・使用コストが比較的高いツールは 普段の作業中に使うのは少し厳しい（特に非エンジニア） 負債が少しずつ溜まっていき、 作業効率の低下だけでなく、 バグや処理負荷問題などの温床になってしまう…

そんなときに役に立つのが Actor Coloration！

Actor Coloration 特定の条件を満たすプロパティを持つActorを着色する機能 誰でも簡単に、一目で欲しい情報や問題をチェックすることが可能！

「真・女神転生Ⅴ」における開発事例紹介 | UNREAL FEST EXTREME 2022 SUMMER

• https://www.youtube.com/watch?v=OBWecodOoig&t=3662s&ab_channel=UnrealEngineJP

UE4における大規模背景制作事例（コリジョン編） 【UE4を用いた大規模開発事例紹介 ~スクウェア・エニックス様をお招きして~ 2019】

• https://www.docswell.com/s/EpicGamesJapan/5GLG8K-UE4_LargeScaleDevSQEX_Environment_Collision

Actor Colorationを活用して 開発効率を向上 & 問題を早期発見・解決するのが大事！

お品書き 1. Actor Colorationってなに？ 2. Actor Colorationの使い方について 3. Custom Actor Colorationプラグインについて

Actor Colorationの使い方 「設定名」と「着色して可視化する条件」を 設定すればOK！ かんたん！

「着色して可視化する条件」とは ◯◯ クラスが持つ △△ プロパティの値が ▢▢ だったら 例えば「CastShadowが有効」の場合は ◯◯ = PrimitiveComponent △△ = CastShadow ▢▢ = True

「設定名」と「着色して可視化する条件」を設定する手順 ①
下記コードをプロジェクトに追加（Editorモジュールでの実装がオススメ）
UCLASS()
class ●●_API UMyEditorBlueprintFunctionLibrary : public UBlueprintFunctionLibrary
{
GENERATED_BODY()
UFUNCTION(BlueprintCallable)
static void SetPropertyColorationTarget(const FString& PropertyValue,
const FName PropertyName, UClass* BaseClass);

};
void UMyEditorBlueprintFunctionLibrary::SetPropertyColorationTarget
(const FString& PropertyValue, const FName PropertyName, UClass* BaseClass)
{
if(GEditor)
{
FProperty* Property = FindFProperty<FProperty>(BaseClass, PropertyName);
FEditPropertyChain* PropertyChain = new FEditPropertyChain();
PropertyChain->AddHead(Property);
GEditor->SetPropertyColorationTarget( GWorld, PropertyValue, Property, BaseClass, PropertyChain);
}
}

• https://zenn.dev/hakuto_gamedev/articles/a546a185dc02f6

「設定名」と「着色して可視化する条件」を設定する手順 ② EditorUtility系のBPにて実装したノードを配置・実行 PropertyValue = True PropertyName = CastShadow BaseClass = PrimitiveComponent

Property Nameに設定する値 プロパティ右クリックメニューの Copy Internal Name で確認可能

Actor Colorationの有効・無効切り替え ShowFlag.PropertyColoration

落とし穴 あれ、有効にしてもすぐに着色されない… プロパティを一回変更しないと着色されない… 描画処理側に Actor Colorationの設定が変更されたことを 通知する必要がある…( PrimitiveSceneProxy の再生成のため）

通知処理を追加
void UMyEditorBlueprintFunctionLibrary::SetPropertyColorationTarget(const FString& PropertyValue,
const FName PropertyName, UClass* BaseClass)
{
if(GEditor)
{
FProperty* Property = FindFProperty<FProperty>(BaseClass, PropertyName);
FEditPropertyChain* PropertyChain = new FEditPropertyChain();
PropertyChain->AddHead(Property);
GEditor->SetPropertyColorationTarget( GWorld, PropertyValue, Property, BaseClass, PropertyChain);
// レベル上の全Actorに対して通知
for (TActorIterator<AActor> It(GWorld); It; ++It)
{
AActor* Actor = *It;
Actor->MarkComponentsRenderStateDirty();
}
}
}

完成！ 動画リンク

• https://twitter.com/pafuhana1213/status/1781960657304482070

課題・問題点 - C++が必須 - EditorUtilityから処理を実行する必要がある - - Actor Colorationの設定を切り替えるのが面倒 細かい条件設定ができない - やりたい場合は…様々な箇所にエンジン改造が必要

エンジン改造の一例 ( PropertyColor の実装を真似する方針） ● ShowFlagsValues.inl ○ ● PrimitiveDrawingUtils.cpp / h ○ ● 490行目付近：↑で追加したShowFlagの初期値を設定 PrimitiveSceneProxy.h ○ ● cpp 1550行目付近：EngineShowFlags に専用Flagを追加 ShowFlag.h ○ ● 443行目付近：253行目付近にある PropertyColoration のコードをコピペ & 編集 800行目付近：周辺コードを参考に、Set/Get関数を追加 PrimitiveSceneProxy.cpp ○ ○ 1500行目付近：FStaticMeshSceneProxyの386行目付近を参考に、 チェックしたい条件に応じた色を渡す処理を実装 1733行目付近：1670行目付近にあるPropertyColorationのコードをコピペ & 拡張 オプション : プロジェクト / エディタ設定にて Colorationの設定を変更可能に https://historia.co.jp/archives/4095/ https://qiita.com/unknown_ds/items/deb25d510caf665e8289

• https://historia.co.jp/archives/4095/
• https://qiita.com/unknown_ds/items/deb25d510caf665e8289

結果の例：物理マテリアルの Coloration

改造範囲がそこそこ広いし 2000-3000個もビルド処理が走って ほんとうにつらい

ここで朗報

古の機能で枯れ切ってたはずが 突然UE5.4で仕様変更・改善が入りました！ 講演前にこういうのやめて！

UE5.4での変更点 ① Showメニューから Viewmode へ

UE5.4での変更点 ① Showメニューから Viewmode へ Show -> Advanced -> Property Coloration VideMode -> Actor Coloration

UE5.4での変更点 ② C++を使わなくてもOK & EditorUtilityを実行しなくてもOK！ EditorSettings系の ini ファイル に設定を追記すれば 自動的にエディタのUIに反映されるように！

例：Hidden In Gameをチェックしたい [/Script/UnrealEd.PropertyColorSettings] +CustomProperties=(Name="HiddenInGame", Text="Hidden In Game", PropertyChain="RootComponent.bHiddenInGame", PropertyValue="True", PropertyColor=(R=255,G=0,B=0))

この設定方法の問題点 AActor自身 と AActorが持つRootComponent（SceneComponent）が持つ プロパティしか扱うことができない… OK！ - IsSpatiallyLoaded ( AActor ) - RootComponent.bHiddenInGame ( SceneComponent ) NG！ - HogeHoge ( 自作Actor ) - RootComponent.CastShadow ( PrimitiveComponent ）

• https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/GameFramework/AActor?application_version=5.3
• https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/Components/USceneComponent?application_version=5.3
• https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/Components/UPrimitiveComponent?application_version=5.3

どうしても問題を解決したい人向け（非推奨。次ページの方法がオススメ）
EditorEngine.cpp 546行目付近にて
AActorが持つプロパティを抽出してるのが原因。
FPropertyColorCustomProperty にてClassを指定するように改造すればOK（のはず）

UStruct* PropertyContainer = AActor::StaticClass();
if (PropertyColorCustomProperty.PropertyChain.ParseIntoArray(PropertyChainNames, TEXT(".")))
{
TSharedRef<FEditPropertyChain> PropertyChain = MakeShared<FEditPropertyChain>();
for (const FString& PropertyName : PropertyChainNames)
{
if (FProperty* Property = PropertyContainer->FindPropertyByName(*PropertyName))

UE5.4での変更点 ③
エンジン改造しなくても、柔軟かつ高度な条件設定が可能に！
C++必須ですが…コードはかんたん！
// Cast Shadowが有効なら赤、無効なら白色にする処理を登録

FActorPrimitiveColorHandler::Get().RegisterPrimitiveColorHandler(
TEXT("CastShadow"), LOCTEXT("CastShadow", "Cast Shadow"),
[](const UPrimitiveComponent* InPrimitiveComponent) ->
FLinearColor
{
if (InPrimitiveComponent->CastShadow)
{
return FLinearColor::Red;
}
return FLinearColor::White;
});

エディタに自動追加！

少し注意点
メッシュなどの描画を行うコンポーネントの基底クラスである
Primitive Component とその派生クラスがActor Colorationの対象になる
何も描画しないActor / Scene Component を
直接チェックすることは不可能（Actorを経由すればチェック可能）

FActorPrimitiveColorHandler::Get().RegisterPrimitiveColorHandler(TEXT("XXX"),
LOCTEXT("XXX", "XXX"), [](const UPrimitiveComponent* InPrimitiveComponent) ->
FLinearColor
{
if (AActor* Actor = InPrimitiveComponent->GetOwner())
{
TArray<USceneComponent*> SceneComponents;
Actor->GetComponents(USceneComponent::StaticClass(), SceneComponents);

UE5.4 最高！！！ 「でも、C++か…なんか難しそう…」 とお悩みの方向けに…

Actor Colorationを C++で実装する サンプルとして プラグインを 作成・公開しました！

• https://github.com/pafuhana1213/UE5_CustomActorColoration

お品書き 1. Actor Colorationってなに？ 2. Actor Colorationの使い方について 3. Custom Actor Colorationプラグインについて

Custom Actor Coloration プラグイン UE5.4対応（5.3以前は対応不可） C++ビルド環境必須 対応しているプロパティ - CastShadow - Capsule Direct / Indirect Shadow - Physical Material - Collision Preset プロジェクト設定で ON/OFFの可否や色設定を変更可能

https://www.youtube.com/watch?v=mJqrIT1iYf4&ab_channel=%E3%81%8A%E3%81% 8B%E3%81%9A

• https://www.youtube.com/watch?v=mJqrIT1iYf4&ab_channel=おかず

拡張する場合はこちら CustomActorColorationSettings.h / cpp - プロジェクト設定に表示する設定項目 CustomActorColorationRegister.h / cpp - ActorColoration への登録処理 いい感じの拡張ができたら是非プルリクを！ https://github.com/pafuhana1213/UE5_CustomActorColoration/pulls

• https://github.com/pafuhana1213/UE5_CustomActorColoration/pulls

Actor Colorationの課題 カラーレーション処理がPrimitiveComponent単位なので、 頂点・ピクセル単位での塗り分けができない（Landscape対応が特に困る…） 「真・女神転生Ⅴ」における開発事例紹介 | UNREAL FEST EXTREME 2022 SUMMER

• https://www.youtube.com/watch?v=OBWecodOoig&t=3662s&ab_channel=UnrealEngineJP

対応策…？ 1. EditorUtilityで Coloration用Materialに一括差し替える？ a. レベル上の各Actor・Componentの設定に 手を加えることになるのが大きな懸念事項 2. ポストプロセス や SceneViewExtension でなんとかする？ a. バッファに情報入れないと出来ることが少ない… CustomStencilでなんとか…？ 3. 描画系のコードをガリガリ改造する？ a. つらい…他のViewModeが取っ掛かりになるか？GBufferやShadingModelを拡張…？ b. ランドスケープに関しては landscape.CollisionMesh.ShowPhysicalMaterial が少し参考になりそう

• https://qiita.com/Pachira762/items/cee45a5f7b0659bdb67e
• https://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap/c/1178-landscape-physical-materials-display

まとめ ● Actor Coloration機能を活用することで プロパティの設定状況が「見える化」 その結果、作業効率が向上したり、 設定ミス・漏れによる不具合をいち早く発見可能に ● UE5.3以前はUE3時代のコードだったため不便だったが UE5.4からは大きく改善され、エンジン改造しなくても拡張が可能に ● 簡易サンプルとしてCustom Actor Colorationをリリースしました みんなからの熱いプルリク、待ってるぜ！！！

おしまい