Custom Lightmaps#

Location

assets/minecraft/optifine/lightmap/

_images/icon9.png

Daylight lightmap#

Custom Lightmaps can change the color of light from light sources. OptiFine allows customizing the lighting in-game.

Vanilla lighting#

Every block has two light values from 0 to 15 assigned to it, one for sky brightness and one for torch brightness. A block in direct sunlight has a sky value of 15. A block in the shade directly adjacent to it has a value of 14 and so on. Blocks deep underground far from any block that can see the sky have sky brightness 0. Similarly for torches. A torch block has light value 14 (15 for glowstone) and the light value drops by 1 each block away from it.

To generate the lighting actually seen in game, Minecraft uses a 16x16 lightmap. Its axes correspond to the 16 light levels of each type. If a block has torch brightness x and sky brightness y, then the point (x, y) is used for its lightmap coordinates.

Important

The lightmap is not in any of the game’s files but is generated each frame.

Two variables affect the lightmap, the time of day and the torch flicker. Minecraft implements dusk/dawn transitions and torch flicker by making the entire lightmap darker or lighter rather than by adjusting the sky/torch brightness values.

Custom lighting#

To create custom lighting, a lightmap palette needs to be created for each world:

  • Nether: assets/minecraft/optifine/lightmap/world-1.png

  • Overworld: assets/minecraft/optifine/lightmap/world0.png

  • The End: assets/minecraft/optifine/lightmap/world1.png

For the overworld optional rain and thunder palettes may also need to specified:

  • Overworld rain: assets/minecraft/optifine/lightmap/world0_rain.png

  • Overworld thunder: assets/minecraft/optifine/lightmap/world0_thunder.png

The rain and thunder palettes are only active when the main world palette is defined.

Each palette can be any width, but must be 32 or 64 pixels tall. If it’s 64, the bottom half is used for night vision, discussed later.

Of the 32 rows of pixels, the top 16 represent sunlight and the bottom 16 represent torchlight.

Two columns, 16 pixels from the top half and 16 pixels from the bottom half, are chosen to form the axes of the final 16x16 lightmap used for rendering.

_images/template.png

Blue: Night, orange: dusk/dawn, cyan: day, yellow: lightning#

In the top half, the left-hand side represents night and the right-hand side represents day, with the dusk/dawn transitions in between. The very far right of the palette represents lightning flashes. Again, there is no specified width for the palette, but more width means more room for detail in the transitions.

Torches work similarly, but in this case the x coordinate is simply a random value simulating torch flicker. The variation along the x dimension will determine how noticable torch flicker is. To have completely steady torchlight with no flicker, make all pixels along each row the same color.

Lightmaps work the same in all three worlds (Overworld, Nether, The End), but since there is no night or day in Nether and The End, the “time of day” value is constant. For these worlds, simply give rows 0 through 15 the same color all the way across.

Night vision effect#

In Vanilla, the night vision effect is computed by scaling the RGB values by 1.0 / max(R,G,B). For example, (0.2, 0.3, 0.6) would brighten to (0.333, 0.5, 1.0) after dividing by 0.6.

This behaviour can be overridden with a custom lightmap by making the height 64 pixels instead of 32. Provide four palettes instead of two: normal sun, normal torch, night vision sun, night vision torch.

Lightmap generation works exactly the same way but using rows 32-47 and 48-63 instead.


🆚️ This documentation assumes the latest OptiFine version. Notes are not made for legacy versions (1.8).
🔙️ This documentation is updated to commit 8410499f.
©️ This file is offered without any copyright restrictions. Please copy and modify it to suit your needs. Credit is optional, but appreciated.