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.

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

1 Static Visuals — Static visuals

2 Character Visuals — Character visuals

3 Production Visuals — Production visuals

4 Continuous Presentation — Continuous presentation / audio / smoke

5 Safe Query Micro-Optimizations — Query micro-optimizations

6 Memory and GC — Memory and GC

7 Safe Advanced Optimizations — Advanced / experimental

9 Diagnostics — Diagnostics

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.

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