概要

UnrealEngine のプライマリデータアセット(UPrimaryDataAsset)を使ってみるメモ書きです。
プライマリデータアセットを管理するアセットマネージャーの差し替えも試してみます。

更新履歴

日付	内容
2020/03/17	4.24での不具合と回避方法と追記
2020/11/14	ボタン機能について追記
2021/03/16	ロードバンドルについて追記

環境

Windows10
Visual Studio 2017
UnrealEngine 4.22, 4.24, 4.25

参考

以下を参考にさせて頂きました、ありがとうございます。

UE4 アセットマネージメントフレームワークについて
 UnrealEngineドキュメント-アセット管理
 https://www.slideshare.net/EpicGamesJapan/ue4action-rpg
[UE4] Asset Managerのアセットの非同期ロード機能についてその3 (PrimaryDataAsset, PrimaryAssetLabelはいいぞ編)

PrimaryAssetLabelを使う

エンジン側で用意されている UPrimaryDataAssetクラスを継承した PrimaryAssetLabelクラスを使ってみます。

データアセットの用意

コンテンツブラウザで右クリック -> 「その他」 -> 「データアセット」を選択し、PrimaryAssetLabelを選びます。

作られたデータアセットの詳細は以下の様になります。

[Explicit Assets]や[Explicit Blueprints]にアセットが設定できます。これがロードされるデータとなります。
テストでDataTableアセットを１つ登録しています。

ロード処理

[Async Load Primary Asset]ノードで非同期ロードができます。解放は[Unload Primary Asset]で行うようです。
複数アセットの場合は[Async Load Primary Asset List]が使えます。
以下はアクターの BeginPlay と EndPlay にてロード、アンロードを行った例です。

ロードメソッドの実体は
Engine/Source/Runtime/Engine/Private/AsyncActionLoadPrimaryAsset.h
の UAsyncActionLoadPrimaryAssetクラスです。
アンロードは UKismetSystemLibraryクラスにあるようです。

ロード済データアセットの扱い例

C++側で UDataTableを持って、そちらに参照をセットすることでC++にて扱うこともできます。

UPROPERTY()
UDataTable* Data;

PrimaryDataAssetの ExplicitAssets に仕込んだ DataTable（FTestParam構造体）を取得する例です。

.cpp

UPrimaryAssetLabel* _pAsset = Cast<UPrimaryAssetLabel>(Data);
if( _pAsset != nullptr){
    // データテーブル取得  
    UDataTable* _Data = Cast<UDataTable>(_pAsset->ExplicitAssets[0].Get());

    // データテーブル展開
    TArray<FTestParam*> OutAllRows;
    FString _Context;       // エラー時用
    _Data->GetAllRows<FTestParam>(_Context, OutAllRows);
    for (FTestParam* _It : OutAllRows)
    {
        // データ表示
        UE_LOG(LogTemp, Log, TEXT("%d, %f"), _It->Param1, _It->Param2);
    }

}

PrimaryAssetLabel は汎用につくられているようなので、クラスの型などが UObject のみとなりいろいろなクラスを扱うにはキャストなどが必要なため、やや面倒になると思われます。
その代わり面倒な設定は一切不要で使うことができます。

UPrimaryDataAssetを継承して使う

データアセットで設定できる項目をカスタマイズしたい場合は自前でUPrimaryDataAssetを継承したクラスをつくる必要があるので試してみます。更にAssetManagerクラスも継承してみます。

C++クラスの用意

PrimaryDataAssetクラスを継承したクラスを用意

試しにアイテムデータを想定してみます。アイテム名やアイコンデータ等を持つクラスというイメージです。

[DataAsset]ディレクトリに ItemDataAsset.h というファイルを作成します。UPrimaryDataAssetを継承して、メンバを持つ基底クラスとします。

ItemDataAsset.h

#include "CoreMinimal.h"
#include "Engine/DataAsset.h"
#include "Styling/SlateBrush.h"
#include "ItemDataAsset.generated.h"


// アイテムデータアセット基底クラス
UCLASS(Abstract, BlueprintType)
class TEST_API UItemDataAsset : public UPrimaryDataAsset
{
    GENERATED_BODY()

public:
    // コンストラクタ
    UItemDataAsset()
        :LiveTime(5.0f)
    {}

    // プライマリアセットID名を取得する
    UFUNCTION(BlueprintCallable, Category = Item)
        FString GetIdentifierString() const;

    // プライマリアセットIDを取得する（要オーバーライド）
    virtual FPrimaryAssetId GetPrimaryAssetId() const override;


    // アイテムタイプ
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "UItemDataAsset")
        FPrimaryAssetType   ItemType;

    // アイテム名
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "UItemDataAsset")
        FText       ItemName;
    // アイテムアイコン
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "UItemDataAsset")
        FSlateBrush ItemIcon;
    // 生存時間
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "UItemDataAsset")
        float       LiveTime;

};

GetPrimaryAssetId()での ItemType は継承先のクラスで設定します。

ItemDataAsset.cpp

#include "ItemDataAsset.h"

// プライマリアセットID名を取得する
FString UItemDataAsset::GetIdentifierString() const
{
    return GetPrimaryAssetId().ToString();
}

// プライマリアセットIDを取得する
FPrimaryAssetId UItemDataAsset::GetPrimaryAssetId() const
{
    return FPrimaryAssetId(ItemType, GetFName());
}

アセットマネージャクラスの用意

自前のアセットマネージャクラスを用意する事は今回のコード例程度では必要ありませんが、追加したFPrimaryAssetType定義をまとめるためと、将来的な拡張のため定義しておきます。（複雑なデータアセット構成になると必要になるはず。。）

AssetManagerを継承した自前のMyAssetManagerクラスを用意します。

プライマリデータアセットのタイプをstaticで定義します。

MyAssetManager.h

#include "CoreMinimal.h"
#include "Engine/AssetManager.h"
#include "MyAssetManager.generated.h"


// アセットマネージャ
UCLASS()
class TEST_API UMyAssetManager : public UAssetManager
{
    GENERATED_BODY()

public:
    // コンストラクタ
    UMyAssetManager(){}

    // 初期ロード開始時
    virtual void StartInitialLoading() override;

    // アイテムタイプ定義
    static const FPrimaryAssetType  DropItemType;

    // アセットマネージャオブジェクトの取得
    static UMyAssetManager& GetObj();
};

アイテムタイプ定義の "DropItem" はプロジェクト設定で設定する必要があります、他のプライマリデータアセットと被るのはNGです。

MyAssetManager.cpp

#include "MyAssetManager.h"
#include "./ItemDataAsset.h"

const FPrimaryAssetType UMyAssetManager::DropItemType = TEXT("DropItem");

// アセットマネージャオブジェクトの取得
UMyAssetManager& UMyAssetManager::GetObj()
{
    UMyAssetManager* This = Cast<UMyAssetManager>(GEngine->AssetManager);

    if (This)
    {
        return(*This);
    }
    else
    {
        UE_LOG(LogTemp, Fatal, TEXT("DefaultEngine.ini でのAssetManagerの設定が不正です。"));
        return(*NewObject<UMyAssetManager>());  // 呼ばれない
    }
}

// 初期ロード開始時(InitializeObjectReferencesから呼ばれる)
void UMyAssetManager::StartInitialLoading()
{
    Super::StartInitialLoading();

}

実際のデータアセットクラスを用意

先ほど作成した UItemDataAsset を継承したクラスを作成します。これが実際のデータを設定するクラスとなります。
基底クラスからアクターを追加したものにしています。

ItemDataAsset_DropItem.h

#include "CoreMinimal.h"
#include "DataAsset/ItemDataAsset.h"
#include "./MyAssetManager.h"
#include "ItemDataAsset_DropItem.generated.h"

// ドロップアイテム
UCLASS()
class TEST_API UItemDataAsset_DropItem : public UItemDataAsset
{
    GENERATED_BODY()

public:
    // コンストラクタ
    UItemDataAsset_DropItem()
    {
        // アセットマネージャで定義しているタイプを設定する
        ItemType = UMyAssetManager::DropItemType;
    }

    // アクター
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "DropItem")
    TSubclassOf<AActor> Actor;
};

C++クラスは以上になります。

アセットブラウザで見ると上記のようになりました。

各種設定

AssetManagerの設定

[プロジェクト設定] -> [ゲーム] -> [Asset Manager] -> [Primary Asset Type to Scan] に設定を追加します。

[Primary Asset Type]には MyAssetManager で記述した "DropItem" を記載します。ここの文字列とGetPrimaryAssetId()で返す文字列の一致が必須のためです。
不一致や名称が被る場合は、アウトプットログに警告 [LogLinker : Warning: ～] がでます。

[Asset Base Class]には作成したクラス [ItemDataAsset_DropItem]を入れます。
[Directories]には実際作成したデータアセットが入っているパスを指定します。もしくは[Specific Assets]でディレクトリ単位ではなく、直接ファイル指定も可能なようです。

[Should Guess Type and Name in Editor]のチェックを外さないとパッケージ化の時に不具合が発生するようです。

DefaultEngine.iniの設定

アセットマネージャを作成したクラスに差し替えるため、[Config]フォルダにある DefaultEngine.iniに以下の設定を追加します。

DefaultEngine.ini

[/Script/Engine.Engine]
AssetManagerClassName=/Script/Test.MyAssetManager

[Test]がプロジェクト名、[MyAssetManager]がアセットマネージャクラス名になります。

データアセットの用意

自作したクラスを使用したデータアセットを作ります。
アセットブラウザにて右クリック -> [データアセット]を選択し、先ほど作成した ItemDataAsset_DropItem クラスを指定します。

作成したデータアセットは以下の様になります。先に定義したItemDataAssetクラスと ItemDataAsset_DropItemクラスのプロパティが設定できます。

必要に応じて複数のデータアセットを作成し、データを切り分けることができます。

ロード処理

ロード処理は PrimaryAssetLabel の時と同じように扱うことができます。

ブラウズに出てこない場合は、プロジェクト設定のAssetManagerの項目を再確認してください。

ロード処理クラスのC++ソースファイルは
Engine/Source/Runtime/Engine/Private/AsyncActionLoadPrimaryAsset.h
です。

アセットバンドルについて

ロード時に Load Bundlesにて追加でロードするアセットを指定できます。

バンドルでロードする場合、以下の様に meta=(AssetBundles = タグ名) を指定することで、このタグを Load Bundlesを渡して追加でロードすることができます。
また普通にアセットのリファレンスパス(SkeletalMesh'/Game/Mesh/TestMesh.TestMesh' など)を指定することもできます。

MyPrimaryDataAsset.h

UCLASS(BlueprintType)
class TEST_API UMyPrimaryDataAsset : public UPrimaryDataAsset
{
    // 省略

    // バンドルでロードするメッシュ１
    UPROPERTY(EditAnywhere, BlueprintReadOnly, meta = (AssetBundles = "Option1")
    TSoftObjectPtr<USkeletalMesh> OptionMesh1;
    // バンドルでロードするメッシュ２
    UPROPERTY(EditAnywhere, BlueprintReadOnly, meta = (AssetBundles = "Option2")
    TSoftObjectPtr<USkeletalMesh> OptionMesh2;
};

上記の場合、引数Load Bundlesに Option1を指定すると OptionMesh1が、Option2を指定すると OptionMesh2が、両方指定すると両方のメッシュがバンドルとしてロードされます。

バンドルの変更

プライマリデータアセットをロード後、追加でロードしたバンドルを細かく変更することができます。対応メソッドとして、Async Change Bundle State for Matching Primary Assets とAsync Change Bundle State for Primary Asset List が用意されています。
個別に追加バンドルと削除バンドルを指定する下のノードを使うのがいいと思います。

追加機能

イベントボタンの付与

データアセット定義に以下のようなメタ情報をつけたメソッドを追加するとデータアセットにボタンを付与でき、任意の処理を実行することができます。


// 任意の処理をする
UFUNCTION(Category="Execute", meta = (CallInEditor = "true", ToolTip = "任意処理をする"))
  void Proc();

.cpp

void UMyDataAsset::Proc()
{
    UE_LOG(LogTemp, Log, TEXT("Proc!"));
}

値のチェックなどの処理を書いたり、別データからパラメータを取得したりなどの処理を書くことができるかと思います。

その他

アセットマネージャからプライマリデータアセットのオブジェクトを取得する

AssetManagerクラスのGetPrimaryAssetObject()でロード済のオブジェクトを取得することができるようです。

// ヘッダファイル
UMyDataAsset* DataFile;

// コンストラクタ
static ConstructorHelpers::FObjectFinder<UMyDataAsset> DataFile(TEXT("MyDataAsset'/Game/TestAsset00.TestAsset00'"));
if (DataFile.Object) {
    DataAsset = DataFile.Object;
}

...

UMyAssetManager& _Mgr = UMyAssetManager::Get();
if (DataAsset) {
    // アセットマネージャから取得する
    if( _Mgr.GetPrimaryAssetObject(DataAsset->GetPrimaryAssetId())){
        UE_LOG(LogTemp, Log, TEXT("Get UObject"));
    } else {
        UE_LOG(LogTemp, Log, TEXT("nullptr")); // メモリにない
    }
}

プライマリアセットIDが分かっている場合はそのままID指定でも取得できます。

.cpp

auto& _Mgr = UMyAssetManager::Get();

// プライマリアセットIDを直接指定して取得
auto _Asset = Cast<UMyDataAsset>(_Mgr.GetPrimaryAssetObject( FPrimaryAssetId(UMyAssetManager::DropItemType, TEXT("TestAsset00")) ) );
if( _Asset ){
    UE_LOG(LogTemp, Log, TEXT("Get![%d]"), _Asset->ParamInt );
} else {
    UE_LOG(LogTemp, Log, TEXT("nullptr")); // メモリにない
}

PrimaryDataAssetをパッケージに含める

PrimaryDataAsset は PrimaryAssetIDで指定するため、通常のアセットと異なり参照がつかないようです、そのためそのままパッケージングを行うとパッケージに含まれません。
対策は以下のようなものがあります。

CookRuleで指定する

プロジェクト設定の [AssetManager] で対象のデータアセットから
[Rules] -> [Cook Rule] で [Always Cook]などを指定する。

プライマリアセットタイプ単位の指定なのでパッケージに含みたくないデバッグ用アセットなどは別のデータタイプとして指定しなければなりません。

パッケージングで設定する

プロジェクト設定の [パッケージング] -> [Additional Asset Directories to Cook]
にフォルダ単位でパッケージに含むように指定をする。

フォルダ単位での指定なのでフォルダ構成を考慮しておかないと余計なファイルが入ってしまいます。

4.24での不具合？と回避方法

[プロジェクト設定] -> [アセットマネージャ] -> [スキャンするプライマリアセットタイプ(Primary Asset Type to Scan)]にてアセットタイプを追加や削除する場合、そのまま追加or削除するとパッケージ化する時にエラーが出ます。

回避するには以下の設定を追加する必要があります。

DefaultGame.ini

[/Script/Engine.AssetManagerSettings]
-PrimaryAssetTypesToScan=(PrimaryAssetType="Map",AssetBaseClass=/Script/Engine.World,bHasBlueprintClasses=False,bIsEditorOnly=True,Directories=((Path="/Game/Maps")))
-PrimaryAssetTypesToScan=(PrimaryAssetType="PrimaryAssetLabel",AssetBaseClass=/Script/Engine.PrimaryAssetLabel,bHasBlueprintClasses=False,bIsEditorOnly=True,Directories=((Path="/Game")))

この設定は4.22の時点では自動で追加されていたのですが、4.24ですと付与されません。(4.23では未確認)

ロードキャンセル

非同期ロードのキャンセルは以下のノードで。個別のキャンセルは見当たりません。

Kismet/GameplayStatics.h

/** 現在キューイングされたストリーミングパッケージを全てキャンセルします */
UFUNCTION(BlueprintCallable, Category = "Game")
static void CancelAsyncLoading();

まとめ

プライマリデータアセットは最小単位でデータがまとまっているように作成するとロード効率が良いと思います。リスト表示のようにパラメータを一気に見るためにはパラメータ部とアセット部を別途切り分けをするようなデータアセット設計を行うと可能かと思います。（あるいはスクリプトで検索して読み込むようにする等）

UE4 PrimaryDataAssetを使ってみる

概要

更新履歴

環境

参考

関連用語

アセットマネージャ(AssetManager)

プライマリデータアセット(PrimaryDataAsset)

アセットオーディット(AssetAudit)

PrimaryAssetLabelを使う

データアセットの用意

ロード処理

ロード済データアセットの扱い例

UPrimaryDataAssetを継承して使う

C++クラスの用意

PrimaryDataAssetクラスを継承したクラスを用意

アセットマネージャクラスの用意

実際のデータアセットクラスを用意

各種設定

AssetManagerの設定

DefaultEngine.iniの設定

データアセットの用意

ロード処理

アセットバンドルについて

バンドルの変更

追加機能

イベントボタンの付与

その他

アセットマネージャからプライマリデータアセットのオブジェクトを取得する

PrimaryDataAssetをパッケージに含める

CookRuleで指定する

パッケージングで設定する

4.24での不具合？と回避方法

ロードキャンセル

まとめ