Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

Mesh level of detail (LOD)

Level of detail (LOD) is one of the most important ways to optimize rendering performance in a 3D project, along with Occlusion culling.

On this page, you'll learn:

  • How mesh LOD can improve your 3D project's rendering performance.

  • How to set up mesh LOD in Godot.

  • How to measure mesh LOD's effectiveness in your project (and alternatives you can explore if it doesn't meet your expectations).

See also

You can see how mesh LOD works in action using the Occlusion Culling and Mesh LOD demo project.

Introduction

Historically, level of detail in 3D games involved manually authoring meshes with lower geometry density, then configuring the distance thresholds at which these lower-detailed meshes should be drawn. This approach is still used today when increased control is needed.

However, in projects that have a large amount of detailed 3D assets, setting up LOD manually can be a very time-consuming process. As a result, automatic mesh decimation and LOD configuration is becoming increasingly popular.

Godot provides a way to automatically generate less detailed meshes for LOD usage on import, then use those LOD meshes when needed automatically. This is completely transparent to the user. The meshoptimizer library is used for LOD mesh generation behind the scenes.

Mesh LOD works with any node that draws 3D meshes. This includes MeshInstance3D, MultiMeshInstance3D, GPUParticles3D and CPUParticles3D.

Visual comparison

Here is an example of LOD meshes generated on import. Lower detailed meshes will be used when the camera is far away from the object:

From most detailed (left) to least detailed (right), shaded view

From most detailed (left) to least detailed (right), shaded view

Here's the same image with wireframe rendering to make the decimation easier to see:

From most detailed (left) to least detailed (right), wireframe view

From most detailed (left) to least detailed (right), wireframe view

See also

If you need to manually configure level of detail with artist-created meshes, use Visibility ranges (HLOD) instead of automatic mesh LOD.

Generating mesh LOD

By default, mesh LOD generation happens automatically for imported 3D scenes (glTF, .blend, Collada, FBX). Once LOD meshes are generated, they will automatically be used when rendering the scene. You don't need to configure anything manually.

However, mesh LOD generation does not automatically happen for imported 3D meshes (OBJ). This is because OBJ files are not imported as full 3D scenes by default, but only as individual mesh resources to load into a MeshInstance3D node (or GPUParticles3D, CPUParticles3D, ...).

To make an OBJ file have mesh LOD generated for it, select it in the FileSystem dock, go to the Import dock, change its Import As option to Scene then click Reimport:

Changing the import type on an OBJ file in the Import dock

Changing the import type on an OBJ file in the Import dock

This will require restarting the editor after clicking Reimport.

Note

The mesh LOD generation process is not perfect, and may occasionally introduce rendering issues (especially in skinned meshes). Mesh LOD generation can also take a while on complex meshes.

If mesh LOD causes a specific mesh to look broken, you can disable LOD generation for it in the Import dock. This will also speed up resource importing. This can be done globally in the 3D scene's import options, or on a per-mesh basis using the Advanced Import Settings dialog.

See Importing 3D scenes for more information.

Comparing mesh LOD visuals and performance

To disable mesh LOD in the editor for comparison purposes, use the Disable Mesh LOD advanced debug draw mode. This can be done using the menu in the top-left corner of the 3D viewport (labeled Perspective or Orthogonal depending on camera mode):

Disabling mesh LOD in the 3D viewport's top-left menu

Disabling mesh LOD in the 3D viewport's top-l