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

Description of OptiFine's Custom Biome Palettes (Grid format)

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

Custom Biome Palettes (Grid format)

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

The vanilla colormap format has a few drawbacks.

First some biomes like desert are represented by only a single pixel in the
colormap, which means their color cannot vary by height.
Further, multiple biomes share their temperature and humidity values, making it
impossible to give them different color schemes.
Even when the base values are different, biomes sometimes overlap at higher
altitudes.

OptiFine offers an alternative,
is -- generally, see Tips below
but the x coordinate represents
height. (See the Minecraft Wiki
This allows complete separation
bedrock to max build height.
first proposed by Misa. Like the vanilla maps, it
-- a 256x256 colormap,
the biome ID number and the y coordinate the
for a list of biome IDs.)
between biomes and gives you full control from

Layout
======

Each column in the colormap represents a single biome. Please note that the image
is "flipped" vertically:
The bottom of the world (y=0) is at the top of the image and the max build height
(y=255) is at the bottom.
Sea level is y=64. Generally, you will make each column some sort of gradient.

Template (images/biome/grid/template.png)

Properties file format (colormap.properties)

(Optional) Format indicator

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

This property simply distinguishes grid-formatted colormaps from vanilla ones.

If not specified, your grid colormap will be interpreted in vanilla
temperature+humidity format, leading to strange results.

# Grid format
format=grid

The format property can be omitted if you set it globally in the

"assets/minecraft/optifine/color.properties" file:

# Grid format
palette.format=grid

This makes all your custom colormaps use the grid format, so be sure that this is
what you want.

(Optional) List of blocks with optional properties

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

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

See Biome Palettes (biome_palettes.txt).

(Optional) Colormap image

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

# Image
source=<image>

See Biome Palettes.

(Optional) Default color

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

# Color
color=<rgb value>

See Biome Palettes.

(Optional) y variance
======================

If set, this property adds random noise 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 value between y - 2 and y + 2, for example.

# Y variance
yVariance=<value>

The default value is 0 (no variation).

This property can also be set globally in

"assets/minecraft/optifine/color.properties":

# Y variance
palette.yVariance=<value>

(Optional) y offset
===================

# Y offset
yOffset=<value>

This subtracts a fixed value from the block's y coordinate before sampling from the
colormap.
For example a value of 64 will use the pixel at 0 for blocks between layers 0 and
64. A block at 65 will use pixel 1, 66 pixel 2, etc.

The default value is 0 (no offset).

Tips
====

Forward compatibility: Unused columns in the map represent unassigned biome IDs
that may be used by either by future Minecraft versions or by mods.
Of course you can create color schemes for particular mod biomes if you know the
IDs that they use. But even if you don't,
it is best to at least pick a neutral-looking gradient for unused columns so that
new biomes will have a reasonable default appearance.

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, you must create a custom colormap in
"assets/minecraft/optifine/colormap/blocks"
and apply it 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 256x256, there is no

strict requirement as 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 exploited if you
want all rare biomes to use the same color schemes
as the corresponding non-rare ones. Simply make your 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 you the same height-based color gradient
across all biomes.
In the y direction, if you provide more than 256 pixels, OptiFine will happily use
them if the server's build height is higher than the default.
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.
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 setting of yOffset=64 gives you 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.

References
==========
https://bitbucket.org/prupe/mcpatcher/wiki/Biome_Palettes_(Grid)
http://www.minecraftforum.net/forums/mapping-and-modding/resource-packs/resource-
pack-discussion/1255785-b?comment=124