===============================================

Description of OptiFine's Custom Biome Palettes

Based on McPatcher's Custom Biome Palettes
===============================================

Custom Biome Palettes

=====================

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,

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

Each file is a 256x256 colormap applied to the base grass or leaf texture (which is
usually grey).

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.

This page is divided into two sections. The first describes the colormap formats
themselves,
and the second shows how to apply them to various elements of the game world.

Vanilla colormap format

=======================

The format used by vanilla Minecraft is a 256x256 colormap with the axes
representing temperature and humidity.
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:
http://www.minecraftforum.net/forums/mapping-and-modding/resource-packs/resource-
pack-discussion/1256322-new-biome?comment=124

The vanilla format is used for all custom colormaps as well, unless you override
this behavior.

OptiFine "grid" format

=======================

An alternative format that offers finer control over each biome. It is detailed on
its own page:
https://bitbucket.org/prupe/mcpatcher/wiki/Biome_Palettes_(Grid)

Other formats
=============

Additionally, 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 reeds (sugar
cane).

Properties file format (colormap.properties)

A custom colormap can consist of either a ".png" file, a properties file, or both
depending on what you're trying to do.
All of the properties are optional and in fact the entire properties file can be
omitted if you do not need to change any of them.

(Optional) Colormap format

==========================

# Colormap format
format=<vanilla | grid | fixed>

If omitted, the default format is vanilla. If you'd rather use grid format by
default,
you can set it globally in the "assets/minecraft/optifine/color.properties" file:

# Grid format
palette.format=grid

Note that this setting 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.
See "Grass and foliage" below for how to use the grid format with these textures.

(Optional) List of blocks with optional properties

==================================================

# List of blocks with optional properties

blocks=<list>

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
(e.g., "cobblestone.properties" -> "blocks=minecraft:cobblestone").

See About Properties Files (properties_files.txt) for the syntax.

# For example:
blocks=stone minecraft:sand minecraft:lever:face=wall:facing=east,west

(Optional) Colormap image

=========================

# Colormap image
source=<image>

For vanilla and grid colormaps only. The path to the image containing the colormap.

If this property is omitted, it defaults to a png with the same name and directory
as the properties file itself,
e.g., "stone.properties" -> "source=stone.png".

(Optional) Default color

========================

# Default color
color=<rgb value>
For "format=fixed", this is simply the fixed color to be applied to all matching
blocks.
If no value is given, the default is white "ffffff".

For "format=vanilla" or "format=grid", this color is used for held or dropped

blocks.
If no value is given, the default color is instead taken from a fixed location
depending on the format:

# Format
format=vanilla: x=127,y=127 (Center of bitmap)
format=grid: x=1,y=64 (Plains biome at sea level)

Applying a custom colormap

==========================

Custom colormaps can be applied to any block or set of blocks.

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

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

For the first method, use the syntax

# Custom colormap
palette.block.<colormap image>=<list of blocks + properties>

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

# Custom colormap
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

Two limitations of this method:

- the source and blocks properties can be set; the rest are defaults.
- if the player is using multiple resource packs, only the first color.properties
file will be read by the game.

An alternative way is by using separate files under

"assets/minecraft/optifine/colormap/blocks".
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":

# Oak colormap
blocks=oak_leaves

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

# Pine colormap
blocks=tall_grass:half=upper

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

# Pine colormap
 blocks=tall_grass:half=lower

This is assuming you have "oak.png", "tall_grass_up.png" and "tall_grass_low.png"

in the same folder.

Single block
============

The simplest case, a custom colormap applied to a single block type with no
property values, 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".

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":

# Stone and ore colormaps

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

Add "format=grid" if using the new format. The source property is unnecessary if
the colormap is also named "stone_and_ore.png".

In "color.properties" this can also be written as:

# Stone and ore colormaps

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 your 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 you can leave your vanilla maps in place for compatibility and create
custom ones for OptiFine users:

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

# Grass colormap
format=grid
# NOTE: "blocks=grass" not needed since it is in the filename
yVariance=2

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

# Oak colormap
format=grid
blocks=oak_leaves

Fixing reeds (sugar cane) in 1.7

Starting in 1.7, Minecraft applies the "grass.png" color to reeds, much to the
annoyance of many artists.
A "fixed" colormap of "ffffff" (white) effectively reverts to the 1.6 behavior.
A 256x256 all-white colormap would of course 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":

# Reeds colormap
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, and underwater colors

=======================================

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 one can have a corresponding properties file to specify the format or other
settings.
These colormaps behave just as terrain-based ones except that they do not care
about the blocks property.

References
==========
https://bitbucket.org/prupe/mcpatcher/wiki/Biome_Palettes
http://www.minecraftforum.net/forums/mapping-and-modding/resource-packs/resource-
pack-discussion/1256322-new-biome?comment=124