Data Layers is a system within World Partition you can use to organize your Actors both in the Editor and at runtime.
With Data Layers, you can separate gameplay elements and environment assets in the Editor. Artists can work on specific elements without interacting with gameplay triggers or objects. Designers can use dynamically loaded layers to design intriguing gameplay and elaborate level transitions.
Using Data Layer Assets and Data Layer Instances, you can load and unload layers of content in the editor and at runtime to manage complex worlds. Actors and the World Partition system define how content streams through the Is Spatially Loaded, Runtime Grid, and Enable Streaming options, while Data Layers act as a filter on top of that streaming. For the states a Data Layer can be in, see Data Layer States.
At runtime, you can change the state of Runtime Data Layers from Blueprints or C++ to drive gameplay such as quests, progression, in-game events, scenario and world variations, and the content of sequences. Runtime Data Layers fully support HLODs: each layer gets its own HLODs, which follow the layer's state. Data Layers are an important tool for managing streaming in a World Partition workflow, and they also work when World Partition streaming is disabled, in which case each Data Layer streams globally as a single Level.
Creating Data Layers
Data Layers are split into two types of assets: Data Layer Assets and Data Layer Instances. Data Layer Assets contain cross-world data and are created in the Data Layers Outliner or in the Content Browser. Data Layer Instances contain world-specific data and are created in the Data Layers Outliner. A third type, External Data Layers, lets a Game Feature Plugin inject content into a World Partition Level. For more information, see External Data Layers.
The Data Layers system requires you to enable World Partition in your map. A map can be converted to World Partition by using Tools > Convert Level or by using the commandlet. For more information on converting existing levels to World Partition, see World Partition.
Data Layer Assets
Data Layer Assets are Unreal Engine assets you can create and view in the Content Browser. They exist at the project level and are not world specific. They contain the following data:
Data Layer Name
Data Layer Type
Debug Color: The color used in debug displays and by the Current Data Layer Color Actor Coloration mode, which colors Actors in the Viewport with the debug color of their current Data Layer and uses white for Actors in more than one current Data Layer.
Load Filter: For Runtime Data Layers, which side considers the layer. None (the default) means both client and server, with the client runtime state replicated from the server; Client Only and Server Only keep the layer local to that side.
Supports Actor Filters: Allows the Data Layer to be used as an Actor Filter on Level Instances. For more information, see Using Data Layers with Level Instancing.
Data Layer Type
Data Layer Assets are set to one of two different types, Editor or Runtime.
You can use Editor Data Layers to keep your assets organized within your project. You can load and unload Editor Data Layers from memory, and toggle visibility using the Data Layers Outliner. Editor Data Layers are not available in Play In Editor or in cooked builds. Use them to isolate working sets such as a cinematic or a gameplay sequence, or to separate procedural and typed content such as buildings, roads, and forests.
Outliner folders and Editor Data Layers overlap as organization tools and become hard to manage in dense worlds. Define your scene structure early and enforce it with Level templates, assign a technical owner for project-wide Data Layers, and pre-define Data Layer Assets that match your project structure, such as missions, events, progression, and work types.
Editor and Runtime Data Layer Assets show the same properties in the Content Browser, but Load Filter only takes effect on Runtime Data Layers.
Runtime Data Layers are similar to Editor Data Layers, but you can also change their state at runtime using Blueprints or C++. In-game events can load, activate, or unload the Actors assigned to them, which opens up options for complex gameplay, level transitions, per-sequence content, and per-platform optimizations.
For example, the Valley of the Ancient sample uses a single Runtime Data Layer to switch the entire world between the Light World and the Dark World shown below. The Matrix Awakens demo uses Runtime Data Layers to stream sequence and gameplay content, to remove content under highways during specific sequences, and to activate rooftops only in drone mode. Large live games use dozens of Runtime Data Layers for seasonal and event changes, per-shot cinematic changes, and layered test configurations.
Data Layer States
Runtime Data Layers have three runtime states:
Unloaded: The content is not in memory and not visible.
Loaded: The content is in memory but not visible.
Activated: The content is in memory and visible.
Each Data Layer Instance sets the layer starting state using Initial Runtime State, per world. In the editor, every Data Layer also has two editor states, loaded and visible. Is Initially Loaded and Is Initially Visible in the instance settings set the defaults, and you can toggle them per user in the Data Layers Outliner.
Logic Operator
When an Actor belongs to several Runtime Data Layers, the Data Layers Logic Operator decides the state of its cell. Using Or, the Actor is loaded or activated as soon as any of its layers are loaded. Using the And operator, all of its layers must be loaded. Operators are set per world, not per layer or actor. Worlds that were created and saved before Operators are set to Or on load.
You can set the default for new maps in Project Settings > World Partition (NewMapsDataLayersLogicOperator) and override it per world in World Settings > World Partition Setup > Advanced > Data Layers Logic Operator.
Editor Data Layers are not affected by the operator. To customize their editor loading, set a DataLayerLoadingPolicyClass under [/Script/Engine.DataLayerManager] in your project's DefaultEngine.ini.
Hierarchy
Data Layer Instances can be nested. A child layer's effective runtime state is the minimum of its own state and the states of its Runtime ancestors, where Unloaded is lower than Loaded and Loaded is lower than Activated. A child set to Activated under an Unloaded parent has an effective state of Unloaded.
Data Layer hierarchies have the following restrictions:
Editor Data Layers cannot be children of Runtime Data Layers.
Layers with a Client Only or Server Only Load Filter cannot be part of a hierarchy.
External Data Layers must always be the root of a hierarchy. Because of this, if an External Data Layer is unloaded then all of its children are also unloaded.
Data Layer Instances
Data Layer Instances are world-specific instances of a Data Layer Asset you can create to reuse their meaning and actors they contain, as well as allowing changes to some of their properties depending on which map they are in. Using instances, a Data Layer Asset can exist in two or more worlds and reference the same Data Layer Asset. Instances are named DataLayer_{GUID} and labeled with the name of their asset.
Two other kinds of Data Layer instances are also available:
Private Data Layers: Editor-only instances without an asset that belong to the world they are created in and cannot be used by other worlds. This type can be renamed and they are the simplest way to define Actor Filters for Level Instances. Create one using Create New Private Data Layer in the Data Layers Outliner.
External Data Layer instances: Instances owned by a Game Feature Plugin. They are always roots, are Activated by default, and cannot be removed from the Outliner. For more information, see External Data Layers below.
For example, you create a neighborhood point of interest (POI) in a world and then decorate the POI using holiday-specific assets. Assigning those to a Runtime Data Layer with a name identifying the event enables them to be loaded and unloaded during runtime. In the standard version of your world, you set a Data Layer Instance of the Runtime Data Layer to not be loaded by default and to toggle on a specific date to celebrate an in-game holiday. In the same project, you can then use a separate instance of the Runtime Data Layer that is always enabled to create a holiday-themed version of the POI separate from your standard world.
External Data Layers
External Data Layers associate Actors in a World Partition Level with a Game Feature Plugin. The streaming Levels generated for those Actors are injected into the world only when the plugin is activated, which can happen at runtime, so plugins can add content to a Level without touching the base game content. This makes External Data Layers suited to downloadable content and live operations. Regular Data Layers can be parented under an External Data Layer, and the Data Layers Outliner validates plugin dependencies when you assign Actors.
External Data Layers require the Game Features plugin and Enable World Partition External Data Layers located in the Editor Preferences > Experimental options.
To set up a Game Feature Plugin:
In the Content Browser, under the plugin's Content folder, create an External Data Layer asset.
Open the plugin's Game Feature Data asset and add the Game Feature Action Add World Partition Content.
In the new action, select the External Data Layer asset. The action can also require a console variable to be set before it injects its content.
Save the Game Feature Data asset.
To add the External Data Layer to a world:
Open the partitioned map that the plugin should inject content into.
Drag the External Data Layer asset into the Data Layers Outliner. Alternatively, you can right-click in the Outliner, select Create New Data Layer With Asset, and pick the External Data Layer asset.
You can then assign, move, and remove Actors on the External Data Layer like any other Data Layer. A commandlet is available to convert existing Content Bundles to External Data Layers. For more information, see the World Partition Builder Commandlet Reference.
Data Layers Outliner
The Data Layers Outliner is used to view all of your existing Data Layer Instances and create new Data Layer Assets and Data Layer Instances. To open the Data Layers Outliner, select Window > World Partition > Data Layers Outliner. The panel opens as a tab named Data Layers.
| Number | Description |
|---|---|
1 | Visibility |
2 | Data Layer Loaded In Editor |
3 | Data Layer Type (External, Runtime, or Editor). The type is shown in the tooltip of the row, not in a column. |
4 | Data Layer Name |
5 | Data Layer Has Errors |
6 | Data Layers Outliner Options |
7 | Data Layer Asset |
8 | Is Initially Visible |
9 | Is Initially Loaded. Whether the Data Layer is loaded in the editor by default. This is an editor setting and does not affect the runtime state. |
Not Shown | Initial Runtime State. The runtime state the Data Layer Instance starts in: Unloaded, Loaded, or Activated. |
The Outliner also has a Remove from Data Layer column by default, and optional columns ID Name, Initial State, Debug Color, and Streaming Priority that you can enable from the column header.
A Data Layer Instance also has properties in the Details panel.
| Option | Description |
|---|---|
Streaming Priority | Determines the streaming priority. A lower value means a higher priority relative to the target grid cells. 0 is the same priority as the cells. |
Override Block On Slow Streaming | Overrides World Partition’s setting for when a cell is slow to stream in. It has the following options: No Override (the default), Blocking, or Not Blocking. |
Is Included | Determines whether to include the data layer when it is used as an Actor Filter. |
Right-clicking in the Data Layers Outliner opens the context menu:
| Selection | Description |
|---|---|
Create New Data Layer With Asset | Creates a Data Layer Instance from the Data Layer Asset you pick in the submenu. The Create New Data Layer entry creates an empty instance, and appears only when the world has no WorldDataLayers Actor yet. |
Create New Private Data Layer | Creates an Editor-only Data Layer that cannot be used by other worlds. |
Add Selected Actor(s) to Selected Data Layer(s) | Adds the selected Actors to the selected Data Layer Instances. |
Add Selected Actor(s) To | Adds the selected Actors to a Data Layer Instance you pick in the submenu. |
Move Selected Data Layer(s) To | Makes the selected Data Layer Instances children of another Data Layer. To create a child directly, drag a Data Layer Asset onto the parent instance. |
Remove Selected Actor(s) from Selected Data Layer(s) | Removes the selected Actors from the selected Data Layer Instances. |
Delete Selected Data Layer(s) | Deletes the selected Data Layer Instances. |
Rename Selected Data Layer | Renames the selected Data Layer. Only Private Data Layers can be renamed, one at a time. Asset-based Data Layers take their name from the asset. To rename an Asset-based Data Layer, rename the asset. |
Select Actor(s) in Data Layer(s) | Selects all the Actors assigned to the selected Data Layer Instances. |
Add Actors in Data Layer(s) to Selection | Adds the contents of the selected Data Layer Instances to your selection. |
Deselect Actor(s) in Data Layer(s) | Removes the contents of the selected Data Layers from your selection. |
Force Load Actor(s) in Data Layer(s) | Loads the Actors in the selected Data Layers in the editor regardless of the loaded region. Release Force Load Actor(s) in Data Layer(s) releases the forced load. |
Copy Selected Data Layer Instance(s) File Path | Copies the file path of the selected instances. Available only for instances stored in external packages. |
Find in Content Browser | Selects the Data Layer Asset of the selected instance in the Content Browser. |
Browse to Plugin Asset | For External Data Layers, selects the asset in the content of its Game Feature Plugin. |
Collapse All Data Layers | Collapses the Data Layer hierarchy. |
Expand All Data Layers | Expands the Data Layer hierarchy. |
Make Current Data Layer(s) | Sets the selected Data Layers as the current Actor Editor Context. For more information on Actor Editor Context, see the Actor Editor Context documentation. |
Remove Current Data Layer(s) | Removes the selected Data Layers from the current Actor Editor Context. |
Clear Current Data Layer(s) | Clears all Data Layers from the current Actor Editor Context. |
Make All Data Layers Visible | Sets the visibility of all Data Layer Instances to visible. |
Clicking the gear icon displays the Data Layers Outliner options:
| Selection | Description |
|---|---|
Expand All | Expands the Data Layer hierarchy. |
Collapse All | Collapse the Data Layer hierarchy. |
Stack Hierarchy Headers | Pins the hierarchy items to the top of the outliner. |
Only Selected | Displays only selected Actors in the Outliner. |
Hide Editor Data Layers | Hides Editor Data Layers In the Outliner. |
Hide Runtime Data Layers | Hides Runtime Data Layers in the Outliner. |
Hide Actors | Hides the list of Actors assigned to Data Layers in the Outliner. |
Hide Unloaded Actors | Hides all Actors from Unloaded World Partition cells in the Outliner. |
Hide Level Instance Content | Hides all assets contained inside Level Instances. |
Highlight Selected | Highlights Data Layer Instances that contain the selected Actors. |
Advanced > Allow Runtime Data Layer Editing | Allows the editing of Runtime Data Layer Instances. |
Advanced > Reset User Settings | Resets the Data Layers user settings to their initial values. |
World > Choose World | Determines which world's Data Layer instances are being displayed. |
Updating Legacy Projects using the Data Layers Commandlet
Projects created prior to the release of Data Layer Assets store their Data Layers in the WorldDataLayers Actor. To convert them to Data Layer Assets and Data Layer Instances, use the Data Layer To Asset commandlet:
Follow the steps below to use the commandlet:
Open a command prompt window.
At the prompt, navigate to the location of the UnrealEditor.exe file. For example: C:\Program Files\UE_5.8\Engine\Binaries\Win64.
Begin typing the command. Start with the name of the
.exefile that will run the commandlet,UnrealEditor.exe.Add the name of the project.
Add the name of the commandlet to run.
Add the name of the level you want to convert and the destination folder.
Press Enter and run the commandlet.
The command will look like this:
UnrealEditor.exe CitySample -run=DataLayerToAssetCommandlet Small_CITY_LVL -DestinationFolder=/Game/DataLayerConversionAll previous Data Layers are converted to Data Layer Instances and Data Layer Assets. All Actors that were referencing Data Layers previously now reference Data Layer Assets.
This commandlet has the following optional arguments:
| Optional Argument | Description |
|---|---|
-Verbose | Logs additional context when converting. This outputs the conversion information for every Actor with a Data Layer. |
-NoSave | Runs the commandlet without saving changes. |
-IgnoreActorLoadingErrors | Ignores errors when an Actor fails to load during conversion. |
Using Data Layers
Creating New Data Layers
To use the Data Layers system in your project, start by creating a Data Layers Asset:
In the Content Browser, navigate to the folder where you want to store your Data Layers Asset, right-click and select Miscellaneous > Data Layer to create the Data Layers Asset.
In the Data Layers Outliner, right-click and select Create New Data Layer With Asset, then pick your Data Layer Asset. This creates a Data Layer Instance labeled with the name of the asset.
If the world has no WorldDataLayers Actor yet, the menu shows Create New Data Layer instead. This creates an empty Data Layer Instance named Unknown. Assign your Data Layer Asset to it by opening the Data Layer Asset drop-down menu in the instance's Details panel and selecting your Data Layer Asset.
Alternatively, dragging and dropping a Data Layer Asset into the Data Layers Outliner creates a new Data Layer Instance with the selected Data Layer Asset assigned. Doing this on an existing Data Layer Instance creates a new child Data Layer Instance with the selected Data Layer Asset assigned.
Assigning Actors to Data Layers
You can assign an Actor to a Data Layer by using the following options:
Add an asset using the context menu in the Data Layers Outliner.
Add an asset using the Data Layers section in the Details Panel.
Partitioned Actors such as Landscape and Foliage cannot be reassigned with these methods. Foliage can be moved between Data Layers with the Move tool in Foliage mode. Partitioned Actors receive Data Layers only from the Actor Editor Context that is active when they are created.
Using the Data Layers Outliner
To add assets to a Data Layer Instance using the Data Layers Outliner:
Select the assets you want to add to the Data Layer Instance in the Viewport.
Right-click the Data Layer Instance in the Data Layers Outliner that you want to add to and select Add Selected Actor(s) to Selected Data Layer(s). You can also use the Add and Remove buttons in the Outliner toolbar.
Using the Details Panel
To add assets to a Data Layer Instance using the Details panel:
Select the assets you want to add to the Data Layer Instance in the Viewport.
Navigate to the Data Layers section of the Details panel and expand Data Layer Assets.
Click the drop-down menu for the Index you want to change and select the Data Layers Asset you want to assign. This will assign it to the instance of that Data Layers asset.
This method only works when an instance of the selected Data Layer Asset exists in the world. If the Actor's Level has its own WorldDataLayers Actor, an instance is created there automatically.
Using Actor Editor Context in the level editor, you can set any number of Data Layer Instances as Current. All Actors added with this context active are automatically assigned to the Data Layer Instances set as Current. To apply the current Data Layers to Actors that already exist, select them and use Data Layer > Apply Actor Editor Context in the Actor context menu. Partitioned Actors such as Foliage and Landscape receive Data Layers only through the Actor Editor Context that is active when they are created. For more information on Actor Editor Context, see Actor Editor Context.
Performance Considerations
Loading too many Actors at once using Data Layers can cause performance issues. Streaming an entirely new environment through Data Layers costs as much as loading a new Level.
To avoid this, preload the content during the initial load, hide the transition behind a cinematic, or make the switch in a cheaper region of the world. In Sequencer, you can use Data Layer tracks to pre-roll layers so their content is loaded before playback starts, and utilize possessable Actors over spawnables so that they stream with the world. State APIs are also available to do the same from C++ or Blueprints.
Monitor Runtime Data Layer usage closely. Each unique combination of Runtime Data Layers on the Actors in a cell produces its own streaming Level, so widely used assets assigned to many Runtime Data Layers multiply streaming Levels and degrade World Partition streaming performance. When level streaming is enabled, activating a Data Layer does not load all of its content at once. It loads and activates all the non-spatially-loaded actors, and only the spatially-loaded actors in cells that overlap a streaming source within their loading range, as expected. Is Spatially Loaded, Runtime Grid, loading ranges, and streaming sources still decide what loads. Use the Streaming Priority and Override Block On Slow Streaming options on a Data Layer Instance to tune how its cells are scheduled.
Using Data Layers with Blueprints
You can use Blueprints to change the runtime state of Data Layer Assets and Data Layer Instances through the Data Layer Manager. For Sequencer, see Using Data Layers with Sequencer.
In the example below, pressing and holding the F key will toggle the DL_RuntimeTest Data Layer.
The above Blueprint works by doing the following:
Pressing and holding the F key gets the Data Layer Manager with the Get Data Layer Manager node.
Using the Set Data Layer Runtime State node, the state of the DL_RuntimeTest Data Layer changes to Loaded. This makes it loaded but not visible in the level.
The second Set Data Layer Runtime State node changes the state of the DL_RuntimeTest Data Layer Instance to Activated. This makes it loaded and visible.
Releasing the F key reverses the process and sets the Data Layer back to its original states.
Using Data Layers with C++
Similar to the Blueprint example above, you can access your project's Data Layers using C++ through UDataLayerManager. The example code shown below creates an Actor named ADataLayerActivator.
UCLASS()
class ENGINE_API ADataLayerActivator : public AActor
{
GENERATED_BODY()
public:
virtual void BeginPlay() override
{
// In client/server only the server can activate a DataLayer
if (HasAuthority())
{
When ADataLayerActivator calls BeginPlay, it references a specific Data Layer Asset and sets its runtime state to Activated. Only the server changes replicated Data Layers. The Data Layer Manager functions are not restricted to authority, but a call made on a client for a replicated layer is ignored and logged at Verbose. Layers with a Client Only or Server Only Load Filter are local to that side, are not replicated, and cannot be part of a hierarchy.
Using Data Layers with Sequencer
A Data Layer track in Sequencer loads, activates, or unloads Data Layers in a World Partition world. Each section of the track lists the Data Layer Assets it controls and sets a Desired State that applies while the section plays and a Preroll State that applies during the section's pre-roll, so content is loaded before it is needed. Flush On Activated waits for the content to finish loading when the section activates, which may cause a hitch, and Flush On Unload does the same on unload. When the section ends, the Data Layers return to their previous state.
Using Data Layers with Level Instancing
Level Instances and Packed Level Actors support Data Layers. Data Layers assigned to a Level Instance Actor propagate to all of its content, but a Packed Level Actor carries Data Layers on the Actor only.
The Actors contained within the Level Instance inherit the Data Layers assigned to its Level Instance Actor by default. Actors within the Level Instance also support additional Data Layers.
Actors inside a Level Instance keep their Data Layer Assets, but these only take effect when the main world has instances of the same assets; the states of those instances then apply. While editing a Level Instance, you can preview its Level-Instance-specific Data Layers and promote them to the main world. Data Layers that have no instance in the world are not carried over.
For example, you can assign a Level Instance that contains the assets to create a house point of interest to a Neighborhood data layer. The Level Instance can also contain holiday-themed items assigned to different holiday data layers only visible when that data layer is enabled.
Using Data Layers with Actor Filters
Data Layers also drive Actor Filters. Private Data Layers and Data Layer Assets with Supports Actor Filters enabled appear as filters on every Level Instance Actor that references the Level, with Is Included as the default, so a single Level can produce static variants per instance. Actor Filters require the Level Instance to use the Embedded Level Behavior. External Data Layers apply to the Level Instance Actor only.
To use Actor Filters, turn on World Partition Actor Filters in Editor Preferences > Experimental.
Managing Files
Keeping with the World Partition system's goal of minimizing file overlap between users, Data Layers reduce the need for users to check out important files, such as the world map file or Actor files, when changes are made.
Each Data Layer has a display label and a unique identifier. Unreal Engine stores this information in a list of Data Layers in the WorldDataLayer file which provides the following benefits:
Assigning Data Layers to an Actor only affects that Actor's file In a World Partition world using One File Per Actor.
Renaming a Data Layer only affects its associated label. There is no need to update any Actors associated with the layer.
Deleting a Data Layer only affects the WorldDataLayer file. Actors previously associated with the deleted Data Layer are automatically cleaned up with no need to modify or save the Actor.
Because every Data Layer Instance lives in the WorldDataLayers Actor by default, a team that frequently adds or removes instances contends for that one file. Enable Use External Package Data Layer Instances on the WorldDataLayers Actor to store each instance in its own external package, so that adding or removing an instance only dirties that package. This is recommended for shared maps.
Debugging and Runtime Overrides
There are several useful console commands for debugging Data Layers during runtime.
| Console Command | Description |
|---|---|
wp.Runtime.DumpDataLayers | Dumps the Data Layers and their runtime state to the log. |
wp.Runtime.DebugFilterByDataLayer | Filters the debug display of World Partition streaming by Data Layer. |
wp.Runtime.SetDataLayerRuntimeState [state] [layer] | Forces a Data Layer to a specific runtime state. |
wp.Runtime.ToggleDataLayerActivation [layer] | Toggles the activation of a specific Runtime Data Layer. |
wp.Runtime.ToggleDrawDataLayers | Displays a list of Data Layers and their states in the main view. |
wp.Runtime.ToggleDrawDataLayersLoadTime | Toggles the debug display of the load time of active Data Layers. |
wp.Runtime.HashSet.ShowDebugDisplayMode 1 | Colors the 2D runtime hash debug display by Data Layer. |
wp.Runtime.ServerDisallowStreamingOutDataLayers | Read-only. A comma-separated list of Data Layer names that cannot be unloaded or deactivated on the server. |
wp.Runtime.DumpDataLayers | Reports all of the effective data layer states. If a layer you activated doesn’t appear under Active, this could mean its hierarchy blocked it. |