WispTorchHeeler

Tiered Mistlands wisp torches and demister lamps with expanded mist clearance, interactive torch painting, and multiplayer color synchronization.

[!NOTE] Client & Server Compatibility: This mod is safe to install on local clients and runs cleanly on dedicated servers with zero desyncs and server-enforced policies. For custom pieces in multiplayer, both client and server require the mod.

The Problem

In native Valheim, clearing the thick mist of the Mistlands requires placing dozens of small, fragile native wisp torches in close proximity. This creates:

• Severe Visual Clutter & Construction Fatigue: Expansive Mistlands bases, farms, and transit paths quickly devolve into chaotic thickets of sticks.
• Performance Overhead: Dozens of overlapping particle system force fields, dynamic point lights, and particle emitters ticking simultaneously cause noticeable framerate drops.
• Rigid Aesthetics: Builders are locked into a single fixed cyan/white color palette that cannot be customized to fit different build themes, architectural styles, or interior moods.
• Fragility: Native torches possess only 100 HP, breaking easily from collateral combat damage, seeker attacks, or stray dvergr fire.

The Solution

WispTorchHeeler introduces four tiered, late-game Mistlands lighting installations with progressively larger mist-clearance radii alongside an interactive, crosshair-driven "Torch Painter" system and multiplayer color synchronization via Valheim's native Zero Data Object (ZDO) architecture:

• Tiered Mist Clearance: Four distinct lighting fixtures ranging from reinforced large torches to colossal dwarven monuments, clearing up to 3.75× the fog radius (~14× coverage area) to drastically reduce piece density and visual clutter.
• Interactive Torch Painter: Aim at any placed torch or lamp and press P to instantly paint its light and particle effects with your chosen color, or LeftShift + P to reset it.
• Auto-Paint on Placement: Newly placed torches and lamps can automatically inherit your active painter color the instant you build them.
• Multiplayer & Server-Synchronized: Stamped directly into each piece's ZDO at creation with zero desync. Unpainted pieces can inherit client-chosen defaults or server-enforced color themes, with ward-protection permissions and admin overrides.
• Zero Asset Bundles: Cloned cleanly from native Valheim prefabs at runtime using Jötunn, ensuring instant load times and lightweight installation.

Features

Tiered Lighting Installations

1. Tier 1 — Large Wisp Torch (piece_wisptorch_heeler_lg):

   • Cloned from the native wooden wisp torch and scaled physically by 1.25x.
   • Mist Clearance: 1.50× radius (relative to 24.0m baseline: 36.0m radius, ~2.25× coverage area).
   • Light: 1.33× intensity and 1.25× range (12.5m light radius).
   • PlayerBase: 20.0m base spawn suppression (scales with PlayerBaseMistRadiusBonus).
   • Durability: 200 HP and immune to weather decay.
   • Crafting: Placed freeform with the building hammer (Wisp:8,YggdrasilWood:5,Sap:1).

2. Tier 2 — Small Lamp (piece_wisplamp_heeler):

   • In-game Name: Dvergr Wisp Lamp
   • Adapts the native Dvergr Demister prop at natural 1.0x scale.
   • Mist Clearance: 2.25× radius (relative to 24.0m baseline: 54.0m radius, ~5.0× coverage area).
   • Light: 1.50× intensity and 1.50× range (15.0m light radius).
   • PlayerBase: 20.0m base spawn suppression (scales with PlayerBaseMistRadiusBonus).
   • Durability: 250 HP and immune to weather decay.
   • Crafting: Requires a Forge (Wisp:15,Copper:5,Iron:2,BlackMarble:2,Sap:2).

3. Tier 3 — Large Lamp (piece_wisplamp_heeler_lg):

   • In-game Name: Large Dvergr Wisp Lamp
   • Cloned from the large Dvergr demister model and scaled up by 1.1x.
   • Mist Clearance: 3.00× radius (relative to 24.0m baseline: 72.0m radius, 9.0× coverage area).
   • Light: 2.25× intensity and 1.75× range (17.5m light radius).
   • PlayerBase: 20.0m base spawn suppression (scales with PlayerBaseMistRadiusBonus).
   • Durability: 500 HP and immune to weather decay.
   • Crafting: Requires a Black Forge (Wisp:22,Copper:8,Iron:3,Eitr:2,BlackMarble:5).

4. Tier 4 — Grand Lamp (piece_wisplamp_heeler_grand):

   • In-game Name: Grand Dvergr Wisp Lamp
   • Cloned from the large Dvergr demister model and scaled up by 1.5x.
   • Mist Clearance: 3.75× radius (relative to 24.0m baseline: 90.0m radius, ~14.0× coverage area).
   • Light: Tuned 2.50× intensity and 2.00× range (20.0m light radius).
   • PlayerBase: 20.0m base spawn suppression (scales with PlayerBaseMistRadiusBonus).
   • Durability: Colossal 750 HP and immune to weather decay.
   • Crafting: Requires a Black Forge (Wisp:30,Copper:10,Iron:4,Eitr:4,BlackMarble:10).

Interactive "Torch Painter" System

• Choose Color: Select your desired paintbrush color (PainterColor) using the in-game Configuration Manager UI (F1) color picker or config file.
• Auto-Paint on Placement: Enable AutoPaintOnPlacement in config to automatically paint newly placed torches and lamps with your active color upon hammer placement.
• Paint in World: Aim your crosshair at any wisp torch or lamp within reach and press P (configurable via PaintTorchHotkey). An on-screen prompt displays when in range.
• Reset Piece: Aim at a painted piece and press LeftShift + P (configurable via ResetTorchHotkey) to revert to default color.
• Ward Protection & Security: Non-permitted players cannot paint pieces inside active wards unless permitted by server policy (AllowPaintingInProtectedWards) or admin status (AdminBypassesWardCheck).
• Multiplayer Synchronization: Painted colors synchronize across all clients via ZDO and persistent world storage without requiring external asset bundles.
• Visual Mist Boundary: Enable ShowMistSuppressionRadius in debug config to project a real-time ground ring showing the active mist suppression radius of all wisp pieces.

Configuration

Settings can be customized directly in-game using the BepInEx Configuration Manager (F1) or by editing BepInEx/config/dreamwraith.WispTorchHeeler.cfg:

Compatibility

• Dedicated Servers: Fully compatible with dedicated servers and singleplayer worlds. Server-synced balance and policy settings are enforced on connecting clients via ConditionalConfigSync.
• Native Wisp Torches: Works with native Mistlands wisp torches (piece_wisptorch) when AffectNativeMistTorches is enabled.
• Ward Protection: Integrates with native Valheim wards (PrivateArea) to prevent unauthorized painting within protected territories.
• Zero Asset Bundles: Requires no external Unity assets or bundle files, eliminating bundle desyncs and memory bloat.
• Mod Managers: Fully compatible with Gale, Thunderstore Mod Manager, and r2modman.

Installation

[!TIP] Mod Manager Recommended: Using a modern mod manager like Gale or Thunderstore makes installation and automatic dependency updates effortless.

Mod Manager (Recommended)

1. Install via Gale, Thunderstore Mod Manager, or r2modman.
2. Launch Valheim and enjoy!

Manual Installation

1. Ensure BepInExPack Valheim and Jötunn (the Valheim Modding Library) are installed.
2. Download and extract the latest release archive.
3. Place WispTorchHeeler.dll into your Valheim/BepInEx/plugins/ directory.
4. Launch Valheim.

Building from Source

The project uses a portable MSBuild configuration that auto-detects standard Steam paths.

dotnet build -c Release

The compiled assembly will be placed in bin/Release/net48/WispTorchHeeler.dll. Building in Release configuration also automatically packages the distribution ZIP to bin/Publish/WispTorchHeeler-<Version>.zip.

Custom & CI Paths

For non-standard Steam library locations or mod manager profiles, copy WispTorchHeeler.csproj.user.example to WispTorchHeeler.csproj.user in the project root (this file is git-ignored and automatically loaded by 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>

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details.