🔥 Lightkeeper - Mod Documentation

🔥 Overview

Lightkeeper adds a new buildable controller piece for Valheim that lets you manage fire and light sources in a smart, networked way.

The mod is designed for bases with many torches, braziers, hearths, campfires, sconces, and other pieces using Valheim's Fireplace component.

With Lightkeeper you can:

• 🔥 Turn connected fire sources ON or OFF from one place
• ⛽ Automatically distribute fuel to fires in range
• 📦 Store fuel inside the Lightkeeper itself
• 🔗 Connect multiple Lightkeepers into one shared network
• 📏 Adjust controller range in-game
• 🚫 Exclude individual fire sources from Lightkeeper control
• 🌐 Keep the system synced in multiplayer

🧩 Lightkeeper works with Valheim fire sources using the vanilla Fireplace component.

🏗️ What This Mod Adds

🔥 Lightkeeper

A new build piece that works as a fire and light control hub.

The Lightkeeper can:

• Detect fire sources in its radius
• Toggle nearby lights ON/OFF
• Prevent fuel consumption while lights are OFF
• Store fuel in its own internal storage
• Automatically refill compatible fires
• Link with other Lightkeepers into a larger network

🧾 Recipe

The Lightkeeper is built with the Hammer.

Requires:

• 🔨 Hammer
• 🧰 Stonecutter nearby

🎮 Controls

⚠️ In Valheim the alt parameter in Interact() is not the keyboard Alt key. Lightkeeper checks the real keyboard Alt key directly.

🔗 Network System

Lightkeepers can connect to each other and act as one network.

Two Lightkeepers are connected when one of them reaches the other with its radius.

Example:

Lightkeeper A range: 10m
Lightkeeper B range: 15m
Distance between them: 12m

A does not reach B.
B reaches A.
Result: connected.

This means a larger-range Lightkeeper can connect to a smaller one even if the smaller one does not reach back.

📏 Dynamic Range

Each Lightkeeper has an adjustable radius.

While hovering the Lightkeeper:

• Press + to increase range
• Press - to decrease range

Changing range can:

• Connect new Lightkeepers
• Disconnect old Lightkeepers
• Merge networks
• Split networks

The network is recalculated after range changes.

🔥 Light Control

When the Lightkeeper network is ON:

• Controlled fires can burn normally
• Fuel consumption works normally
• Auto-fuel can refill fires if enabled

When the Lightkeeper network is OFF:

• Controlled fires are forced OFF
• Controlled fires stop consuming fuel
• Auto-fuel does not run

Toggling one Lightkeeper affects every connected Lightkeeper in its current network.

⛽ Auto-Fuel System

Lightkeeper can automatically refill fire sources using fuel stored in connected Lightkeeper containers.

Auto-fuel is network-wide:

• If you turn auto-fuel OFF on one connected Lightkeeper, it turns OFF for the whole connected network.
• If you turn it ON, it turns ON for the whole connected network.

Auto-fuel only runs when:

• The Lightkeeper network is ON
• Auto-fuel is ON
• A valid fire source is inside the network
• The fire source is not ignored
• Matching fuel exists in connected storage
• The storage is not currently open by a player

📦 Fuel Storage

Each Lightkeeper has a small internal storage.

Storage size:

This is not meant to replace a full chest. It is a compact fuel buffer for the controller network.

If multiple Lightkeepers are connected, their available storage is treated as a shared fuel pool.

🧠 Smart Fuel Distribution

The auto-fuel system is designed to be efficient.

It does not try to fuel every fire every frame.

Instead it:

• Runs on a timed interval
• Uses one network leader
• Checks fires in batches
• Uses round-robin scanning
• Skips invalid or destroyed objects
• Skips containers currently opened by players
• Refills missing fuel instead of adding only one item at a time

This helps avoid FPS spikes in large bases.

👑 Network Leader

Only one Lightkeeper in a connected network performs auto-fuel logic.

This prevents:

• Duplicate fueling
• Multiple controllers consuming the same fuel
• Excessive scans
• Multiplayer desync issues

The leader is selected automatically from the connected network.

🚫 Ignoring Individual Fires

Each fire source can be excluded from Lightkeeper control.

While hovering a fire source:

Ignored fires:

• Do not get forced ON/OFF by Lightkeeper
• Do not receive auto-fuel from Lightkeeper
• Continue using vanilla behavior

This is useful for decorative fires, special modded lights, or lights controlled by another system.

🌐 Multiplayer Behavior

Lightkeeper is designed for multiplayer.

The important states are stored in ZDO data:

• Controller ON/OFF state
• Auto-fuel ON/OFF state
• Controller radius
• Fire ignore state

This allows the system to persist across:

• World reloads
• Server restarts
• Player reconnects
• Zone unload/reload

⚙️ Performance Notes

Lightkeeper avoids expensive global scans.

The system uses:

• Registered controller lists
• Registered fire lists
• Timed cleanup
• Batched fire checks
• Network leader logic
• Range cache invalidation only when needed

Destroyed or removed fires are validated and cleaned up automatically.

🧩 Compatibility Notes

Lightkeeper is designed to be compatible with other mods that interact with fire sources.

Important compatibility choices:

• Normal E on fires remains vanilla behavior
• Lightkeeper controller uses modifier keys for special actions
• Individual fires can ignore Lightkeeper
• The mod works with pieces using the vanilla Fireplace component

Future light/color control mods should be able to coexist more easily because Lightkeeper separates:

• Light ON/OFF control
• Auto-fuel control
• Fire ignore state

🧪 Example Setup

[Lightkeeper A] ---- connected ---- [Lightkeeper B] ---- connected ---- [Lightkeeper C]

If these are connected by radius:

• Turning off A turns off A, B, and C
• Turning off auto-fuel on B disables auto-fuel for A, B, and C
• Fuel stored in any available connected Lightkeeper can be used
• If one storage is open by a player, that storage is skipped

📘 Translation Support

All player-facing text uses translation keys in the format:

$tag_lightkeeper_*_bal

Translation JSON keys should not include the $ prefix.

Example:

{
  "tag_lightkeeper_name_bal": "Lightkeeper",
  "tag_lightkeeper_open_storage_bal": "Open fuel storage"
}

🌍 Translation Keys

{
  "tag_lightkeeper_name_bal": "Lightkeeper",
  "tag_lightkeeper_description_bal": "Allows control over fire sources in area and centralizes fuel supply",
  "tag_lightkeeper_on_bal": "ON",
  "tag_lightkeeper_off_bal": "OFF",
  "tag_lightkeeper_open_storage_bal": "Open fuel storage",
  "tag_lightkeeper_turn_lights_bal": "Toggle lights",
  "tag_lightkeeper_turn_autofuel_bal": "Toggle auto-fuel",
  "tag_lightkeeper_adjust_range_bal": "Adjust range",
  "tag_lightkeeper_storage_skipped_bal": "Open storage is skipped by auto-fuel.",
  "tag_lightkeeper_noaccess_bal": "$piece_noaccess",
  "tag_lightkeeper_msg_turned_on_bal": "Lightkeeper turned on.",
  "tag_lightkeeper_msg_turned_off_bal": "Lightkeeper turned off.",
  "tag_lightkeeper_msg_autofuel_enabled_bal": "Auto-fuel enabled.",
  "tag_lightkeeper_msg_autofuel_disabled_bal": "Auto-fuel disabled.",
  "tag_lightkeeper_msg_range_bal": "Lightkeeper range:",
  "tag_lightkeeper_fire_ignore_bal": "Ignore Lightkeeper",
  "tag_lightkeeper_fire_obey_bal": "Obey Lightkeeper",
  "tag_lightkeeper_fire_msg_ignored_bal": "This light now ignores Lightkeeper.",
  "tag_lightkeeper_fire_msg_obey_bal": "This light now obeys Lightkeeper."
}

❓ FAQ

💬 Community & Support

• Join our Discord: Balrond's Den
• Support on Ko-fi: ko-fi.com/balrond1020

🧾 Changelog

Check the mod page changelog for version history.

📌 Final Notes

Lightkeeper is built to reduce repetitive fire maintenance while keeping Valheim's fuel systems meaningful.

It gives players control, automation, and convenience without turning fire sources into free infinite lights.