1.21.1 Mod API

Java Mod API

Version: Minecraft 1.21.1 (NeoForge).

Beam Lights provides a lightweight Java API in the package it.ratlab.beamlights.api. Other mods can register custom beam providers, listen to and mutate active beams via NeoForge events, or inspect beam states without hard runtime dependencies.

The current API version is 1 (BeamLightsApi.API_VERSION).

---

1. Dependency Configuration

You can depend on the API artifact during compilation (compileOnly), ensuring that your mod compiles cleanly whether Beam Lights is present at runtime or not:

Gradle Setup (build.gradle)

repositories {
    mavenLocal()
    // Or local repository:
    // maven { url = uri('/path/to/beamlights/build/repo') }
}

dependencies {
    // API classes only (safe for compileOnly)
    compileOnly 'it.ratlab:beamlights:1.1.3:api'

    // Optional: include the full mod in your dev runtime client/server
    // runtimeOnly 'it.ratlab:beamlights:1.1.3'
}

NeoForge Declaration (neoforge.mods.toml)

Declare Beam Lights as an optional dependency:

[[dependencies.yourmod]]
    modId = "beamlights"
    type = "optional"
    versionRange = "[1.0,)"
    ordering = "NONE"
    side = "BOTH"

---

2. Implementing a BeamProvider

A BeamProvider allows your code to decide each tick whether an entity emits a beam, its direction, and its properties.

package com.example.mymod.compat;

import it.ratlab.beamlights.api.Beam;
import it.ratlab.beamlights.api.BeamProvider;
import net.minecraft.world.entity.Entity;
import net.minecraft.world.entity.LivingEntity;
import net.minecraft.world.phys.Vec3;

import java.util.function.Consumer;

public final class CustomFlashlightProvider implements BeamProvider {

    @Override
    public String name() {
        return "mymod:flashlight";
    }

    /**
     * Hot path: Evaluated every tick for candidate entities.
     * Keep this method lightweight (e.g. simple item checks).
     */
    @Override
    public boolean mayEmit(Entity entity) {
        return entity instanceof LivingEntity l && l.getMainHandItem().is(MyItems.CUSTOM_FLASHLIGHT.get());
    }

    /**
     * Called only if mayEmit returned true. Runs on both Client and Server.
     */
    @Override
    public void collect(Entity entity, float partialTick, Consumer<Beam> out) {
        LivingEntity l = (LivingEntity) entity;
        if (!MyItems.CUSTOM_FLASHLIGHT.get().isOn(l.getMainHandItem())) {
            return;
        }

        Vec3 eyePos = l.getEyePosition(partialTick);
        Vec3 lookVec = l.getViewVector(partialTick);

        // Beam.of(origin, direction, range, coneHalfAngle, luminance, rgbColor)
        Beam beam = Beam.of(
            eyePos,
            lookVec,
            30.0f,     // Range in blocks
            25.0f,     // Cone half-angle in degrees
            15,        // Luminance (0 to 15)
            0xFFE8B0   // RGB color (hex integer)
        );

        out.accept(beam);
    }
}

Registration

Register your provider during common setup (FMLCommonSetupEvent), on both sides:

event.enqueueWork(() -> {
    BeamLightsApi.register(new CustomFlashlightProvider());
});

---

3. Listening to BeamCollectEvent

Beam Lights posts BeamCollectEvent to the NeoForge.EVENT_BUS whenever beams are collected for an entity on either side.

Because the list of beams is mutable, mods can inspect, modify, or cancel beams:

@SubscribeEvent
public static void onBeamsCollected(BeamCollectEvent event) {
    Entity entity = event.getEntity();

    // Example: Dim all beams if the entity is submerged underwater
    if (entity.isUnderWater()) {
        event.getBeams().replaceAll(beam -> 
            beam.withLuminance(Math.max(0, beam.luminance() - 5))
        );
    }

    // Example: Completely extinguish beams during a blackout status effect
    if (entity instanceof LivingEntity living && living.hasEffect(MyEffects.EMP)) {
        event.getBeams().clear();
    }
}

---

4. Querying Active Beams

You can query beam states on any entity:

• BeamLightsApi.isBeamActive(Entity entity): Checks if the entity is currently casting a beam.
• BeamLightsApi.getBeams(Entity entity): Returns a snapshot list of all active Beam objects emitted by the entity.