星光

📖 概述

这是一个客户端光照计算优化模组，通过缓存光照查询结果、优化区块构建时的数据读取路径，并与 Sodium Dynamic Lights 集成以消除冗余计算，从而降低区块加载、相机旋转和大规模方块变动期间的 CPU 开销。

简而言之：光照计算速度提升一倍，区块构建速度提升 49%，探索过程更流畅，卡顿显著减少。

---

✨ 关键成果

基于 120 秒 Spark A/B 测试，唯一变量为是否安装 LightStar：

指标	未安装 Lightstar	安装 Lightstar	提升幅度
光照计算总耗时	基准	-52.5%	2 倍速度
光照处理吞吐量	1.0x	2.1x	+110.5%
Embeddium 区块构建吞吐量	1.0x	1.49x	+49%
动态光照查询耗时	82.3 秒	0.05 秒	-99.94%

测试结果来自两个测试组（开启/关闭光影）的等权平均值。

测试配置： AMD Ryzen 9 9950X3D + NVIDIA RTX 4080 Super OC。实际使用中，中低端配置将体验到更为显著的提升。

---

🎯 预期收益

• 减少 Embeddium 异步区块构建过程中的冗余光照查询、坐标转换和数组清理操作。
• 减少重复采样同一位置时的哈希查找和数组访问次数。
• 复用相同不可变区块快照的静态光照结果，降低重复区块构建的成本。
• 阻止不支持 Forge 外部面剔除的方块进入相邻面剔除查询流程。
• 安装 Sodium Dynamic Lights 后，减少动态光照查询时的冗余遍历、读写锁竞争和线程局部状态开销。

---

⚙️ 实现细节

光照缓存

采用 4 路组相联的线程局部原始类型缓存存储近期光照值，并为最近访问的位置增加了单条目快速路径。光照更新会使数值代际计数器递增，立即使旧结果失效。DataLayer 半字节读取使用直接索引和位运算，减少热路径上的辅助方法调用和乘法运算。

Embeddium 区块构建

• 单次遍历即可读取方块光和天空光，消除了对同一坐标的第二次区块段查找。
• 方块光固定于低 4 位，天空光固定于高 4 位，不再依赖枚举排序。
• 使用 16 位代际数组，而非为每个构建任务清零全部 8000 个缓存槽位。
• 为克隆的不可变区块段分配数值修订号；仅当世界、原点及所有区块段修订号匹配时才复用跨任务缓存。
• 跨任务缓存采用访问顺序淘汰策略，并在玩家登录/退出世界时清空。

Sodium Dynamic Lights 集成

• 动态光照查询状态和包含 4096 个条目的 4 路组相联缓存直接由 ArrayLightDataCache 实例持有，消除了 ThreadLocalMap 查找。
• 每个构建任务开始时，在 SDL 读锁下复制动态光源引用的快照。任务内的查询直接遍历此快照，避免了每次采样时获取 ReentrantReadWriteLock。
• 光源更新会使代际计数器递增；移动中的光源永远不会写入持久缓存，也不会留下静态残影。
• 非区块构建路径保留完整的 SDL 回退行为，以确保兼容性。

---

⚠️ 不兼容项

• Starlight — 不兼容。
• Sodium/Embeddium Options API — 不兼容。此模组没有实际用途，并且不是 Sodium Dynamic Lights 的必需依赖项。