World Partition - Hierarchical Level of Detail

How to use Hierarchical Levels of Detail in your World Partition world.

Windows
MacOS
Linux

The World Partition system uses a grid to separate your world into cells that can be dynamically loaded and unloaded at runtime. Yet there are times when you want Actors that are distant and non-interactive — such as distant mountains, trees, and cliffs — to still be visible.

HLODs Off

HLODs On

HLODs Off. Only content in loaded cells is dsiplayed.

HLODs On. Content in unloaded cells is replaced with HLODs.

The World Partition - Hierarchical Level of Detail (HLOD) system uses custom HLOD Layers to organize large amounts of Static Mesh Actors and generate a single proxy mesh and Material. This technique is used to visualize unloaded World Partition grid cells, to reduce the number of draw calls per frame, and to increase performance, especially when used with large open worlds.

Some world components, such as Landscapes and Water components, are currently not supported by HLOD Actors.

Creating HLOD Layers

World Partition HLODs are controlled by the HLOD Layer asset. These specialized assets contain your settings, and your project can use multiple HLOD Layers:

image alt text

  1. Create a new HLOD Layer asset by opening the Content Drawer and clicking + Add to open the menu. Navigate to the Miscellaneous menu and select the HLOD Layer asset. (Right-clicking in the Content Drawer opens the same menu.)

  2. Double-click the new HLOD Layer to open it in the Asset Editor:

image alt text

Setting

Description

Layer Type

Select the layer type from the following options:

  • Instancing

  • Merged Mesh

  • Simplified Mesh

Mesh Merge Settings/Proxy Settings

Displays additional options when the Merged Mesh or Simplified Mesh layer type is selected.

Always Loaded

Determines whether the HLOD proxy mesh generated by this layer will be always loaded.

Cell Size

Sets the cell size of the runtime grid created to contain the HLOD Actors in this layer. This option is not available if you set your HLOD Layer to Always Loaded.

Loading Range

Sets the distance at which the runtime grid streams its cells. This option is not available if you set your HLOD Layer to Always Loaded.

Parent Layer

Enables the assets created by this HLOD Layer to be automatically assigned to a designated HLOD Layer.

HLODMaterial

Sets the base material to use when baking materials for Merge Mesh and Simplified mesh layer types.

This is an advanced setting. The default material is sufficient for most use cases.

Choosing a Layer Type

The first step to using HLOD Layers is to select the layer type:

image alt text

Layer Type

Description

Instancing

Static Mesh assets in this type of layer are replaced with Instanced Static Mesh (ISM) components using the lowest Level of Detail (LOD) settings for those assets. This type is ideal for imposter meshes, such as trees and foliage.

Merged Mesh

Static Mesh assets in this type of layer are merged to create a single proxy mesh.

Simplified Mesh

Static Mesh assets in this type of layer are merged into a single proxy mesh and mesh simplification is performed.

Mesh Merge Settings

These settings are only available if Merged Mesh is selected:

image alt text

Setting

Description

Generate Lightmap UV

Generates lightmap UVs for the merged mesh. This new layout will be placed in the Target Lightmap UVChannel.

Target Lightmap Resolution

Specifies the lightmap resolution used for generating lightmap UV coordinates on the generated Static Mesh. This controls the distance between UV islands. Higher resolutions yield tighter spaces between each UV island.

Computed Lightmap Resolution

Determines if the lightmap resolution should be computed by summing the lightmap resolutions for the input mesh components.

Pivot Point at Zero

Determines whether the position of the merged mesh's pivot point is at the world origin or the first merged component.

Merge Physics Data

Determines whether to merge the physics data of the mesh components, specifically collision primitives.

Merge Materials

Merges source materials into a single flat material. This is only available when merging a single LOD level, as determined by your LODSelection Type.

Material Settings

Contains material settings for the simplified material created when Merge Materials is enabled.

Gutter Size

Adds space to the subchart for baked materials for the top mip level. Measured in texels.

Create Merged Materials

Creates a flat material from all source component materials, as well as a new set of UV coordinates. This material is not applied to any section by default.

Bake Vertex Data to Mesh

Bakes vertex data, such as vertex colors and normals, into the resulting proxy mesh.

Output UVs

Outputs the specified UV channels into the merged mesh. Source mesh components must contain valid UVs for the specified channels.

LODSelection Type

Determines which LOD selection mode to use when generating the merged static mesh:

  • Use all LOD levels: Uses all available LOD levels when merging Actors

  • Use specific LOD level: Uses the selected LOD level when merging Actors.

  • Calculate correct LOD level: Calculates the appropriate LOD model for the given screen size.

  • Always use lowest detail LOD: Uses the lowest detail LOD when merging Actors.

Specific LOD

Specifies a LOD level to export from the source meshes.

Use Vertex Data for Baking Material

Bakes vertex data, such as vertex colors and normals, into the baked-out materials. Only available if Merge Materials is selected.

Use Texture Binning

Calculates varying output texture sizes according to their importance in the final atlas texture. Only available if Merge Materials is selected.

Reuse Mesh Lightmap UVs

Determines whether to reuse the lightmap UVs from the source mesh when baking the material. If false, the engine will generate a new set of UVs.

Merge Equivalent Materials

Attempts to merge materials that are deemed equivalent. The process can cause artifacting in the merged mesh if world position or actor position is used to determine output color.

Use Landscape Culling

Uses available landscape geometry to cull invisible triangles. For example, if you had a tree mesh that was placed where the lowest triangles were below the surface of a landscape, then those occluded triangles would be removed upon merge.

Include Imposters

Includes any imposter LODs that are part of the source mesh components.

Allow Distance Fields

Allows distance fields to be computed for this mesh. Disabling this will save memory if the merged mesh is only rendered in the distance.

Generate Nanite Enabled Mesh

Enables Nanite on the generated mesh.

Proxy Settings

These settings are only available if Simplified Mesh is selected:

image alt text

Setting

Description

Screen Size

Determines size of the resulting proxy mesh in pixels.

Calculate Correct LODModel

Calculates which LOD model is sufficient based on the specified screen size. This is done by analyzing each input mesh and selecting the correct LOD based on each LOD transition size.

Override Spatial Sampling Distance

Overrides when converting multiple source meshes for proxy LOD merging.

Large geometry with small sampling has a very high memory cost.

Material Settings

Contains settings for material simplification.

Merge Distance

Distance at which meshes should be merged. This can close gaps like doors and windows in distant geometry.

Unresolved Geometry Color

Assigns a base color that is shown when merged geometry can't be associated with the source geometry, such as doors and windows that have been closed by the Merge Distance.

Transfer Distance Override

Overrides the search distance used when discovering texture values for simplified geometry. Used when non-zero Merge Distance settings generate new geometry in concave corners.

Hard Edge Angle

Angle at which a hard edge is introduced between faces. This will increase vertex counts and may introduce additional UV seams. Only recommended when not using normal maps.

Normal Calculation Method

Controls the method used to calculate the normal for simplified geometry:

  • Angle Weighted: Normals are weighted using the angle of the surrounding faces.

  • Area Weighted: Normals are weighted using the area of the surrounding faces.

  • Equal Weighted: Normals are weighted using an average of the normals of the surrounding faces.

Lightmap Resolution

Sets the resolution of the newly generated lightmap.

Compute Lightmap Resolution

Computes the lightmap resolution by summing the dimensions for each mesh included in the merging process.

Enable Volume Culling

Allows culling volumes to exclude geometry.

Allow Distance Fields

Allows distance fields to be computed for this mesh. Disabling this will save memory if the merged mesh is only rendered in the distance.

Reuse Mesh Lightmap UVs

Determines whether to reuse the lightmap UVs from the source mesh when baking the material. If false, the engine will generate a new set of UVs.

Group Identical Meshes for Baking

Bakes identical meshes or mesh instances only once. Will result in better quality baked textures and reduced baking times. Can lead to discrepancies between the merged mesh and the source mesh visual.

Create Collision

Generates collision for the merged mesh.

Allow Vertex Colors

Allows the saving of vertex colors in the merged mesh.

Generate Lightmap UVs

Generates lightmap UVs for the merged mesh.

Generate Nanite Enabled Mesh

Enables Nanite on the generated mesh.

Using HLOD Layers

To generate HLOD proxy meshes, Actors need to be added to an HLOD Layer and told to generate HLODs. Once this is done, a commandlet is run to generate the proxy geometry.

Currently, the commandlet is the only way to generate HLOD proxy geometry.

Adding Actors

Actors are currently added to HLOD Layers in the following ways:

  1. The HLOD property in an Actor's Details panel.

    image alt text

  2. The Default HLOD Layer property of a Data Layer.

    image alt text

  3. The Default HLOD Layer property of the World Settings.

    image alt text

There are HLOD Layer options also available when using the WorldPartitionConvertCommandlet. Using the conversion ini file, you can specify HLOD Layer properties:

[/Script/UnrealEd.WorldPartitionConvertCommandlet]
EditorHashClass=Class'/Script/Engine.WorldPartitionEditorSpatialHash'
RuntimeHashClass=Class'/Script/Engine.WorldPartitionRuntimeSpatialHash'
HLODLayerAssetsPath="/Game/WorldPartition/HLODLayers"
DefaultHLODLayerName="HLODLayer_Default"
HLODLayersForActorClasses=(ActorClass=/Game/Blueprint/Base_Tree.Base_Tree_C,HLODLayer="HLODLayer_Tree")

[HLODLayer_Default HLODLayer]
LayerType=MeshMerge
MeshMergeSettings=(TargetLightMapResolution=256,OutputUVs[0]=OutputChannel, ...)
HLODMaterial=/Engine/EngineMaterials/BaseFlattenMaterial.BaseFlattenMaterial
RuntimeGrid="HLODGrid_Default"
LoadingRange=30000.000000

[HLODLayer_Tree HLODLayer]
LayerType=Instancing
RuntimeGrid="HLODGrid_Trees"
LoadingRange=30000.000000

A world converted with this configuration specifies a DefaultHLODLayerName (in this example, HLODLayer_Default), which will be created using the properties specified in the matching .ini section. Actors created by HLODLayer_Default will be assigned to HLODLayer_Tree with the properties defined in that section of the .ini file.

Generating 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.

HLOD Actors will not be recreated or built if no changes have been made to their source Actors. Making changes to the Actors themselves or their meshes, materials, or textures will result in the HLOD being rebuilt if you re-execute the commandlet.

Follow the steps below to use the commandlet:

  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 following arguments:

    YourProject YourMap -run=WorldPartitionBuilderCommandlet -AllowCommandletRendering -Builder=WorldPartitionHLODsBuilder

    Where YourProject is the name of your project folder and YourMap is the name of the map file in which you want to build HLODs.

    image alt text

  5. Additionally, one of the following options can be provided to change the behavior of this command:

Option

Description

-SetupHLODs

Sets up the HLOD Actors for the World Partition cells but does not build their geometry. Can potentially update, delete, or create new Actors.

-BuildHLODs

Builds the geometry for all existing HLOD Actors.

-DeleteHLODs

Deletes all HLOD Actors.

Visualizing HLODs

HLOD Actors can be visualized in the Editor Viewport, while the status of HLOD cells can be visualized at runtime.

In the Editor

In the Editor, change the View Mode to Level of Detail Coloration and choose Hierarchical LOD Coloration. Actors assigned to an HLOD Layer will be green. Zooming the view out will make HLODs appear in Blue.

In the Viewport, changing the View Mode to Level of Detail Coloration and selecting Hierarchical LOD Coloration will display Actors assigned to an HLOD Layer in green:

image alt text

Moving the camera away from the Actors will show their HLOD proxy mesh in blue:

image alt text

At Runtime

Running the console command wp.Runtime.ToggleDrawRuntimeHash2D at runtime displays the HLOD cells that are loaded in green.

image alt text