World Partition

Building large maps used to require developers to manually divide maps into sublevels, then use the Level streaming system to load and unload them as the player traversed the landscape. This method often created issues sharing files between multiple users, and viewing the whole world in context became a difficult task.

World Partition is an automatic data management and distance-based level streaming system that provides a complete solution for large world management. The system removes the previous need to divide large levels into sublevels by storing your world in a single persistent level separated into grid cells, and provides you with an automatic streaming system to load and unload those cells based on distance from a streaming source.

World Partition works closely with the following features:

• One File Per Actor

• World Partition - Data Layers

• Level Instancing

• World Partition - Hierarchical Levels of Detail

Enabling World Partition

There are three ways to enable World Partition within Unreal Engine:

• Creating a new project from a template in the Games category.

• Creating a new Level using the Open World template.

• Converting existing levels to use World Partition.

Creating Your Project using a Games Template

World Partition is enabled by default in many of the project templates found in the Games category.

To reduce complexity and provide a scalable solution when creating new projects, grid cell streaming can be enabled and disabled using the Enable Streaming option in the World Settings.

The following templates use World Partition but have Enable Streaming disabled by default:

• Blank

• First Person

• Third Person

• Top Down

• Vehicle Advanced

Using the Open World Default Map

The Open World default map type is designed to be a starting point for creating large open-world maps and comes with the following features enabled by default:

• World Partition

• One File Per Actor

• Data Layers

• Hierarchical Levels of Detail

The map contains a sample 2 km x 2 km Landscape with a Landscape Material and lighting setup for an outdoor environment. This includes a sky atmosphere, skylight, directional light, exponential height fog, and volumetric clouds.

To use the Open World default map type within your project:

1. Open the File menu and select New Level.

2. Select the Open World map type.

3. Click the Create button to create a new map.

Converting Existing Levels to use World Partition

You can add World Partition to any Level by converting it using the Tools > Convert Level menu option, or by using the World Partition Convert Commandlet.

To use the World Partition Convert commandlet, follow these steps:

Command: UnrealEditor.exe QAGame -run=WorldPartitionConvertCommandlet Playground.umap -AllowCommandletRendering

To convert your existing Levels to World Partition:

1. In Windows, open a Command Prompt window.

2. At the prompt, begin by navigating to the location of the UnrealEditor.exe executable file. In the above example: c:\Builds\Home_UE5_Engine\Engine\Binaries\Win64.

3. Next, begin the command with the name of the .exe file that will run the commandlet, UnrealEditor.exe

4. Add the name of the project. Here, QAGame.

5. Continue with the name of the commandlet to run, -run=WorldPartitionConversionCommandlet.

6. Add the name of the map file that will be converted. In the above example Playground.umap.

7. Finish the command with the additional argument -AllowCommandletRendering.

8. Press Enter and the commandlet will convert the map to use World Partition.

The following optional arguments are available for this commandlet:

If you want to alter the conversion settings, use a default conversion .ini file with the commandlet. The .ini file needs to be in the same folder as your map file and have the same filename as your map, but with the .ini extension. For example, an .ini file written for the FirstPersonExampleMap.umap would be named FirstPersonExampleMap.ini.

Here is an example of a default conversion .ini file:

    [/Script/UnrealEd.WorldPartitionConvertCommandlet]
    EditorHashClass=Class'/Script/Engine.WorldPartitionEditorSpatialHash
    RuntimeHashClass=Class'/Script/Engine.WorldPartitionRuntimeSpatialHash
    LevelsGridPlacement=(("/Game/Maps/Highrise_Audio", Bounds),("/Game/Maps/Highrise_Collisions_Temp", Bounds),("/Game/Maps/Highrise_Gameplay", Bounds),("/Game/Maps/Highrise_Lights", Bounds),("/Game/Maps/Highrise_Vista", AlwaysLoaded))
    HLODLayerAssetsPath=
    DefaultHLODLayerName=

    [/Script/Engine.WorldPartitionEditorSpatialHash]
    CellSize=51200
    WorldImage=None
    WorldImageTopLeftW=(X=0.000000,Y=0.000000)
    WorldImageBottomRightW=(X=0.000000,Y=0.000000)

    [/Script/Engine.WorldPartitionRuntimeSpatialHash]
    Grids=(GridName="MainGrid",CellSize=3200,LoadingRange=25600.000000,DebugColor=(R=0.500000,G=0.500000,B=0.500000,A=1.000000))

Using World Partition

The World Partition system works by storing your world in a single persistent Level file and subdividing the space into streamable grid cells using a configurable runtime grid. These cells are loaded and unloaded at runtime by the presence of streaming sources, such as the player. In this way, Unreal Engine only loads the parts of the Level that the player sees and interacts with at a given time.

Actors in World Partition

When editing the world, Actors can be added anywhere and are automatically assigned to a grid cell based on their Is Spatially Loaded setting, found in their Details panel's World Partition section.

Since Actors are saved to their own individual files using the One File Per Actor feature, you do not need to check out the Level file from source control to make changes to the Actors in the world. This frees up the Level file for others on your team.

For more information on the One File Per Actor system and Unreal Engine's integrated source control, see the One File Per Actor documentation.

Streaming Sources

Streaming of grid cells within the grid at runtime is determined by two factors:

• Streaming Sources

• Runtime Grid Settings

The first is the position of streaming sources in the Level.

Streaming sources are components that define a position in the world and trigger the loading of cells around them. Player Controllers are a streaming source. Other streaming sources can be added to the world using the World Partition Streaming Source component. For example, a streaming source component can be activated at the location that a player will teleport to, so it can load the cells there. Once the grid cells are loaded, the player teleports to the location and the streaming source component is deactivated. Since there is no longer a streaming source at the player's previous location, those grid cells would be unloaded.

Using the Player as a Streaming Source

Each Player Controller is used as a World Partition streaming source using the Enable Streaming Source option. This is enabled by default:

Using the World Partition Streaming Source Component

World Partition streaming is also done using the World Partition Streaming Source component:

This component has the following options:

The Blueprint functions Enable Streaming Source and Disable Streaming Source will enable and disable streaming with this component.

The Blueprint function Is Streaming Completed returns true when the component has finished streaming the grid cells that it intersects with.

Runtime Grid Settings

The second factor that determines whether a grid cell is loaded or unloaded at runtime is the settings of the runtime grid itself. Runtime grid settings are located in the World Settings panel, in the World Partition Setup section.

A 2D Runtime Hash grid is provided by default. Using more than one grid can negatively impact performance.

For more information on the recommended setup and settings for your 2D Runtime Hash grid, see the Big City map located in the City Sample project.

Loading and Unloading Regions in the Editor

To support the development of large worlds, the world is initially unloaded. When the Level opens, the Editor only loads Actors that have their Is Spatially Loaded setting marked as False, such as environment backdrops and managers. This supports the development of large worlds where it is impossible to load the entire map in the Editor.

Load and Unload Regions Using the World Partition Window

In the World Partition window, you can manually select the region to work in. Open the window by selecting Window > World Partition > World Partition Editor from the main menu.

In the window, click and drag out a region. Then, right-click the selection to open the context menu and select Load Region from Selection.

Load and Unload Regions Using Location Volumes

Regions can also be loaded and unloaded using Location Volumes.

A Location Volume is an Editor-only volume placed into the level that represents a region of the map in the World Partition window.

To add a Location Volume to your level, follow the steps below:

1. Open the Place Actors window, if it is not already open.

2. Search for Location Volume. Click on it and drag one into your level.

3. Save your level.

Once the level is saved, a new region will appear in the World Partition window with the same name as the Location Volume.

Select the region and right-click to open the context menu. Click Load Selected Region to load the region. Several regions can be loaded or unloaded at the same time by drag selecting or ctrl+clicking multiple regions.

Location Volumes have the following supported settings:

Brush Settings

World Partition

Generating a Minimap for the World Partition Window

You can generate a Minimap to make navigating in the World Partition window easier by using the Build Minimap option found in the World Partition section of the Build menu, or by using the World Partition Minimap Builder commandlet.

Running this commandlet creates a Minimap image of your World Partition world and places it in the World Partition window.

Useful Shortcuts and Options in the World Partition Window

Generating Hierarchical Levels of Detail (HLODs)

HLODs are generated using the Build HLODs option found in the World Partition section of the Build menu, or by using the World Partition HLODs Builder commandlet.

Running this commandlet creates the HLOD Actors for your World Partition cells according to the generation settings you specified in your HLOD Layers. For more information about using Hierarchical Levels of Detail (HLODs) in World Partition and using the World Partition HLODs Builder commandlet, see the World Partition - Hierarchical Level of Detail documentation.

Cooking a World Partition world

Cooking a World Partition map requires the use of the Cook commandlet:

Command: UnrealEditor.exe QAGame -run=cook -targetplatform=WindowsNoEditor -Unversioned -map=Playground

To cook your World Partition map:

1. In Windows, open a Command Prompt window.

2. At the prompt, begin by navigating to the location of the UnrealEditor.exe executable file.

3. Next, begin the command with the name of the .exe file that will run the commandlet, UnrealEditor.exe.

4. Add the name of the project. Here, QAGame.

5. Continue with the name of the commandlet to run, -run=cook.

6. Finish the command with the following arguments:

   • -targetplatform=WindowsNoEditor cooks the project for Windows platforms.

   • -UnVersioned saves all of the cooked packages without versions. These are then assumed to be the current version on load.

   • -map=Playground specifies the name of the map, in this case Playground.umap.

For more information on using the Cook commandlet, see Content Cooking.

Using World Partition with Blueprint

Both Blueprint Classes and Level Blueprints are supported in a World Partition world. However, Blueprint Classes are preferred, as any Actors referenced in the Level Blueprint will be marked as Always Loaded.

Testing a Partitioned World

Debugging and Runtime Overrides

There are several useful console commands for debugging a World Partition world during runtime.

World Partition Builder Commandlets

World Partition introduces a builder commandlet framework through the UWorldPartitionBuilderCommandlet and the UWorldPartitionBuilder base class.

These commandlets are used to automate batch processes and generate or modify data in World Partition Levels. Large worlds will not have to be loaded all at once to do things like generating HLODs, AI Nav Data, or resave a large number of Actors.

World Partition HLODs Builder

HLODs are generated using the World Partition HLODs Builder commandlet. Running this commandlet creates the HLOD Actors for your World Partition cells according to the generation settings you specified in your HLOD Layers.

Command: UnrealEditor.exe "C:\Users\user.name\Documents\Unreal Projects\MyProject\MyProject.uproject" "/Game/ThirdPersonBP/Maps/OpenWorldTest" -run=WorldPartitionBuilderCommandlet -AllowCommandletRendering -builder=WorldPartitionHLODsBuilder

For more information about using Hierarchical Levels of Detail (HLODs) in World Partition and using the WorldPartitionHLODsBuilder commandlet, see the World Partition - Hierarchical Level of Detail documentation.

World Partition MiniMap Builder

The World Partition MiniMap Builder commandlet generates or updates the minimap that displays in the WorldPartition Editor window.

Command: UnrealEditor.exe "C:\Users\user.name\Documents\Unreal Projects\MyProject\MyProject.uproject" "/Game/ThirdPersonBP/Maps/OpenWorldTest" -run=WorldPartitionBuilderCommandlet -AllowCommandletRendering -builder=WorldPartitionMiniMapBuilder

World Partition Rename Duplicate Builder

The World Partition Rename Duplicate Builder commandlet automates the process of renaming or duplicating an existing World Partition Level and all its actors.

Command: UnrealEditor.exe "C:\Users\user.name\Documents\Unreal Projects\MyProject\MyProject.uproject" "/Game/ThirdPersonBP/Maps/OpenWorldTest" -run=WorldPartitionBuilderCommandlet -SCCProvider=None -builder=WorldPartitionRenameDuplicateBuilder -NewPackage=/Game/ThirdPersonBP/Maps/NewPackage

This will create a duplicate World Partition Level of the OpenWorldTest map named NewPackage and leave the original map untouched.

To rename your World Partition map rather than make a copy, add the -Rename argument.

World Partition Resave Actors Builder

The World Partition Resave Actors Builder commandlet resaves all Actors of a World Partition Level and supports a class filter to resave only a subset of Actors.

Command: UnrealEditor.exe "C:\Users\user.name\Documents\Unreal Projects\MyProject\MyProject.uproject" "/Game/ThirdPersonBP/Maps/OpenWorldTest" -run=WorldPartitionBuilderCommandlet -SCCProvider=None -builder=WorldPartitionResaveActorsBuilder

When you execute the above example, all of the Actor's packages in the OpenWorldTest level are resaved.

You can use the -ActorClass argument to specify only a subset of Actors to be resaved. For example, adding -ActorClass=StaticMeshActor will resave only the Static Mesh Actors in the specified Level.

World Partition Foliage Builder

In a World Partition map, the default Instanced Foliage Grid Size for Foliage Instances is 256 meters. The World Partition Foliage Builder commandlet is used to change the Instanced Foliage Grid Size for existing World Partition level.

Command: UnrealEditor.exe QAGame Playground.umap -run=WorldPartitionBuilderCommandlet -Builder=WorldPartitionFoliageBuilder -NewGridSize=Value

For more information on using Foliage Mode with World Partition, see the Foliage Mode documentation.

World Partition Navigation Data Builder

The World Partition Navigation Data Builder commandlet rebuilds the navmesh in your World Partition Level.

Command: UnrealEditor.exe "C:\Users\user.name\Documents\Unreal Projects\MyProject\MyProject.uproject" "/Game/ThirdPersonBP/Maps/OpenWorldTest" -run=WorldPartitionBuilderCommandlet -AllowCommandletRendering -builder=WorldPartitionNavigationDataBuilder -SCCProvider=None

This commandlet takes the following arguments:

World Partition Smart Object Collection Builder

The World Partition Smart Object Collection Builder commandlet rebuilds the smart object collection from all the smart object components in your World Partition Level.

Command: UnrealEditor.exe "C:\Users\user.name\Documents\Unreal Projects\MyProject\MyProject.uproject" "/Game/ThirdPersonBP/Maps/OpenWorldTest" -run=WorldPartitionBuilderCommandlet -builder=WorldPartitionSmartObjectCollectionBuilder

When you execute the above example, all of the Smart Object Collection in the OpenWorldTest level are rebuilt. You can use the -SCCProvider argument with this commandlet to specify which source control provider to use.