COLOR GRADING AND TONEMAPPING 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 several Color Gradng and Tonemapping controls in Minecraft. Color Grading controls include midtones, highlights, and shadows. Tonemapping operators include Reinhard, Hable, and several other options.
You can override all of these settings to change the contrast, gamma, gain, and more of shadows, midtones, and highlights, as well as how colors are remapped using tonemapping.

JSON Format#

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

{
          "format_version": "1.21.90",
          "minecraft:color_grading_settings": {
          "description": {
            "identifier": "my_pack:default_color_grading"
          },
          "color_grading": {
            "midtones": {
            "contrast": [1.3, 1.3, 1.3],
            "gain": [1.0, 1.0, 1.0],
            "gamma": [2.2, 2.2, 2.2],
            "offset": [0.0, 0.0, 0.0],
            "saturation": [1.05, 1.05, 1.05]
            },
            "temperature": {
            "enabled": true,
            "temperature": 6500,
            "type": "color_temperature"
            }
          },
          "tone_mapping": {
            "operator": "generic"
          }
          }
        }
    

Adding Color Grading and Tonemapping Settings#

Color Grading and Tonemapping Settings are read from JSON files in the "color_grading" subfolder of resource packs. Loading enforces one Color Grading and Tonemapping settings collection per file. The settings collection's identifier acts as its name and must be namespaced. If two resource packs define the same Color Grading and Tonemapping 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 Color Grading and Tonemapping data location will make it available for the game to use, while existing Color Grading and Tonemapping settings can be overridden using another settings collection with the same identifier.

Schema#

Color Grading JSON File v1#

Name	Type	Required?	Description
format_version	String	Required	Specifies the version of the game these Color Grading Settings were made in. If the version is lower than the current version, any changes made to the settings in the vanilla version will be applied to it.
minecraft:color_grading_settings	Object of type ColorGradingSettings	Optional	Color Grading Settings definition which includes the 'midtones,' 'temperature,' 'shadows,' and 'highlights' sections.

ColorGrading#

Name	Type	Required?	Description
highlights	Object of type Highlights	Optional	Parameters to control highlights.
midtones	Object of type Midtones	Optional	Parameters to control midtones.
shadows	Object of type Shadows	Optional	Parameters to control shadows.
temperature	Object of type Temperature	Optional	Parameters to control temperatur.

ColorGradingDescription#

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

ColorGradingSettings#

Name	Type	Required?	Description
color_grading	Object of type ColorGrading	Optional	Parameters to control color grading.
description	Object of type ColorGradingDescription	Optional	Identifier for the Color Grading Settings.
tone_mapping	Object of type ToneMapping	Optional	Parameters to control tone mapping.

Highlights#

Name	Type	Required?	Description
contrast	Object of type vec3	Optional	A value between 0.0 and 4.0 which describes the tonal range, the difference in luminance between the bright and dark pixels in an image.
enabled	Boolean	Optional	Whether or not highlights are on or off.
gain	Object of type vec3	Optional	A value between 0.0 and 10.0 which is a multiplication factor applied to each color channel to adjust the overall luminance intensity of the image.
gamma	Object of type vec3	Optional	A value between 0.0 and 4.0 which is an exponential factor applied to the final color after both color grading and tone mapping to adjust the overall luminance intensity of the image.
highlightsMin	Float	Optional	A value between 1.0 and 4.0 which is a factor multiplied by the average luminance of the scene to determine which pixels are considered highlights.
offset	Object of type vec3	Optional	A value between 0.0 and 4.0 which is an exponential factor applied to the final color after both color grading and tone mapping to adjust the overall luminance intensity of the image.
saturation	Object of type vec3	Optional	A value between 0.0 and 10.0 which determines the hue intensity of colors.

Midtones#

Name	Type	Required?	Description
contrast	Object of type vec3	Optional	A value between 0.0 and 4.0 which describes the tonal range, the difference in luminance between the bright and dark pixels in an image.
gain	Object of type vec3	Optional	A value between 0.0 and 10.0 which is a multiplication factor applied to each color channel to adjust the overall luminance intensity of the image.
gamma	Object of type vec3	Optional	A value between 0.0 and 4.0 which is an exponential factor applied to the final color after both color grading and tone mapping to adjust the overall luminance intensity of the image.
offset	Object of type vec3	Optional	A value between 0.0 and 4.0 which is an exponential factor applied to the final color after both color grading and tone mapping to adjust the overall luminance intensity of the image.
saturation	Object of type vec3	Optional	A value between 0.0 and 10.0 which determines the hue intensity of colors.

Shadows#

Name	Type	Required?	Description
contrast	Object of type vec3	Optional	A value between 0.0 and 4.0 which describes the tonal range, the difference in luminance between the bright and dark pixels in an image.
enabled	Boolean	Optional	Whether or not shadows are on or off.
gain	Object of type vec3	Optional	A value between 0.0 and 10.0 which is a multiplication factor applied to each color channel to adjust the overall luminance intensity of the image.
gamma	Object of type vec3	Optional	A value between 0.0 and 4.0 which is an exponential factor applied to the final color after both color grading and tone mapping to adjust the overall luminance intensity of the image.
offset	Object of type vec3	Optional	A value between 0.0 and 4.0 which is an exponential factor applied to the final color after both color grading and tone mapping to adjust the overall luminance intensity of the image.
saturation	Object of type vec3	Optional	A value between 0.0 and 10.0 which determines the hue intensity of colors.
shadowsMax	Float	Optional	A value between 0.1 and 1.0 which is a factor multiplied by the average luminance of the scene to determine which pixels are considered shadows.

Temperature#

Name	Type	Required?	Description
enabled	Boolean	Optional	Whether or not temperature is on or off.
temperature	Float	Optional	A value between 1000.0 and 15000.0 which is the overall image temperature measured in Kelvin. The default value is 6500.0, the standard 'daylight' illumination.
type	"white_balance", "color_temperature"	Optional	The name of the desired temperature type from the following list: 'white_balance' or 'color_temperature'.

TemperatureGrading Type#

Name	Type	Required?	Description
color_temperature	"white_balance", "color_temperature"	Required	Causes higher temperature values to result in a warmer image, while lower temperature values will result in a cooler image.
white_balance	"white_balance", "color_temperature"	Required	Causes higher temperature values to result tin a cooler image, while lower temperature values will result in a warmer image.

ToneMapping#

Name	Type	Required?	Description
operator	"aces", "hable", "reinhard", "reinhard_luma", "reinhard_luminance", "generic"	Optional	The name of the desired tonemapping operator from the following list: 'aces', 'hable', 'reinhard', 'reinhard_luma', 'reinhard_luminance', 'reinhard_luminance', or 'generic'.

Tonemapper#

Name	Type	Required?	Description
aces	"aces", "hable", "reinhard", "reinhard_luma", "reinhard_luminance", "generic"	Required	A filmic tone mapping operator meant to emulate the behaviors of real-life film, specifically following the ACES standard used in television and film.
generic	"aces", "hable", "reinhard", "reinhard_luma", "reinhard_luminance", "generic"	Required	A generic tone mapping curve that has been hand-tuned by Mojang's artists. It is similar to the other filmic operators but preserves a bit more hue saturation at high luminance regions.
hable	"aces", "hable", "reinhard", "reinhard_luma", "reinhard_luminance", "generic"	Required	A filmic tone mapping operator meant to emulate the behaviors of real-life film, developed and shared by John Hable at a GDC talk from 2010 titled 'Uncharted 2 : HDR Lighting'.
reinhard	"aces", "hable", "reinhard", "reinhard_luma", "reinhard_luminance", "generic"	Required	A low-cost tone mapping operator that remaps HDR color values in the range [0, ∞) to [0, 1). This operator looks especially good when applied to low-contrast scenes whose values are already within the range of [0, 1), but tends to mute higher luminance values.
reinhard_luma	"aces", "hable", "reinhard", "reinhard_luma", "reinhard_luminance", "generic"	Required	An extended version of the Reinhard operator that comes at a slightly higher cost, but it preserves details in low dynamic range regions of an image that would otherwise be lost by the standard Reinhard operator.
reinhard_luminance	"aces", "hable", "reinhard", "reinhard_luma", "reinhard_luminance", "generic"	Required	A version of the extended Reinhard operator modified to adjust the luminance of the input colors. It comes at a slightly higher cost, but it preserves colors in high luminance regions of an image that would otherwise be washed out by the standard Reinhard operator.