概要

UnrealEngine5 のDataLayerとLevelInstanceについてのメモです。
DataLayerのステート切り替えと、LevelInstanceの動的作成について検証しました。

更新履歴

日付	内容
2023/04/24	初版

参考

以下の記事を参考にいたしました、ありがとうございます。
UE公式：World Partition - データレイヤー
 UE公式：レベルのインスタンス化
 【UE5】WorldPartitionのDataLayerについてあれやらこれやら
 【UE5】Level Instance の使い方
 LevelInstanceActorのLevelStreamingモードと動的レベルインスタンス生成

環境

Windows10
Visual Studio 2022
UnrealEngine 5.1.1

関連ソース

"Engine\Source\Runtime\Engine\Public\WorldPartition\DataLayer\DataLayer.h"
"Engine\Source\Runtime\Engine\Public\LevelInstance\LevelInstanceActor.h"

データレイヤー(DataLayer)について

WorldPartitionレベルにて指定のアクターをまとめてロード/アンロード管理をするための仕組みです。

BPでのステート切り替え

データレイヤーアウトライナーにてデータレイヤーを作成します。

BPではDataLayerSubsystemからSetDataLayerInstanceRuntimeStateでステートを切り替えができます。Activateはロードして表示、Loadedはロードはするが表示しない、Unloadはアンロードとなります。

C++でのステート切り替え

C++でも UDataLayerSubsystemからステートを切り替えることができます。
以下のサンプルコード。

このコードはストリーミング切り替え時の処理を登録して、まだ完了していない場合は強引に再登録してストリーミング完了を確認していますが、本来は別途完了待ちタスク等を作成して監視するようにすべきかと思います。

データレイヤーステート切り替え

#include "WorldPartition/WorldpartitionSubsystem.h"
#include "WorldPartition/WorldPartitionRuntimeCell.h"
#include "WorldPartition/DataLayer/DataLayerSubsystem.h"
#include "WorldPartition/DataLayer/DataLayerAsset.h"


UDataLayerSubsystem* _DLSubsystem = GetWorld()->GetSubsystem<UDataLayerSubsystem>();
UDataLayerAsset* _DLAsset = LoadObject<UDataLayerAsset>(nullptr, TEXT("/Game/NewDataLayerAsset.NewDataLayerAsset"), nullptr, LOAD_None, nullptr);


if (_DLSubsystem) {
	// ステート切り替え時の処理登録 ＃登録メソッド宣言にはUFUNCTION()が必須＃
	_DLSubsystem->OnDataLayerRuntimeStateChanged.AddDynamic(this, &UMyActorComponent::OnDataLayerRuntimeStateChanged);

	// ステート切り替え
	_DLSubsystem->SetDataLayerInstanceRuntimeState(_DLAsset, EDataLayerRuntimeState::Activated);
}


// ステート切り替え時の処理
void UMyActorComponent::OnDataLayerRuntimeStateChanged(const UDataLayerInstance* _DataLayer, EDataLayerRuntimeState _State)
{
	UDataLayerSubsystem* _DLSubsystem = GetWorld()->GetSubsystem<UDataLayerSubsystem>();
	UWorldPartitionSubsystem* _WPSubsystem = GetWorld()->GetSubsystem<UWorldPartitionSubsystem>();
	TArray<FWorldPartitionStreamingQuerySource> _QuerySources;

	FWorldPartitionStreamingQuerySource _Item; _Item.DataLayers.Add(_DataLayer->GetDataLayerFName());
	_QuerySources.Add(_Item);

	// ストリーミング完了チェック
	bool _IsCompleted = _WPSubsystem->IsStreamingCompleted(EWorldPartitionRuntimeCellState::Activated, _QuerySources, true);

	if (!_IsCompleted) {
		// まだ完了していない

		// タイマーで無理やり再設定して確認する
		FTimerHandle    _Handle;
		FTimerDelegate  _TimerDelegate;

		_TimerDelegate.BindUFunction(this, FName("OnDataLayerRuntimeStateChanged"), _DataLayer, _State);
		GetWorld()->GetTimerManager().SetTimer(_Handle, _TimerDelegate, 0.001f, false);
	}
	else {
		// ストリーミング完了
	}
}

レベルインスタンス(LevelInstance)について

レベルをインスタンス化し、同じものを複数配置することができる仕組み。WorldPartitionレベルに置くとストリーミングの対応も行われるようです（埋め込みモード）。

BPでの動的作成

インスタンス化するレベルを作成し、次にLevelInstanceを継承したBPを作成し、[Level]に設定します。

このアクターは通常のアクターのようにスポーンができるので以下のように生成/破棄が可能です。

C++での動的作成

BPで作成済のレベルインスタンスアクターはアクターとして生成ができます。
以下コード例。

.h

// レベルインスタンスアクター
UPROPERTY()
TObjectPtr<ALevelInstance> LvInstActor;

レベルインスタンスアクター生成

#include "LevelInstance/LevelInstanceActor.h"
#include "LevelInstance/LevelInstanceSubsystem.h"

ULevelInstanceSubsystem* _LISubsystem = GetWorld()->GetSubsystem<ULevelInstanceSubsystem>();
	
// レベルインスタンスアクターをスポーン
if (!::IsValid(LvInstActor)) {
	UBlueprint* _Bp = FindObject<UBlueprint>(NULL, TEXT("/Game/LevelInstanceBP.LevelInstanceBP"));
	if (::IsValid(_Bp)) {
		LvInstActor = GetWorld()->SpawnActor<ALevelInstance>(_Bp->GeneratedClass, FVector(1280, 1220, 250), FRotator(0, 0, 0));
	}
}

// レベルインスタンスアクターを破棄
if (::IsValid(LvInstActor)) {
	LvInstActor->Destroy();
}

C++での動的作成2

レベルインスタンスアクターなしで(レベルのみで)生成する場合は以下のように。ただし SetWorldAssetがエディタオンリーなメソッドなのでランタイムで使うには ALevelInstanceクラスを継承して自前で改造が必要だと思われます。

UWorld* _LevelData = LoadObject<UWorld>(nullptr, TEXT("/Script/Engine.World'/Game/LevelInstanceTest.LevelInstanceTest'"), nullptr, LOAD_None, nullptr);
LvInstActor = GetWorld()->SpawnActor<ALevelInstance>(ALevelInstance::StaticClass(), FVector(1280, 1220, 250), FRotator(0, 0, 0));
LvInstActor->SetWorldAsset(_LevelData);		// Ediorのみ
LvInstActor->LoadLevelInstance();

レベルインスタンスの動的生成時の注意点

動的生成が可能なレベルインスタンスは非ワールドパーティションレベル(OneFilePerActorが設定されていない)である必要があるようです。
レベルの設定だとワールドセッティングの詳細設定[外部アクタを使用]にチェックが入っていると動的作成ができません。

作成済レベルからチェックを外すことはできないので新たにレベルを作成してコピペ等の対応が必要になります。

非ワールドパーティションレベルの判別

レベルを右クリックして[パーティション化のストリーミングサポートを追加]というメニューが出た場合は非ワールドパーティションレベルと判別できます。

まとめ

任意のロード管理はDataLayerがわかりやすいのでLevelInstanceに置いて使うといいのかと思ったのですが、構造が複雑になってしまいますかね。