Balrond Core Optimizer

CPU, presentation, query and GC optimization for Valheim

Documentation target: 0.2.7 — development source after the Safe Diagnostics, Quiet Logging and Five Safe Modules updates (20 October 2026). Runtime release validation is still required.

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. It is not a general GPU graphics enhancer, nor a replacement for vanilla AI, physics or networking.

Safety contract: BCO must not change gameplay authority, combat outcomes, crafting/production timers, ZDO ownership or structural support. Each Harmony gate resolves its runtime target and may run, delegate to an audited owner, or fail closed. No static-building clusters or GPU batching of construction pieces are implemented.

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

---

What's new in 0.2.7

• bco_diag on-demand console diagnostics: snapshot, timed session, full report, method/Harmony inventory and material incident scan. Output is local TXT under BepInEx/BCO_Diagnostics/.
• More reliable diagnostics: approximate sampled frame-interval percentiles and hitch indicators, available main-thread allocation readings, BCO-owned service timings, scene-registry counts and external-mod inventory. These are not per-method CPU or GPU profiling.
• Reduced routine logging: successful initialization and diagnostic registration are silent or Debug-only; actionable warnings and errors remain visible. Enabling Runtime Statistics can produce periodic Debug output.
• Safer lifecycle handling: stronger weak-reference identity checks and reduced allocation/scheduler overhead; LightLod rollback continues restoring other lights when one object fails.
• Better interoperability: exact-target Harmony ownership and conservative delegation around BAO, MonsterMayhem, BetterBuild, CharacterCustomization, RuneRails and compatible external providers. WearNTear/WearNTearUpdater remain BetterBuild-owned.
• External material/render diagnostics: detect suspected shader incidents on demand; recognize PUP FPS, RenderHeim, ImmersiveCameraEnhanced, ShadowPerson fixes, SteadyFrame and ValheimVisuals from plugin metadata. This does not repair shaders or alter foreign rendering.
• Five internal safety utilities (see below). They are deliberately scoped to BCO-owned data and do not introduce new Harmony targets or config entries.
• Build and project maintenance: 0.2.7 version metadata, current ILRepack/ServerSync integration, updated safety checks and offline Valheim-method audit tools.

Not yet claimed: validated FPS gains, complete game-runtime compatibility, cross-platform multiplayer certification or full per-method profiling. Static tests and a successful build are not substitutes for in-game tests.

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.7. The dedicated server registers ServerSync but does not install client presentation patches.
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: 62 config entries (the server-lock entry plus 61 synced 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. There is no separate client-only toggle synchronization scheme in 0.2.7.

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.

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.

Five bounded safety utilities (0.2.7)

These have no user-facing config switches; they do not automatically optimize every renderer or Valheim method.

Utility	Implemented scope and fallback
CacheVerification	Samples camera-identity cache correctness every 32 cache hits. A mismatch disables only that cache for the session and reads the live camera. It does not validate gameplay or all caches.
FrameCameraSnapshot	Per-Unity-frame camera-identity reuse only inside optional LightLod; positions remain live. Known camera/post-FX providers bypass caching.
OwnedStateGuard<T>	Tracks BCO's own experimental material enableInstancing writes; rollback skips state with changed shader/observed value. Identical third-party writes cannot be reliably distinguished.
ReusableBufferPool<T>	Capped, clearing array pool used only for BCO's diagnostic external-provider report; not Unity scene, particle, ZDO or network buffers.
ExternalOptimizerDiagnostics	Advisory plugin detection and reporting for SteadyFrame, ValheimVisuals and other supported visual/camera providers; not an automatic global conflict verdict.

Reports expose cache verification and ownership counters through [safe_cache_and_ownership].

Conservative Mode and fail-safe policy

Recommended default: Conservative Mode = true. Individual feature settings can still display true; the installer physically refuses to install the higher-risk cadence/scheduler/replacement group while conservative mode is active.

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.

BCO reports patch states as active, delegated, disabled/conflicting or blocked, with effective-covered including active plus approved delegated targets. Unknown exact-target Harmony combinations fail closed. The game should continue using vanilla or the responsible external mod where BCO declines a gate.

Hard ownership boundaries: BetterBuild owns WearNTear; BAO owns its shader replacement, FX and content; BMM owns creature AI/spawning/combat authority. BCO does not replace ZNetScene, ZDOMan, ZSyncTransform, physics/world streaming or the global MonoUpdaters dispatcher.

Configuration reference — exact 0.2.7 keys

This table is derived from the current Config/OptimizerConfig.cs. The Config/BalrondVisualOptimizer.example.cfg file is illustrative; the generated .cfg is authoritative for installed values. 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	Distance threshold / check tuning for the corresponding gated feature.

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 — Advanced / experimental

Config key	Default	Purpose / gate
SkyAlpha Short Cache	true	Aggressive, exact target required; blocked if target absent.
SkyAlpha Maximum Age Seconds	2.5	Tuning for the optional SkyAlpha cache; unavailable without target.
SkyAlpha Movement Tolerance	0.20	Tuning for the optional SkyAlpha cache; unavailable without target.
SkyAlpha Piece Invalidation Radius	48	Tuning for the optional SkyAlpha cache; unavailable without target.
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.

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 external graphics providers by GUID/name (including PUP FPS, RenderHeim, SteadyFrame, ValheimVisuals, ImmersiveCameraEnhanced and ShadowPerson fixes). Detection by itself is not proof that a conflict exists.

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