1.21.1 Performance and Motion

Performance & Motion

Version: Minecraft 1.21.1 (NeoForge).

The primary performance cost of dynamic lighting in Minecraft does not come from calculating ray intersections; it comes from the graphics engine (Sodium / Embeddium) re-meshing chunk sections whenever a light source moves to a new block or changes luminance.

Beam Lights includes a specialized Motion Governor and a Tick Budget Manager specifically designed to eliminate stutter and keep frame rates smooth even during rapid mouse movement.

---

1. The Motion Governor

When you pan your camera quickly (e.g. whipping around to face a Creeper), conventional dynamic lighting mods try to re-mesh every chunk section touched by the beam on every frame, causing micro-stutters.

Beam Lights monitors angular velocity (degrees per second) and linear speed (blocks per second):

• Fast Motion Mode (> 90°/s or > 8 blocks/s):
  • Auxiliary side rays and intermediate midpoints freeze in place.
  • Only the central crosshair ray tracks the camera in real-time.
  • The cone light (if active) holds its position until the camera slows down.
  • Result: Light changes drop from ~7 per tick down to ~1 per tick during fast turns.
• Moderate Motion Mode (30°/s to 90°/s):
  • Side rays update at a reduced rate (every 3 ticks).
• Still Mode (< 30°/s):
  • All rays smoothly glide and snap to their target positions.

---

2. Performance Settings & Budgets

The [performance] section of config/beamlights-client.toml controls how updates are throttled:

Setting	Default	Description
maxMovesPerTick	6	Maximum number of light position changes allowed across all beams per tick. Priority is given to the local player's central beam.
snapToBlock	true	Snaps light points to integer block centers. Avoids sub-block jitter that triggers unnecessary chunk re-renders.
remoteUpdateInterval	2	Raycast interval for other players and mobs (evaluates every N ticks).
lodDistance	24	Beyond this distance (in blocks), other players and mobs only project a single central ray, discarding side rays.
mergeSameSection	false	When multiple light points fall into the same 16x16x16 chunk sub-section, merges them to trigger only one section rebuild.

---

3. Smoothing & Hysteresis

To prevent light points from constantly flickering between adjacent blocks:

• Move Hysteresis (moveHysteresis): A light source will not shift its position unless the target point has moved by at least 1.5 blocks (or 0.75 blocks for the central focal ray).
• Glide Smoothing (glideMinTicks): Light moves smoothly across blocks over multiple ticks rather than teleporting instantly.
• Fade Transitions (fadeSteps): Dimming or brightening lights step through subtle transitions to avoid harsh flashes.

---

4. Performance Presets

You can switch performance profiles instantly with the command:

/beamlights perf preset <quality | balanced | performance>

Preset	maxMovesPerTick	lodDistance	mergeSameSection	Recommended System
quality	16	48 blocks	false	High-end PCs with heavy GPU headroom.
balanced	6	24 blocks	false	Standard gaming laptops and mid-range PCs (default).
performance	3	16 blocks	true	Low-end PCs, steam decks, integrated graphics.

---

5. Live Diagnostics

To measure the real-time FPS impact and chunk rebuild rates, enable the debug overlay:

/beamlights debug overlay on

The overlay reports:

• sources: Number of active light sources registered with the backend.
• motion: Current camera angular velocity and motion state (STILL, MOVING, FAST).
• moves/s: Number of light coordinate changes per second.
• rebuilds/s: Estimated chunk section re-renders per second triggered by Beam Lights.
• area: Current environment state (INDOOR vs OUTDOOR).