World Partition

An overview and how to for the World Partition system.

Windows
MacOS
Linux

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 creates issues sharing files between multiple users, and viewing the whole world in context becomes a difficult task.

image alt text

World Partition is a new 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:

Enabling World Partition in Your World

There are two ways to enable World Partition.

Project Settings

You can use the Project Settings to enable World Partition globally. Go to the Engine > World Partition section, then click the Enable World Partition checkbox.

image alt text

World Partition Conversion Commandlet

Use the WorldPartitionConvert commandlet to convert existing worlds to use World Partition:

  1. In Windows, open a Command Prompt window.

    image alt text

  2. At the prompt, begin by navigating to the location of the UE4Editor.exe file. For example: C:\Program Files\Epic Games\UE_4.26\Engine\Binaries\Win64.

    image alt text

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

  4. Add the name of the commandlet and the following arguments:

    projectname -run=WorldPartitionConvertCommandlet mapname.umap options -AllowCommandletRendering

    Where projectname is the name of your project, mapname.umap is the name of your map, and options is any additional optional arguments as seen in the table below.

    image alt text

  5. Press Enter and the commandlet will convert the project to use World Partition.

The following optional arguments are available:

Option

Description

-SCCProvider=[None|Perforce|...]

Specifies which source control provider to use.

-Verbose

Displays verbose logging.

-ConversionSuffix

Appends the _WP suffix to a converted map. This is useful when converting levels for testing purposes, while keeping the source level intact.

-DeleteSourceLevels

Deletes source levels after conversion.

-ReportOnly

Reports what would have been done during the conversion. Does not do the conversion.

-GenerateIni

Generates a default .ini conversion file for this map. Does not do the conversion.

-SkipStableGUIDValidation

Skips the unstable actor GUIDs validation; levels with unstable actor GUIDs will result in different conversion output when converting several times. Resaving the level fixes this.

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, the 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 Grid Placement setting, found in their Details panels' World Partition section.

image alt text

Setting

Description

Bounds

Places the Actor in all the grid cells that intersect its bounds volume.

Location

Places the Actor in the grid cell that contains the center point of their bounds volume.

Always Loaded

Always loads the Actor.

Since Actors are saved to their own individual files using the One File Per Actor feature, it is not required 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.

Actors that reference other Actors in the Level will be bundled together and loaded at the same time.

Streaming Sources in World Partition

Streaming of grid cells within the grid at runtime is determined by two factors. The first is the position of streaming sources in the Level.

Streaming Sources

Streaming sources loading and unloading grid cells at runtime.

Streaming sources are components that define a position in the world and trigger the loading of cells around them. A player always acts as a streaming source. Streaming sources can be added to the world using a 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.

Changing the 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.

image alt text

Setting

Description

Grid Name

Contains the name of the runtime grid.

Cell Size

Determines the size of the grid cells that are used to generate the streaming levels. In the example, the Cell Size is 32 square meters.

Loading Range

Determines the range from a streaming source where cells are loaded. In the image above, the Loading Range is a 256 meter radius around a streaming source.

Debug Color

Determines the color of the grid lines that are shown when Preview Grids is enabled.

Preview Grids

When enabled, displays the grid lines in the viewport.

Loading and Unloading Grid Cells in the Editor

To support the development of large worlds, all grid cells are initially unloaded. When the Level opens, the Editor will only load Actors that have their Grid Placement setting marked as Always Loaded, 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.

In the World Partition window, you can manually select which grid cells to work in. Open the window by selecting Window > World Partition.

image alt text

In the window, click and drag grid cells to select them. Then right-click the selection to open the contextual menu to load and unload the cells.

image alt text

Generating Hierarchical Levels of Detail (HLODs)

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

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

Blueprint Support

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 that are used for debugging a World Partition world during runtime.

Command

Description

wp.Runtime.ToggleDrawRuntimeHash2D

Toggles 2D debug display of world partition runtime hash.

wp.Runtime.ToggleDrawRuntimeHash3D

Toggles 3D debug display of world partition runtime hash.

wp.Runtime.ShowRuntimeSpatialHashGridLevel

Chooses which grid level to display when showing world partition runtime hash.

wp.Runtime.ShowRuntimeSpatialHashGridLevelCount

Chooses how many grid levels to display when showing world partition runtime hash.

wp.Runtime.ShowRuntimeSpatialHashGridIndex

Shows a specific grid when showing world partition runtime hash. An invalid index will show all.

wp.Runtime.RuntimeSpatialHashCellToSourceAngleContributionToCellImportance

Takes a value between 0 and 1 that modulates the contribution of the angle between streaming source-to-cell vector and source-forward vector to the cell importance. The closer the value to 0, the less the angle will contribute to the cell importance.

wp.Runtime.OverrideRuntimeSpatialHashLoadingRange

Sets the runtime loading range. Takes the following arguments:

  • -grid=[index]: Sets the runtime grid you would like to affect.

  • -range=[override_loading_range]: Sets the new runtime loading range.

wp.Runtime.MaxLoadingLevelStreamingCells

Limits the number of concurrent loading world partition streaming cells.

wp.Runtime.HLOD 0

Shows the world without HLODs using wp.Runtime.HLOD.