Colormaps#

_images/biome_grid_template.png

The “grid” template#

Colormaps modify a texture’s tint based off it’s biome and height.

A custom colormap can consist of either a PNG file, a .properties file, or both, depending on what is intended. OptiFine greatly expands this functionality to other blocks and to ambient sky and fog colors.

Artists can use this to great effect to give each biome its own feel. Custom colormaps can be applied to any block or set of blocks.

They can also be applied to ambient fog, sky, and underwater colors.

Formats#

“vanilla” format#

See also

See the Fandom page on tint for more details

Caution

This format is difficult to manipulate and is not recommended

The format used by vanilla Minecraft is a 256×256 pixel PNG, with the axes representing temperature and humidity, respectively. Each biome has fixed base temperature and humidity values corresponding to a single pixel in the colormap. As the y coordinate increases, the position in the colormap slowly moves toward the lower-right.

_images/vanilla.png

An approximation of how Vanilla colormaps work#

A forum post by khanador illustrates how this works.

The vanilla format is used for all custom colormaps as well, unless this behavior is overridden!

Biome colormaps use a triangular gradient by default. However, only the colors in the lower-left half of the image are used, even though the upper-right side of foliage.png is colored.

_images/vanilla_foliage.png

The Vanilla foliage.png file, the upper-right side of foliage.png is colored is entirely unused.#

Furthermore, a select few pixels are considered when the colormap is read by the game, and are determined by the code below.

The adjusted temperature and adjusted rainfall values are used when determining the biome color to select from the colormap. Treating the bottom-right corner of the colormap as Temperature = 0.0 and Rainfall = 0.0, the adjusted temperature increases to 1.0 along the X-axis, and the adjusted rainfall increases to 1.0 along the Y-axis. The values used to retrieve the colors are computed as follows:

NewTemperature = clamp(Temperature, 0.0, 1.0)
NewRainfall = clamp(Rainfall, 0.0, 1.0) * NewTemp

“grid” format#

See also

MCPatcher source

An alternative format that offers finer control over each biome.

This format is similar to Vanilla’s 256×256 format, but the x coordinate represents the biome ID number, and the y coordinate represents the height. This allows complete separation between biomes, and gives full control from bedrock to maximum build height.

Each column in the colormap represents a single biome.

_images/biome_grid_template.png

Please note that the above image is “flipped” vertically:

  • The bottom of the world (y=0) is at the top of the image

  • The max build height (y=255) is at the bottom

  • Sea level is y=64

Generally, each column should be some sort of gradient.

Forward compatibility#

Unused columns in the map represent unassigned biome IDs that may be used by either by future Minecraft versions or by mods. Color schemes can be created for particular modded biomes if the IDs that they use are known.

If the IDs aren’t known, it is best to at least pick a neutral-looking gradient for unused columns so that new biomes will have a reasonable default appearance.

Backwards compatibility#

The vanilla grass.png and foliage.png maps in assets/minecraft/textures/colormap are always in the vanilla format, regardless of any properties file setting. This preserves compatibility for non-OptiFine users. To use the grid format with grass or leaves, a custom colormap must be present in assets/minecraft/optifine/colormap/blocks and be applied to the appropriate block(s). For OptiFine users, the custom colormap overrides the vanilla one; for non-OptiFine users, only the vanilla one will be used.

Resolution#

While colormaps in this format are generally 256×256, there is no strict requirement as there is with the vanilla format.

Minecraft 1.7 introduced rare variants of many biomes. For example “Birch Forest M” (ID 155) is the rare version of “Birch Forest” (ID 27).

Conveniently, the rare is always common + 128. This fact can be utilized (or, exploited) if all rare biomes should use the same color schemes as the corresponding non-rare ones.

Simply make the colormap 128 pixels wide instead of 256, and OptiFine will “wrap” it in the x direction when assigning columns to biomes. Similarly, a 1-pixel wide colormap gives the same height-based color gradient across all biomes.

In the y direction, if more than 256 pixels is provided, OptiFine will use them if the server’s build height is higher than 256, as is the case with 1.17 onward. Similarly, if the colormap is shorter than 256 pixels, it will simply “top out” at that height giving all blocks above that the same color as the top-most pixel of the map.

In particular, a height of 64 pixels allows for variation underground and a fixed color above sea level.

A height of 192 pixels combined with a property of yOffset=64 gives just the opposite: variation above ground and a fixed color below. A height of 1 pixel allows for variation across biomes but not by height.

“fixed” format#

OptiFine offers a simple “fixed” colormap format. This format does not require an image; it is simply a single color applied to all blocks regardless of location. Its primary purpose is to override certain hardcoded block colors like sugar cane.

Properties#

Note

All values here are optional

Note

The format property does not affect the vanilla “grass.png” and “foliage.png” files in assets/minecraft/textures/colormap, those are always interpreted in the vanilla format in order to preserve compatibility for non-Optifine users

Note

The yVariance property can also be set globally in assets/minecraft/mcpatcher/color.properties

Note

The format property can be omitted if it’s set globally in the assets/minecraft/optifine/color.properties file: palette.format=grid
This makes all custom colormaps use the grid format, so ensure that this is intentional

Note

This file can be omitted if no properties need to be changed

Key

Values

Meaning

format

Values: String, one of: grid, vanilla, fixed
Required: ❌ No
Default: vanilla
If not specified, uses vanilla format
Has exceptions, see NOTE above

blocks

Values: List of blocks
Required: ❌ No
List of blocks to apply colormap to
For colormaps applied to terrain (as opposed to fog, sky, and underwater), this is a list of blocks and optional property values to apply the map to
If this property is not specified, the block name is taken from the filename: cobblestone.propertiesblocks=minecraft:cobblestone

Example: blocks=stone minecraft:sand minecraft:lever:face=wall:facing=east,west
See the Properties Files document for more information

source

Values: String, path to texture
Required: ❌ No
File path to colormap
For vanilla and grid colormaps only
If this property is omitted, colormap defaults to a PNG with the same name and directory as the properties file itself: stone.propertiessource=stone.png

color

Values: String, hexadecimal RGB value
Required: ❌ No
Default: vanilla: (x 127, y 127), grid: (x 1, y 64), fallback: ffffff
Default color, no #
For fixed colormaps:
• This color will be applied to all matching blocks (blocks property)

For vanilla and grid colormaps:
• This color is used for held or dropped blocks

yVariance

Values: Integer
Required: ❌ No
Default: 0
If set, this property adds random noise to the y coordinate before sampling from the colormap, giving flat areas a more varied appearance
Only applies to grid format
A value of 2 causes the game to pick a value between y - 2 and y + 2

yOffset

Values: Integer
Required: ❌ No
Default: 0
Subtracts a fixed value from the block’s y cooardinate before sampling from the colormap.
For example, a value of 64 will use the pixel at y=0 for blocks between layers 0 and 64. A block at 65 will use pixel 1, 66 uses pixel 2, and so on

Applying a custom colormap#

Block-based colormaps can be applied in one of two ways:

  • as a list in assets/minecraft/optifine/color.properties

  • as separate files under assets/minecraft/optifine/colormap/blocks

As a list#

Warning

If the player is using multiple resource packs, only the first color.properties file will be read by the game

Key

Values

Meaning

palette.block.<colormap image>

Values: List of blocks
Required: ❌ No

Assigns each block it’s colormap

None

For example, the below assigns the four basic types of leaves their own colormaps:

  • palette.block.colormap/oak.png=oak_leaves

  • palette.block.colormap/tall_grass_up.png=tall_grass:half=upper

  • palette.block.colormap/tall_grass_low.png=tall_grass:half=lower

As separate files#

Important

This is assuming “oak.png”, “tall_grass_up.png”, and “tall_grass_low.png” are all in the same folder.

Subfolders are allowed and are useful to make organization easier. The above example could also be done this way:

In assets/minecraft/optifine/colormap/blocks/oak.properties:

blocks=oak_leaves

In assets/minecraft/optifine/colormap/blocks/tall_grass_up.properties:

blocks=tall_grass:half=upper

In assets/minecraft/optifine/colormap/blocks/tall_grass_low.properties:

blocks=tall_grass:half=lower

Single block#

This is the most simple case. Since a custom colormap is applied to a single block type, it does not need a properties file.

For example, assets/minecraft/optifine/colormap/blocks/sand.png applies to sand blocks without the need to specify blocks=sand in the colormap properties file.

Multiple blocks#

Note

The source property is unneeded if the colormap is also named the same

To apply the same colormap to all stone and ore blocks, use a properties file:

In assets/minecraft/optifine/colormap/blocks/stone_and_ore.properties:

blocks=stone gold_ore iron_ore coal_ore lapis_ore diamond_ore redstone_ore redstone_ore:lit=true emerald_ore

Use format=grid if using the grid format.

In color.properties this can also be written as:

palette.block.~/colormap/custom/stone.png=stone gold_ore iron_ore coal_ore lapis_ore diamond_ore redstone_ore redstone_ore:lit=true emerald_ore

Add palette.format=grid to use grid format for all the custom colormaps (except the vanilla “grass.png” and “foliage.png”).

Grass and foliage#

Custom colormaps will override the vanilla grass.png and foliage.png. This means vanilla maps can be left in place for compatibility; creating custom ones for OptiFine users.

Biome grass and foliage colors are selected from two 256×256 colormap images: grass.png and foliage.png. Both colormaps, shown below, can be found in assets\minecraft\textures\colormap.

_images/vanilla_grass.png

The Vanilla grass.png file, sets the colors for the grass block top and sides (along with other types of grass, such as tall grass, ferns, double tall grass, etc.)#

_images/grass_and_foliage.png

A template for foliage colormaps, created by Rodrigo Al#

_images/vanilla_foliage.png

The Vanilla foliage.png file, sets the colors for tree leaves (with the exception of spruce and birch)#

Note

blocks=grass property is not needed since it is in the filename

In assets/minecraft/optifine/colormap/blocks/grass.properties:

format=grid yVariance=2

In assets/minecraft/optifine/colormap/blocks/oak.properties:

format=grid blocks=oak_leaves

Swamp & badlands colors#

Vanilla Minecraft has no support for colormaps on swamp and badlands/mesa biomes. This is intentional, but OptiFine can override this behavior:

_images/swamp_colors.png

Button and tooltip for the option, found in Video Settings ➔ Quality#

Fixing sugar cane in 1.7#

Note

This only applies to 1.7 and above

Starting in 1.7, Minecraft applies the grass.png color to reeds sugar cane.

A fixed colormap of ffffff (white) effectively reverts to the 1.6 behavior. A 256x256 all-white colormap would accomplish the same thing, but this method is more efficient.

The simplest way to do this is to create a properties file containing just one line:

In assets/minecraft/optifine/colormap/blocks/reeds.properties:

format=fixed

This works because the blocks property defaults to the filename (reeds) and the color property defaults to ffffff for fixed colormaps.

Ambient fog, sky, underwater color#

Note

These behave like terrain-based ones, except that they do not care about the blocks property

_images/water.png

A template for water colormaps, created by Rodrigo Al#

These specifically-named colormaps override the default fixed ambient colors:

  • Overworld fog: assets/minecraft/optifine/colormap/fog0.png

  • Overworld sky: assets/minecraft/optifine/colormap/sky0.png

  • Underwater: assets/minecraft/optifine/colormap/underwater.png

Each file can have a corresponding properties file to specify the format or other settings.


🆚️ 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.