可配置颜色的自发光球体火炬，无火焰效果，并设有最近光源性能预算。部署前请查看验证说明。

光球灯 1.0.0

球炬是一个独立的锤子部件：一个木制立式火炬，带有一个光滑的白色自发光球体和一盏预算点光源。原版火炬保持不变。无需自定义资源包。

验证状态： 看 校验.md 针对已完成的测试和剩余检查。不要因为构建成功就推断多人游戏或视觉验证也已通过。

安装

在你的英灵神殿模组管理器配置文件中安装这些依赖项，然后导入 宝珠之光-1.0.0.zip 作为本地模组：

• BepInExPack Valheim 5.4.2351
• 尤顿 2.30.2

手动安装时，请先安装这些依赖项，然后复制压缩包中的 BepInEx/plugins/OrbLights 将目录放到游戏目录中的对应位置。不要把整个ZIP放进去 插件. 启动一次模改游戏以生成 BepInEx/配置/org.orblights.valheim.cfg.

ZIP 压缩包根目录下包含清单文件、README 和 256×256 的 PNG 图标，可直接提交至 Thunderstore。请自行选择上传者或团队账号；其中未嵌入任何账号或虚构的仓库地址。依赖项已声明，并未打包捆绑。

建造并使用

查找 宝珠火炬 在锤子的家具/照明选择中。默认花费： 2 木材，1 树脂，1 焰灵之核。使用普通锤子的操作来建造、修理和拆除。克隆的Piece、WearNTear、碰撞体、吸附点和ZNetView保留正常的放置、结构损伤和资源返还行为。正常的建造结界生效。法球火把不会造成火焰伤害、热量、烟雾或声音。

此版本有意使用全局设置。它具有 每支火把无 Shift/Alt 颜色或亮度控制，并且不存储每个火把的颜色覆盖。全局选项包括暖白、中性白、冷白、红、橙、黄、绿、青、蓝、紫、粉和自定义。自定义读取RGB值。保留标准部件持久化和可选的原版燃料ZDO存储。

配置

生成的CFG包含描述和可接受范围。参考副本包含在 示例它不会自动安装，也不允许覆盖现有配置。

区域	选项
1. 通用	启用灯光，棋子类别
2. 配方	木材，树脂，焰灵之核，制作站需求
3. 光源颜色	颜色预设，红，绿，蓝
4. 光源外观	强度，光照半径，光球大小，光球发光强度，光球颜色与光照匹配，启用闪烁，闪烁幅度，闪烁速度
5. 性能	性能预设，仅发光模式，启用阴影，最大渲染距离，最大活动光源数量
6. 燃料	需要燃料，燃料消耗率，雨中熄灭
7. 多人模式	锁定配置
8. 调试	启用调试日志记录

默认暖光RGB 255,225,185，强度 1.2，宝珠直径 0.22米，白色球体材质，发光强度 2无闪烁、无阴影、无需燃料、也不会被雨淋灭。RGB 接受 0–255；强度 0–4；半径 1–25 米；光球直径 0.05–0.6 米；自发光 0–5；距离 5–100 米；最大光源数 0–128。非有限浮点数会回退到安全默认值。配方数量接受 0–100；为零则省略该材料。成本全为零时，该部件免费。

在游戏运行时编辑CFG：每两秒检测一次更改，并在下一个半秒调度时应用。现有球体会更新。燃料/降雨状态每两秒采样一次。更改建造类别、配方或工作站最好在开始会话前进行，然后重启所有对等端，以使建造菜单缓存和需求保持一致。光照设置无需重建部件。

选择 自定义 使用你各自的半径、距离、数量、阴影和闪烁设置。其他预设会覆盖这些字段。RGB、强度、光球大小和发光仍会应用于每个预设。 启用光源=false 或 仅发射模式=true 禁用所有点光源，无论预设如何。

预设	半径	点光源距离	最大灯光数	暗影/闪烁
土豆	—	—	0	关
性能	8分钟	25米	16	关
均衡（默认）	12分钟	40米	32	关
品质	16分钟	60米	64	关
自定义	配置	配置	配置	配置

白色光球外观与光色独立。启用 光球匹配光颜色 对于有色球体而言，泛光效果取决于 Valheim 的渲染器和后处理设置；关闭泛光时，自发光并不保证会产生可见的光晕。降低自发光可以减少过度泛光。

需要燃料=真 消耗树脂，容量为十单位，并使用原版燃料补充机制。新放置的火把初始拥有一单位燃料。 燃料消耗率 每实际小时树脂量（0.05–10）。燃料更新使用所属对等端和原版ZDO字段；禁用燃料模式不会持续写入燃料数据。可选的雨水熄灭会检查头顶遮挡。燃料耗尽或雨水熄灭会隐藏光球，直到它能再次点亮。销毁时燃料不会作为额外配方材料返还。

多人游戏和专用服务器

安装 服务器和每个客户端上的OrbLights版本及两个依赖项均相同· 当双方都启用 Jotunn 时，Jotunn 的必需模组握手会拒绝缺失或不匹配的 OrbLights 客户端。完全未安装模组的主机无法运行此自定义部件。移除模组后，请勿打开包含 Orb Torches 的世界；请先备份世界并拆除这些部件。插件无法保护在其插件系统被移除后打开的世界。

配方、类别和燃料设置是由Jotunn同步的服务器管理员设置。 锁定配置=true 同时同步/锁定画面和性能设置。设为 False 则允许这些画面/性能设置仅在本地生效；请在开始游戏前修改，并重启所有对等端。锁定本身仍由服务器控制。调试日志记录在本地。服务器管理员由 Jotunn 根据 Valheim 的管理员列表识别。非管理员客户端对已锁定条目的更改受 Jotunn 的配置同步机制约束。

在Linux专用服务器上，请按照BepInEx的Linux启动说明进行安装，然后使用完全相同的OrbLights DLL和Jotunn DLL。在没有本地玩家的情况下，调度器不会启用任何点光源。服务器拥有的可选燃料仍会更新。没有针对Epic Loot或其他模组的补丁，且针对Fireplace的补丁会立即对非OrbLights部件回退到原版行为。与任何特定模组包的共存仍需进行集成测试。

性能指引

每盏实时点光源都会带来性能开销。 移除火焰、烟雾和阴影有所帮助，但最大活动光源限制和渲染距离才是超大型基地中最重要的防护措施。先从性能入手；对于最大的基地，使用土豆模式或仅发光模式。增加半径会影响更多像素和几何体。即使数量很低，启用阴影也可能开销很大。

一个共享调度器每秒采样两次邻近范围，并选出离本地玩家最近的光源。没有OrbInstance拥有Update或LateUpdate。可选闪烁仅以每秒十次采样影响激活集。所有光球共享一个缓存材质。点光源剔除不会隐藏自发光几何体；常规游戏区域卸载仍然生效。选择使用可复用列表并对附近候选进行排序；对于无限加载对象而言，这并不能作为基准性能保证。

故障排除

• 无棋子： 检查游戏是否以模组模式启动，两个依赖项是否都已存在，并且 BepInEx/LogOutput.log 包含 已注册 OrbLights_OrbTorch. BepInEx 的硬依赖检查报告缺少 Jotunn。注册失败会记录一个异常；请将依赖项与游戏一起更新。
• 球体可见，无照明： 检查土豆、仅发光模式、启用光照、强度为零、活动光源预算和距离。距离更近的光球优先。尝试用自定义设置一个适中的非零数量。
• 轻微的编辑似乎被忽略了： 选择自定义可单独控制性能表现；请检查服务器锁定状态。CFG更改最多需要2.5秒生效。
• 燃料/雨水： 检查 RequireFuel 和 ExtinguishInRain；用树脂补充或全局禁用燃料。默认忽略这两项。
• 黑色/缺失材质或错误放置的球体： 保留日志并报告你的 Valheim/Jotunn 版本。注册会从原始火把光源推导出法球位置，并使用已加载的游戏着色器及回退处理；新的游戏更新可能会改变这些资源。
• 诊断： EnableDebugLogging 最多每 30 秒打印一次已注册、附近、活跃和预算计数。检查完后请将其关闭。
• 每秒帧数： 先减少数量，再调整半径/距离；禁用阴影/闪烁。可见的自发光球体仍有网格渲染开销。

源代码构建

需要 .NET SDK、已安装的 Valheim 1.0.16 兼容游戏和 PowerShell。运行 ./build.ps1 -ValheimPath 'D:\SteamLibrary\steamapps\common\Valheim'它会将固定的官方构建依赖项下载到 构建/依赖项，编译 Release 版本，并写入 bin/Release/netstandard2.1/OrbLights.dll. 游戏及依赖 DLL 仅为引用，不再分发。 package.ps1 从发布输出创建安装ZIP。MIT许可证涵盖原始代码和图标；Valheim及其依赖项保留各自的许可证。