1.21.1 KubeJS

KubeJS Integration

Version: Minecraft 1.21.1 (NeoForge) with KubeJS 7 (2101.7+).

Beam Lights exposes native bindings to KubeJS under the global binding BeamLights. Modpack developers can assign beam data to items, query entity beam activity, or inspect active beams dynamically using JavaScript scripts.

---

Global Binding: BeamLights

The BeamLights helper is available in both startup and server scripts:

Item Manipulation Methods

Method	Description
BeamLights.setBeam(itemStack, beamData)	Attaches or updates beam data on an item stack via custom_data.
BeamLights.getBeam(itemStack)	Returns a map containing the beam data stored on the item, or null if none.
BeamLights.clearBeam(itemStack)	Removes the beam data component from the item stack.

Entity Query Methods

Method	Description
BeamLights.isBeamActive(entity)	Returns true if the entity is currently projecting at least one active beam.
BeamLights.beamCount(entity)	Returns the number of beams currently active on the entity.
BeamLights.beams(entity)	Returns an array of active Beam snapshot objects emitted by the entity on the current side.

---

Script Examples

1. Attaching a Beam to an Item on Crafting (Server Script)

You can assign beam parameters directly to items produced by recipes or quests:

server_scripts/miner_helmet_reward.js:

ServerEvents.recipes(event => {
    // When crafting a special miner's helmet, attach a bright forward beam
    event.shaped(
        Item.of('minecraft:golden_helmet', {
            'minecraft:custom_data': {
                'beamlights:beam': {
                    luminance: 15,
                    range: 30.0,
                    cone: 22.0,
                    color: '#FFE8B0',
                    slots: ['head']
                }
            }
        }),
        [
            ' G ',
            'LHL',
            '   '
        ],
        {
            G: 'minecraft:glowstone',
            L: 'minecraft:lantern',
            H: 'minecraft:iron_helmet'
        }
    )
})

2. Dynamically Setting Beams with setBeam

In your server scripts:

ItemEvents.rightClicked('minecraft:amethyst_shard', event => {
    let player = event.player
    let item = event.item

    // Toggle a magical purple beam on the amethyst shard
    let existing = BeamLights.getBeam(item)
    if (existing) {
        BeamLights.clearBeam(item)
        player.tell("The amethyst shard stops glowing.")
    } else {
        BeamLights.setBeam(item, {
            luminance: 14,
            range: 25.0,
            cone: 35.0,
            color: '#D080FF',
            slots: ['mainhand', 'offhand']
        })
        player.tell("The amethyst shard begins projecting a radiant purple beam!")
    }
})

3. Detecting if a Player Shines Light on a Monster

You can check whether a player is illuminating hostile mobs:

EntityEvents.hurt(event => {
    let attacker = event.source.actual
    let target = event.entity

    if (attacker && attacker.isPlayer() && target.isMonster()) {
        if (BeamLights.isBeamActive(attacker)) {
            // Player is shining a light while attacking
            target.tell("Blinded by the light!")
        }
    }
})