1.21.1 Data Beams

Data-Driven Beams

Version: Minecraft 1.21.1 (NeoForge).

Pack makers can configure any vanilla or modded item to emit a directional beam using standard datapack JSON files. No code or compilation is required.

Beam definitions are loaded on the server and automatically synced to all connected clients upon joining and whenever /reload is executed.

---

File Location

Place beam definitions inside your datapack (or KubeJS kubejs/data/ folder):

data/<namespace>/beamlights/beams/<name>.json

---

JSON Specification

{
  "items": [
    "minecraft:lantern",
    "minecraft:soul_lantern",
    "#c:flashlights"
  ],
  "slots": [
    "mainhand",
    "offhand",
    "head",
    "curios"
  ],
  "luminance": 14,
  "range": 24.0,
  "cone": 25.0,
  "color": "#FFE8B0",
  "condition": {
    "component": "mymod:is_turned_on",
    "equals": true
  },
  "origin": {
    "forward": 0.3,
    "down": 0.2
  },
  "priority": 10
}

Property Reference

Property	Type	Required	Default	Description
items	Array of strings	Yes	—	List of item identifiers (e.g. "minecraft:lantern") or tag identifiers (prefixed with "#", e.g. "#c:tools/mining_helmets"). Unregistered items from optional mods are safely ignored.
slots	Array of strings	No	["mainhand", "offhand"]	Inventory slots where this item emits light. Valid values: "mainhand", "offhand", "head", "curios". (curios checks any worn Curios accessory slot if Curios API is present).
luminance	Integer	Yes	—	Light level emitted by the beam (1 to 15).
range	Double	No	16.0	Maximum reach of the beam in blocks (1.0 to 128.0).
cone	Double	No	25.0	Cone half-angle in degrees (1.0 to 89.0).
color	String	No	"#FFFFFF"	RGB hex color string (e.g. "#FFE8B0" for warm tungsten, "#88DDFF" for blue LEDs).
condition	Object	No	Always active	Evaluates a custom data component on the item stack before activating the beam.
origin	Object	No	{"forward": 0.0, "down": 0.0}	Positional offset relative to the entity's eyes (forward and down in blocks, range -4.0 to 4.0).
priority	Integer	No	0	If multiple beam definitions match the same item, the definition with the highest priority is chosen.

---

Condition Checks

The condition block allows you to restrict beam emission based on item components (NBT/data components in 1.21):

1. Component Presence

Checks if a component exists on the item:

"condition": {
  "component": "mymod:battery",
  "present": true
}

2. Component Equality

Compares the value of a component:

"condition": {
  "component": "mymod:state",
  "equals": "ACTIVE"
}

---

Examples

1. Warm Hand Lantern

data/mymodpack/beamlights/beams/lantern.json:

{
  "items": ["minecraft:lantern"],
  "slots": ["mainhand", "offhand"],
  "luminance": 13,
  "range": 18.0,
  "cone": 45.0,
  "color": "#FFC060",
  "origin": { "forward": 0.2, "down": 0.3 }
}

2. Spelunking Mining Helmet

data/mymodpack/beamlights/beams/mining_helmet.json:

{
  "items": ["#c:helmets/mining", "minecraft:iron_helmet"],
  "slots": ["head", "curios"],
  "luminance": 15,
  "range": 32.0,
  "cone": 20.0,
  "color": "#E0F0FF",
  "origin": { "forward": 0.1, "down": -0.1 }
}

3. Ghostly Soul Lantern

data/mymodpack/beamlights/beams/soul_lantern.json:

{
  "items": ["minecraft:soul_lantern"],
  "slots": ["mainhand", "offhand"],
  "luminance": 10,
  "range": 14.0,
  "cone": 35.0,
  "color": "#60D0FF"
}