Colormaps

Colormaps are a special object added by the mod. By themselves they do nothing but they can be Attached to many things via other Polytone concepts to alter how their colors are choosen. These are:

• Fluids -> Fluid Modifiers
• Blocks -> Block Properties Modifiers
• Particles -> Particle Modifiers
• Sky/Fog -> Dimension Modifiers
• Item -> Item Modifiers

Note

If you are using (some versions of) Sodium, due to this issue, some Colormaps will be completely off until they fix.

Consider using Embeddium (fabric) instead.

Usage

Colormaps are composed of 1 or 2 objects depending on their type: a .png texture and a .json configuration file.

There are 4 types of colormaps you can use/create:

• Builtin: Built-in Colormap. Can be added By Reference in your Modifiers (some kinds of these such as grass color dont need a new texture)
• Standalone: Colormap object created in its own folder in colormaps. It can be made with a .png and or.json. Can be added By Reference in your Modifiers
• Inlined: Colormap json definition can be inlined directly into the colormap field IN your Modifier (.png texture will have to be placed in the folder where your modifier lives)
• Implicit Inlined: Just like above but without anything in the modifier, Simply adding a .png file i the Modifier folder will attach the colormap to it, provided the .png has matching name fo the Modifier

Without devling into the specifics immediately here are some examples to keep things practical.

Here we are using a Builtin colormap in a Block Modifier .json, assigning the already existing grass color logic to the block.

{
  "colormap": "minecraft:grass_color"
}

Here's another example of an Inlined colormap in a Fluid Modifier file. A .png file needs to be added to the folder where this modifier lives.

{
  "fog_colormap": {
    "x_axis": "POS_Y/256",
    "y_axis": 0
  }
}

Finally here is a colormap with idential logic to the above but defined as a Standalone one in colormaps folder. It can be them used By Reference in any of our modifiers, very similar to the builtin example above, just having a different ID.

{
  "x_axis": "POS_Y/256",
  "y_axis": 0
}

The Colormaps Folder

Standalone Colormaps will be defined in their own /colormaps folder. Then they will be able to be Referenced and used elswhere.

To function, Colormaps need a .png and/or a .json file in /colormaps.

As stated previously, you can also inline colormaps by adding their .png to either the /block_modifiers, /dimension_modifiers or /fluid_modifiers folders to have them automatically attached to either entries. This mainly servers as a shorthand.

We'll first go over how to add one in /colormaps.

Png Texture

A Colormap .png needs to be added for each tint index you intend to use (texture can be any size). These will be placed right next the Colormap .json at the following path: assets/[your pack namespace]/polytone/colormaps/[your colormap name]_[tint index].png.

If you are only using 1 tint index you can omit the tint index information.

Aa an Example let's say you have a blockmodel that uses "tintindex = 1" for one of its face. The texture file will be called something like mì my_colormap_1.png. Note the last underscore matching the ting index.

Json Configuration

Json configuration file is used to precisely define the sampler behavior of the colormap. You can omit it to have the vanilla biome temperature/humidity sampler used in grass color (refer to Minecraft Wiki for more info).

It must be placed in the same folder as the .png file, so in: assets/[your pack namespace]/polytone/colormaps/[your colormap name].json

Each Json needs to have the following attributes:

Attribute Name	Default Value	Explanation
x_axis	- (not optinlal)	X Sampler. A math expression that determines the colormap texture x coordinate. Output has to be from 0 to 1 (will be clamped if not)
y_axis	- (not optinlal)	Y Sampler. A math expression that determines the colormap texture y coordinate. Output has to be from 0 to 1 (will be clamped if not)
default_color	Color at texture 0.5, 0.5	The default color that blocks will have. Mainly relevant when said blocks will have an item form. If blank it will pick the center color.
triangular	true	Boolean. Determines if only lower half of the colormap will be used (like vanilla grass color). By default is off so the entire texture will be used.
biome_blend	true*	Boolean. If colors should blend in between biomes. Active by default for all maps that use the TEMPERATURE or DOWNFALL values in their samplers
biome_id_mapper	Hardcoded biome mapper	Assigns each biome name a unique number to be used in the BIOME variable or biome_id sampler type
rounds	true	if output of the samplers is rounded to nearest pixel instead of floored to the greatest whole pixel below. Generally dont add this

For more info about Math Expressions Scripting visit its respective Page.

Here's an example Colormap .json for Tint Index 0 and 1. Note that you can use -1 to apply the colormap to all Tint Inexes.

{
  "default_color": 23433,
  "x_axis": "0.5+cos(POS_X*0.2)*0.5",
  "y_axis": "0.5+sin(POS_Z*0.1)*0.5 + TEMPERATURE"
}

Once you have added your Colormap file the only thing you need to do is Reference it in all your Block Modifiers, Fluid Modifiers Item Modifiers or Particle Modifers Json files like so:

{
   "colormap": "[your pack namespace]:[your colormap name]"
}

Note that some might usemultiple Colormaps and thus have different names for their fields. Item Modifiers for example use the colormap field for item tint and bar_colormap for durability bar colors.

Inlining

Inlining allows to create and immediately associate Colormaps directly in any Modifier .json that supports it (for example such as in block_modifiers and item_modifiers).

There are two ways of doing this:

• If you have a Modifier .json already (such as a biome_modifier one), you can fill in its colormap(s) field(s) with a Colormap definition. Then you will have to place the relevant textures in that same folder using the same name as the .json. For Modifiers that support multiple colormaps this name will be postfixed by some name (i.e. _fog and _sky for Biome Modifiers)
• If you dont have a Modifier .json you can omit creating one. You can then just paste the colormap texture in the Modifier folder, calling with the same name as the Target of that Modifier. For example dirt to target Dirt block in a Block Modifier.

Note however that inlining is NOT RECCOMENDED if you are using the SAME COLORMAP MULTIPLE TIMES. This is because the game will create MULTIPLE Colormap instances which needlessly wastes resources. Expecially relevant if those maps have Biome Blend on.

Compound Colormaps

NOTE: this section is only usable for INLINED colormaps in BLOCK MODIFIERS or ITEM MODIFIERS

Compound colormaps are used to assing a Different Colormap to each tintindex, usefulif you want to have different colormaps for each model part for example.

Here's an example that assings the first colormap to tint index 1 and the second to tint index 3.

{
  "1": "[first colormap definition/refence]",
  "3": "[second colormap definition/reference]"
}

In Block Properties

As an example, to give a custom Colormap to minecraft:sugar_cane you'll just have to place (one or more depending on tint index) file at the location assets/[your pack name]/polytone/block_properties/minecraft/sugar_cane_[tint index].png. (Once again you can omit /minecraft or _[tint index] if you so choose.)

Note that when done this way the Colormap .png must be placed in the ./block_properties/[my property].json folder, following same convention as its json file.

{
   "colormap": {
      "1": {
         "x_axis": "state_prop(0)",
         "y_axis": "0",
         "default_color": 4764952
      }
   }
}

In this specific example we are creating a colormap for Wheat Block using a 7x1 texture. The sampler will look up the AGE BlockState Property (the only property that block has, hence why index 0) and sample one of the 15 columns accordingly.

Note that if you intend to only have a tint applied to ALL tint indexes you can omit the "[tint index]":{} part and straight out define a colormap like you would in Fluid Properties here below.

In Fluid Properties

These work exactly the same as block properties except you wont have to define any logic related to the tint index. As such the json can be as follows:

{
   "colormap": {
      "x_axis": "TEMPERATURE",
      "y_axis": "DOWNFALL",
   }
}

Built-In Colormaps

Below follows a list of all the already defined colormaps (types) you can use incase you dont want to define your own. Note that the first 3 types already have a texture associated as those are the 3 vanilla existing colormaps so you won't need to add a texture when using those.

Default Colormap Types	Requires Custom Texture	Description
grass_color	false	Vanilla grass biome color resolver (grasscolor.png)
foliage_color	false	Vanilla foliage biome color resolver (foliagecolor.png)
water_color	false	Vanilla biome water color resolver (watercolor.png)
biome_sample	true	Samples with similar logic as grass_color, having TEMPERATURE on one axis and HUMIDIFY on the other. Unlike grass color its NOT triangular
triangular_biome_sample	true	Samples with same exact logic as grass_color (temperature/ humidity on each axis, with triangular shape)
fixed	true	Just gets a single pixel at 0,0
grid	true	Assigns each biome its Registry numerical ID divided by 256 and uses it to sample the X axis. Y axis is sampled based on block y position. Just used for Optifine backwards compat. Only use with biome_id_mapper. This interns uses biome_id sampler explained below.
damage	true	Used for Items only. Samples a texture picking a x value that depends on the damage of the item, 0 at no damage and 1 at max damage

Example of using a pre defined (or custom) colormap by reference in Block Properties Modifier Json

{
  "colormap": "fixed"
}

Default Samplers

Default Samplers	Description
temperature	equivalent of writing TEMPERATURE. gets the temperature of the biome at that pos
downfall	equivalent of DOWNFALL. gets the downfall of the biome at that pos
legacy_temperature	returns height dependant temperature. This is how colormaps used to operate before 1.17
biome_id	returns the current biome Registry Index divided by 255 or the value given by biome_id_mapper. Ideally only use when paired with biome_id_mapper
item_damage	returns a number from 0 to 1 depending on the itemstack damage

Example of using a pre defined sampler (on the y axis). Showing here a Colormap Json instead. As you can see the second one is an expression while the first one is equivalent of having written just "TEMPERATURE" and will use the pre defined temperature sampler.

{
  "y_axis": "temperature"
  "x_axis": "TEMPERATURE+2"
}

If you want to have something simple like a single color colormap, just set the samplers to 0 and give it a single pixel texture as colormap. At that point however you should consider using for your model a different colored texture instead

Biome Id (Grid) Colormap

When using the biome_id sampler or the pre defined grid colormap type it is recommended that you also include a biome_id_mapper to manually define the numerical "ID" of each biome.

See in modern versions registry entries such as biomes dont have a static numerical ID associated with them and instead they have a resource location (i.e. minecraft:forest). Moreover in a modded enrivonment the registry order of them could vary depending on the installed mods and thus is not static.

For these reason its necessary to have a way to tell the mod what numerical value to associated to each biome such that the biome texture can be sampled accordingly.

To do so you'll have to add a biome_id_mapper to your colormap json or alternatively define it in the /polytone/biome_id_mappers/ folder and reference it by ID like we did many times before.

Note that when this is omitted, the mod will assign to each biome registry index divided by 255. It's clear how in a modded environment this isnt nearly enough control to guarantee that modded biomes work as expected.

To proceed, simply add this block to your colormap json. It contains a map of biome IDs to numerical values. These values will have to be from 0 to 1. Note that we use "biome_id" as sampler as that is the only one that will use the biome id mapper object.

{
  "x_axis": "biome_id",
  "y_axis": "0",
  "biome_id_mapper": {
    "minecraft:forest": 0.01,
    "swamp": 0.9
  }  
}

Note that all biomes that are NOT included will map to 0.

If you wish to work with pixel coordinates instead, you can add the texture_size string to it. This will divide all your values by that amount, essentially letting you workwith pixel coordinates instead of relative ones. Obviousluy texture size will have to match your colormap dimension.

{
  "biome_id_mapper": {
    "minecraft:forest": 1,
    "swamp": 14,
    "plains": 15,

    "texture_size": 16
  }  
}

Finally if you do not wish to copy paste these into all your colormaps, you can also statically define them in assets/[your pack namespace]/polytone/biome_id_mappers/[your mapper name].json.

Once you have done that you can simply reference them in your colormaps as follows

{
  "biome_id_mapper": "my_pack_name:my_mapper_name"
}

Noise

Want to add perlin noise to your block colors? Check out the Scripting /Expressions section on this wiki to know more. For a quick summary you'll be able to define custom 2d perlin noise samplers functions which you can reference in any expression field such as a colormap sampler. A simple usa case could be this where the X axis of our texture will be sampled according to some noise value calculated using the X and Z coordinates of the block. This uses the builtin noise function but you can add more with more octaves if you want.

{
  "x_axis": "noise(POS_X, POS_Z)"
  "y_axis": "0"
}