1.21.1 Ray Layouts

Ray Layouts & Patterns

Version: Minecraft 1.21.1 (NeoForge).

Beam Lights calculates where light rays travel through the world. A beam can consist of a single focused central ray, or an arrangement of side rays that spread out across the cone to illuminate a broader field of view.

---

Ray Patterns

Ray patterns control how auxiliary side rays are arranged around the main look vector:

Pattern	Rays	Description	Recommended Usage
CENTER_ONLY	1	Single pencil-thin beam aimed exactly at the crosshair.	Long-range spotlights, high-performance setups.
TRIANGLE	4	Central ray + 3 surrounding rays forming an equilateral triangle.	Standard flashlights (balanced illumination and performance).
CROSS	5	Central ray + 4 rays (top, bottom, left, right).	Weapon-mounted lights, mining helmets.
RING	7	Central ray + 6 rays arranged in a circular ring.	Hand lanterns, searchlights.
DOUBLE_RING	19	Central ray + 6 inner ring rays + 12 outer ring rays.	High-end inspection lamps, cinematic screenshots.
HORIZONTAL_FAN	5	Central ray + 4 rays fanning horizontally across the horizon.	Vehicle headlights, sweeping tunnels.
VERTICAL_FAN	5	Central ray + 4 rays fanning vertically up and down.	Climbing shafts, inspecting ravines.
CUSTOM	User	Custom angle offsets defined in config or layout JSON.	Modpack-specific tools.

---

Layout Presets

Presets configure both the ray pattern, angular spread, and midpoint subdivisions with a single command:

/beamlights layout preset <name>

Preset	Pattern	Side Spread	Description
default	TRIANGLE	0.55	Balanced 3-ray pattern with moderate spread for standard flashlights.
wide	RING	0.75	6-ray circular layout that covers an entire cavern room.
performance	CENTER_ONLY	0.0	1 central ray only; minimal FPS impact on budget systems.
cliff	VERTICAL_FAN	0.65	Vertical fan ideal for descending deep ravines or spelunking.
floodlight	DOUBLE_RING	0.85	Expansive floodlight covering near and medium distances.

---

Side Rays & Midpoints

A ray doesn't just light the terminal block it strikes; it can also illuminate the air along the way using midpoints:

• Midpoints (midpointCount): Number of intermediate light points placed along each ray between the player and the wall (default 2).
• Minimum Distance for Midpoints (minDistanceForMidpoints): Shorter rays (< 4 blocks) skip midpoints to prevent unnecessary light sources in tight spaces.
• Side Spread (sideSpread): How far side rays deviate from the central axis, as a fraction of the beam's cone angle (0.1 to 1.0).
• Luminance Falloff (sideLuminanceOffset): Side rays are typically set 1–2 light levels lower than the central focal point to produce a natural hotspot effect.

---

Indoor vs Outdoor Patterns

Beam Lights allows you to use different patterns depending on whether you are indoors or outdoors:

• Indoor Pattern (rayPattern): Used in caves and buildings (e.g. TRIANGLE).
• Outdoor Pattern (openAreaPattern): Used when pointing into open skies or vast outdoor fields (default: CENTER_ONLY).

This setup gives you broad, atmospheric lighting while exploring dungeons and ruins, and automatically streamlines down to a single long-range beam when walking across open plains at night, keeping chunk rebuilds to an absolute minimum.