LevelInstanceActorのLevelStreamingモードと動的レベルインスタンス生成

はじめに

レベルインスタンスアクターはUE5で追加されたアクターです。
大規模なワールドを効率的に作成するための機能ですが、実はいろいろな機能があるので簡単に解説します。

ざっくりとどんなもの？

LevelInstanceActorは誤解を恐れずにいうとワールドパーティションを使ったレベルで使えるサブレベルに「近い」ものです。実際にアクターのパラメータとしてレベルを指定するので表面上はサブレベルをパーシスタントレベルに置くといった使い道が可能です。
作り方と使い方について簡単に説明すると・・・

パーシスタントレベル上にあるアクターを複数選択して"Create Level Instance" で作ります。レベル名を指定してレベルアセットとして保存されます。

配置する時はそのレベルをドラッグ&ドロップします。

特徴や利点、制限など

• レベルをコピペすることが可能で、一つを編集するとすべてのレベルインスタンスが同時に変更されます
• パーシスタントレベル上で塊として移動可能
• 軽量な編集用の別のパーシスタントレベル上でレベルインスタンスを編集することが可能
• ワールドパーティションセルの分割に影響をうけます
• クック時にレベルインスタンスは解体されてパーシスタントレベルのワールドパーティションセルに組み込まれるのでランタイムコストがありません
• 基本的にワールドパーティションレベル上で利用します(※後で補足)
• LevelInstanceActorで扱うレベルはOneFilePerActor(OFPA)が有効なレベルである必要があります(※後で補足)そうではないレベルを指定すると警告が表示されます。
  WorldPartitionレベルはデフォルトでOFPAが有効になりますが、WorldPartitionレベルではない通常のレベルでもExperimental機能としてOFPA化できます。
• データレイヤーに登録すると内部のアクター達も同じデータレイヤーに自動的に登録されます。編集中に表示非表示を切り替えたり、ランタイムで任意のタイミングでのロードやアンロードの制御に利用できます。従来のレベルでのサブレベルで行っていた任意のタイミングでのロードの管理はこのデータレイヤーで行います。

Packed Level Actor について

同じような名前のPacked Level Actorについても簡単に触れます。前述のレベルインスタンスアクターに大変近いですが、StaticMeshなどの一部のタイプのアクターしか含められない代わりに自動インスタンス化を行いパフォーマンスを改善することができる機能となっています。
具体的にはStaticMeshComponentが非NaniteメッシュならHierachicalInstancedStaticMeshComponentに、NaniteメッシュならInstancedStaticMeshComponentに変換されるのでコンポーネント数が減少し効率が向上するという寸法です。当然ですがモジュラーアセットのような形式で同じアセットを繰り返し使わないとあまり効果がありません。

OneFilePerActorについて補足

ワールドパティションではないレベルでもOFPAを有効にしたい場合は上記公式ドキュメントの冒頭の警告にあるようにExperimental機能を有効化したあと、ワールドセッティングのUseExternalActorにチェックを入れてください。

=============ここまで前置き=================

本題のLevelStreamingモード！

さてここからが本題となります。
レベルインスタンスに関する公式ドキュメント

をみるとなにやら二つのモードについて解説があることに気付きます。

• 埋め込みモード (Pertitioned)
• レベルストリーミングモード (LevelStreaming)

です。
ちょっと説明を読んだだけだと「どういうことだってばよ？？？」と思ってしまいますね(個人的感想です)。
そもそもこの二つのモードが一体何なのかということが分かりません。ということで調べました。

LevelInstanceTypes.h

UENUM()
enum class ELevelInstanceRuntimeBehavior : uint8
{
	None UMETA(Hidden),
	// Deprecated exists only to avoid breaking Actor Desc serialization
	Embedded_Deprecated UMETA(Hidden),
	// Default behavior is to move Level Instance level actors to the main world partition using World Partition clustering rules
	Partitioned,
	// Behavior only supported through Conversion Commandlet or on non OFPA Level Instances
	LevelStreaming UMETA(Hidden)
};

・・・どうやら非OFPAレベルのインスタンスを扱えるらしい。といわけでこのLevelStreamingモードについて解説します！

使い方

まずエンジンの標準機能では任意にこのLevelStreamingモードを使うことはできません。というわけでALevelInstanceを継承したアクターを自プロジェクト内に追加します。

MyStreamingLevelInstanceActor

#pragma once
#include "CoreMinimal.h"
#include "LevelInstance/LevelInstanceActor.h"
#include "MyStreamingLevelInstanceActor.generated.h"

UCLASS()
class AMyStreamingLevelInstanceActor : public ALevelInstance
{
	GENERATED_BODY()
	
#if WITH_EDITOR
	// Begin ILevelInstanceInterface
	virtual ELevelInstanceRuntimeBehavior GetDesiredRuntimeBehavior() const override { return ELevelInstanceRuntimeBehavior::LevelStreaming; }
	virtual ELevelInstanceRuntimeBehavior GetDefaultRuntimeBehavior() const override { return ELevelInstanceRuntimeBehavior::LevelStreaming; }
	// End ILevelInstanceInterface
#endif
};

WITH_EDITORマクロで囲われているので、ILevelIsntaceInterfaceの一部のAPIはパッケージビルドでは使えないことに注意してください。
レベルアセット(ワールドアセット)を設定するAPIもパッケージビルドではなくなります。(※自分のクラスに追加することは可能です)

class ENGINE_API ILevelInstanceInterface
{
...
#if WITH_EDITOR
	virtual bool SetWorldAsset(TSoftObjectPtr<UWorld> WorldAsset) = 0;

さてビルドしてエディタが立ち上がったら、まずレベルを作ります。 ワールドパーティションではない Empty Level を選びます。 このレベルはOFPAが有効化されていません。

適当に球メッシュを並べて保存します。

このワールドパーティション+OFPAではないレベルをワールドパーティションレベルにLevelInstanceとしてドラッグアンドドロップしてPIEを動かすと。。。

△ Level Instance HundredSpheres (/Game/WPLevel) is not using external actors /Game/HundredSpheres.HundredSpheres

と怒られてしまいます。前述の通りLevelInstanceActorはOFPA(+ワールドパーティション)のレベルが想定されているからです。

さて問題点が分かったところで、新しく作ったLevelStreamingモードのLevelInstanceActorを使ってみましょう

アクターを追加したらそのアクターのプロパティを開いて OFPAではないレベルを設定してPIEを起動！
100個の球がLevelStreamingモード+非OFPAレベルで、立方体はPartitionedモード+OFPAレベルです。

Level Streaming Mode pic.twitter.com/mJaqEMlgPr

— Takashi.Suzuki (@wankotank) December 4, 2022

立方体の方がワールドパーティションセルに分割されてストリーミングされているのに対して球の方は一括で出現したり消えたりします。
つまりワールドパーティションへの埋め込まれていないことがわかります。
公式ドキュメントで警告されているのはこのモードを用いてレベルストリーミングを行うと埋め込まれないため「ランタイムで制御するレベルストリーミングの数が増加する」ということです。

ブループリント化

さて次にこのアクターをブループリント化してみましょう。
新規ブループリント作成でMyStreamingLevelInstanceActorを親として指定して、ブループリントアセットを作成し、プロパティに先ほどの非WPレベルを指定します。

このBPをレベルに配置しても問題無く動作します。

動的レベルインスタンスの作成と削除

このブループリントはアクターなのでSpawnActorで任意の位置に実体化することができます。個々のLevelInstanceActorはULevelStreamingLevelInstanceとして処理されるので動的にレベルインスタンス作成が可能です。
またアクターを削除することでレベルをストリームアウトさせることももちろん可能です。
テスト用にブループリントを書いてみます。SpawnActorでLevelInstanceActorを作り、DestroyActorしています。

動かしてみるとこのように任意のタイミングで動的にレベルインスタンスを生成したり、アクターの削除によってレベルインスタンスをストリームアウトさせることができることが確認できます。

Dynamic Level Instance creation using ILA pic.twitter.com/BBOepTU19w

— Takashi.Suzuki (@wankotank) December 4, 2022

この機能はLoadLevelInstanceを代替することが可能で、パーシスタントレベルがワールドパティションレベルか非ワールドパティションレベルかを問わずに動作します

まとめ

• LevelInstanceActorをBP化して動的インスタンスを作ることできます
• LevelInstanceActorで非OFPAレベルを扱いたい場合はLevelStreamingモードを使う。これにはプロジェクト側でのクラスの宣言が必要です
• 非OFPAレベルがソースになっているなら、非ワールドパティションおよびワールドパティションレベルの両方のレベルで動的インスタンス生成が可能です。
• 非OFPAレベルはワールドパーティションセルに埋め込まれ「ません」
• 非WPレベルにWPレベルをロードすることはできません。クラッシュの原因になります