Level Instancing is a level-based workflow designed to improve and streamline the level editing experience. Use the Level Instancing workflow with one or more Actors to create Level Instances that can be placed down and repeated across your world. In the editor, you can also create, edit, and break Level Instances from Python. For more information, see Scripting Level Instances.
This workflow provides the following benefits:
Level Instances are edited in-context, letting you immediately see how your changes will affect your world. Changes made to one instance are repeated across all instances when saved.
Reuse a set of Actors as many times as you need: points of interest, houses, interiors, building floors, decoration sets, villages, and standalone gameplay setups. Level Instances are not prefabs. Every instance references the same source Level, and per-instance variation comes from Actor Filters and Property Overrides. For more information, see Variants.
Pack dense, visual-only static setups such as building facades, static buildings, and interior decoration sets into a single optimized Actor. For more information, see Packed Level Actors.
Production-ready process used across Epic Games' own large open-world titles and in the City Sample and Valley of the Ancient demos. Level Instances are used for individual buildings, houses, and points of interest, and Packed Level Actors for hand-crafted hero buildings and rooftop assemblies.
Level Instances do not have streaming management or streaming strategies outside of a World Partition main world, although you can use them with standard Level Streaming. Use Level Instances in World Partition Levels with One File Per Actor (OFPA) enabled. A non-OFPA Level Instance that is not embedded streams as a separate Level for every placed instance, which costs performance, and HLODs are not generated for it. For more information, see Level Behavior.
Creating Level Instances
There are two types of Level Instances:
Level Instances: Collections of Actors that are combined to create a sublevel. Multiple instances of a sublevel can be repeated across your project, something not possible in previous versions of Unreal Engine. Use this type for points of interest and standalone gameplay setups.
Packed Level Actors: A single Blueprint Actor optimized for rendering. Use this type for dense, visual-only setups such as static buildings, facades, and interior decoration sets.
Packing converts the Static Mesh Components of the Actors in the source Level into Instanced Static Mesh Components (Hierarchical Instanced Static Mesh Components when a mesh has more than one instance and does not use Nanite) in a Blueprint named
BPP_<LevelName>whose parent class isAPackedLevelActor.Nested Level Instances are flattened into the result. Everything else in the source Level is discarded: other component types are not packed, and the Output Log reports
Component 'Name' was not packedandConsider using a regular ALevelInstance instead.A Packed Level Actor streams as one Actor, and its bounds decide which streaming cell loads it, so keep each one smaller than a streaming cell. You can place Packed Level Actors inside Level Instances like any other Actor.
Creating a Level Instance
You create Level Instances from selected Actors in either the Viewport or the Outliner. You can also drag a Level from the Content Browser into a World Partition Level to create a Level Instance Actor that references that Level.
Build and review Level Instances in a dedicated editor-only Level that contains your project's lighting and post-processing, away from the full world. Add a shared base Level Instance with Is Main World Only enabled so that it loads only when you open the Level Instance on its own, and reuse that setup as a template for new Level Instances. For more information, see Main World Only Level Instances.
After selecting the Actors, right-click one of them to open the context menu. Navigate to Level > Actor Selection, and select Create Level Instance.... The New Level Instance dialog opens.
The New Level Instance dialog has the following settings:
| Setting | Description |
|---|---|
External Actors | Enables the One File Per Actor (OFPA) system for the new Level. In a World Partition Level, this option is hidden and always enabled; in other Levels it is enabled by default. For more information, see the One File Per Actor documentation. |
Pivot Type | Sets where the pivot of the Level Instance is located:
|
Pivot Actor | Selects the Actor that is the pivot point of the Level Instance when Pivot Type is Actor. |
Choose Level Instance Template... | Selects the template for the new Level. This option appears only when your project defines Level Instance templates. |
Always show dialog | Shows this dialog every time you create a Level Instance. When disabled, the editor reuses your last settings without opening the dialog. You can change this in Editor Preferences > Content Editors > Level Instance. |
Once you have selected your settings and click Ok, you are asked to save the new Level Instance.
This process creates a new Level Instance 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 are applied to the Level Instance.
The Actors that make up the Level Instance remain visible in the Outliner as children of the Level Instance Actor. By default, you cannot select them outside of edit mode.
To select them, enable Allow Read Only Selection of Level Instance Level Actors in Editor Preferences > Content Editors > Level Instance; in the Viewport, use Shift + Mouse Scroll Up and Shift + Mouse Scroll Down to move the selection into and out of the Level Instance.
To hide the child Actors, enable the Hide Level Instance Content filter in the Outliner. Moving Actors into or out of a Level Instance still requires edit mode.
The Outliner and Viewport show the state of each Level Instance. A Level Instance's label turns green while you edit it and blue while you edit its Property Overrides, and a Level Instance Overrides column appears in the Outliner when Property Overrides are enabled. The Actor Coloration options Level Color and Level Instance Property Override color Actors in the Viewport by the Level Instance they belong to.
Creating a Packed Level Actor
Like Level Instances, Packed Level Actors are generated from selected Actors and can be created by right-clicking in the Viewport or the Outliner.
After selecting the Actors, right-click one of them to open the context menu. Navigate to Level > Actor Selection, and select Create Packed Level Actor.... The New Packed Level Actor dialog opens.
The dialog has the same settings as the New Level Instance dialog. Select your settings and click Ok. You are then asked to save the new Level and the new Packed Level Blueprint, which is saved as BPP_<LevelName> next to the Level. If the editor cannot create the Blueprint, it logs Failed to create packed level blueprint. Creating non blueprint packed level instance instead. and places a Packed Level Actor that is not backed by a Blueprint.
This process creates a new Packed Level Actor in the Level, associated with your Packed Level Blueprint. Packed Level Actors have fixed limits: the source Level never loads at runtime, Packed Level Actors never partially load in the editor, they do not support Actor Filters or Property Overrides, and they carry Data Layers on the Actor only.
Level Instance Settings
The following settings control how Level Instances behave in the editor.
| Setting | Description |
|---|---|
Enable Streaming | Enables streaming for Level Instances. Found in Project Settings > Editor > Level Instance. |
Is Edit in Place Streaming Enabled | Allows editing Level Instances whose Level is partitioned with streaming enabled. Found in Project Settings > Editor > Level Instance. For more information, see Editing a Level Instance. |
Always show dialog | Shows the New Level Instance dialog every time you create a Level Instance or Packed Level Actor. Found in Editor Preferences > Content Editors > Level Instance. |
Pivot Type | Sets the default Pivot Type of the New Level Instance dialog. Found in Editor Preferences > Content Editors > Level Instance. |
Allow Read Only Selection of Level Instance Level Actors | Allows selecting the Actors inside a Level Instance without entering edit mode. Found in Editor Preferences > Content Editors > Level Instance. |
Keep Folders During Break | Sets the default of the Keep Folders option when breaking Level Instances. Found in Editor Preferences > Content Editors > Level Instance. |
The following console variables are useful when working with Level Instances:
| Console Variable | Description |
|---|---|
| Forces every Level Instance to stream as Standalone instead of embedding. The default is 0. |
| Repacks every Packed Level Blueprint that shares a source Level when you save an edit, not only the one you edited. The default is 0. |
| Disables partial loading of Level Instances in the editor. The default is 0. |
| Enables experimental Editor Path support. The default is 0. For more information, see Editor Paths. |
Editing Level Instances
Once created, you can copy Level Instances and Packed Level Actors and place them across your world. Inside a World Partition Level with streaming enabled, embedded Level Instances load partially in the editor, following the loaded region, and load fully when you edit them. Packed Level Actors never partially load. To disable partial loading, set wp.Editor.DisableLevelInstanceEditorPartialLoading to 1.
Editing a Level Instance
To edit a Level Instance, select it in the Viewport, right-click to open the context menu, and under Level select Edit.
You can also click Edit in the Details panel, or Alt + double-click the Level Instance in the Outliner.
For nested Level Instances, the Edit submenu (Context) lists the selected instance and its ancestors so you can choose which one to edit. Only one Level Instance can be edited at a time, entering edit mode clears the undo history, and the editor loads the instance synchronously while it displays Loading Level Instance for edit....
You cannot edit in place a Level Instance whose Level is partitioned with streaming enabled; the editor reports Level Instance can't be edited in place because it has streaming enabled. To allow it, enable Is Edit in Place Streaming Enabled in Project Settings > Editor > Level Instance.
This grays out all other Actors in your world and makes them unselectable, so you can edit the Level Instance in context. Press Shift + L (Toggle Context Restriction) to turn the selection restriction off and on.
Entering edit mode loads the entire Level Instance synchronously, even if it was only partially loaded, so keep Level Instances to a manageable size. Prioritize one Level Instance per location over a single world-sized Level Instance, and use Editor-Only Data Layers to organize content by type. Outside edit mode you cannot edit, copy, or view the properties of the Actors inside a Level Instance, which also prevents copying Actors from one Level Instance into another one that you are editing. You can, however, change the visibility of those Actors from the Outliner without entering edit mode.
When you finish, select the Level Instance Actor in the Outliner and click Save in the Details panel. Save is also available in the editor mode toolbar and in the context menu under Level > Current Edit. To discard your changes instead, click Cancel.
To discard changes, click Cancel in the Details panel. If you moved Actors into or out of the Level while editing, you cannot discard the edit; the editor reports Can't discard edit because some actors were moved from/to level while editing.
Pressing Esc from the Details panel opens the prompt Unsaved Level changes will get discarded. Do you want to save them now? with Yes, No, and Cancel. Selecting No will discard your changes, and selecting Cancel will return you back to the Details panel to continue editing.
Any changes made to a Level Instance propagate to all copies of the Level Instance in your world.
Editing a Packed Level Actor
To edit a Packed Level Actor, locate an instance of it in the Outliner and click Edit to edit its source Level in context, as for a Level Instance.
You can also open the Packed Level Blueprint in the Blueprint Editor by double-clicking it in the Content Browser. When you save an edit, the editor repacks the Blueprint you edited. Other Packed Level Blueprints that share the same source Level are repacked only if levelinstance.ShouldAutoUpdatePackedBlueprintsOnCommit is set to 1 (the default is 0).
To repack manually, use Update Packed Blueprint in the Actor's context menu, Build > Packed Level Actor > Pack Level Actors, or Update Packed Blueprints in the Content Browser.
Any changes to the source Level propagate to every Packed Level Actor that uses the Blueprint. Repacking updates only the Instanced Static Mesh Components of the Packed Level Blueprint, so components, variables, and graphs that you add in the Blueprint Editor persist across repacks.
Breaking Level Instances
Breaking a Level Instance removes the Level Instance Actor or Packed Level Actor from the world and replaces it with the Actors that it contains. It does not delete the Level or the Packed Level Blueprint from the Content Browser.
To break one or more selected Level Instances, right-click one of them and select Level > Break. In the Break Level Instance(s) dialog, set Depth (use 1 to break only the top-level instance and keep nested Level Instances intact) and Keep Folders (keeps the Outliner folders of the released Actors), then click Break Level Instance(s) and confirm the prompt.
This operation cannot be undone.
Not every Actor is released. The Level's default brush, its World Settings, and Actors with Is Main World Only enabled are dropped, and the released Actors inherit the Data Layers of the Level Instance Actor. You cannot break a Level Instance while it is being edited or overridden, or when a nested Level contains Level Blueprint logic; the editor reports Failed to completely break Level Instance because some children have Level Scripts
Editor Paths
By default, Actors outside a Level Instance cannot reference Actors inside it. Editor Paths (experimental) let objects in the persistent world or in a parent Level Instance reference objects inside a Level Instance, including nested ones, through the standard reference picker. The editor resolves the paths when it generates streaming for Play In Editor and when cooking, so the references point at the embedded Actors.
To enable Editor Paths, set Editorpaths.Enabled to 1 under [SystemSettings] in your project's DefaultEngine.ini. The default is 0.
Variants
Level Instances are not prefabs. Every instance references the same source Level, and editing one changes all of them. Two features give individual instances controlled variation without duplicating the Level.
Actor Filters
Actor Filters (experimental) include or exclude Actors per Level Instance using Data Layers. To enable them, turn on World Partition Actor Filters in Editor Preferences > Experimental.
In the source Level, Private Data Layers and Data Layer Instances that are set to support Actor filtering appear as filters on every Level Instance Actor that references the Level. Each filter has a default state, and each Level Instance Actor can override it.
Actor Filters are static: the editor applies them when it generates streaming for Play In Editor and when cooking, and filtered-out Actors are removed from the game entirely. Use them for alternate layouts, decoration sets, lighting sets, decals, and style changes.
For content that you need to toggle at runtime, use Runtime Data Layers instead.
Actor Filters are available only on embedded Level Instances. They are not available on Standalone Level Instances or on Packed Level Actors.
To reuse a configured set of filters, right-click a Level in the Content Browser and select New Blueprint.... This creates a Blueprint named BP_<LevelName> with the Level preset. Set its filters, then place the Blueprint like any Level Instance.
Property Overrides
Property Overrides (experimental) let you change properties of the Actors inside one Level Instance without changing the source Level or any other instance. Overrides work on World Partition Level Instances in World Partition worlds, including nested instances, and can be restricted with a policy class. They are not available on Packed Level Actors.
To enable Property Overrides, turn on the Level Instance Property Overrides editor flag, and set a policy class in your project's DefaultEngine.ini. There is no Project Settings entry for the policy class:
[/Script/Engine.LevelInstanceSettings]
PropertyOverridePolicyClass=/Script/Engine.LevelInstancePropertyOverrideSamplePolicy
The sample policy allows every property to be overridden. To restrict overrides, create your own policy class and override CanOverridePropertyImpl; returning false prevents the property from being serialized as an override and makes it read-only in the Details panel.
To override properties, right-click the Level Instance and select Level > Override. The Level Instance enters override mode, which works like edit mode but highlights the instance in blue instead of green in the Outliner. Select Actors inside the Level Instance and change their properties, then click Save to keep the overrides or Cancel to discard them. To remove all overrides from an instance, click Reset Overrides.
Main World Only Level Instances
Enable Is Main World Only on a Level Instance Actor to load it only when its owning Level is loaded directly as the main world. Use this for content that you want to see while working on a Level Instance by itself, such as base lighting in a building template, but that must not be included when the Level Instance is placed in the game world. Actors with Is Main World Only enabled are dropped when a Level Instance is embedded or broken.
Scripting Level Instances
In the editor, you can drive Level Instances from Python through the Level Instance Subsystem (unreal.LevelInstanceSubsystem). The functions are editor-only and are not available in Blueprints. They:
Require an editor world (not a Play In Editor session), never open dialogs, and raise
RuntimeErrorwhen an operation is refused.Take Actors as arguments and cover the full workflow:
create_level_instance_from_actors,edit_level_instance,commit_level_instance,discard_level_instance,get_editing_level_instance, the equivalent functions for Property Overrides,break_level_instance,move_actors_to_level_instance,get_level_instances,get_parent_level_instance, andget_child_level_instances.
Creating
create_level_instance_from_actors(actors, level_package_name, creation_type, pivot_type=CENTER_MIN_Z, pivot_actor=None) creates a Level Instance or Packed Level Actor from the given Actors. The package name must be a new long package name; if it already exists, the call fails with Package 'Name' already exists; level instances are created in a new level.
In a partitioned world the new Level always uses external actors, and the Level Instance class and streaming settings come from the editor settings. No save dialog opens and Level Instance templates are not applied.
Editing
edit_level_instance, commit_level_instance, discard_level_instance, and get_editing_level_instance correspond to Edit, Save, Cancel, and the current edit. edit_level_instance refuses to start when another edit has unsaved changes, with Another level instance edit has unsaved changes; commit or discard it first., instead of prompting. Other blockers report Level instance 'Name' can't be edited: Reason.
Breaking
break_level_instance(level_instance, levels=1, keep_folders=False) breaks a Level Instance and returns the released Actors. It shows no confirmation, requires a loaded Level Instance that is not being edited and a levels value of 1 or more, and, like the menu command, cannot be undone.
Level Instances at Runtime
Data Layers
Level Instances and Packed Level Actors support World Partition: Data Layers.
The Actors inside a Level Instance inherit the Data Layers assigned to the Level Instance Actor. Actors inside the Level Instance can also have their own Data Layers, but only Data Layers that have an instance in the main world take effect. When you create a Level Instance, only non-private, non-external Data Layer assets that have an instance in the source world are copied into the new Level. External Data Layer assignments are removed from the moved Actors and are set on the Level Instance Actor only when all of the moved Actors shared them. Packed Level Actors carry Data Layers on the Actor only.
For example, a Level Instance that contains the assets to create a house point of interest can be assigned to a Neighborhood data layer. The Level Instance can also contain holiday themed items that are assigned to different holiday data layers that are only visible when that data layer is enabled.
Level Behavior
Each Level Instance Actor defines how its content streams at runtime with the Level Behavior property, in the Level category (advanced) of the Details panel. The values are Embedded (the default) and Standalone. Packed Level Actors do not use Level Behavior; a Packed Level Actor is a single Actor and streams like any other Actor, based on its bounds.
Which behaviors a Level supports depends on whether the Level is partitioned, uses One File Per Actor (OFPA), and has streaming enabled:
| Partitioned | OFPA | Streaming Enabled | Embedded | Standalone |
|---|---|---|---|---|
No | No | N/A | Yes | Yes |
No | Yes | N/A | Yes | Yes |
Yes | Yes | No | Yes | Yes |
Yes | Yes | Yes | Yes | Yes |
Embedded
When Level Behavior is Embedded, the Level Instance exists only in the editor. When the editor generates streaming for Play In Editor and when cooking, the Level Instance Actor is discarded and its Actors are added to the World Partition grid of the owning world, where they also join its HLODs. This is the default and the recommended way to stream Level Instance content.
Embedding requires the source Level to use One File Per Actor (OFPA) or, for a non-OFPA Level, to have been saved with Actor metadata. If a non-OFPA Level is not compatible, the Level Instance silently falls back to Standalone streaming and the streaming generation log reports is not using external actors, resave level to add compatibility; resave the Level to fix it. Embedded non-OFPA Levels support HLODs, but not Data Layers on the Actors they contain. To force every Level Instance to stream as Standalone for testing, set levelinstance.debug.forcelevelstreaming to 1.
Because embedded Actors are broken into the owning world, Level Instances do not support Level Blueprints. Static lighting with CPU Lightmass (experimental) supports World Partition Levels and Level Instances, including both lightmaps and volumetric lightmaps.
Some Actors that do not use OFPA are lost when a Level Instance is embedded. The Level's World Settings, its default brush, and Actors with Is Main World Only enabled do not exist at runtime, and the engine does not warn about it. Do not rely on these Actors, or set Level Behavior to Standalone when you need them.
Standalone
When Level Behavior is Standalone, the Level Instance is kept as a block and streams as its own Level when the World Partition cell that contains the Level Instance Actor loads. Any Level can be Standalone, including Levels that use OFPA. If the Standalone Level is itself partitioned with streaming enabled, it runs its own World Partition as a sub-world partition and streams its content from its own grid, which suits large, distinct locations with their own streaming needs inside a larger world.
The HLODs of a Standalone Level Instance are visible before the Level streams in only when Standalone HLOD (experimental) is enabled. Actor Filters are not available on Standalone Level Instances.
Standalone streaming has an added runtime cost because every instance adds a Level to stream. Avoid a high density of Standalone Level Instances.
Embedded Level Instances with World Partition: Data Layers approximate what dynamically loaded Levels did before. Use Actor Filters for static variation that is baked when streaming is generated, and Runtime Data Layers for content that you toggle in game.