TacLight

English | 中文

给 Minecraft 加"真正会投射锥形光照的灯"。

TacLight 让手电筒和枪挂灯投射真实的锥形光：有明确的光锥边界、有距离衰减、在雾和尘埃里能看到光柱，被墙挡住的地方不漏光。灯本身是游戏里的物品，拿在手上和装在枪上都会跟着动。

配合 Iris/Oculus 光影包使用时，光直接进入光影包的照明和体积光管线，所以观感跟光影包自己的光照是一致的，不会被原版光照模型拖低。

当前版本 0.11.6（预览版）。核心功能可用，观感仍在打磨。

特性

• 手持手电筒：真实锥形光，可调内外锥角、照距、亮度、衰减。
• 枪挂照明附件：装到 TaCZ 枪械上，光从枪口出，跟随枪的朝向和第三人称姿态。
• 体积光：雾、尘埃、水下能看到光柱（丁达尔效应）。
• 遮挡阴影：墙后不漏光，遮挡由体素栅格判定，取向偏保守（宁可多挡，不肯漏光）。
• 多人游戏：别人能看到你的灯，开关状态随实体同步，远程灯的姿态由对端客户端重建，不新增网络包。
• 光影包兼容：运行时把灯注入到你已经装好的光影包里，模组不重新分发任何改版光影包。

测试环境

下面这套版本组合是本版发布前实测通过的。它不是硬性限制，其他版本大概率也能用，只是没有实测过；如果你遇到问题，请先回到这个组合再判断是不是模组的问题。

组件	版本	放哪	作用
Minecraft Forge	1.20.1-47.1.3	启动器	运行平台，客户端与服务端
TacLight	0.11.6	mods/	本模组
Oculus	1.8.0	mods/	光影管线，锥形光依赖它
Embeddium	0.3.31	mods/	提升帧率
光影包 Complementary Reimagined	r5.9	shaderpacks/	锥形光生效的前提，主线适配
光影包 iterationT	3.2.0	shaderpacks/	另一套已适配模板，与 Complementary 二选一
Timeless and Classics Zero (TaCZ)	1.1.8-hotfix	mods/	枪挂灯联动
Player Animator	1.0.2-rc1+1.20	mods/	TaCZ 的第三人称动画需要它

几点要说清楚的：

• 模组本体只要求 Forge 1.20.1，其他 Forge 版本没有实测。
• 锥形光必须有光影包。 本模组不自带包；只装模组的话，物品和开关都正常，但看不到锥形光和光柱。
• 光影包不用打补丁，也不要改。 模组在运行时把自研 GLSL 注入到你那份原版包里，不附带也不分发任何第三方光影包的副本。
• 注入按包内容匹配（关键文件哈希 + 锚点逐字），文件名带什么后缀都不影响。已适配的只有 Complementary Reimagined r5.9 与 iterationT 3.2.0 两套；换成改动过源码的改版包或未适配的新版本仍可能匹配不上，此时聊天栏会提示不在支持列表。

安装

1. 装 Forge 1.20.1。
2. 把 taclight-0.11.6.jar 放进 .minecraft/mods/。
3. 客户端再放 Oculus（建议顺手放 Embeddium）。
4. 把 Complementary Reimagined 解压或直接放 zip 到 .minecraft/shaderpacks/（模组不自带光影包，这一步不能省）。
5. 进游戏，视频设置 → 光影 里选中 Complementary Reimagined。

获得物品

• 手电筒：原版工作台合成 —— 2 个铁锭（上、下中）、1 个铜锭 + 1 块玻璃 + 1 份红石（中间一行）。
• 枪挂照明附件：在 TaCZ 的枪械工作台里合成 —— 8 个铁锭 + 3 份红石，与 TaCZ 自带激光配件同一套配方形态（没装 TaCZ 时这条自然不存在，手电筒仍照常可做）。

两样都默认是关的，拿到手按一下才亮。

使用

按键（可在 选项 → 控制 → TacLight 里改）：

按键	作用
J	手电筒开关
M	枪灯开关

• 两种灯默认都是关的。 新做出来的手电筒、新装上的枪灯都不会自己亮，按一下才亮。
• 手电筒的开关状态存在这支手电筒自己的物品数据里。切到别的物品再切回来，状态还在。
• 枪灯是逐把枪独立的，每把枪有自己的开关状态。
• 光效参数在 config/taclight-client.toml：半径、强度、内外锥角、光束密度、枪灯倍率、手持光照值。
• 想边看边调，直接在聊天栏敲 /taclight tune（= help）：先给你一条能直接用的示例， 然后 /taclight tune list 看有哪些可调，/taclight tune cone help 看某一项的含义与范围。 调参形如 /taclight tune cone 12、/taclight tune atten 8：即时生效并写回上面那个 toml（重启保留）。 调参只对单人/主机的本机生效；专用服务器上命令只回显不生效（改的是本机文件）。
• 每项都会列出当前值、范围、默认值，并说明调大/调小分别会怎样；想还原某一项就 /taclight tune cone clear（清除覆盖、回默认值）。
• /taclight tune held <0..15> 单独管玩家周围那圈暖氛围底光（Iris 的 heldBlockLightValue， 即光影包里的 "Dynamic Handheld Lighting" 选项；Complementary 默认开着）。它和锥形主光是两条通道： held 0 只是关掉氛围底光，锥形光仍在。默认 10。
• 多人游戏里，你开关灯，同服务器的其他人能看到；远程玩家的灯姿态由你自己的客户端重建，不需要额外同步。

已知限制

如实列出，避免你按预期之外的效果去判断它坏了：

1. 复杂形状方块的遮挡是保守的。 栅栏、楼梯、雪层、半砖这类非满方块的遮挡用体素栅格判定，遇到"灯线擦着横杆底边过去"这种几何关系，会宁可判成被挡住。结果是可能偏暗，做不到像素级形状精度。这是当前技术路线的上限，不是调参能消除的。
2. 只在 Oculus/Iris 加光影包时才有锥形光。 没有光影管线时模组本体照常工作，但没有光锥和光柱。
3. 光影注入按包内容匹配。 文件名（含 (1) 这类重复下载后缀）不影响；但换成改过源码的改版包或未适配的新版本，注入可能不生效，聊天栏会提示。
4. 参数是手动调参，没有按场景自动适配。
5. 仓库里带着内部调试面与验证台：src/main/java/dev/taclight/debug 与 devonly 是开发期工具，打包时会被剔除，不进发布件（/taclight 的调试子命令 kit/cam/scene/light 也在其中；发布件保留调参用的 tune）；src/test 的契约测试需要显式运行（见下）。
6. 预览版定位：核心功能可用，观感仍在打磨。

性能

开发机实测（2026-09，旧测试台，4K，双灯；不是验收数字，随硬件和场景变化）：

• 体积光遮挡查表：最坏视角 38.4 → 65.4 FPS（约 +70%），画面差异 0.16% 像素。
• 体积光时间复用：116.2 → 183.5 FPS，灯侧开销 6.24 → 3.08 ms。

这两项都已随本版发布。详细口径与原始数据见开发者文档。

从源码构建

前置：JDK 17。

./gradlew jar              # 产物 build/libs/taclight-<version>.jar
./gradlew packShaderZip    # 旧自研光影包的打包任务，已不作为产品路径发布（见下）
./gradlew build            # 全量构建
./gradlew taclightContracts # 跑契约测试（注意：没有接进 build，必须显式运行）

TaCZ 与 Oculus 的 jar 需要你自己下载后放进 libs/（本项目不重分发，理由见 THIRD_PARTY.md）。缺件时构建会在 checkLocalDeps 阶段明确报出缺哪个文件，而不是丢一个编译错误。

许可与致谢

• 本模组与自带光影包源码：GPL-3.0-or-later（LICENSE，全文 LICENSE-GPL-3.0.txt）。
• 不重分发任何第三方 jar，依赖的许可与再分发口径见 THIRD_PARTY.md。
• 不重分发任何改版光影包。光影包的注入由用户的本地环境在运行时完成。
• 上游思想借鉴（均未逐字复制代码）与 Minecraft/Forge 的链接使用，见 THIRD_PARTY.md。

目录

src/main/java/dev/taclight/   模组源码（debug/ 与 devonly/ 是开发期工具，打包时剔除）
src/main/resources/           资源：mixin 配置、枪灯枪包、光影补丁模板与内联 GLSL
src/test/                     契约测试（显式运行 taclightContracts）
pack/shaders/                 自研光影包源码。模组已不再自带或安装它，只保留其中的
                              lib/taclight_core.glsl 与 taclight_math.glsl 作为注入用的 GLSL 源
tools/                        开发期工具：场景、机位、像素比对
docs/开发纪律与路线图.md        面向开发者：分支模型、纪律、状态、路线图
CHANGELOG.md                  变更历史
THIRD_PARTY.md                第三方致谢与许可

文档

• CHANGELOG.md：版本变更历史。
• docs/开发纪律与路线图.md：开发纪律、当前状态、路线图与验证方式。
• THIRD_PARTY.md：第三方依赖、许可与署名。