Level of Detail (LOD) add-on for Godot 3.x

This add-on provides level of detail for meshes, lights and particles. It can be used to improve performance in large scenes significantly.

This repository only contains the add-on. See godot-extended-libraries/godot-lod-demo for the demonstration project.

Features

• Supports lights, meshes and particles (Particles and CPUParticles).
• Each node has its own LOD distance properties, but you can also define a LOD bias project setting to improve visual quality or performance for the target hardware.
• Lights can have their shadow smoothly fade off with distance, then the light itself smoothly fade off as well.
• Works with both the GLES3 and GLES2 renderers.
• Written in performance-conscious GDScript. Easy to install and use, but scales to hundreds of LOD instances (and perhaps thousands on more powerful hardware).

The LOD add-on only runs in the running project, not while in the editor. This is done by design to avoid accidentally saving modified versions of the scene. You need to run the project to test LOD functionality.

Installation

Using the Asset Library

• Open the Godot editor.
• Navigate to the AssetLib tab at the top of the editor and search for "lod".
• Install the Level of Detail (LOD) plugin. Keep all files checked during installation.
• In the editor, open Project > Project Settings, go to Plugins and enable the Level of Detail (LOD) plugin.

Manual installation

Manual installation lets you use pre-release versions of this add-on by following its master branch.

• Clone this Git repository:

git clone https://github.com/godot-extended-libraries/godot-lod.git

Alternatively, you can download a ZIP archive if you do not have Git installed.

• Move the addons/ folder to your project folder.
• In the editor, open Project > Project Settings, go to Plugins and enable the Level of Detail (LOD) plugin.

Usage

Meshes

1. After enabling the plugin (see above), add a LODSpatial node.

2. Add 2 or 3 child nodes. These must have with the -lod0 (high detail), -lod1 (medium detail) or -lod2 (low detail). -lod2 is optional. If you only have the -lod0 and -lod1 LOD levels (high and low), keep in mind the node will be invisible if -lod2 should be displayed given the current distance.

   Your scene tree should now look like this:

   - LODSpatial
     - MeshInstance-lod0
     - MeshInstance-lod1
     - MeshInstance-lod2
     - (other, unrelated nodes can be placed here too)
   

3. Configure the distance properties in the LODSpatial node.

4. To smoothly fade out the least detailed LOD before it disappears completely, see TIPS.md.

Note: As its name implies, LODSpatial is not limited to MeshInstances. It can hide and show any node that inherits from Spatial.

Lights

1. After enabling the plugin (see above), add a LODOmniLight or LODSpotLight node.
2. Configure the node as you would configure a typical light node.
3. Set a maximum light and shadow distance in the inspector. By default, lights will no longer be visible at all if the camera is more than 50 units away. Their shadows will also no longer be visible if the camera is move than 25 units away.
4. You can also configure the fade factors to make the fade-in less dramatic. This can be useful to make transitions less noticeable if the camera moves quickly.

Note: Since the light's energy will be tweaked for LOD purposes, don't change it manually while the project is running. You can still set a fixed energy value in the inspector, though. The add-on will take it into account for its calculations. To change the light's intensity over time (e.g. using AnimationPlayer), darken or lighten its color instead.

Note: If you add child nodes to a LODOmniLight or LODSpotLight, they will no longer be visible if the light is fully hidden due to the distance.

Particles

1. After enabling the plugin (see above), add a LODParticles or LODCPUParticles node.
2. Configure the node as you would configure a typical particles node.
3. Set a maximum emission distance in the inspector. By default, particles will no longer emit if the camera is more than 50 units away.

You can safely add child nodes to a LODParticles or LODCPUParticles node, as the node itself is never hidden.

Configuration

There are several Project Settings you can define to customize this add-on's behavior. You can set them directly in a script (ProjectSettings.set_setting("section/key", value)) or use the Project Settings in the editor to do so.

lod/spatial_bias, lod/light_bias, lod/particle_bias

Default: 0

The distance bias (in 3D units) to use for LOD calculations. Positive values will improve performance at the cost of visual quality, whereas negative values will improve visual quality at the cost of performance.

lod/refresh_rate

Default: 0.25

The rate at which the LOD mesh and particle instances update (in seconds). Lower values are more reactive but use more CPU. Each LOD instance uses a random jitter to avoid applying updates on all instances at the same time.

Since meshes and particles are updated in a "discrete" manner rather than a continuus one, the default refresh rate is quite low. The difference is hardly visible, yet it helps decrease CPU usage significantly in scenes with hundreds of instances (or more).

lod/light_refresh_rate

Default: 0.05

The rate at which the LOD light instances update (in seconds). Lower values are more reactive but use more CPU. Each LOD instance uses a random jitter to avoid applying updates on all instances at the same time.

Since lights are updated in a "continuous" manner rather than a discrete one, the default refresh rate is relatively high. Despite not quite being 60 FPS (0.01666), it often looks very close in practice unless the camera is moving really fast.

Tips and tricks

See TIPS.md for useful tips on improving performance and visual quality of your 3D project. These tips can be followed even if you don't use this add-on.

License

Copyright © 2020 Hugo Locurcio and contributors

Unless otherwise specified, files in this repository are licensed under the MIT license. See LICENSE.md for more information.