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.

These JSONs consist 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. See Event Flags.
• 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
}

Event Flags

Event flags are a dynamic way to enable or disable certain lightmap settings in case the type-based conditions aren't enough for your needs and you want something more specific. They are essentially named booleans (resource locations) that your mod or other systems can toggle at runtime using Java.

How They Work

A setting can list multiple flags in its event_flags array. For that setting to be eligible, all listed flags must be currently enabled. For example this provided JSON requires it to be raining during a new moon for its condition to match and be used:

  "event_flags": [
    "elysium_api:rain",
    "elysium_api:new_moon"
  ],

Default Event Flag Conditions

Elysium API comes with a set of built‑in event flags that update automatically based on the game state. You can use these immediately in your lightmap settings with no extra code required. All built‑in flags are in the elysium_api namespace.

Flag	Behavior
elysium_api:wither_nearby	Enabled when the player is near The Wither boss.
elysium_api:ender_dragon_nearby	Enabled when the player is near The Ender Dragon.
elysium_api:rain	Enabled while it is raining.
elysium_api:thunder	Enabled during a thunderstorm.
elysium_api:underwater	Enabled when the player's eyes are submerged in water.
elysium_api:underlava	Enabled when the player's eyes are submerged in lava.
elysium_api:lightning_strike	Enabled for a short duration when a lightning bolt strikes nearby.
elysium_api:access_to_skylight	Enabled if the player has a direct line of sight to the sky (no blocks overhead).
elysium_api:full_moon	Enabled during a full moon.
elysium_api:waning_gibbous	Enabled during a waning gibbous moon.
elysium_api:third_quarter	Enabled during a third quarter moon.
elysium_api:waning_crescent	Enabled during a waning crescent moon.
elysium_api:new_moon	Enabled during a new moon.
elysium_api:waxing_crescent	Enabled during a waxing crescent moon.
elysium_api:first_quarter	Enabled during a first quarter moon.
elysium_api:waxing_gibbous	Enabled during a waxing gibbous moon.

These flags can give you additional control over how your lightmaps are loaded but If you need custom flags beyond the provided defaults, you can always define your own and toggle them manually using the Java API.

Java API

Applying your own custom Event Flags is very easy, just call the LightmapSettingsManager class and use the enableEventFlag or disableEventFlag methods with your own namespaced flag provided with a ResourceLocation:

// Enables a flag
LightmapSettingsManager.enableEventFlag(ResourceLocation.parse("mymod", "inferno"));

// Disables a flag
LightmapSettingsManager.disableEventFlag(ResourceLocation.parse("mymod", "inferno"));

Then you'd just provide the custom event as usual and it'll start conditionally loading based on your provided toggle behavior

  "event_flags": [
    "mymod:inferno",
  ],

You can get very handsy with it and can toggle lightmaps based on practically any custom behavior within your mod this way!

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,

  "event_flags": [],
  "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.

During a rainy new-moon

{
  "type": "global",
  "sky_light_color": "#B2FFEF",
  "block_light_color": "#B2FFEF",
  "ambient_brightness_multiplier": 5.0,

  "event_flags": [
    "elysium_api:rain",
    "elysium_api:new_moon"
  ],
  "priority": 0,
  "fade_multiplier": 1.0
}

Makes the sky and block light a faint cyan with an increased ambient brightness when it is raining during a new moon night

End-Flashes

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

  "sky_light_color": "#FF00FF",
  "ambient_brightness_multiplier": 1.5,

  "event_flags": [
    "custommod:end_flash"
  ],
  "priority": 10,
  "fade_multiplier": 3.0
}

This lightmap setting backports the end flashes from 1.21.9 using a custom mod provided "custommod:end_flash" event flag; it makes the sky a vibrant magenta with an increased ambient brightness just like from the newer versions. it even has increased priority and fade multiplier to make it take increased priority over other mods and to make it appear more instantly.

Blacken all sky and block light during a custom blackout event in every other dimension

{
  "type": "not_dimension",
  "dimensions": [
    "thebetweenlands:the_betweenlands"
  ],

  "sky_light_color": "#000000",
  "block_light_color": "#000000",
  "ambient_brightness_multiplier": -4.0,

  "event_flags": [
    "netherexp:blackout"
  ],
  "priority": 3,
  "fade_multiplier": 2.5
}

This lightmap setting blacks out all sky and block light during a custom "netherexp:blackout" event in every dimension that is not the Betweenlands, showing you an example of how you can add checks to even modded dimensions and biomes even if they aren't loaded during runtime.

Config-based disabling of Lightmaps

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

  "sky_light_color": "#FFFFFF",
  "block_light_color": "#FFFFFF",
  "ambient_brightness_multiplier": 1.0,

  "event_flags": [
    "netherexp:disable_jne_lightmaps"
  ],
  "priority": 100
}

Let's be honest, not everyone likes colored ambient light and in such cases you can very easily add a lightmap setting with custom event such as "netherexp:disable_jne_lightmaps" that only activates if a certain config value is disabled. This would turn off all the other lightmaps in the nether because of its high priority and how it's setting sky and block light to white and resetting the ambient multiplier to 1.0.

Future Plans

Warning

These planned features are all subject to change and NONE of the features listed below have been implemented yet.

Expanded Setting Types

More setting types are planned to be implemented in the future such as:

• height - checks the client player's current y level and options to set:
  • min - minimum height to toggle on the condition
  • max - maximum height to keep the condition toggled on
• status - checks for the status effect inflicted on the client player, with its very own mob_effects list to define all the effects that can trigger it.

Event Flag Load Types

Right now the event_flags list requires all of the provided flags to be active in order to be matched. But this may be undesirable for certain people who'd rather want any of the provided flags to be active or even inverse it so the lightmap is disabled when a flag is active. That's what this is for:

• event_flag_load_type - specify how you want event flag conditions to be handled (default: all). It can be any of the following types:
  • all - loads if all the provided event flag are true
  • any - loads if any of the provided event flag are true
  • not - loads if all the provided event flag are false
  • xor - exclusive or, loads when only one event flag is true

Lightmap Texture Override

This feature is still a hypothetical and as such it might not make it, but the idea is to allow you to change out the lightmap texture itself for a custom conditionally loaded one. Not too dissimilar to how you'd do it with Optifine.

Optifine lightmap texture for reference

This way you'd have more control over the indevidual colors on a lightmap texture and more easily allow you to even modify daynight cycle colors and night-vision colors. The lightmap texture would be chosen with this optional override component within the JSON:

  "lightmap_texture_override": "your_mod:desert_override",

the texture would be supplied from assets/<namespace>/textures/lightmap_settings