Supernova

[!INFO] Git Commit: 见 relation.md | Minecraft 1.7.10 / Forge（@Mod 用 acceptedMinecraftVersions = "[1.7.10]"）

彩色光照（colored light）引擎重写：把原版「单一亮度」换成 RGB 三通道存储。

简介

Supernova（modid supernova）是 1.7.10 的光照引擎替换 mod。 它同时是 coremod 与普通 mod：

• 两种光照模式 —— RGB（3 通道彩色）/ SCALAR（单通道，等价 Starlight）。
• 63 个方块兼容适配 —— 24 个 ModCompat 常量 / 57 个 modid。
• 6 种着色混合 —— 方块光 × 天光的 TintBlendMode。
• 3 个 mixin JSON 全无 mixins 数组 —— 全部由 gtnhmixins 动态注册。
• ChunkAPI 强依赖（仅 RGB 模式） —— 缺失时强制改写配置为 SCALAR。

⚠️ 分类名 supernova 与 modid 一致，但内容与「超新星/恒星」无关 —— SCALAR 仅表示「等价 Starlight 的快速无色模式」，是光照技术名词。

概念总览

核心

• Supernova — @Mod，硬依赖仅 hodgepodge@[2.7.179,)
• SupernovaCore — IFMLLoadingPlugin + IEarlyMixinLoader
• Targeted Mod — 仅 1 个常量（Angelica）

Mixin

• Mixins — 3 组：ENGINE / VANILLA_RENDERING / ENTITY_RENDERING
• Supernova Late Mixins — 指向 mixins.supernova.late.json
• LateMixins — 空枚举，实际注册 0 个

光照引擎

• Supernova Engine — 抽象基类，13 个抽象方法
• Supernova RGB Engine — 中间抽象层
• Scalar Engine — 单通道，直接继承基类
• Scalar Engines — ScalarBlockEngine + ScalarSkyEngine 两个可执行实现
• RGB Engines — SupernovaBlockEngine + SupernovaSkyEngine
• Engine Internals — FaceOcclusion / SafeBlockAccess / 队列位布局
• World Light Manager — Lane 线程调度
• Initial Light Coordinator — Publisher 用接口解耦
• Chunk Tasks — 3 个 IntOpenHashSet/Boolean[]
• SWMRNibbleArray — ARRAY_SIZE = 16³/2
• Chunk Light Helper — RGB ↔ 原版单通道（取各通道最大值）
• Light Registries — rebuildAll() 无条件触发
• Light Stats — AtomicLong 多线程计数
• Light Registry Diagnostics — dumpUnregistered
• Light Queue — 单生产者/单消费者的按区块任务队列
• Dynamic Emission Snapshots — 主线程采样 TE 发光
• Supernova Chunk — Chunk 侧半字节存储与脏标记

注册表与 API

• Light Color Registry — 反射判 getLightValue 覆写
• Translucency Registry — markUncacheable 应对动态方块
• Light Colors — 7 个常量，通道 0–15
• Packed Color Light
• Extended Chunk — mixin 让原版 Chunk 实现的接口
• Extended Section — ExtendedBlockStorage 侧的非平凡光照标志
• Extended World — 公开 API + 内部 SupernovaWorld 句柄
• Block ID Index — 包私有的 id 快速索引
• Colored Light Source — 供他 mod 实现的发光接口
• Colored Translucency — 逐通道透光接口（15 = 全透）
• Face Light Occlusion — 按朝向区分遮光量

兼容

• ModCompat — 24 常量 / 57 modid
• ColorRegistrationHelper — 7 类注册入口
• Angelica Compat — 与渲染补丁互斥
• EndlessIDs Compat — Holder 惰性探测
• EasyColoredLights Dummy Container — modid 占位
• Mod Color Tables — 23 个 *Colors 类的 265 次颜色登记

设置与命令

• Supernova Config — 3 项，lightingMode 默认 RGB
• Supernova Client Config — 1 项，tintBlendMode
• Tint Blend Mode — 6 种，默认 SQUARED_WEIGHT
• Block Color Config — load/reload/dump
• Block Translucency Config — 同构，命令 translucency
• Default Colors — 原版/模组兜底预设
• Command Supernova — /supernova(OP2) 与 /csupernova(OP0)

存储

• Supernova Data Manager — versionChangeMessage 必须返回 null
• Data Managers — 抽象基类 + 方块光/天光两个 ChunkAPI 实例

客户端

• Colored Light Helpers — 顶点与实体着色，readLight 是六通道布局

依赖范围

源码缺陷

1. SupernovaCore 静态块改写并保存用户配置 —— 缺 ChunkAPI 时把 lightingMode 改为 SCALAR 并 ConfigurationManager.save(...) 落盘。用户设的 RGB 被永久改写， 之后装了 ChunkAPI 也不会自动改回。
2. 依赖探测用资源路径而非 modid —— getResource("com/falsepattern/chunk/api/DataRegistry.class") != null 只要 classpath 上有该 jar 就算「存在」，比 Loader.isModLoaded 宽松， 间接依赖也会误判。
3. Angelica 是软依赖但影响 mixin 排除 —— dependencies = "after:angelica@[2.1.61,)" 不阻止旧版 Angelica 加载； 旧版会被 .addExcludedMod(TargetedMod.ANGELICA) 排除， 但 AngelicaCompat 却要求 api/BlockLightProvider.class 存在 —— 两者判据不同步， 可能出现「原版补丁被排除但兼容未启用」的中间态。
4. enableStatsLog 日志无界增长 —— 配置注释自述 the file grows without bound while enabled， 无轮转/截断逻辑。
5. versionChangeMessage 的 ChunkAPI 陷阱 —— 若在版本未变时返回非 null，ChunkAPI 视为不兼容变更， 每次读世界都弹启动询问框。源码已注释警示。
6. 配置字段无 Java 初值 —— lightingMode / scaleEmissionToVanillaLight / enableStatsLog / tintBlendMode 均为 public static 且无字段初值， 真实默认只存在于 @Config.Default* 注解里； 而 Tint Blend Mode 的 current 字段有 Java 初值 SQUARED_WEIGHT —— 两处默认值来源不同， 改任一处需同步另一处。
7. late mixin 为空壳 —— LateMixins 枚举无常量， mixins.supernova.late.json 存在但永不注入； 统计 mixin 数时「框架文件 2 个」与「实际注入 0 个」不可混淆。