LightStar

📖 Overview

This is a client-side lighting computation optimization mod that reduces CPU overhead during chunk loading, camera rotation, and large-scale block changes by caching lighting query results, optimizing data read paths during chunk building, and integrating with Sodium Dynamic Lights to eliminate redundant computations.

In simple terms: lighting calculations are twice as fast, chunk building is 49% faster, exploration is smoother, and stuttering is significantly reduced.

✨ Key Results

Based on 120-second Spark A/B tests, with the only variable being the presence of LightStar:

Results are equally weighted averages from two test groups (shaders on/off).

Test Configuration: AMD Ryzen 9 9950X3D + NVIDIA RTX 4080 Super OC. In practice, lower-end and mid-range configurations will experience even more noticeable improvements.

🎯 Expected Benefits

• Reduces redundant lighting queries, coordinate conversions, and array cleanup during Embeddium's async chunk building.
• Reduces hash lookups and array accesses when sampling the same position repeatedly.
• Reuses static lighting results from identical immutable chunk snapshots, lowering the cost of repeated chunk builds.
• Prevents blocks that do not support Forge's external face culling from entering the neighbor face culling query.
• When Sodium Dynamic Lights is installed, reduces redundant traversal, read-write lock contention, and thread-local state overhead during dynamic light queries.

⚙️ Implementation Details

Lighting Caching

Uses a 4-way set-associative thread-local primitive cache to store recent lighting values, with an additional single-entry fast path for the most recently accessed location. Lighting updates advance a numeric generation counter, immediately invalidating old results. DataLayer nibble reads use direct indexing and bitwise operations to reduce helper method calls and multiplication on the hot path.

Embeddium Chunk Building

• Reads block light and sky light in a single pass, eliminating a second section lookup for the same coordinates.
• Block light is fixed in the lower 4 bits and sky light in the upper 4 bits, removing dependency on enum ordering.
• Uses a 16-bit generation array instead of zeroing out all 8000 cache slots for each build task.
• Assigns a numeric revision to cloned immutable sections; cross-task caching is reused only when the world, origin, and all section revisions match.
• Cross-task cache uses access-order eviction and is cleared on world login/logout.

Sodium Dynamic Lights Integration

• Dynamic light query state and a 4096-entry 4-way set-associative cache are directly owned by the ArrayLightDataCache instance, eliminating ThreadLocalMap lookups.
• At the start of each build task, a snapshot of dynamic light source references is copied under the SDL read lock. Queries within the task iterate directly over this snapshot, avoiding ReentrantReadWriteLock acquisition per sample.
• Light source updates advance a generation counter; moving light sources never write to persistent caches or leave static afterimages.
• Non-chunk-building paths retain full SDL fallback behavior for compatibility.

⚠️ Incompatibilities

• Starlight — Not compatible.
• Sodium/Embeddium Options API — Not compatible. This mod serves no meaningful purpose and is not a required dependency for Sodium Dynamic Lights.