彩色照明 钠 兼容

概述

这是 erykczy的Colorful Lighting (MIT) 的一个分支，使其彩色光照能与 Sodium 和 Iris 光影包 协同工作，并从源头修复了上游渲染和光传播的一系列缺陷。一个 jar 文件即可替代原来的 colorful_lighting jar 和单独的 colorful_lighting_sodium_compat jar。

功能特性

• 方块可发出可配置的彩色光；染色玻璃会过滤穿过它的光
• 颜色由数据驱动：资源包（或其他模组）通过 JSON 定义发光体和滤光片
• 仅客户端模组——可加入任何服务器，随时移除模组而无需改动世界
• Sodium 地形支持：彩色光通过 Sodium 的紧凑区块顶点格式传递
• Iris 光影包支持：兼容的光影包（如 Complementary）会将彩色方块光注入其自身光照系统，包括实体、方块实体、粒子和手持物品的光照；其他光影包会被自动清理，确保不会渲染成黑色或全亮
• 可与 ScalableLux/Starlight 等光照引擎替代模组协同工作（方块更新从客户端级别获取，而非原版光照引擎内部）

版本与兼容性

	版本	备注
Minecraft	1.21.1	NeoForge 21.1.x（已在 21.1.241 上测试）
Sodium	0.8.13-beta.1	可选。 接受版本范围 [0.8.13-beta.1, 0.8.14)
Iris	1.8.14-beta.1	可选，需要 Sodium。接受版本范围 [1.8.14-beta.1, 1.8.15)
ScalableLux	0.3.0-alpha.0.6（已测试）	可选。 有无皆可正常工作
Sodium Extra	0.9.3（已测试）	可选

Sodium 和 Iris 在运行时被检测：未安装时，模组使用原版核心着色器路径（与上游相同）；仅安装 Sodium 时，地形使用紧凑顶点路径；同时安装 Sodium 和 Iris 时，光影包集成功能也会激活。安装这些模组时，其版本必须符合上述范围——模组会修补渲染器内部，并且会故意拒绝未经测试的渲染器版本，而不是在游戏中崩溃。

关于 NeoForge 1.21.1 完整技术栈的说明：Sodium 0.8.13 + Iris 1.8.14 还需要小型社区补丁模组 "Iris Sodium 0.8 Compat Patch"（irissodiumcompat）来实现它们之间的互操作。光影包彩色光照已在 Complementary Shaders — Unbound r5.8.1 上测试（Reimagined 使用相同的光照核心）；没有识别到相应挂钩的光影包会回退为正确但无彩色的光照。

添加新的彩色光源

颜色就是普通的资源包数据——无需编写代码。在资源包（或模组资源）的任何命名空间中，在 textures/models 旁创建 light 文件夹：

assets/<命名空间>/light/emitters.json —— 定义方块发出的光颜色：

{
	"minecraft:torch": "#00FF00",
	"minecraft:red_candle": "red",
	"minecraft:redstone_lamp": [ 0, 255, 255 ],
	"minecraft:soul_torch": "purple;5",
	"minecraft:oak_leaves": "light_blue;F"
}

• 颜色值："#RRGGBB" 十六进制、染料名称（"red"、"light_blue" 等），或 [r, g, b] 数组。
• 数组：整数使用 0–255 范围，浮点数使用 0.0–1.0 范围 —— [255, 0, 0] 和 [1.0, 0.0, 0.0] 都是纯红色，但 [1, 0, 0] 是黑色。
• 可选的 ;X 后缀（十六进制数字 0–F）可覆盖发出的光等级；不添加时使用方块的原版发光等级。这能让原本不发光的方块（如上例中的树叶）发出光。
• 会发光但没有对应条目配置的方块会发出白光。

方块状态特定的颜色 (此分支新增) —— 键可以使用命令语法携带方块状态属性，这样 ID 不变的方块（例如通过右键重新染色的灯）可以按状态获得不同的光颜色：

{
	"minecraft:trial_spawner[ominous=true]": "#90fbff",
	"yourmod:oil_lamp[color=red]": "red",
	"yourmod:oil_lamp[color=lime]": "#80FF00",
	"yourmod:oil_lamp[lit=false]": "black;0"
}

• 只需匹配列出的属性；未列出的属性为通配符。最具体的匹配条目生效，纯 modid:block 条目作为该方块的默认回退。
• 属性和值会在加载时针对方块进行验证——拼写错误会被记录并跳过。
• 状态变化就是普通的方块更新，因此重新给灯染色会立即重新传播其光。

assets/<命名空间>/light/filters.json —— 定义穿过方块的光颜色（颜色语法相同）：

{
	"minecraft:red_stained_glass": "#FF0000",
	"minecraft:green_stained_glass": "red",
	"minecraft:glass": [ 0, 255, 255 ]
}

来自所有已加载资源包和模组的条目会被合并（高优先级资源包优先），使用 F3 + T 可重载并重新照亮世界——方便调试颜色。模组可以在自己的资源中提供相同文件来注册其方块；参见 erykczy 的 colorful-glowstone 示例模组。

实体光源

(此分支新增) 实体也可以发出彩色光——即采用动态光照方案（如 LambDynamicLights 所推广的）在彩色引擎上运行：每个客户端 tick，模组会追踪所有可见实体的光，并在其位置、等级或颜色变化时重新传播。纯客户端视觉效果；原版光照值和游戏玩法不受影响。

静态按类型颜色 —— assets/<命名空间>/light/entity_emitters.json，颜色语法与方块发光体相同（缺少 ;X 等级后缀表示满级 15）：

{
	"minecraft:glow_squid": "#61f2d0;7",
	"yourmod:will_o_wisp": "cyan;9"
}

默认配置：发光鱿鱼、烈焰人、岩浆怪和悦灵会以自身颜色发光，任何燃烧中的实体都会发出火焰色的光。

有状态光源（Java API） —— 当光取决于实体状态时，可注册一个提供者；它会在每个客户端 tick 被调用，因此返回不同的值只需移动/重新着色光即可：

import me.erykczy.colorfullighting.api.*;

EntityLightSources.register(MyEntities.LANTERN_SPIRIT.get(), entity -> {
    LanternSpirit spirit = (LanternSpirit) entity;
    if (!spirit.isLit()) return null;                            // 无光
    return EntityLight.fromDye(spirit.getDyeColor(), 11);        // 染料名称...
    // 或：EntityLight.fromHex("#80FF00", 11) / EntityLight.fromRGB8(128, 255, 0, 11)
});

注册的提供者会替换该类型的 JSON 条目。提供者在客户端线程上运行，应是对同步实体数据的低成本只读查询。