1.21.1 Backends and Cone

Light Backends & Cone Light

Version: Minecraft 1.21.1 (NeoForge).

Beam Lights integrates with modern client-side dynamic lighting mods. Rather than implementing a custom rendering pipeline that clashes with shader packs or graphics mods, Beam Lights feeds dynamic light points into established lighting engines.

---

Supported Backends

Beam Lights automatically detects the installed backend at launch:

1. LambDynamicLights (Recommended)

• Features: Supports directional point lights along rays and smooth volumetric soft cone lighting.
• Renderer: Uses LDL custom light sources (LambDynamicLights.newLightSource(...)).
• Performance: Dynamic light updates and chunk section re-meshing are managed through LDL's optimized pipeline.
• Cone Lighting: Only available with LambDynamicLights.

2. Sodium Dynamic Lights

• Features: Supports directional point lights along the central and side rays.
• Renderer: Uses Sodium Dynamic Lights' light point registrations.
• Cone Lighting: Not supported (falls back automatically to point lights only).

---

The Soft Cone Light (Indoor Illumination)

When indoors or looking at nearby walls (under LambDynamicLights), a flashlight shouldn't merely light a tiny dot on the wall; it should illuminate the surrounding corridor or room.

The Cone Light system projects a volumetric cone of soft light from your eyes or flashlight bulb along the central beam.

Cone Parameters ([cone] section in config/beamlights-client.toml):

Config Key	Command Parameter	Default	Description
ldlConeLight	/beamlights cone enabled <true|false>	false	Global toggle for cone illumination.
ldlConeLuminanceOffset	/beamlights cone luminanceOffset <offset>	-3	Relative light level of the cone compared to the central beam.
coneMaxAngle	/beamlights cone maxAngle <deg>	25	Maximum half-angle of the light cone in degrees (5° to 60°).
coneMaxLength	/beamlights cone maxLength <blocks>	16	Maximum distance the cone reaches in blocks (4 to 48).
coneMinLength	/beamlights cone minLength <blocks>	3	Hits closer than this get no cone, only the central point light.
coneMaxDistanceForCone	/beamlights cone maxDistance <blocks>	20	If the hit is farther than this (or open sky), cone fades out.
coneEndFactor	/beamlights cone endFactor <factor>	0.5	Ratio of light level at the cone base compared to the apex (0.1 to 1.0).
coneEdgeSoftness	/beamlights cone edgeSoftness <factor>	0.25	Outer radius fraction that softens toward the perimeter (0.0 to 1.0).
coneFreezeWhenFast	/beamlights cone freezeWhenFast <bool>	true	Preserves cone light without rebuilding during rapid camera motion.

Quick Presets

You can adjust the cone characteristics with one command:

• /beamlights cone preset light: Subtle, narrow indoor cone (angle 18°, length 12 blocks, max distance 14 blocks).
• /beamlights cone preset balanced: Default balanced indoor cone (angle 25°, length 16 blocks, max distance 20 blocks).
• /beamlights cone preset wide: Wide, floodlight-style cone for large cavern halls (angle 35°, length 24 blocks, max distance 28 blocks).

---

Indoor / Outdoor Gating (Open Area Gate)

Lighting vast outdoor landscapes with a soft cone wastes FPS because hundreds of blocks must be evaluated. Beam Lights features an Open Area Gate that detects whether the beam is in an enclosed space or facing open outdoor areas:

1. Outdoor Condition: A beam switches to outdoor (open area) mode if:
   • There is no obstacle within range (pointing at the night sky).
   • The surface hit is farther than coneMaxDistanceForCone + openAreaHysteresis.
   • The surface hit has sky light exposure >= openAreaSkyLight (default 15).
2. Indoor Condition: A beam switches back to indoor mode once the hit distance drops below coneMaxDistanceForCone - openAreaHysteresis.
3. Hysteresis: A transition buffer (default 2.0 blocks) ensures the light never flickers when standing near thresholds.
4. State Hold Duration: Each state is held for at least openAreaMinTicks (default 10 ticks = 0.5s) to prevent rapid toggling.
5. Smooth Fade: When transitioning to outdoor mode, outdoor side rays begin dimmer for openAreaFadeTicks (default 6 ticks) to provide a natural blend.