WispTorchHeeler

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

分级迷雾之地鬼火火炬与除雾灯具，具备扩展的雾气清除范围、交互式火炬染色、随身佩戴的鬼火之光定制，以及多人游戏颜色同步。

[!NOTE] 客户端与服务器兼容性： 本模组可以安全地安装在本地客户端上，并能在专用服务器上稳定运行，零不同步，且支持服务器强制策略。对于多人游戏中的自定义部件，客户端与服务器均需安装本模组。

问题所在

在原版《英灵神殿》中，要清除迷雾之地浓密的雾气，需要在近距离放置数十个小型、脆弱的原版鬼火火炬。这会导致：

严重的视觉杂乱与建造疲劳：广阔的迷雾之地基地、农场和运输路径很快就会变成混乱的枝条丛林。
性能开销：数十个重叠的粒子系统力场、动态点光源和粒子发射器同时运行，会造成明显的帧率下降。
僵化的美学：建造者被锁定在单一的固定青色/白色调色板中，无法根据不同的建造主题、建筑风格或室内氛围进行定制。
脆弱性：原版火炬仅有 100 点生命值，很容易因战斗中的附带伤害、探 Seekers 的攻击或德维格尔的流弹而损坏。

解决方案

WispTorchHeeler 引入了四种分级的、后期迷雾之地照明装置，具有逐渐增大的雾气清除半径，并配有交互式、准星驱动的“火炬染色器”系统，以及通过《英灵神殿》原生零数据对象（ZDO）架构实现的多人游戏颜色同步：

分级雾气清除：四种不同的照明装置，从加固的大型火炬到巨大的矮人纪念碑，可清除高达 3.75 倍 的雾气半径（约 14 倍覆盖面积），大幅减少部件密度和视觉杂乱。
交互式火炬染色器：瞄准任何已放置的火炬或灯具，按 P 键即可立即用你选择的颜色为其灯光和粒子效果染色，或按 LeftShift + P 重置。
放置时自动染色：新放置的火炬和灯具可以在建造的瞬间自动继承你当前激活的染色器颜色。
随身佩戴的鬼火之光定制：为你装备的鬼火之光配件（漂浮的 demister_ball 跟随光球）提供完整的外观定制，包括自定义颜色、光照与自发光强度倍率、透明度，以及多人游戏颜色同步。
多人游戏与服务器同步：在创建时直接写入每个部件的 ZDO，零不同步。未染色的部件可以继承客户端选择的默认值或服务器强制的颜色主题，并支持结界保护权限和管理员覆盖。
零资源包：使用 Jötunn 在运行时从原生《英灵神殿》预制件干净地克隆，确保即时加载和轻量安装。

功能特性

分级照明装置

1 级 — 大型鬼火火炬（piece_wisptorch_heeler_lg）：
- 从原版木制鬼火火炬克隆，物理缩放 1.25 倍。
- 雾气清除：1.50 倍 半径（相对于 24.0m 基准：36.0m 半径，约 2.25 倍覆盖面积）。
- 光照：1.33 倍 强度与 1.25 倍 范围（12.5m 光照半径）。
- PlayerBase：20.0m 基础生成抑制（随 PlayerBaseMistRadiusBonus 缩放）。
- 耐久度：200 点生命值，免疫天气侵蚀。
- 制作：使用建筑锤自由放置（Wisp:8,YggdrasilWood:5,Sap:1）。
2 级 — 小型灯具（piece_wisplamp_heeler）：
- 游戏内名称：Dvergr Wisp Lamp
- 采用原生德维格尔除雾道具的自然 1.0 倍 缩放。
- 雾气清除：2.25 倍 半径（相对于 24.0m 基准：54.0m 半径，约 5.0 倍覆盖面积）。
- 光照：1.50 倍 强度与 1.50 倍 范围（15.0m 光照半径）。
- PlayerBase：20.0m 基础生成抑制（随 PlayerBaseMistRadiusBonus 缩放）。
- 耐久度：250 点生命值，免疫天气侵蚀。
- 制作：需要 锻造炉（Wisp:15,Copper:5,Iron:2,BlackMarble:2,Sap:2）。
3 级 — 大型灯具（piece_wisplamp_heeler_lg）：
- 游戏内名称：Large Dvergr Wisp Lamp
- 从大型德维格尔除雾模型克隆，并放大 1.1 倍。
- 雾气清除：3.00 倍 半径（相对于 24.0m 基准：72.0m 半径，9.0 倍覆盖面积）。
- 光照：2.25 倍 强度与 1.75 倍 范围（17.5m 光照半径）。
- PlayerBase：20.0m 基础生成抑制（随 PlayerBaseMistRadiusBonus 缩放）。
- 耐久度：500 点生命值，免疫天气侵蚀。
- 制作：需要 黑锻造炉（Wisp:22,Copper:8,Iron:3,Eitr:2,BlackMarble:5）。
4 级 — 宏伟灯具（piece_wisplamp_heeler_grand）：
- 游戏内名称：Grand Dvergr Wisp Lamp
- 从大型德维格尔除雾模型克隆，并放大 1.5 倍。
- 雾气清除：3.75 倍 半径（相对于 24.0m 基准：90.0m 半径，约 14.0 倍覆盖面积）。
- 光照：调校为 2.50 倍 强度与 2.00 倍 范围（20.0m 光照半径）。
- PlayerBase：20.0m 基础生成抑制（随 PlayerBaseMistRadiusBonus 缩放）。
- 耐久度：巨大的 750 点生命值，免疫天气侵蚀。
- 制作：需要 黑锻造炉（Wisp:30,Copper:10,Iron:4,Eitr:4,BlackMarble:10）。

交互式“火炬染色器”系统

选择颜色：使用游戏内配置管理器 UI（F1）的颜色选择器或配置文件，选择你想要的画笔颜色（PainterColor）。
放置时自动染色：在配置中启用 AutoPaintOnPlacement，即可在用锤子放置新火炬和灯具时，自动使用你当前激活的颜色为其染色。
在世界中染色：将准星瞄准触及范围内的任何鬼火火炬或灯具，按 P 键（可通过 PaintTorchHotkey 配置）。在范围内时会显示屏幕提示。
重置部件：瞄准已染色的部件，按 LeftShift + P 键（可通过 ResetTorchHotkey 配置）恢复默认颜色。
结界保护与安全：未经许可的玩家无法对激活结界内的部件染色，除非服务器策略允许（AllowPaintingInProtectedWards）或具有管理员身份（AdminBypassesWardCheck）。
多人游戏同步：染色后的颜色通过 ZDO 和持久化世界存储在所有客户端之间同步，无需外部资源包。
可视化雾气边界：在调试配置中启用 ShowMistSuppressionRadius，即可投射一个实时地面环，显示所有鬼火部件的有效雾气抑制半径。

随身佩戴的鬼火之光定制

针对玩家装备的 鬼火之光 功能配件（即飞行跟随光球，内部及配置中称为 Demister / demister_ball）的外观定制：

自定义颜色：通过配置管理器（F1）或配置文件中的 DemisterColor 选择你的鬼火之光颜色。
点光源与自发光倍率：独立缩放鬼火之光的点光源强度（DemisterLightIntensityMultiplier，0.1 倍至 5.0 倍）和核心着色器自发光亮度（DemisterEmissionIntensityMultiplier，0.1 倍至 5.0 倍）。
透明度：通过 DemisterEnableAlpha 为你的鬼火之光启用可选透明度。透明度下限被限制为 15%，以防止完全隐形。
空闲悬浮速度与半径倍率：平息并平滑鬼火之光的空闲动画（DemisterIdleSpeedMultiplier，0.0 至 2.0）和游荡半径（DemisterIdleRadiusMultiplier，0.0 至 2.0），以消除围绕头部的快速蝇虫式嗡鸣和抖动。
多人游戏颜色同步：启用后（DemisterSyncMultiplayer），你的鬼火之光颜色会被写入跟随光球的 ZDO（wisptorch_demister_color），并对其他运行本模组的玩家可见。
强度倍率为客户端本地：你的光照和自发光强度设置严格保持在本地——其他玩家的鬼火之光在你的屏幕上始终以默认校准亮度渲染。
严格为外观性质：不会改变雾气抑制半径、清除力场或鬼火之光装备属性。

配置

可以直接在游戏内使用 BepInEx 配置管理器（F1）自定义设置，或编辑 BepInEx/config/dreamwraith.WispTorchHeeler.cfg：

分区 | 键 | 类型 | 默认值 | 描述

1 - General | EnableMod (Requires Restart) | bool | true | 启用或禁用本模组功能的总开关。（需要重启）

1 - General | AffectNativeMistTorches | bool | true | 允许对标准原生鬼火火炬进行染色和颜色默认设置。

1 - General | PlayerBaseMistRadiusBonus | float | 0.0 | 附加加成百分比（0.0 至 1.0），将 PlayerBase 生成抑制从 20.0m 基准向有效雾气清除半径缩放。为 0.0 时，所有自定义部件使用 20.0m 基准。为 1.0 时，抑制半径与有效雾气揭示边界匹配。

2 - Large Torch | Torch_MistClearRangeMultiplier | float | 1.5 | 大型火炬雾气清除半径倍率（相对于 24.0m 基准，范围：1.0 - 10.0）。

2 - Large Torch | Torch_LightIntensityMultiplier | float | 1.33 | 大型火炬光发射强度倍率（相对于 1.0 基准，范围：0.5 - 5.0）。

2 - Large Torch | Torch_LightRangeMultiplier | float | 1.25 | 大型火炬光发射范围半径倍率（相对于 10.0m 基准，范围：0.5 - 5.0）。

2 - Large Torch | Torch_Health | float | 200.0 | 大型火炬结构生命值（1.0 - 5000.0）。

2 - Large Torch | Torch_CraftingStation | string | "" | 所需工作站，格式为 StationPrefab（例如 piece_workbench、piece_forge，或 "" 表示使用锤子自由放置）。

2 - Large Torch | Torch_Recipe | string | Wisp:8,YggdrasilWood:5,Sap:1 | 制作配方字符串，格式为 ItemPrefab:Amount,...，根据 ObjectDB 解析。

3 - Small Lamp | SmallLamp_MistClearRangeMultiplier | float | 2.25 | 2 级小型灯具雾气清除半径倍率（相对于 24.0m 基准，范围：1.0 - 10.0）。

3 - Small Lamp | SmallLamp_LightIntensityMultiplier | float | 1.5 | 2 级小型灯具光发射强度倍率（相对于 1.0 基准，范围：0.5 - 5.0）。

3 - Small Lamp | SmallLamp_LightRangeMultiplier | float | 1.5 | 2 级小型灯具光发射范围半径倍率（相对于 10.0m 基准，范围：0.5 - 5.0）。

3 - Small Lamp | SmallLamp_Health | float | 250.0 | 2 级小型灯具结构生命值（1.0 - 5000.0）。

3 - Small Lamp | SmallLamp_CraftingStation | string | forge | 所需工作站，格式为 StationPrefab 或 Jotunn 名称（默认为 'forge'）。

3 - Small Lamp | SmallLamp_Recipe | string | Wisp:15,Copper:5,Iron:2,BlackMarble:2,Sap:2 | 制作配方字符串，格式为 ItemPrefab:Amount,...，根据 ObjectDB 解析。

4 - Large Lamp | LargeLamp_MistClearRangeMultiplier | float | 3.0 | 3 级灯具雾气清除半径倍率（相对于 24.0m 基准，范围：1.0 - 15.0）。

4 - Large Lamp | LargeLamp_LightIntensityMultiplier | float | 2.25 | 3 级灯具光发射强度倍率（相对于 1.0 基准，范围：0.5 - 8.0）。

4 - Large Lamp | LargeLamp_LightRangeMultiplier | float | 1.75 | 3 级灯具光发射范围半径倍率（相对于 10.0m 基准，范围：0.5 - 5.0）。

4 - Large Lamp | LargeLamp_Health | float | 500.0 | 3 级灯具结构生命值（1.0 - 5000.0）。

4 - Large Lamp | LargeLamp_CraftingStation | string | blackforge | 所需工作站，格式为 StationPrefab 或 Jotunn 名称（默认为 'blackforge'）。

4 - Large Lamp | LargeLamp_Recipe | string | Wisp:22,Copper:8,Iron:3,Eitr:2,BlackMarble:5 | 制作配方字符串，格式为 ItemPrefab:Amount,...，根据 ObjectDB 解析。

5 - Grand Lamp | GrandLamp_MistClearRangeMultiplier | float | 3.75 | 4 级宏伟灯具雾气清除半径倍率（相对于 24.0m 基准，范围：1.0 - 15.0）。

5 - Grand Lamp | GrandLamp_LightIntensityMultiplier | float | 2.5 | 4 级宏伟灯具光发射强度倍率（相对于 1.0 基准，范围：0.5 - 8.0）。

5 - Grand Lamp | GrandLamp_LightRangeMultiplier | float | 2.0 | 4 级宏伟灯具光发射范围半径倍率（相对于 10.0m 基准，范围：0.5 - 8.0）。

5 - Grand Lamp | GrandLamp_Health | float | 750.0 | 4 级宏伟灯具结构生命值（1.0 - 5000.0）。

5 - Grand Lamp | GrandLamp_CraftingStation | string | blackforge | 所需工作站，格式为 StationPrefab 或 Jotunn 名称（默认为 'blackforge'）。

5 - Grand Lamp | GrandLamp_Recipe | string | Wisp:30,Copper:10,Iron:4,Eitr:4,BlackMarble:10 | 制作配方字符串，格式为 ItemPrefab:Amount,...，根据 ObjectDB 解析。

6 - Lighting Policy | EnforceServerDefaultColor | bool | false | 如果为 true，所有客户端必须以服务器默认颜色渲染未染色的部件。

6 - Lighting Policy | ServerDefaultLightColor | Color | #B4F0FF | 在被强制时，未染色部件的服务器级默认颜色。

6 - Lighting Policy | AllowTorchPainting | bool | true | 服务器总开关，允许玩家对单个部件进行染色。

6 - Lighting Policy | AllowPaintingInProtectedWards | bool | false | 如果为 false，玩家无法对其无权访问的结界内部件染色。

6 - Lighting Policy | AdminBypassesWardCheck | bool | true | 如果为 true，经验证的服务器管理员在染色时绕过结界限制。

6 - Lighting Policy | EnableAlphaCustomization | bool | false | 允许使用颜色选择器中的透明度滑块自定义光照和粒子透明度（下限限制为 15%）。

7 - Client Lighting | DefaultLightColor | Color | #B4F0FF | 客户端对未染色部件的个人默认颜色（当服务器未强制时生效）。

8 - Torch Painter | PainterColor | Color | #FF8800 | 玩家通过 UI 颜色选择器抽屉选择的活动染色颜色。

8 - Torch Painter | PaintTorchHotkey | KeyboardShortcut | KeyCode.P | 瞄准火炬/灯具时按下以应用 PainterColor 的热键。

8 - Torch Painter | ResetTorchHotkey | KeyboardShortcut | KeyCode.P + LeftShift | 瞄准火炬/灯具时按下以清除自定义颜色的热键。

8 - Torch Painter | PainterRaycastDistance | float | 10.0 | 瞄准并染色部件的最大距离（米）（2.0 - 25.0）。

8 - Torch Painter | ShowPainterFeedback | bool | true | 在染色/重置时显示屏幕 HUD 文本确认。

8 - Torch Painter | AutoPaintOnPlacement | bool | false | 如果为 true，新放置的火炬和灯具在放置时会自动使用你当前激活的 PainterColor 染色。

9 - Worn Demister | EnableDemisterCustomization | bool | true | 为你装备的鬼火之光配件启用颜色、光照和自发光属性的外观定制。

9 - Worn Demister | DemisterSyncMultiplayer | bool | true | 将你的鬼火之光颜色广播到跟随光球 ZDO，使其他安装本模组的玩家看到你的自定义颜色。

9 - Worn Demister | DemisterColor | Color | #B4F0FF | 你的鬼火之光、粒子和自发光光晕的活动外观颜色。

9 - Worn Demister | DemisterLightIntensityMultiplier | float | 1.0 | 缩放鬼火之光发出的点光源亮度的倍率（0.1 - 5.0）。

9 - Worn Demister | DemisterEmissionIntensityMultiplier | float | 1.0 | 缩放鬼火之光核心球体和光晕的着色器自发光亮度的倍率（0.1 - 5.0）。

9 - Worn Demister | DemisterEnableAlpha | bool | false | 允许 DemisterColor 的透明度通道自定义鬼火之光粒子和材质透明度（安全限制为 15% 下限以防止隐形）。

9 - Worn Demister | DemisterIdleSpeedMultiplier | float | 1.0 | 缩放你装备的鬼火之光跟随光球的空闲浮动和振翅速度的倍率（0.0 - 2.0；0.3 为平静，1.0 为《英灵神殿》原生速度，0.0 冻结空闲运动）。

9 - Worn Demister | DemisterIdleRadiusMultiplier | float | 1.0 | 缩放你装备的鬼火之光跟随光球在你头部周围的悬浮和抖动距离的倍率（0.0 - 2.0；1.0 为《英灵神殿》原生距离）。

10 - Debug | EnableDebugLogs | bool | false | 在 BepInEx 控制台中启用详细诊断日志。

10 - Debug | ShowMistSuppressionRadius | bool | false | 在鬼火火炬和灯具周围投射地面边界环，显示其有效雾气抑制半径。

兼容性

专用服务器：完全兼容专用服务器和单人世界。服务器同步的平衡和政策设置通过 ConditionalConfigSync 在连接客户端上强制执行。
原生鬼火火炬：当启用 AffectNativeMistTorches 时，可与原生迷雾之地鬼火火炬（piece_wisptorch）配合使用。
结界保护：与原生《英灵神殿》结界（PrivateArea）集成，防止在受保护领地内未经授权的染色。
零资源包：不需要外部 Unity 资源或包文件，消除包不同步和内存膨胀。
模组管理器：完全兼容 Gale、Thunderstore Mod Manager 和 r2modman。

安装

[!TIP] 推荐使用模组管理器： 使用现代模组管理器如 Gale 或 Thunderstore 可使安装和自动依赖更新变得轻松。

模组管理器（推荐）

通过 Gale、Thunderstore Mod Manager 或 r2modman 安装。
启动《英灵神殿》即可享受！

手动安装

确保已安装 BepInExPack Valheim 和 Jötunn（《英灵神殿》模组库）。
下载并解压最新发布存档。
将 WispTorchHeeler.dll 放入你的 Valheim/BepInEx/plugins/ 目录。
启动《英灵神殿》。

从源码构建

本项目使用可移植的 MSBuild 配置，可自动检测标准 Steam 路径。

dotnet build -c Release

编译后的程序集将放置于 bin/Release/net48/WispTorchHeeler.dll。以 Release 配置构建还会自动将分发包打包至 bin/Publish/WispTorchHeeler-<Version>.zip。

自定义与 CI 路径

对于非标准 Steam 库位置或模组管理器配置文件，将 WispTorchHeeler.csproj.user.example 复制到项目根目录下的 WispTorchHeeler.csproj.user（此文件已被 git 忽略，并由 MSBuild 自动加载）：

<?xml version="1.0" encoding="utf-8"?>
<Project>
  <PropertyGroup>
    <GamePath>D:\SteamLibrary\steamapps\common\Valheim</GamePath>
    <BepInExCorePath>$(UserProfile)\AppData\Roaming\com.kesomannen.gale\valheim\profiles\<ProfileName>\BepInEx\core</BepInExCorePath>
  </PropertyGroup>
</Project>

打包、发布与版本发布

所有用于发布管理、打包以及发布到 Thunderstore、Hexium 和 Nexus Mods 的开发者自动化工具，均已整合到单一的 PowerShell 7 入口点 [url=.scripts/modtools.ps1].scripts/modtools.ps1[/url]，由共享的 [url=https://github.com/DreamWraith/DW-ValheimModTools][b]DW.ValheimModTools[/b][/url] 模块提供支持：

发布管理：pwsh ./.scripts/modtools.ps1 release 以 Release 配置编译，创建模组和源码存档，提取变更日志说明，并使用 gh CLI 发布 GitHub Releases（默认草稿，或使用 -Publish 发布）。
打包与版本递增：pwsh ./.scripts/modtools.ps1 package -Bump Patch 在 WispTorchHeeler.csproj 中递增 SemVer，更新 manifest.json，并打包分发存档。
门户发布：pwsh ./.scripts/modtools.ps1 publish -Target All 直接上传到 Thunderstore、Hexium 和 Nexus Mods API。
CI/CD 工作流：[url=.github/workflows/publish.yml].github/workflows/publish.yml[/url] 提供自动化的 GitHub Actions 工作流，在发布 GitHub Release 时自动发布到 Thunderstore、Hexium 和 Nexus Mods。

有关标志、工作流和密钥配置的详细文档，请参见 [url=.scripts/README.md].scripts/README.md[/url]。

许可证与作者说明

本项目根据 GNU 通用公共许可证 v3.0 授权 - 详情请参见 [url=LICENSE.md]LICENSE.md[/url] 文件。
[url=https://gist.github.com/dreamwraith/98564f8441dc234bfadd7e2b605c694c][b]关于我针对《英灵神殿》模组制作的一点说明[/b][/url] - 关于开源模组制作、社区包容性和反把关的思考。
[url=https://gist.github.com/dreamwraith/77c91d656c842611bf8c40febf8056f2][b]关于 AI、软件工艺以及本代码为何存在的说明[/b][/url] - 关于软件工艺、人类能动性和工程责任的个人随笔。