OrbLights 1.0.0

Orb Torch is a separate Hammer piece: a wooden standing torch with a smooth white emissive orb and a budgeted point light. Vanilla torches are unchanged. No custom asset bundle is required.

Validation status: see VALIDATION.md for completed tests and remaining checks. Do not infer multiplayer or visual verification from a successful build.

Install

Install these dependencies in your Valheim mod-manager profile, then import OrbLights-1.0.0.zip as a local mod:

• BepInExPack Valheim 5.4.2351
• Jotunn 2.30.2

For a manual installation, install those dependencies first, then copy the archive's BepInEx/plugins/OrbLights directory to the matching location in the game directory. Do not put the entire ZIP inside plugins. Launch the modded game once to generate BepInEx/config/org.orblights.valheim.cfg.

The ZIP has its manifest, README and 256×256 PNG icon at the root and can be submitted directly to Thunderstore. Choose your own uploader/team account; no account or fictional repository URL is embedded. Dependencies are declared, not bundled.

Build and use

Find Orb Torch in the Hammer's Furniture/Lighting selection. Default cost: 2 Wood, 1 Resin, 1 Surtling Core. Build, repair and dismantle with the normal Hammer controls. The cloned Piece, WearNTear, colliders, snap points and ZNetView retain normal placement, structural damage and resource-return behavior. Normal build wards apply. Orb torches do not emit fire damage, heat, smoke or sound.

This version intentionally uses global settings. It has no Shift/Alt per-torch color or brightness controls, and stores no per-torch color overrides. Global choices include WarmWhite, NeutralWhite, CoolWhite, Red, Orange, Yellow, Green, Cyan, Blue, Purple, Pink and Custom. Custom reads RGB values. Standard piece persistence and optional vanilla fuel ZDO storage are retained.

Configuration

The generated CFG includes descriptions and acceptable ranges. A reference copy is included under examples; it is not installed automatically or allowed to overwrite an existing configuration.

Defaults are warm light RGB 255,225,185, intensity 1.2, orb diameter 0.22m, white orb material, emission strength 2, no flicker, no shadows, no fuel and no rain extinction. RGB accepts 0–255; intensity 0–4; radius 1–25m; orb diameter 0.05–0.6m; emission 0–5; distance 5–100m; maximum lights 0–128. Non-finite floats fall back to safe defaults. Recipe amounts accept 0–100; zero omits the material. All-zero cost makes the piece free.

Edit the CFG while the game runs: changes are detected every two seconds and applied by the next half-second scheduler pass. Existing orbs update. Fuel/rain state is sampled every two seconds. Changing build category, recipe or station is best done before starting the session, then restarting all peers so the build-menu cache and requirements agree. Light settings do not require rebuilding pieces.

Choose Custom to use your individual radius, distance, count, shadow and flicker settings. Other presets override those fields. RGB, intensity, orb size and emission still apply with every preset. EnableLight=false or EmissionOnlyMode=true disables every point light regardless of preset.

White orb appearance is separate from light color. Enable OrbMatchesLightColor for a tinted sphere. Bloom depends on Valheim's renderer and post-processing settings; emission is not a promise of a visible halo with bloom disabled. Reducing emission can reduce excessive bloom.

RequireFuel=true uses Resin, a ten-unit capacity and vanilla refueling. A newly placed torch starts with one fuel unit. FuelBurnRate is Resin per real hour (0.05–10). Fuel updates use the owning peer and vanilla ZDO fields; disabled fuel mode does not continuously write fuel data. Optional rain extinction checks overhead cover. Fuel exhaustion or rain extinction hides the orb until it can light again. Fuel is not refunded as an extra recipe ingredient on destruction.

Multiplayer and dedicated servers

Install the same OrbLights version and both dependencies on the server and every client. Jotunn's required-mod handshake rejects missing or mismatched OrbLights clients when Jotunn participates on both sides. An entirely unmodded host cannot run this custom piece. Do not open a world containing Orb Torches after removing the mod; back up worlds and dismantle the pieces first. A plugin cannot protect a world opened with its plugin system removed.

Recipe, category and fuel settings are server-admin settings synchronized by Jotunn. LockConfiguration=true also synchronizes/locks visual and performance settings. False allows those visual/performance settings to be local; change this before play and restart all peers. The lock itself stays server-controlled. Debug logging is local. Server admins are those recognized by Jotunn from Valheim's admin list. Changes to locked entries on non-admin clients are governed by Jotunn's configuration synchronization.

On Linux dedicated servers, install BepInEx using its Linux launch instructions, then use the identical OrbLights DLL and Jotunn DLL. With no local player, the scheduler enables no point lights. Server-owned optional fuel still updates. There are no patches to Epic Loot or other mods, and patches to Fireplace immediately defer to vanilla for non-OrbLights pieces. Coexistence with any particular modpack still requires an integration test.

Performance guidance

Every real-time point light has a performance cost. Removing flames, smoke and shadows helps, but the maximum-active-light limit and render distance are the most important protections in very large bases. Start with Performance; use Potato or EmissionOnlyMode for the largest bases. Increasing radius affects more pixels and geometry. Enabling shadows can be expensive even at a low count.

One shared scheduler samples proximity twice per second and selects the nearest lights to the local player. No OrbInstance has Update or LateUpdate. Optional flicker affects only the active set at ten samples per second. All orbs share one cached material. Point-light culling does not hide emissive geometry; normal game zone unloading still applies. Selection uses a reusable list and sorts nearby candidates; it is not a benchmark guarantee for unlimited loaded objects.

Troubleshooting

• No piece: check that the game is launched modded, both dependencies are present, and BepInEx/LogOutput.log contains Registered OrbLights_OrbTorch. Missing Jotunn is reported by BepInEx's hard dependency check. Registration failure logs one exception; update dependencies/game together.
• Orb visible, no illumination: check Potato, EmissionOnlyMode, EnableLight, zero intensity, active-light budget and distance. Closer orbs take priority. Try Custom with a modest nonzero count.
• Light edits seem ignored: choose Custom for individual performance controls; check the server's lock. Allow up to 2.5 seconds for CFG changes.
• Fuel/rain: inspect RequireFuel and ExtinguishInRain; refill with Resin or disable fuel globally. Defaults ignore both.
• Black/missing material or misplaced orb: retain the log and report your Valheim/Jotunn versions. Registration derives the orb position from the original torch light and uses loaded game shaders with fallback handling; new game updates can change those assets.
• Diagnostics: EnableDebugLogging prints registered, nearby, active and budget counts at most every 30 seconds. Turn it off after checking.
• FPS: reduce count first, then radius/distance; disable shadows/flicker. A visible emissive sphere still has a mesh-rendering cost.

Source build

Requires a .NET SDK, an installed Valheim 1.0.16-compatible game and PowerShell. Run ./build.ps1 -ValheimPath 'D:\SteamLibrary\steamapps\common\Valheim'. It downloads the pinned official build dependencies to .build/deps, compiles Release, and writes bin/Release/netstandard2.1/OrbLights.dll. Game and dependency DLLs are references only; they are not redistributed. package.ps1 creates the install ZIP from the Release output. The MIT license covers the original code and icon; Valheim and dependencies keep their own licenses.