balrond lightkeeper

🔥 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.

| Resource | Amount | |---|---:| | Stone | 20 | | Ruby | 4 | | Tin | 5 | | Resin | 15 |

Requires:

• 🔨 Hammer
• 🧰 Stonecutter nearby

---

🎮 Controls

| Action | Input | |---|---| | Open fuel storage | E | | Toggle connected lights ON/OFF | Alt + E | | Toggle auto-fuel ON/OFF | Ctrl + E | | Increase range | + or Numpad + | | Decrease range | - or Numpad - | | Ignore / obey Lightkeeper on individual fire | Ctrl + E while hovering the fire |

> ⚠️ 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:

| Width | Height | Slots | |---:|---:|---:| | 3 | 4 | 12 |

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:

| Action | Input | |---|---| | Toggle ignore / obey Lightkeeper | Ctrl + E |

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