Balrond Core Optimizer

Performance, visual optimization and optional terrain caching for Valheim

Version: 0.2.8 (29 October 2026). New terrain features are experimental and disabled by default. Performance results vary by hardware, world and mod setup.

Balrond Core Optimizer (BCO) reduces redundant work in selected Valheim presentation and query paths: static visuals, character equipment, production effects, lights, smoke rendering, idle audio and range queries. BCO targets CPU overhead and avoidable managed allocations, especially in complex modded scenes. Version 0.2.8 also adds optional grass, decoration visibility and terrain-rendering controls. It does not replace vanilla AI, physics, world generation or networking.

Gameplay first: BCO does not alter combat, crafting and production times, network ownership or building stability. When another compatible mod already manages the same optimization, BCO can leave that feature to the other mod. It does not batch player-built structures.

Balrond's Den · All Balrond mods · Support on Ko-fi

---

What's new in 0.2.8

• Fewer small CPU allocations: an additional distance-check optimization can avoid temporary allocations when the installed Valheim version benefits from it.
• Optional decoration draw-distance limit: reduce how far one chosen decorative layer is rendered. Objects, collisions and multiplayer state are not removed.
• Optional grass distance limit: lower the maximum grass draw radius without increasing its existing distance.
• Experimental terrain mesh cache: reuse already generated terrain rendering meshes when returning to eligible, previously visited and unmodified zones. Cached entries use a limited amount of RAM and are cleared when leaving a world.
• Experimental Far Terrain Preview: optionally show cached terrain surfaces from previously visited, currently unloaded zones. It does not generate distant unexplored terrain or add distant trees, rocks, grass and other world objects.
• Optional dedicated-server improvement: a headless server can skip generating terrain rendering meshes it does not display. Terrain collision and gameplay are unaffected.
• Compatibility and stability updates: improved coexistence with other visual, terrain, audio and performance mods; safer cleanup of the optional ground-loot optimization.

The terrain cache, Far Preview, grass cap, decoration cap and dedicated-server option are off by default. Experimental client features require Conservative Mode = false. No external optimizer is required.

Also included from 0.2.7: the bco_diag in-game diagnostics, quieter normal logging, and improved optimization safeguards.

Installation and multiplayer

1. Install BepInEx for Valheim and the correctly built BalrondCoreOptimizer.dll.
2. Install that DLL on both server and client: the current build sets ServerSync ModRequired = true, and its minimum required version is 0.2.8. Dedicated servers do not run client presentation options; only the separate, optional headless terrain optimization can run there.
3. For manual installation, place the DLL under BepInEx/plugins/BalrondCoreOptimizer/ and launch the game once to generate the config.
4. Do not deploy the source project's Libs/ServerSync.dll or publicized Valheim assemblies to players. ServerSync is merged into the release DLL by the build.

The generated configuration file is:

BepInEx/config/balrond.astafaraios.BalrondCoreOptimizer.cfg

ServerSync details: 75 config entries (the server-lock entry plus 74 synchronized entries) are registered. With Server Configuration Locked = true, the server governs the synchronized values while clients are connected, including diagnostics and local visual toggles. Offline clients use their local settings. This also applies to the new graphics and terrain settings: when the server lock is active, the server controls whether clients may use them.

Turning on terrain and graphics features

The new options are in [7 Safe Advanced Optimizations] in BepInEx/config/balrond.astafaraios.BalrondCoreOptimizer.cfg. The distance-check optimization is in [5 Safe Query Micro-Optimizations].

1. For the experimental client graphics features, set Conservative Mode = false in [0 General] (the server may lock this setting).
2. To try terrain caching, set Terrain Mesh Cache (Experimental) = true. The default Terrain Cache Maximum MiB = 32 limits estimated mesh data, not all GPU or material memory.
3. To display previously visited terrain farther away, additionally set Far Terrain Preview (Visited Zones Only) = true. This feature requires the terrain cache. Adjust its starting distance, maximum distance and maximum mesh count to suit your hardware.
4. Grass and decoration limits are independent, optional ways to reduce visual draw distance. They do not extend vanilla visibility.
5. Dedicated Skip Heightmap Render Mesh is a separate option for headless dedicated servers only; it has no benefit on a normal game client.

Important: Far Preview uses in-memory cached meshes from visited zones. It is not a full distant-terrain rendering system and does not persist its cache across game sessions. Enable experimental features one at a time and check visual transitions, terrain edits and performance before keeping them on.

What BCO optimizes

Stable static and network-backed presentation

• ArmorStand and ItemStand visual-revision gates: avoid redundant visual reconstruction when the relevant network-backed revision is unchanged.
• PrivateArea/Ward status visuals: avoid repeated stable material and activation writes while preserving vanilla flashing behavior.
• TeleportWorld/portal stable emission: transitions run normally; stable endpoint color writes may be skipped.
• Optional aggressive: ArmorStand cloth check throttling. Blocked by Conservative Mode.

Character equipment and appearance

• VisEquipment equipment signature and color gates avoid unnecessary recomputation when equipment, model, materials or colors are unchanged.
• Optional aggressive: broad whole-player UpdateVisuals gate. Disabled by Conservative Mode.
• Compatibility policy may delegate VisEquipment targets to BAO/CharacterCustomization if they control the exact method; correctness wins over cache hits.

Production and station presentation

• Smelter, Fireplace and CookingStation gates avoid repeating unchanged presentation writes; fuel, ore, roof/weather rules, resources and cooking timers are untouched.
• Optional aggressive: CraftingStation idle dormancy; vanilla update runs first, then an idle station may be removed from the updater until a supported wake condition. Disabled by Conservative Mode.

Effects, light, smoke and audio

• Conservative-profile endpoints: EffectFade, MaterialFader, terminal non-looping ZSFX and LineConnect no-peer gates. Objects remain safely reconciled without changing sound/event authority.
• Optional aggressive: distant LightFlicker throttling, central LightLod scheduler, SmokeRenderer presentation throttling and smoke buffer reuse, Windmill/Vagon audio cadence reduction and Vagon detached tether skipping.
• Catapult and SiegeMachine composite vehicles always bypass the Vagon optimizations.

Exact scope query savings

BCO uses squared-distance comparisons against the current live vanilla collection for eligible Piece, CraftingStation and StationExtension radius lookups. Individual methods are subject to exact Harmony ownership and may be delegated to BAO/RuneRails rather than double-patched.

Terrain, grass and draw-distance optimization (new in 0.2.8)

• Terrain Mesh Cache (Experimental): may avoid rebuilding a terrain rendering mesh when revisiting an eligible, unchanged zone. Modified zones are excluded; the cache is memory-limited and is cleared on world changes.
• Far Terrain Preview (Visited Zones Only): uses the terrain cache to show some previously visited, unloaded areas at longer distances. It may increase graphics load and does not extend physics, object simulation or multiplayer range.
• Grass Distance Ceiling: optionally reduce the distance at which ground clutter appears. It never raises the game's existing distance.
• Camera Decoration Layer Cull: optionally limit draw distance for a single decorative camera layer. It does not remove gameplay objects.
• Dedicated Skip Heightmap Render Mesh: optionally avoid invisible terrain rendering work on headless dedicated servers. It does not change collision or terrain data.

These options may automatically stand down when a supported graphics/terrain mod already controls the relevant feature. They are not required to use BCO.

Advanced features — not general-purpose FPS switches

• SkyAlpha Short Cache requires an exact, compatible method target. In the audited Valheim build the target was unavailable, so that gate was blocked with vanilla fallback; merely enabling its setting does not make it functional.
• Ground Loot NonAlloc Physics is off by default. ItemDrop remains a protected gameplay surface; do not assume the setting is an active optimization.
• GPU Instancing Allowlist is off by default and experimental. It requires exact prefab/material allowlists, respects BAO material ownership and competing renderers, and uses conditional rollback. It is not static-building batching.

Stability safeguards

BCO includes safeguards that periodically recheck cached visual information, restore changes when an optimization is turned off, and avoid competing with supported mods that control the same game feature. If an optimization cannot be applied safely, the normal game behavior is retained. The bco_diag reports can help identify features that are currently active or unavailable.

Conservative Mode and fail-safe policy

Recommended default: Conservative Mode = true. More aggressive optimization options — including the new experimental client terrain features — are not active in this mode, even if their individual switches are set to true.

Conservative Mode limits the effective fallback reconciliation interval to 5 s for dynamic visuals and 10 s for static ZDO-backed visuals without rewriting config-file values. It is not a blanket guarantee: state invalidation and the actual target implementation still need runtime verification.

The diagnostic reports show which optimizations are running, disabled or handled by another mod. If BCO cannot safely apply a feature, the game or other compatible mod retains control.

BCO does not take over creature AI, combat, building stability, physics, network synchronization or world simulation.

Configuration reference — 0.2.8 settings

The names and defaults below match the 0.2.8 configuration. Your generated .cfg file is authoritative for values actually in use. Changes to synced settings may be locked by the server. Enabled-by-default aggressive flags do not override Conservative Mode.

0 General — General / ServerSync

Config key	Default	Purpose / gate
Server Configuration Locked	true	Server controls synchronized settings while connected.
Enabled	true	Master optimization switch.
Conservative Mode	true	Keeps cadence/scheduler and high-risk replacement gates uninstalled.
Disable On Foreign Harmony Patches	true	Fail closed on unaudited exact-target patch overlaps.
Compatibility Recheck Seconds	60	Interval for checking late Harmony changes.
Visual Safety Refresh Seconds	30	Dynamic visual fallback refresh; capped at 5 s in conservative mode.
Static Visual Safety Refresh Seconds	30	Static network-backed refresh; capped at 10 s in conservative mode.

1 Static Visuals — Static visuals

Config key	Default	Purpose / gate
ArmorStand Revision Gate	true	Independent feature toggle; subject to compatibility and conservative policy.
ArmorStand Cloth Throttling	true	Aggressive; disabled by Conservative Mode.
ArmorStand Cloth Checks Per Second	10	Target frequency (Hz); subject to feature gate.
ItemStand Revision Gate	true	Independent feature toggle; subject to compatibility and conservative policy.
PrivateArea Status Visual Gate	true	Independent feature toggle; subject to compatibility and conservative policy.
Portal Stable Emission Gate	true	Independent feature toggle; subject to compatibility and conservative policy.

2 Character Visuals — Character visuals

Config key	Default	Purpose / gate
VisEquipment Whole Player Revision Gate	true	Aggressive; disabled by Conservative Mode.
VisEquipment Equipment Signature Gate	true	Independent feature toggle; subject to compatibility and conservative policy.
VisEquipment Color Signature Gate	true	Independent feature toggle; subject to compatibility and conservative policy.

3 Production Visuals — Production visuals

Config key	Default	Purpose / gate
Smelter Visual State Gate	true	Independent feature toggle; subject to compatibility and conservative policy.
Fireplace Visual State Gate	true	Independent feature toggle; subject to compatibility and conservative policy.
CookingStation Visual Signature Gate	true	Independent feature toggle; subject to compatibility and conservative policy.
CraftingStation Idle Dormancy	true	Aggressive; disabled by Conservative Mode.

4 Continuous Presentation — Continuous presentation / audio / smoke

Config key	Default	Purpose / gate
Light Flicker Distance Throttling	true	Aggressive; disabled by Conservative Mode.
Light Flicker Near Distance	40	Distance threshold / check tuning for the corresponding gated feature.
Light Flicker Mid Distance	60	Distance threshold / check tuning for the corresponding gated feature.
Light Flicker Far Distance	100	Distance threshold / check tuning for the corresponding gated feature.
Light Flicker Mid Updates Per Second	10	Target frequency (Hz); subject to feature gate.
Light Flicker Far Updates Per Second	5	Target frequency (Hz); subject to feature gate.
Light Flicker Distant Updates Per Second	2	Target frequency (Hz); subject to feature gate.
Light Flicker Distance Checks Per Second	2	Target frequency (Hz); subject to feature gate.
LightLod Central Scheduler	true	Aggressive; disabled by Conservative Mode.
LightLod Distance Checks Per Second	1	Target frequency (Hz); subject to feature gate.
LightLod Checks Per Frame	512	Per-frame work cap for optional LightLod scheduler.
LightLod Fractional Check Budget	true	Independent feature toggle; subject to compatibility and conservative policy.
Smoke Renderer Throttling	true	Aggressive; disabled by Conservative Mode.
Smoke Renderer Updates Per Second	10	Target frequency (Hz); subject to feature gate.
Windmill Audio Throttling	true	Aggressive; disabled by Conservative Mode.
Windmill Audio Updates Per Second	10	Target frequency (Hz); subject to feature gate.
Vagon Audio Throttling	true	Aggressive; Catapult/SiegeMachine bypass.
Vagon Audio Updates Per Second	10	Target frequency (Hz); subject to feature gate.
Vagon Idle Tether Visual Gate	true	Aggressive; Catapult/SiegeMachine bypass.
EffectFade Endpoint Dormancy	true	Independent feature toggle; subject to compatibility and conservative policy.
MaterialFader Endpoint Dormancy	true	Independent feature toggle; subject to compatibility and conservative policy.
ZSFX Idle Dormancy	true	Independent feature toggle; subject to compatibility and conservative policy.
LineConnect Stable No-Connection Gate	true	Independent feature toggle; subject to compatibility and conservative policy.

5 Safe Query Micro-Optimizations — Query micro-optimizations

Config key	Default	Purpose / gate
Piece Squared Distance Queries	true	Distance threshold / check tuning for the corresponding gated feature.
CraftingStation Squared Distance Queries	true	Distance threshold / check tuning for the corresponding gated feature.
StationExtension Squared Distance Query	true	Reduce unnecessary distance-calculation work near stations.
Chebyshev Distance No-Allocation	true	Avoid a temporary allocation in compatible Valheim distance checks; automatically stands down if unnecessary or conflicting.

6 Memory and GC — Memory and GC

Config key	Default	Purpose / gate
Smoke No-Allocation Chunk Transfers	true	Aggressive smoke-path replacement; suppressed by Conservative Mode.
Smoke Adaptive Chunk Particle Buffers	true	Aggressive smoke-path replacement; suppressed by Conservative Mode.
Smoke Initial Chunk Particle Capacity	8	Initial particle scratch capacity; grows when needed.
Ground Loot NonAlloc Physics	false	Default OFF; protected ItemDrop target may be delegated.

7 Safe Advanced Optimizations — Optional graphics and terrain

Config key	Default	Purpose / gate
SkyAlpha Short Cache	true	Optional short-term visual cache; stays inactive if unsupported by your game version.
SkyAlpha Maximum Age Seconds	2.5	Maximum time to reuse a cached result, when the feature is available.
SkyAlpha Movement Tolerance	0.20	Player movement threshold for refreshing this optional cache.
SkyAlpha Piece Invalidation Radius	48	Nearby building changes that can trigger a cache refresh.
GPU Instancing Allowlist	false	Experimental; OFF by default; BAO and competing renderer safeguards.
GPU Instancing Prefabs Per Tick	2	Processing budget for experimental GPU instancing.
GPU Instancing Prefab IDs	(empty)	Semicolon-delimited exact prefab IDs; no wildcards.
GPU Instancing Material Names	(empty)	Semicolon-delimited exact material names; no wildcards.
Camera Decoration Layer Cull	false	Optional limit on the draw distance of a decorative layer; requires Conservative Mode off.
Camera Decoration Layer Name	Default_small	Exact decorative layer to limit. Avoid player or gameplay layers.
Camera Decoration Maximum Metres	120	Maximum draw distance for that layer; does not increase an existing shorter limit. Range: 40–200 m.
Grass Distance Ceiling	false	Optionally reduce grass draw distance; requires Conservative Mode off.
Grass Maximum Distance Metres	32	Target grass distance cap, 16–40 m; does not increase the current radius.
Dedicated Skip Heightmap Render Mesh	false	Headless dedicated-server-only option to skip invisible terrain rendering meshes.
Terrain Mesh Cache (Experimental)	false	In-memory cache of rendering meshes for eligible revisited, unmodified zones; requires Conservative Mode off.
Terrain Cache Maximum MiB	32	Approximate memory limit for cached mesh geometry, 4–128 MiB; excludes some graphics overhead.
Far Terrain Preview (Visited Zones Only)	false	Optional distant display of cached terrain from previously visited unloaded zones; requires terrain cache and Conservative Mode off.
Far Preview Start Metres	160	Distance beyond which cached terrain previews may appear. Range: 128–512 m.
Far Preview Maximum Metres	384	Maximum display distance for cached previews. Range: 192–1024 m; more distance may cost GPU performance.
Far Preview Maximum Meshes	16	Maximum number of visible preview meshes at once. Range: 4–64.

9 Diagnostics — Diagnostics

Config key	Default	Purpose / gate
Runtime Statistics	false	OFF by default; enables debug-level periodic statistics.
Performance Samples	false	Requires Runtime Statistics for periodic sampling; OFF by default.
Performance Sample Every N Frames	120	Periodic sampling stride (not full-session stride).
Statistics Interval Seconds	30	Periodic log interval when Runtime Statistics is ON.

Diagnostics — bco_diag

Use the in-game F5 console on the client (not dedicated server). Diagnostic commands create local text files in BepInEx/BCO_Diagnostics/. A timed session clamps duration to 10–180 seconds; the default is 60 seconds.

Command	Output
bco_diag	Instant snapshot of settings, patch ownership, registered mods, available counters.
bco_diag start 60	Time-bounded light session; frametime/GC sampling and optimizer counters.
bco_diag full 90	All-in-one timed report: sampling, BCO service timings, start/end registry snapshots, method/Harmony inventory and final material scan.
bco_diag methods	Static candidate-method availability, Harmony ownership, registry snapshot; not a per-method time profiler.
bco_diag materials	On-demand scan of loaded material/shader incidents. May cause a short hitch. Does not replace shaders.
bco_diag stop	Save the active session early.
bco_diag help	Console help and report directory.

Metrics labelled frameMetrics=DELIVERED_FRAME_INTERVALS_NOT_CPU_OR_GPU_PROFILE measure intervals between delivered frames, not isolated main-thread CPU time or GPU render-thread cost. Allocation estimates are main-thread-only when the runtime supports the counter. An instant snapshot can legitimately show samples=0 without a running session.

For comparable performance evidence, run bco_diag full 90 in the same settled scene with identical resolution, graphics settings, seed, mods and camera location. Compare frametime percentiles, hitches, allocation counters and patch coverage. The end-of-session material scan is outside the timed sample.

Logging policy: routine BCO success messages are silent/Debug-only. Warning and Error remain visible. Set Runtime Statistics = true only when periodic debug output is needed; explicit bco_diag commands work with periodic logging off.

Compatibility and support

BCO's targeted Harmony policy can coexist with audited known owners while declining unsupported exact-method overlaps. It recognizes Balrond mod groups and detects supported external graphics and performance providers (including RenderHeim, PerformantTerrain, ValheimTune, ValheimPerformanceFixes and various camera/visual mods). Detected conflicts can cause a specific BCO feature to remain inactive rather than compete with the other mod. Detection alone does not mean the two mods are incompatible. None of these optional mods is required by BCO.

For a bug report, include BCO and Valheim versions, BepInEx log, mod list, the relevant BCO_full_*.txt or BCO_snapshot_*.txt, the action/object reproducing the issue and whether disabling the matching feature changes it. Do not share private information accidentally included in game or platform logs.

Support development

Balrond's Den · Ko-fi · Balrond mods on Thunderstore