Getting started

Installing for players

Put the Lambent jar for your Minecraft version and loader in the client’s mods folder. The jar names follow lambent-<loader>-<minecraft>-<version>.jar, for example lambent-neoforge-1.21.1-0.1.0.jar or lambent-forge-1.20.1-0.1.0.jar.

Lambent is client only. Servers do not need it. A server that has it loads it and does nothing, and a server without it lets players who have it join.

A mod that uses Lambent (Veltorque, say) needs it installed on every client. If it is missing, the loader stops at startup and names it as a missing dependency.

On Minecraft 26.2 and later, keep Video Settings, Graphics API on OpenGL (the default). Lambent draws with OpenGL, so on Vulkan the game runs normally but no Lambent lights show.

Depending on Lambent from your mod

Getting the artifacts

Lambent is published to your local Maven repository by its own build (see Building from source). The coordinates are:

Artifact	What it holds	Use it for
`com.raiiiden.lambent:lambent-<loader>-<mc>:<version>`	The mod jar for one loader. Reobfuscated on Forge 1.20.1.	Running the game in your dev environment, and compiling a loader project.
`com.raiiiden.lambent:lambent-common-<mc>:<version>`	The API and engine for that Minecraft version, vanilla only, in Mojang names, never reobfuscated.	Compiling a vanilla-only `common` project of your own.

<loader> is forge (1.20.1) or neoforge (everything else). <mc> is 1.20.1, 1.21.1, 26.1.2, 26.2 or 26.3. The POMs carry no dependencies.

repositories {
    mavenLocal {
        content { includeGroup 'com.raiiiden.lambent' }
    }
}

dependencies {
    // ModDevGradle legacyforge on 1.20.1
    modImplementation "com.raiiiden.lambent:lambent-forge-1.20.1:0.1.0"

    // ModDevGradle on NeoForge
    implementation "com.raiiiden.lambent:lambent-neoforge-26.3:0.1.0"

    // A vanilla-only common project
    compileOnly "com.raiiiden.lambent:lambent-common-26.3:0.1.0"
}

Declaring the dependency

Declare lambent as a required client-side dependency that loads before your mod.

mods.toml (Forge 1.20.1):

[[dependencies.yourmod]]
    modId="lambent"
    mandatory=true
    versionRange="[0.1.0,)"
    ordering="AFTER"
    side="CLIENT"

neoforge.mods.toml:

[[dependencies.yourmod]]
    modId="lambent"
    type="required"
    versionRange="[0.1.0,)"
    ordering="AFTER"
    side="CLIENT"

Only touch Lambent classes from client-only code. On a dedicated server Lambent may not be installed.

A first light source

Register sources once while the client starts, from your client setup. This one gives the player a flashlight that fades in at night:

import com.raiiiden.lambent.api.Beam;
import com.raiiiden.lambent.api.LightFrame;
import com.raiiiden.lambent.client.LambentClient;

public static void initClient() {
    LambentClient.register(10, frame -> {
        Player player = frame.minecraft().player;
        if (player == null || !frame.lampRoom()) return;
        float partial = frame.partialTick();
        Vec3 eye = player.getEyePosition(partial);
        Vector3f ambient = frame.ambient(eye);
        float dark = Math.max(LightFrame.darkness(ambient), frame.weather());
        if (dark < 0.01f) return;
        int key = -1 - player.getId();
        float fade = frame.fade(key, 0.15f);
        Vector3f color = new Vector3f(1f, 0.95f, 0.85f).mul(1.2f * dark * fade);
        frame.spot(key, Beam.FLASHLIGHT, player, frame.relative(eye),
                player.getViewVector(partial).toVector3f(), 1f, color, ambient, 0f, true);
    });
}

Everything here is covered in Light sources. Things to note:

frame.relative(eye) makes the position camera-relative. Every position Lambent takes is.
frame.ambient(eye) is the lightmap color at that point, and LightFrame.darkness turns it into how much the light should show: 1 in the dark, 0 in daylight.
frame.fade(key, seconds) eases a light in. Lambent remembers the fade by key for as long as you keep asking for it every frame.
glare is 0 because this is the viewer’s own flashlight; another player’s flashlight seen from in front should glare. handheld is true because it swings about with the player’s look.

Building from source

Gradle 9.8 on a Java 25 daemon (picked from a local JDK 25 through gradle/gradle-daemon-jvm.properties). Each project compiles with its own toolchain: 17 for 1.20.1, 21 for 1.21.1, 25 for 26.x.

gradlew buildAll                    # every jar, copied to build/dist
gradlew publishAllToMavenLocal      # what dependent mods resolve
gradlew :26.3:neoforge:build        # one target
gradlew -Plambent.only=26.3 build   # configure only one Minecraft version (faster)
gradlew :1.20.1:forge:runClient     # dev runs: runClient / runServer on every loader project

After changing Lambent, run publishAllToMavenLocal before building a mod that depends on it.

Dev client options:

Property	Effect
`-Pmc_username=Name`	The dev player’s name.
`-PquickPlay="World"`	Loads straight into that singleplayer world.
`-Plambent.shaders`	Adds Iris and Sodium (Oculus and Embeddium on 1.20.1) to the dev client. 1.20.1 and 1.21.1 only.
`-Plambent.selftest`	Runs the in-game self-test and closes the game. See Testing.

Layout

versions/<mc>/
  gradle.properties           that version's Minecraft, loader and Java versions
  common/                     vanilla only: api/, client/ (LambentClient, LambentConfig, render/, selftest/),
                              mixin/, shaders under assets/lambent/shaders/
  forge|neoforge/             the loader entry point and mods.toml / neoforge.mods.toml
gradle/
  lambent-java.gradle         toolchain, repositories
  lambent-common.gradle       applied by each common project; publishes lambent-common-<mc>
  lambent-loader.gradle       compiles the common sources into the loader jar, fills in the toml, publishes