Colormaps¶

Colormaps modify a texture's tint based off its 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 one block or to a set of blocks. They can also be applied to ambient fog, sky, and underwater colors.

Formats¶

"vanilla" format¶

The format used by vanilla Minecraft is a 256px by 256px 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.

A forum post by khanador illustrates how this works.

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.

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:

new_temperature = clamp(temperature, 0.0, 1.0)
new_rainfall = clamp(rainfall, 0.0, 1.0) * new_temperature

"grid" format¶

An alternative format that offers finer control over each biome.

This format is similar to Vanilla's 256by by 256px 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 minimum to maximum build height.

Each column in the colormap represents a single biome.

Please note that the above image is "flipped" vertically:

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

• The normal maximum build height (y=255) is at the bottom.

• Sea level is y=64.

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, even if the pack isn't updated.

Backward 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 256px by 256px, 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¶

If the format is not fixed, the location of this file should sit in the same folder as the colormap image it will apply to. It should have the same base name as the texture.

format¶

The format to use for this colormap. If not specified, uses vanilla format. Has exceptions, see NOTE above.

blocks¶

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.properties ↔ blocks=minecraft:cobblestone

Example: blocks=stone minecraft:sand minecraft:lever:face=wall:facing=east,west. See Blocks and items for more information.

source¶

File path to colormap texture.

If this property is omitted, colormap defaults to a PNG with the same name and directory as the properties file itself: stone.properties <-> source=stone.png.

color¶

Differing behavior depending on format:

yVariance¶

If set, this property adds a random integer to the Y coordinate before sampling from the colormap, giving flat areas a more varied appearance. A value of 2 causes the game to pick a Y coordinate of y + randomInteger(0, 2).

yOffset¶

Subtracts a fixed value from the block's Y coordinate in the world before sampling from the colormap.

For example, a value of 64 will use the pixel at y=0 for blocks on Y-level 64. A block at y=65 will use pixel 1. A block whose y=66 uses pixel 2, and so on.

Applying a colormap¶

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

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 256px by 256px colormap images: grass.png and foliage.png. Both colormaps, shown below, can be found in /assets/minecraft/textures/colormap/.

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:

Fixing sugar cane in 1.7+¶

From 1.7 onward, Minecraft applies the grass.png color to sugar cane.

A fixed colormap of ffffff (white) effectively reverts to the 1.6- behavior. A 256px by 256px 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.

Other colors¶

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

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

Examples¶

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¶

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").

Custom biome palettes¶

Custom biome palettes may be assigned to any standard block (one that does not already have its own special color multiplier method). Each custom colormap should have a .properties file in ~/colormap/custom.

In Vanilla Minecraft, the grass and leaf textures vary in color depending on the climate of the surrounding biome. This is controlled by two files:

1. /assets/minecraft/textures/colormap/grass.png

2. /assets/minecraft/textures/colormap/foliage.png

Each file is a 256px x 256px colormap applied to the base grass or leaf texture (which is usually greyscale).

JSON schema¶

{
	"$schema": "http://json-schema.org/draft/2020-12/schema",
	"$id": "https://gitlab.com/whoatemybutter/optifinedocs/-/blob/master/schemas/colormap.schema.json",
	"title": "Colormap",
	"description": "Colormaps modify a texture's tint based off its biome and height.",
	"type": "object",
	"properties": {
		"format": {
			"enum": ["grid", "vanilla", "fixed"],
			"default": "vanilla",
			"description": "The format to use for this colormap."
		},
		"blocks": {
			"$ref": "common.schema.json#/$defs/item_id_list",
			"description": "List of blocks to apply colormap to."
		},
		"source": {
			"$ref": "common.schema.json#/$defs/resource",
			"description": "File path to colormap texture."
		},
		"color": {
			"type": "string",
			"pattern": "^[0-9a-fA-F]{6}$",
			"description": "Color will be applied to all matching blocks (fixed) or held and dropped blocks (else).",
			"default": "ffffff"
		},
		"yVariance": {
			"type": "integer",
			"default": 0,
			"description": "Add a random number to the Y coordinate before sampling from the colormap. Only for grid."
		},
		"yOffset": {
			"type": "integer",
			"default": 0,
			"description": "Subtracts a fixed value from the block's Y coordinate before sampling from the colormap."
		}
	},
	"dependentRequired": {
		"yVariance": ["grid"]
	},
	"allOf": [
		{
			"if": {
				"properties": {
					"format": {
						"enum": [
							"vanilla",
							"grid"
						]
					}
				}
			},
			"then": {
				"not": {
					"required": [
						"source"
					]
				}
			}
		}
	],
	"additionalProperties": false
}