Illumination API

Developer Library · NeoForge 1.21.1

Illumination API is a shader-based lighting library for Minecraft mods that need more than vanilla block light.

It was originally created from the lighting system developed for Create: Illumination, where projectors needed directional light, visible beams and real-time shadows. Instead of keeping that renderer tied to a single mod, Illumination API turns it into a reusable system that other mods can build on.

The goal is simple: a mod should be able to describe what kind of light it needs, while Illumination API handles the rendering behind it.

A projector can create a narrow spotlight. A fluorescent ceiling panel can create a rectangular area light. A moving machine can update its light position and direction at runtime.

The dependent mod does not need to implement its own shadow maps, volumetric renderer or multiplayer synchronization.

Lighting beyond vanilla

Minecraft's normal lighting system works well for illuminating blocks, but it is not designed for directional or volumetric light sources.

Illumination API adds a separate shader-driven lighting layer capable of rendering light with an actual position, direction, shape and range.

Supported light types currently include spot lights and rectangular area lights.

Lights may also cast dynamic shadows from world geometry and entities, allowing objects to physically block the light instead of the effect simply passing through them.

Volumetric rendering can make the light itself visible in the air, which makes the system suitable for projectors, fluorescent lighting, searchlights, industrial environments, horror maps and similar effects.

Designed as an API

Lights can be created, updated and removed while the game is running.

Their position, rotation, intensity, color, range, dimensions and other rendering properties can be changed dynamically, allowing the same system to support both static lamps and moving light sources.

Multiplayer synchronization is built into the library so that server-controlled lights can be represented consistently for connected players while the actual GPU rendering remains client-side.

Persistent lights are also supported when a light needs to survive world reloads or server restarts.

Performance

Illumination API is designed around the fact that a world may contain significantly more than one light source.

Expensive rendering work such as shadow rendering is therefore separated from cheaper light rendering, allowing the system to prioritize nearby or important lights instead of treating every light in the world as equally expensive.

This is especially important for environments containing many repeated sources, such as fluorescent ceiling panels.