LIGHTING DOCUMENTATION

This is documentation for a preview release of Minecraft. New features, components, and capabilities in this release are not final and might change without notice before the final release.
Be sure to check the documentation once the release is out of preview if your add-on isn't working properly. Resource and Behavior Packs created for the preview are not guaranteed to work on the final release.

Index

Overview

There are many different Lighting controls in Minecraft. Things like sun color, ambient color, and moon illuminance are all lighting controls.
You can override all of these lighting controls to change the colors and illuminance of many things!

JSON Format

All lighting settings overrides should specify the version that they target via the "format_version" field. The remainder of the lighting data is divided up into independent JSON sub-objects for each lighting control.
These overrides define the lighting data of the overarching light settings collection. To be valid, a definition must include exactly one of these type objects. See the full lighting schema below for additional details and the full list of supported lighting overrides.
Here is a sample lighting file.

{
        "format_version": "1.21.40",
        "description": {
          "identifier": "myResourcePack:default_lighting"
        },
        "directional_lights": {
          "sun": {
            "illuminance": {
              "0.0": 109880.0,
              "0.25": 20000.0,
              "0.35": 400.0,
              "0.5": 1.0,
              "0.65": 400.0,
              "0.75": 20000.0,
              "1.0": 109880.0
            },
            "color": [ 255.0, 255.0, 255.0, 255.0 ]
          },
          "moon": {
            "illuminance": 0.27,
            "color": {
              "0.0": "#ffffffff",
              "1.0": "#ffffffff"
            }
          },
          "orbital_offset_degrees": 3.0
        },
      "emissive": {
          "desaturation": 0.1
        }
      }

Adding Lighting Settings

Lighting Settings are read from JSON files in the "lighting" subfolder of behavior packs. Loading enforces one lighting settings collection per file. The settings collection's identifier acts as its name and must be namespaced. If two behavior packs define the same lighting settings name (including namespace), then the settings from the highest pack in the stack will be used. Adding a file with a new name to the lighting data location will make it available for the game to use, while existing lighting settings can be overridden using another settings collection with the same identifier.

Schema

AmbientLight

Name	Type	Required?	Description
color	Object of type Keyframes	Required	The 'color' value can be expressed either as an array of three numerical values in the range of 0–255, or as a six-digit hexadecimal string. This can also be specified using keyframes in a time_of_day:color format where time_of_day ranges from 0-1 inclusive.
illuminance	Object of type Keyframes	Required	The 'illuminance' value corresponds to the strength, in lux (lx), of the ambient light, and should be kept quite low in general. The allowed range for this value is 0.0 - 5.0. This can also be specified using keyframes in a time_of_day:illuminance format where time_of_day ranges from 0-1 inclusive.

DirectionalLights

Name	Type	Required?	Description
flash	Object of type StaticDirectionalLight	Optional	A single Static Directional Light definition, containing Static Directional Light settings defined by resource pack
orbital	Object of type OrbitalLights	Optional	A single Orbital Light definition, containing Orbital Light settings defined by resource pack

Emissive

Name	Type	Required?	Description
desaturation	Float	Optional	The 'desaturation' is a factor from 0.0 to 1.0 that controls how much the albedo of a given pixel is desaturated when computing the color of emissive light.

KeyframedDirectionalLightImpl

Name	Type	Required?	Description
color	Object of type Keyframes	Optional	The 'color' value can be expressed either as an array of three numerical values in the range of 0–255, or as a six-digit hexadecimal string. This can also be specified using keyframes in a time_of_day:color format where time_of_day ranges from 0-1 inclusive.
illuminance	Object of type Keyframes	Optional	The 'illuminance' value corresponds to the strength, in lux (lx) as a float. This can also be specified using keyframes in a time_of_day:illuminance format where time_of_day ranges from 0-1 inclusive.

Lighting JSON File

Name	Type	Required?	Description
format_version	String	Required	Specifies the version of the game this entity was made in. If the version is lower than the current version, any changes made to the entity in the vanilla version will be applied to it.
minecraft:lighting_settings	Object of type LightingSettings	Optional	Lighting Settings definition which includes the 'description,' 'ambient,' 'directional_lights,' 'emissive,' and 'sky sections.

LightingDescription

Name	Type	Required?	Description
identifier	Object of type Identifier	Required	The name of this Lighting Description in the format 'namespace_name:description_name'.

LightingSettings

Name	Type	Required?	Description
ambient	Object of type AmbientLight	Optional	Parameters to control ambient lighting.
description	Object of type LightingDescription	Optional	Identifier for the Lighting Settings.
directional_lights	Object of type DirectionalLights	Optional	Parameters to control directional lights like the sun and moon.
emissive	Object of type Emissive	Optional	Parameters to emissives.
sky	Object of type SkyIntensity	Optional	Parameters to control sky intensity.

OrbitalLights

Name	Type	Required?	Description
moon	Object of type KeyframedDirectionalLightImpl	Optional	The directional light description including color and illuminance values to control the moon.
orbital_offset_degrees	Object of type Keyframes	Optional	A pair of float:float values with the format time_of_day:orbital_offset, where the time_of_day is in a range from 0-1 inclusive.
sun	Object of type KeyframedDirectionalLightImpl	Optional	The directional light description including color and illuminance values to control the sun.

SkyIntensity

Name	Type	Required?	Description
intensity	Object of type Keyframes	Optional	The sky's 'intensity' value is a factor from 0.1 to 1.0 that controls how much sky light is factored into the indirect term for both diffuse and specular. A value of 1.0 causes the sky to contribute more to indirect light, and will result in shadows being less dark; a value of 0.1 will result in darker shadows, because less indirect light is contributed from the sky. The default value, if not provided, is 1.0.

StaticDirectionalLight

Name	Type	Required?	Description
color	Object of type Color255RGB	Optional	The 'color' value can be expressed either as an array of three numerical values in the range of 0–255, or as a six-digit hexadecimal string.
illuminance	Float	Optional	The 'illuminance' value corresponds to the strength, in lux(lx) as a float.

LIGHTING DOCUMENTATION

Index#

Overview#

JSON Format#

Adding Lighting Settings#

Schema#

AmbientLight#

DirectionalLights#

Emissive#

KeyframedDirectionalLightImpl#

Lighting JSON File#

LightingDescription#

LightingSettings#

OrbitalLights#

SkyIntensity#

StaticDirectionalLight#