Lightmaps
Lightmaps are a tool to tweak Sky and Block light colors as time varies.
To understand Lightmaps its important to understand how lighting works in the game.
The game works by having two Light Values: Block Light and Sky Light. Block light is emanated by blocks such as torches while skylight only depends on sky access. Certain dimensions have a constant skylight or no skylight at all.
Each of them can have an integer value between 0 and 15.
To get the actual light color at a certain position the game simply reads a 16x16 "Light Texture" pixel value at the coordinates x = block light and y = sky light
This "Light Texture" is not a static texture that can be edited with texture pack but something internal that is updated by the game every frame. More precisely, Minecraft darkens/brightness the texture as a whole when time of day changes, as well as applies to it various other post processing like gamma correction or even random variation to torch light values to simulate torch flicker.
Polytone does NOT allow to alter said texture directly, instead provides a tool to affect how its created using Lightmaps.
Just for illustration purposes, here's the actual light texture that the game generated at noon. As you can see each pixel represent a unique combination of sky and block light with full bright being on the bottom right.
Polytone lightmap feature allows to fully customize the lightmap behavior through the use of some Lightmap Textures
To create a Lightmap, just like Colormaps, you'll need a .png file and optionally a .json configuration file. These have to be at the location assets/[target dimension namespace]/polytone/lightmaps/[target dimension name].png (preferred) or assets/[your mod namespace]/polytone/lightmaps/[target dimension namespace]/[target dimension name].png
Once again both files will need to have the same name to be associated with eachother.
As you might have noticed Lightmaps are per dimension. They will work for both modded and vanilla ones.
To break up this text here's an image of a lightmap template, showing what will be explained below
Just like colormaps, Lightmaps are just a texture that will be sampled at specific points to gather certain information.
- Width: can be any size. The bigger you make it, the more "detail" you'll be able to have, allowing for smoother color transitions
- Height: MUST be EITHER 16, 32 or 64
Lightmaps work in Rows. Only the first one is required as the rest is optional. Here's what each of them does
| row | use |
|---|---|
| 1 | Sky light |
| 2 | Torch Light |
| 3 | Night Vision Sky Light |
| 4 | Night Vision Torch Light |
- Vertical axis: Each Row Y value represents one specific Light Level (from 0 to 16). First Row will be relevant to sky light while second Row will e for torch light.
- Horizontal axis: Each Row X value represents a time of day / math expression. The specific of this depends on the particular sampler used. Refer to sections below
By adding the string _thunder or _rain at the very end of your texture file you'll be able to define lightmaps specific for those events. Note that if you do the .json file will need its normal name. Obviously adding these extra textures is optional.
Note that if you dont the game will follow its normal logic, sampling the lightmap using lower skylight valye when its raining and thundering (say from 0 skylight to 10 instead of 15).
If you do however define them know that by default their sampling behavior will span the entire lightmap meaning you are likely want to darken them manually.
In addition to adding one or more texture files you can also add a .json file to provide additional configuration. It can contain the following entries:
| Parameter | Default value | Function |
|---|---|---|
sky_getter |
default |
determines how the game calculates which X axis pixel to choose from the Sky Lightmap (upper 16 pixels). |
torch_getter |
random |
determines how the game calculates which X axis pixel to choose from the Torch Lightmap (lower 16 pixels). |
lightning_strike_columns |
true | true if last column should represent lightning strike colors. |
sky_lerp_factor |
0.5 | affects sky colors iterpolation time. Set to 0 to have instant transitions. Set to a higher numbers to have smoother transition between colors. |
sorch_lerp_factor |
0 | affects sky colors iterpolation time. Best to keep it low if you intend to use torch flicker. |
All parameters are optional.
Let's see an example first
{
"sky_getter": "smooth",
"torch_getter": "rand()*rand()",
"torch_lerp_factor": 0.001
}Getters (or samplers) are an advanced concept that give you fine grained control over WHICH colors are displayed at WHAT TIME during the day.
Why is this useful?
Vanilla behavior only samples from the first to the last row in a short time window at dusk and dawn. For the rest of the day the game will always either pick the last or first column.
This means we wouldnt have control over which colors would be displayed at say 10 in the morning or cant have a unique color during Dawn that is not the same as Dusk!
To break this up lets look at an example of how a Lightmap using the smooth_2 sampler
Getters are essentially a simple function that takes in 3 parameters, TIME, RAIN and THUNDER and spits out a number, normally used as the X texture coordinate..
Their function is to essentially spit out a X value at which to sample the palette you provide. Their output goes from 0 to 1 but will be normalize depending on your Lightmap width. This means that if a getter spits out 0.5, the game will pick the center row of your Lightmap at that instant.
As you might have noticed these 2 fields can either be a Reference or an Expression.
Here is a list of the already defined ones you can use by Reference.
| Getter | Explanation |
|---|---|
random |
Default torch sampler. Randomly spits out a number between 0 and 1 each frame |
default |
Vanilla sky sampler. Essentially a slanted Square Wave function that returns 0 for most of the night, 1 for most of the day and goes from 0 to 1 from dawn to dusk. |
smooth |
A sine wave. Starts at 0 at midning and smoothly rises to 1 at mid day following a sine curve |
linear |
A Sawtooth Wave. Starts at 0 at midnight, rires linearly to 1 at noon to then fall back down to 0. Useful if you want to have equally spaced colors for every hour of (half of a) day |
default_2 |
Like default but with twice the resolution. Stays at 0 from midnight to dawn, then rises to 0.5 and stays there for mostof the day. Then rises again to 1 and stays there from sundown to midning |
smooth_2 |
Just like smooth but twice the resolution. Half sine wave from midning at 0 to noon at 0.5. Then from 0.5 to 1 from noon to midning |
linear_2 |
Rises linearly from 0 at midning to 0.5 at noon and continues linearly till 1 shortly before midning |
As you can see the ones marked with _2 have the characteristic of being a Two-Way Function meaning that they map each time of day to an unique value. This can be very useful if say you want yo give a dark red color to dawn and a brigh yellow color to sunset as by default those 2 times of days would map to the same Lightmap X values.
If you still want even more control you can define your own Getter using an Expression (see related page), just as follows:
{
"sky_getter": "(TIME<0.5)*0.5 + RAIN*0.5"
}This silly example will return Lightmap X position 0 when time is day (<0.5) and 0.5 when night, all offsetted by the value of rain amount. Essentially this way first column of your Lightmap would be for day and no rain, following ones till mid texture would be day & rain, and then the same for night for the other hald of the texture.
Here is a graph of all the builtin getters. As you can see they are function that map Time Of Day to Texture X coordinate.
You'll notice that all the non 2 variant are not two way functions meaning that for many times of day the light map will sample from the same pixel coordinate. You can also notice how smooth_2 and linear_2 allow to map each time of day to a unique X position on the light texture and hence a unique color
As a bonus feature, Polytone fixes the issue where gui will just sample from the world lightmap (using max sky and block light), making them insteaed sample a dedicated static texture.
This change allows for custom lightmap to have a non-white full bright color without altering the GUI color.
This also fixes issues such as warden darkness effect affecting GUI text elements making them turn blue.
To tweak the GUI lightmap simply add a texture in assets/polytone/lightmaps/gui.png. You can check out the one already there to see how its setup. Normally only the lower right pixel is sampled so you can make it a static color too. Normally you shouldnt have reasons to change this unless you intend to change GUI colors.