Level Instancing

An introduction to Level Instancing and how it can be used in your projects

Windows
MacOS
Linux

Level Instancing is a level-based workflow that facilitates the porting of non World Partition worlds to the World Partition system. It can be used to create complex streaming strategies using the following features:

  • Level instancing with transforms using a specifically-designed Actor.

  • Streaming multiple instances of the same Level at runtime. This was not possible in previous versions of Unreal Engine.

  • Hierarchical nesting of additional sublevels within a sublevel.

For example, you can use World Partition to populate a map with a large number of Actors. In cases where Actors need to be specifically arranged and reused, Level Instances provide an in-context editing workflow which replaces the old Level view.

Though it is possible to use Level Streaming without using World Partition, Level instances do not automatically have streaming management or streaming strategies outside of a World Partition main world.

Creating Level Instances

New Level instances are generated from selected Actors and can be created in either the Viewport or the World Outliner.

image alt text

After selecting the Actors, right-click one of them to pull up the context-sensitive menu and select Create from selection.

You will see a dialog box with the following settings:

image alt text

Setting

Description

Type

The type of Level Instance:

  • Level Instance

  • Packed Level Instance

  • Packed Level Instance Blueprint

External Actors

Enable external Actors to use the One File per Actor system. For more information, see the One File Per Actor documentation.

Pivot Type

The type of Pivot the Level instance will have:

  • Center Min Z: Pivot will be located at the center of the Level Instance at the lowest Z value.

  • Center: Pivot: Pivot will be located at the center of the Level Instance.

  • Actor: Pivot will be located at the center of the specified Actor.

Pivot Actor

If Actor is selected as the Pivot, use this dropdown to select which Actor will be the pivot point for the Level Instance.

Once you have selected your settings, you will be asked to save the new Level Instance.

This process will create a new ALevelInstance Actor in the level which replaces the previously selected Actors. This Actor represents the Level that was just created and all transforms applied to this Actor will be applied to the Level Instance.

image alt text

In the World Outliner, the Level Actors will be grayed out since they can't currently be selected or edited.

image alt text

It is possible to drag a ALevelInstance Actor into your Level and assign a .umap file to it in the Details panel.

It is possible to provide Level Instance templates through Unreal Engine .ini files using entries similar to regular Level creation templates. Do this by adding the following to the DefaultEditor.ini file for your project:

[/Script/LevelInstanceEditor.LevelInstanceEditorSettings]
+TemplateMapInfos=(ThumbnailTexture=Null,Map="/Game/Maps/Tools/TM-Template")

Packed Level Instances

A Packed Level Instance is a type of Level instance that tries to group a Level's static meshes into as few static mesh instances as possible.

There are two types of Packed Level Instances:

  • Packed Level Instances: The packing process creates a Packed Level Instance centered on the ALevelInstance Actor's location.

  • Packed Level Instance Blueprint: The packing process creates a Level instance that can be referenced from a Blueprint.

Actors and Components that are not static meshes are not included in the packing process and will remain separate in the source Level.

Packing a Level Instance does not change the editing workflow when working with the Level.

Packed Level Instances are currently an experimental feature and may change or be removed in later versions of Unreal Engine.

Editing Level Instances

Level instances can be edited in context from the Viewport or the Details panel.

image alt text

Shown above, editing mode is opened by doing the following:

  1. Select the Level instance in the Viewport.

  2. Right-click to open the context-sensitive menu.

  3. In the Level Instance section of the menu, hover over the Edit option and select the Level you would like to edit.

Editing mode can also be opened from the Detail panel:

image alt text

Select the Level Instance that you would like to edit and click the Edit button in the Details panel.

Level Streaming at Runtime

Embedded Mode

When using Embedded Mode, Level instances that use the One File Per Actor (OFPA) system are discarded and their Actors are added to the World Partition grid at runtime. This is the default runtime mode and the suggested method of streaming Level content. This also makes Level instances exist within the editor only.

Some Actors that do not use OFPA are lost at runtime when using Embedded Mode. For example, the AWorldSettings object of an embedded Level Instance does not exist at runtime as this is a non-OFPA Actor.

It is your responsibility to avoid relying on this or to use Level Streaming mode when needed.

Level Streaming Mode

Level instances that do not use OFPA cannot be embedded in the World Partition grid and will instead use standard Level streaming at runtime. This means that when the ALevelInstance Actor is loaded through its owning World Partition runtime cell, it will load the associated Level.

This method of Level streaming has an added runtime cost as it adds more Levels to the stream. It is not recommended to use a high density of Levels that use this streaming mode due to the performance impact.

Embedded mode with World Partition: Data layers is a great way to approximate what could previously be done with dynamically loaded Levels.

Data Layers

Level Instances support World Partition: Data layers when using Embedded Mode or Level Streaming Mode. The Actors contained in the Level Instance will inherit the data layers from the ALevelInstance Actor.