WispTorchHeeler

Tiered Mistlands wisp torches and demister lamps with expanded mist clearance, interactive torch painting, body-worn Wisplight customization, 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.
• Body-Worn Wisplight Customization: Full cosmetic customization for your equipped Wisplight accessory (the floating demister_ball follower orb), including custom color, light and emission intensity multipliers, alpha transparency, and multiplayer color sync.
• 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.

Body-Worn Wisplight Customization

Cosmetic customization for the player-equipped Wisplight utility accessory (the flying follower orb, referenced internally and in config as Demister / demister_ball):

• Custom Color: Choose your Wisplight color via DemisterColor in the Configuration Manager (F1) or config file.
• Point Light & Emission Multipliers: Scale the Wisplight's point light intensity (DemisterLightIntensityMultiplier, 0.1x to 5.0x) and core shader emission brightness (DemisterEmissionIntensityMultiplier, 0.1x to 5.0x) independently.
• Alpha Transparency: Optional transparency for your Wisplight via DemisterEnableAlpha. Clamped to a 15% minimum to prevent invisibility.
• Idle Hover Speed & Radius Multipliers: Calms and smooths the Wisplight's idle animation (DemisterIdleSpeedMultiplier, 0.0 to 2.0) and wander radius (DemisterIdleRadiusMultiplier, 0.0 to 2.0) to eliminate rapid fly-like buzzing and jittering around your head.
• Multiplayer Color Sync: When enabled (DemisterSyncMultiplayer), your Wisplight color is written to the follower orb's ZDO (wisptorch_demister_color) and visible to other players running the mod.
• Intensity Multipliers Are Client-Local: Your light and emission intensity settings stay strictly local; other players' Wisplights always render on your screen at default calibrated brightness.
• Strictly Cosmetic: Does not alter mist suppression radius, clearance force fields, or Wisplight equipment stats.

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 handles installation and dependency updates automatically.

Mod Manager (Recommended)

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

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 custom installations, non-standard Steam paths, or mod manager profiles, copy Environment.props.example to Environment.props in the project root to configure your paths:

• VALHEIM_INSTALL: Root Valheim installation folder.
• BEPINEX_PATH: Root BepInEx folder (containing core, plugins, etc.).

Alternatively, you can set VALHEIM_INSTALL and BEPINEX_PATH as environment variables.

Packaging, Publishing & Releases

All developer automation tools for release management, packaging, and publishing to Thunderstore and Nexus Mods are consolidated into the single PowerShell 7 entrypoint .scripts/modtools.ps1, powered by the shared DW.ValheimModTools module:

• Release Management: pwsh ./.scripts/modtools.ps1 release compiles in Release, creates mod & source archives, extracts changelog notes, and publishes GitHub Releases (Draft by default, or published with -Publish) using the gh CLI.
• Packaging & Version Bumping: pwsh ./.scripts/modtools.ps1 package -Bump Patch increments SemVer in WispTorchHeeler.csproj, updates manifest.json, and bundles distribution archives.
• Portal Publishing: pwsh ./.scripts/modtools.ps1 publish -Target All uploads directly to Thunderstore and Nexus Mods APIs.
• CI/CD Workflow: .github/workflows/publish.yml provides an automated GitHub Actions workflow to publish to Thunderstore and Nexus Mods whenever a GitHub Release is published.

For detailed documentation on flags, workflows, and secret configuration, see .scripts/README.md.

License, Author Notes

• This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details.
• A Small Note from Me about Valheim Modding Specifically - Thoughts on open-source modding, community inclusivity, and anti-gatekeeping.
• A Note on AI, Software Craft, and Why This Code Exists - Personal essay on software craft, human agency, and engineering responsibility.

Changelog

All notable changes to WispTorchHeeler will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.3.0] - 2026-10-19

Changed

• Switch to compile-time publicized game assemblies via Jötunn prebuild task (DoPrebuild.props, JotunnLib).
• Removed legacy manual references to Jötunn assembly DLL in favor of package-managed dependencies.
• Remove Hexium publish target and tooling.
• Cleaned up component lookups with native TryGetComponent and simplified Unity null checks.

[1.2.2] - 2026-10-08

Changed

• Centralized build and release automation tooling to shared DW.ValheimModTools.
• Added support for automated Nexus Mods packaging and publishing.

[1.2.1] - 2026-10-08

Added

• Wisplight Idle Animation Speed & Radius Multipliers: Added DemisterIdleSpeedMultiplier (0.0–2.0, default 1.0) and DemisterIdleRadiusMultiplier (0.0–2.0, default 1.0) client config options to calm and smooth the equipped Wisplight's idle hover animation and eliminate frantic fly-like buzzing.
  • note: The wisplight now glides slowly and gracefully around your head instead of darting like an agitated insect. You can adjust the speed or freeze it in place completely.
• Modern Build & Release Automation: Upgraded repository release tooling with SSOT versioning, multi-portal publishing (.scripts/), and automated GitHub Actions CI/CD.

[1.2.0] - 2026-10-02

Added

• Body-Worn Wisplight Customization: Cosmetic customization for the equipped Wisplight follower orb (the floating demister_ball accessory), including color, point light intensity (0.1×–5.0×), and emissive glow multiplier (0.1×–5.0×).
  • note: Your wisplight now uses your color setup instead of being stuck at stock cyan.
• Wisplight Multiplayer Color Sync: Replicates follower orb color to other clients via ZDO string key wisptorch_demister_color with local polling. Light and emission intensity multipliers are client-local and do not replicate.
  • note: Other players with the mod see your wisplight color. Light and emission multipliers stay local so nobody's 5.0× intensity setting affects your screen.
• Wisplight Alpha Transparency: Optional alpha transparency (DemisterEnableAlpha) clamped to a 15% minimum to prevent invisibility.
  • note: You can tone the orb down, but it's clamped at 15% so you don't accidentally make it invisible.
• Configuration Section 9 - Worn Demister: Added 6 config entries for Wisplight customization, lighting, and multiplayer sync. EnableDemisterCustomization and DemisterSyncMultiplayer support server/client sync toggles via ConditionalConfigSync.
  • note: Server admins can toggle server control per-setting if they want to enforce stock wisplights or let players do their thing.
• DemisterPatches: ZNetView.Awake postfix attaching WispDemisterColorController to demister ball objects. Prefab hash pre-filter keeps per-object overhead negligible.

Changed

• WispVisualApplicator: Extracted shared rendering logic (lights, particle gradient tinting, material instancing, shader properties) into a standalone class used by both WispTorchColorController and WispDemisterColorController, removing duplicated code.
• Config event wiring moved to Initialize() methods: Plugin.cs now calls WispTorchColorController.Initialize() and WispDemisterColorController.Initialize() rather than wiring events inline.

[1.1.0] - 2026-09-29

Added

• PlayerBase Support on Lamps: Added PlayerBase components and trigger colliders to all custom Dvergr lamps on the character_trigger layer so they suppress enemy spawns and count toward player base structure recognition.
  • note: I managed to release custom lamps that didn't actually count as base structures. You can now build them without enemies spawning all up in your base.
• Dynamic Spawn Suppression Slider: Added the PlayerBaseMistRadiusBonus server-synced config setting, allowing spawn suppression to scale from the native 20m base up to matching the full mist clearance radius.
  • note: If you want your safe zone to match your clear view, now it can. If you leave it at 0, it stays at the native 20m default so the game balance still balances... mostly.
• Normalized Native Baselines: Standardized internal base values across all tiers to 24m mist clearance, 10m light range, 1.0 light intensity, and 20m PlayerBase suppression radius.
  • note: Each fixture originally inherited whatever numbers Iron Gate gave its donor prefab. I should have looked way closer at the default values on the prefabs I was using, as this made the configuration confusing as all hell. Now everything is normalized on the same base values, so the math can math much mathier.

Changed

• Linear Tier Scaling Toward Grand Demister: Re-adjusted default mist clearance multipliers to scale in clean +0.75x (+18m) steps up to the 90m Grand Demister default:
  • Tier 1 (Large Torch): 1.50x (36m)
  • Tier 2 (Small Lamp): 2.25x (54m)
  • Tier 3 (Large Lamp): 3.00x (72m)
  • Tier 4 (Grand Lamp): 3.75x (90m)
  • note: The earlier progression was uneven because I was eyeballing multiplier jumps. It now steps by an even 18 meters per tier.
• Normalized Light Scaling: Light ranges and intensities now scale off common 10m and 1.0 baselines across all tiers.
  • note: The large demister prop had a native 20m light range that doubled on top of my multipliers and created a miniature sun. It now scales from 10m like everything else.
• Clean Config Descriptions: Rewrote config descriptions to state final numbers relative to stated baselines instead of referencing internal prefab mechanics.
  • note: All my homies reading config files didn't have a clue what I was rambling about. It now just tells you what baseline number you are multiplying.
• Terminology Cleanup: Replaced occurrences of "vanilla" with "native" across code comments and documentation.
  • note: I know the community loves the term vanilla, but I differ, and prefer native. Nonetheless... I went against my own principles in a few places originally, and have now cleaned those up.

Fixed

• Crop Growth Blocked by Lamps (Commit 39add34): Fixed piece collider setup in WispPieceManager to skip trigger colliders when assigning objects to the piece layer. Triggers remain on character_trigger (Layer 14).
  • note: Yes, my torches were accidentally suffocating your cheesy poofs. Unity triggers placed on physical layers make the crop spacing check think there's a solid rock in the dirt (or above the cheesy poofs knob). This was just me using a blunt instrument to solve a collider problem for the build hammer. No more!

[1.0.0] - 2026-09-24

Added

• Initial Release of WispTorchHeeler.
• Tiered Mistlands Lighting Installations:
  • Tier 1 — Large Wisp Torch (piece_wisptorch_heeler_lg): Cloned from native wooden wisp torch and scaled physically by 1.25x. Clears 1.5× mist radius (9m, ~2.25× coverage area), 200 HP (double native torch), weather decay immune, placed freeform with building hammer.
  • Tier 2 — Small Lamp / Dvergr Wisp Lamp (piece_wisplamp_heeler): Adapts native Dvergr Demister prop at 1.0x scale. Clears 2.0× mist radius (12m, 4× coverage area), 250 HP, weather decay immune, crafted at Forge.
  • Tier 3 — Large Lamp (piece_wisplamp_heeler_lg): Cloned from large Dvergr demister model and scaled up by 1.1x. Clears 2.5× mist radius (15m, ~6.25× coverage area), 500 HP, weather decay immune, crafted at Black Forge.
  • Tier 4 — Grand Lamp (piece_wisplamp_heeler_grand): Cloned from large Dvergr demister model and scaled up by 1.5x as a colossal monument. Clears 3.0× mist radius (18m, 9× coverage area), 750 HP, weather decay immune, crafted at Black Forge.
• Interactive "Torch Painter" System:
  • Real-time in-world piece painting (P) and color reset (LeftShift + P) hotkeys via native ZInput buttons registered with Jötunn.
  • In-game Configuration Manager GUI drawer with RGB/Hex color picker and optional alpha transparency customization (safely clamped to minimum 15% opacity to prevent invisible pieces).
  • Auto-Paint on Placement: Automatically stamps newly placed torches and lamps with your active PainterColor upon placement via native IPlaced.OnPlaced().
  • In-game HUD text feedback confirmations and crosshair hover prompts (Paint Light, Reset Color).
• Multiplayer & Server Synchronization:
  • Native ZDO persistence (WTH_Color) synchronizing colors across all clients and saving cleanly with world data with zero desync.
  • Server-enforced lighting policy synchronization via ConditionalConfigSync (EnforceServerDefaultColor, ServerDefaultLightColor, AllowTorchPainting).
  • Native Valheim ward (PrivateArea) integration preventing unauthorized painting within protected territories, with server admin overrides (AdminBypassesWardCheck).
• Native Wisp Torch Support:
  • Configurable support (AffectNativeMistTorches) allowing painting and custom color defaults on standard native wooden wisp torches (piece_wisptorch).
• Visual Mist Boundary Debugger:
  • Optional ShowMistSuppressionRadius debug setting projecting a real-time ground ring indicator showing the active mist suppression radius of all wisp pieces.
• Zero Asset Bundles:
  • Clones and configures native Valheim game prefabs at runtime using Jötunn, ensuring instant loading, zero asset bloat, and full compatibility.
• Build & Distribution Automation:
  • Portable MSBuild configuration with automated Thunderstore release ZIP packaging.