📖 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:

Metric	Without Lightstar	With Lightstar	Improvement
Total lighting computation time	Baseline	-52.5%	2x faster
Lighting processing throughput	1.0x	2.1x	+110.5%
Embeddium chunk building throughput	1.0x	1.49x	+49%
Dynamic light query time	82.3 s	0.05 s	-99.94%

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.