Lightmap Settings

Introduction

A lightmap (or known internally as LightTexture) is a texture generated at runtime that Minecraft uses to determine the color and brightness of nearly every object in the world, based on block light and sky light. Unfortunately, if you’ve ever tried to modify these lightmaps, you’ve probably noticed that Mojang’s implementation is... difficult to work with. It’s one of the more stubborn hardcoded features to change, especially if you’re inexperienced with Mixins. Modifying it can easily lead to unintended incompatibilities with other mods that also want to alter lightmaps. And to make matters worse, lightmaps are shared with GUI rendering, which causes screens to become tinted too. Very nasty stuff!

Elysium offers a solution by doing all the hard technical work for you! And you are given full control over lightmaps with a simple, resource‑driven system that resource packs and mods can use. This feature is called Lightmap Settings, and it acts as a dynamically loaded patch on top of any pre‑existing lightmap to ensure that any modifications you make are compatible with virtually any mod you decide to use them with.

We've also provided various conditional loading options that let you apply lightmap settings only when specific conditions are met. This means you're not stuck with a single, global lightmap for every situation. Instead, you can define settings that activate only in certain biomes, dimensions, or even during dynamic in‑game events like boss fights or weather changes.

Note

Lightmap Settings are loaded only on the client-side and thus have no effect on the actual light level of a block nor does it influence mod spawning.

Lightmap Settings Overview

A Lightmap Setting is a .json file that goes into assets/<namespace>/elysium_api/lightmap_settings these JSON-defined configurations tell the game what skylight color, block light color, and ambient brightness to use under specific conditions. Each setting can optionally be restricted to certain biomes, dimensions, or event flags.

Each setting consists of the following components:

• type - How the setting gets matched for loading, it can take any of the following types:
  • global - constantly loaded assuming event flags allow it.
  • biome - only if the biome that the client player is currently occupying matches.
  • dimension - only if the dimension that the client player is currently occupying matches.
  • not_biome - NOT-gate counterpart of biome.
  • not_dimension - NOT-gate counterpart of dimension.
• biomes - A singleton or a list of Biome IDs to match (only relevant for biome and not_biome types).
• dimensions - A singleton or a list of Dimension IDs to match (only relevant for dimension and not_dimension types).
• sky_light_color - An #RRGGBB hex color that multiplies the sky light channel.
• block_light_color - An #RRGGBB hex color that multiplies the block light channel.
• ambient_brightness_multiplier - A float that scales the ambient brightness (default: 1.0).
• event_flags - A set of namespaced flags that must all be enabled for this setting to apply.
• priority - An integer value, higher priority settings are evaluated first (default: 0).
• fade_multiplier - Controls how fast the lightmap fades to this setting (default: 1.0).

JSON Skeleton of a Lightmap Setting:

{
  "type": "?",
  "sky_light_color": "#FFFFFF",
  "block_light_color": "#FFFFFF",
  "ambient_brightness_multiplier": 1.0,
  "event_flags": [],
  "priority": 0,
  "fade_multiplier": 1.0
}

Examples

As you can see you have quite a few options to mess around with already, but to really help showcase the potential of Lightmap Settings. We've provided many example JSONs with practical use-cases and explanations attached to them as a means to learn and get an idea on what you can do with these:

Biome-based Skylight Color Example

{
  "type": "biome",
  "biomes": [
    "minecraft:desert"
  ],

  "sky_light_color": "#FFFF00",
  "ambient_brightness_multiplier": 1.0,

  "priority": 1,
  "fade_multiplier": 1.0
}

A very simple lightmap setting that makes the sky light yellow while keeping the block light unchanged. It also has a slightly increased priority meaning unless specified otherwise, this lightmap setting will take precedent over settings provided by other resource packs or mods.

Dimension-based Sky, Block and Ambient Light Modification based on Event Flag

{
  "type": "dimension",
  "dimensions": [
    "minecraft:the_end"
  ],

  "sky_light_color": "#E182FF",
  "block_light_color": "#E182FF",
  "ambient_brightness_multiplier": -2.5,

  "event_flags": [],
  "priority": -1,
  "fade_multiplier": 1.0
}

This lightmap setting makes the end sky and block light into a dull-purple with a decreased ambient light to prevent the dimension from looking as bright as it usually does. It also has a lowered priority meaning any other lightmap setting added by other mods with similar conditions naturally take precedent over it.