Precompute your level

For Enlighten to update lighting in real time, you need to run the Enlighten precompute. This creates the Enlighten data for the level.

Before you run the precompute, make sure the level is configured well for Enlighten. To learn how to do this, see the beginner tutorials.

Run the Enlighten precompute

  1. From the Build menu, select Enlighten Precompute.

    The Enlighten precompute starts. GeoPrecompMonitor opens, showing the Enlighten precompute progress.

    A notification shows that the Enlighten precompute is running.

    You can still use the editor while the precompute runs.

  2. When the precompute is finished, click Apply Now. If you don't take an action, the precompute applies automatically.

If the precompute takes a long time, check that the level is configured well for Enlighten. To learn how to do this, see the Set up Enlighten in Unreal from scratch tutorial.

Precompute variations

You can use the variations in the Build > Build Enlighten menu to perform various useful precomputation functions.

  • To quickly generate lightmap UVs, run the Enlighten Parameterize . This enables the Enlighten lightmap visualizations.
  • To export your scene to view and debug it in GeoRadiosity, use Export Only and Open in GeoRadiosity.

The Build > Enlighten > Re-run option reruns the last Enlighten precompute variation you chose.

Precompute only part of the world

To quickly see the results of the precompute for a limited part of the world, you can include only part of the world in the precompute.

In a world with many sublevels, in the Levels window, show only the levels you want to include.

You can also choose to precompute only the current level or selected actors. Use the options in Build > Build Enlighten > Precompute to choose between All Levels, Current Level or Selected Actors.

Only the actors included in the precompute have valid Enlighten lighting after the precompute completes. The Enlighten lighting for all other actors is invalidated. When this happens, a warning is displayed when you run a map check (Build > Map Check).

To guarantee correct indirect lighting, run the precompute for All Levels, with all sublevels visible.

Distribute the precompute

If you've already installed IncrediBuild, Enlighten automatically distributes the precompute across all available agents. The Enlighten precompute requires the IncrediBuild for Dev Tool Acceleration license option.

For maximum performance with IncrediBuild, configure each IncrediBuild agent's File Cache:

  • Size: 32767MB
  • Folder: any path located on fast local storage (e.g. SSD)

The time taken by the precompute is reduced in approximate inverse proportion to the number of logical cores available. To maximize CPU use, make the additional logical cores provided by Hyper-threading available. For example, an 8-core CPU with Hyper-threading provides up to 16 logical cores for the distributed precompute.

To ensure sufficient memory to run the precompute on each agent, install at least 2GB physical memory per logical core used with the distributed precompute.

Precompute options

To speed up the precompute, Enlighten re-uses the results of the previous precompute. When the previous precompute used an older version of Enlighten, this can cause unexpected errors.

To force a fresh precompute, clean your Enlighten output files using Build > Build Enlighten > Clean Output.

By default, Enlighten uses IncrediBuild or SN-DBS (if available) to distribute the precompute.

To force a local (non-distributed) precompute, choose Build > Enlighten Settings > Precompute Distributor > Local.

Automate the precompute

You can use the EnlightenPrecompute commandlet to automate the build of Enlighten data using a command line script.

To run the Enlighten Precompute commandlet, use the following command:

UE4Editor <project> -run=EnlightenPrecompute <map-name> -AllowCommandletRendering -AutoCheckOutPackages

This runs the Enlighten Precompute for the specified map, checks out the modified packages from source control, and saves them.

This doesn't require a powerful GPU. Because Enlighten renders the albedo texture after running the precompute, the commandlet requires a D3D context. For this, an interactive session is required on the machine running the commandlet (along with a GPU and the UE4 prerequisites.)

Alternatively, when you run Build And Submit, UE4 will also build and submit the Enlighten data for the level. Currently, Build And Submit doesn't support submitting changes to Enlighten data stored in a separate .uasset file.

The following additional switches are supported:

SwitchFunction

-Distributor=<type>

Control the way tasks are distributed across machines:

  • Local: Run all tasks on the host machine.
  • XGE: Use Incredibuild to distribute tasks.
  • SNDBS: Use SN-DBS to distribute tasks.

-NoDistribute

Equivalent to -Distributor=Local

-unattended

Run the precompute without a build monitor window. Significantly reduces the precompute time when the world is extremely large.

-MemoryLimit=<N>

Limit the maximum allow memory use of the precompute to a percentage of the total system memory. Default: 90.

-MapList

Replaces the <map-name> parameter. The name of a text file within the project Content folder which contains a list of map names, one per line.