1.21.1 Getting Started

Getting Started

Version: Minecraft 1.21.1 (NeoForge).

Beam Lights transforms ordinary Minecraft light sources into focused directional beams. This guide walks through installing the mod, configuring your preferred dynamic lights backend, and verifying that beams work properly in-game.

---

1. Installation

1. Install Minecraft 1.21.1 with NeoForge 21.1.x+.
2. Download and drop Beam Lights into your mods/ directory.
3. Install one client-side dynamic lights mod:
   • Recommended: LambDynamicLights (4.8.x+) — Supports directional point lights along the ray and soft volumetric cone lighting indoors.
   • Alternative: Sodium Dynamic Lights — Supports point lights along the ray (no cone lighting).
4. (Optional) Install Omega Flashlight for ready-to-use flashlights.
5. (Optional) Install Curios API if you plan to use helmet lamps or head-mounted lights.

---

2. In-Game Verification

Load a world and run the following command in chat:

/beamlights status

You will see a summary of the active configuration:

• Active Backend: Shows lambdynamiclights or sodiumdynamiclights.
• Enabled: true or false.
• Active Sources: Number of entities currently emitting a beam nearby.
• Ray Layout & Cone Status: Indicates active ray pattern and whether the soft cone is enabled.

---

3. Using Beams in Game

A. Flashlights (Omega Flashlight)

Hold an Omega Flashlight in your main hand or offhand and turn it on:

• Look at a distant wall or cave floor: the exact hit point is brightly lit.
• Look into a corridor: points along the path are illuminated, revealing obstacles and depth.
• In enclosed spaces (with LambDynamicLights), a soft expanding cone fills the room.

B. Custom Items & Lanterns

By default or via datapacks (see Data-Driven Beams), held lanterns, helmet lights, or custom gear will project beams automatically.

You can also test any item immediately using Minecraft's /give command with custom component data:

/give @s minecraft:lantern[minecraft:custom_data={"beamlights:beam":{luminance:14,range:24,cone:30}}]

Hold the lantern in your hand: it now projects a 24-block beam with a 30° cone.

---

4. Helpful Player Controls

All client settings are adjustable directly in-game and save immediately to config/beamlights-client.toml:

Action	Command
Toggle Beams On/Off	/beamlights on or /beamlights off
Change Ray Pattern	/beamlights layout pattern TRIANGLE (options: CENTER_ONLY, TRIANGLE, CROSS, RING, etc.)
Change Layout Preset	/beamlights layout preset wide (options: default, wide, performance, cliff, floodlight)
Adjust Cone Presets	/beamlights cone preset balanced (options: light, balanced, wide)
Switch Performance	/beamlights perf preset performance (options: quality, balanced, performance)

---

5. Diagnostic Tools

If you want to visualize how beams are cast or inspect performance:

• /beamlights debug overlay on: Displays live diagnostic metrics in the upper left corner (active emitters, ray count, FPS budget, moves/s, estimated chunk rebuilds/s).
• /beamlights debug render on: Renders 3D colored laser lines showing rays, hit points, and cone bounds in real-time.