Balrond Core Optimizer

Client-side CPU, presentation and query optimization for Valheim

Current documentation target: Balrond Core Optimizer 0.2.0

Balrond Core Optimizer (BCO) reduces repeated CPU work that Valheim performs for visual state, equipment presentation, lights, effects, audio and frequently queried world-object lists. It is designed primarily for large bases, dense modded worlds and scenes containing many active components.

BCO follows a conservative rule: do not change gameplay authority just to gain frames. It avoids combat, AI, networking authority, structural integrity, dropped-item physics and production timing. When a result is already known and unchanged, BCO skips redundant presentation/query work. More invasive cadence and scheduler replacements are separated behind Conservative Mode.

Join Balrond's Den · All Balrond mods · Support development on Ko-fi · Commission inquiries

---

What does BCO optimize?

Static and network-backed visuals

• Armor Stand visual revision gate — skips repeated ArmorStand.UpdateVisual reconstruction while the relevant network-backed data revision is unchanged.
• Item Stand visual revision gate — avoids rebuilding the same attachment visual when its network-backed state has not changed.
• Ward / PrivateArea status visual gate — avoids repeated SetActive and emission writes while preserving vanilla flash re-arming.
• Portal stable emission gate — portal transitions remain full-rate; once the fade reaches a stable endpoint, BCO stops rewriting the same emission color every frame.

Aggressive optional static optimization

• Armor Stand cloth throttling — replaces the vanilla every-frame cloth-distance decision with a throttled squared-distance check.

This feature is blocked by default while Conservative Mode = true.

Character presentation

• VisEquipment equipment signature gate — avoids repeated equipment reconstruction checks when equipped-item state is unchanged.
• VisEquipment color signature gate — avoids repeated skin/hair material color writes when colors, model and generated visual instances are unchanged.

The color gate treats a player model change as an invalidation event, so unchanged RGB values are still re-applied to a newly selected model.

Aggressive optional character optimization

• VisEquipment whole-player revision gate — can skip the entire UpdateVisuals pass while the player visual revision is unchanged, avoiding UpdateBaseModel plus nested equipment/color work.

This feature is blocked by default while Conservative Mode = true.

Production presentation

• Smelter visual-state gate — caches only presentation/animation state. Fuel, ore, roof checks, smoke simulation and production remain vanilla.
• Fireplace visual-state gate — skips stable visual tiers while preserving the vanilla wet-owner toggle/RPC path when it can run.
• Cooking Station visual signature gate — caches slot/status/fire/fuel-visible presentation. Cooking timers and fuel consumption remain vanilla.

Aggressive optional station optimization

• Crafting Station idle dormancy — vanilla CustomUpdate always executes first. Only after the vanilla timers reach their idle thresholds may BCO remove a fully idle station from the CraftingStation updater source. PokeInUse and extension queries wake it again.

This feature is blocked by default while Conservative Mode = true.

Continuous presentation and effects

The conservative profile keeps low-risk endpoint/no-op gates available:

• Cart/Vagon idle tether gate — a detached cart whose tether is already hidden can skip redundant LateUpdate work, with periodic vanilla reconciliation.
• EffectFade stable-endpoint gate — the component stays enabled; BCO skips terminal no-work frames and periodically lets vanilla reconcile.
• MaterialFader stable-endpoint gate — the component stays enabled; direct field changes from other mods remain observable on the next frame.
• ZSFX idle fast gate — ZSFX instances remain registered in Valheim's updater. BCO only skips terminal non-looping no-work frames.
• LineConnect stable no-connection gate — short-caches the hidden/no-peer result to reduce repeated ZNetScene.FindInstance work while still reconciling streaming changes.

Aggressive optional continuous optimizations

When Conservative Mode = false, the following individually enabled features are allowed to install:

• LightFlicker distance throttling — near persistent lights stay full-rate; distant persistent lights update progressively less often. Temporary/TTL/fading lights remain vanilla.
• Central LightLod scheduler — replaces one LightLod.UpdateLoop coroutine per light with a single time-sliced scheduler while preserving active fade behavior.
• SmokeRenderer presentation throttling — reduces renderer refresh cadence only; smoke spawning and blockage simulation remain untouched.
• Smoke no-allocation chunk transfers — replaces per-transfer tuple allocations with a reusable move buffer.
• Smoke adaptive particle scratch buffers — sparse chunks start small and grow only when needed instead of reserving the vanilla-sized scratch array immediately.
• Windmill audio throttling — reduces UpdateAudio cadence only.
• Vagon audio throttling — reduces cart audio update cadence only; cart physics and attachment remain vanilla.

These features are more likely to produce visible CPU/FPS gains in dense scenes, but they change update cadence or replace larger presentation loops and therefore remain outside the default conservative profile.

Exact query micro-optimizations

Selected radius queries keep Valheim's live collections and traversal semantics but compare squared distance instead of repeatedly calculating square roots:

• Piece.GetAllPiecesInRadius
• Piece.GetAllComfortPiecesInRadius
• CraftingStation.UpdateKnownStationsInRange
• CraftingStation.HaveBuildStationInRange
• CraftingStation.FindStationsInRange
• CraftingStation.FindClosestStationInRange
• StationExtension.OtherExtensionInRange

BCO reads the current vanilla collection references rather than retaining startup snapshots, which avoids stale-list behavior when other mods replace/rebuild those collections.

---

Conservative Mode

Conservative Mode = true is the 0.2.0 default.

This does not mean the individual feature toggles are off. It means BCO physically keeps the higher-risk cadence-changing, scheduler-replacement, updater-removal and complex renderer-loop patches uninstalled while leaving cache/no-op gates and equivalent query optimizations available.

In Conservative Mode, BCO also bounds fallback reconciliation to:

• 5 seconds for dynamic visual caches;
• 10 seconds for static ZDO-backed visual caches.

The config-file values themselves are not overwritten, so turning Conservative Mode off restores the configured cadences.

For troubleshooting and correctness-first public releases, keep Conservative Mode enabled. For controlled performance testing in a copied/test world, disable it and benchmark the aggressive features individually.

---

Harmony compatibility model

BCO 0.2.0 no longer treats every foreign Harmony owner as an automatic conflict.

For each exact target, the runtime can choose one of three outcomes:

1. Active — BCO owns and runs the optimization.
2. Delegated — another known mod already owns the same performance surface, so BCO deliberately stands down on that exact target.
3. Disabled/conflicting — the combination has not been audited, so BCO fails closed instead of guessing patch order.

The runtime summary reports all three states:

[patches] patches active=.../...,
          delegated=...,
          disabled=...,
          permanently-blocked=...,
          effective-covered=.../...

effective-covered counts both BCO-owned optimizations and explicitly delegated equivalents.

BCO periodically rechecks Harmony ownership so late-loaded patches can be reconciled. Config changes request reconciliation on the next Unity update.

Valheim Community Patch (VCP)

BCO and VCP overlap on several optimization domains. In 0.2.0, if VCP owns the exact same BCO target method, BCO delegates that target to VCP rather than double-throttling or racing a competing fast path. Non-overlapping BCO optimizations remain active.

Balrond RuneRails

The current audited RuneRails station-range postfixes can safely compose with BCO on:

• CraftingStation.HaveBuildStationInRange
• CraftingStation.FindStationsInRange
• CraftingStation.FindClosestStationInRange

BCO performs the optimized vanilla station scan first; RuneRails then appends/checks its custom builder workstations in postfixes.

Balrond Character Customization

VisEquipment.UpdateColors is delegated to Balrond Character Customization when that mod owns the method. Race/model/material correctness takes priority over BCO's optional color cache. Other non-conflicting VisEquipment optimizations remain available.

Balrond Absolute Overhaul and Balrond Monster Mayhem

The currently audited BAO/MM builds do not overlap BCO's present target set. BCO does not assume that every future Balrond patch is automatically safe: a new exact overlap fails closed until it is audited.

Balrond Better Build

Better Build owns structural-integrity/support optimization. BCO treats WearNTear and WearNTearUpdater as protected surfaces and does not compete for support authority.

FiresGhettoNetworking

FiresGhettoNetworking remains the network/authority specialist. BCO deliberately avoids transport, ZDO replication, RPC routing, zone authority and ZSyncTransform responsibilities.

FpsProtector

FpsProtector 1.0.2 patches ZNetScene.RemoveObjects and ZNetScene.CreateObject to recover from corrupted/null active-instance entries and repeated attempts to create missing prefabs.

BCO 0.2.0 does not patch either method and treats ZNetScene as a protected subsystem, so the current versions have no direct Harmony target overlap.

---

What BCO intentionally does not optimize

BCO 0.2.0 intentionally does not patch or replace:

• ItemDrop, Floating or dropped-item Rigidbody physics;
• ZSyncTransform / ZSyncAnimation;
• ZDOMan, ZNetScene, ZRoutedRpc, ZRpc, ZNet or socket transport;
• ZNetView.Register / gameplay RPC registration;
• Valheim's global MonoUpdaters dispatcher itself;
• WearNTear / WearNTearUpdater structural integrity;
• player combat, attacks, projectiles or damage authority;
• AI/pathfinding/spawn simulation;
• smoke spawning/blockage simulation;
• production timers or resource consumption.

BCO may read existing local/ZDO state to decide whether presentation needs refreshing, but it adds no custom RPC protocol, no custom ZDO keys and no competing network-authority layer.

---

Valheim update compatibility

BCO no longer uses assembly_valheim MVID, assembly version or raw IL SHA-256 as a runtime allow/deny gate.

Those identifiers are diagnostic only. Publicizing/rewriting an assembly can change metadata tokens and MVID even when method semantics are unchanged, so global fingerprint checks caused false incompatibility in older builds.

Current compatibility is enforced at the actual integration boundaries:

• the exact runtime target signature must resolve;
• protected gameplay/network/physics/support surfaces are refused;
• known Harmony owners may coexist or receive explicit delegation;
• unaudited same-target conflicts fail closed;
• a Harmony install/signature exception disables only the affected gate for that session;
• vanilla remains authoritative whenever a BCO gate is unavailable.

There is no Allow Unknown Game Build option in 0.2.0.

---

What performance should I expect?

Performance depends on the current bottleneck. BCO is primarily a main-thread CPU optimizer, not a GPU graphics-quality mod.

A dense base containing many lights, stands, stations, carts, effects and query-heavy pieces has much more opportunity for BCO to save work than a small world that is already GPU-bound.

During earlier development, an intentionally extreme scene with more than 120,000 instances in one area was reported at roughly 5 FPS without the optimizer and 14 FPS with an earlier optimizer build. Treat that only as a stress-test signal, not as a normal-world FPS promise.

Why can the default gain look small?

The default 0.2.0 profile is intentionally conservative. It leaves the higher-impact cadence/scheduler/SmokeRenderer replacements physically uninstalled. The default therefore focuses on correctness-first cache, no-op and exact-query savings.

If you are testing whether BCO can move FPS in a CPU-bound dense base:

1. benchmark the default conservative profile first;
2. then test Conservative Mode = false in the same scene;
3. keep all other graphics/mod settings identical;
4. compare frametime, 1% lows and p95/p99 spikes, not only average FPS;
5. verify lights, smoke, equipment, production visuals and multiplayer transitions after enabling aggressive features.

A feature counter proves that work was skipped; it does not by itself prove a measurable FPS gain.

---

Installation

Thunderstore / mod manager

Install the compiled release with a Thunderstore-compatible manager. BepInEx is required by the package/dependency chain.

Manual installation

Copy the compiled DLL into your BepInEx plugins directory, for example:

Valheim/BepInEx/plugins/BalrondCoreOptimizer/

Start Valheim once so BepInEx creates:

BepInEx/config/balrond.astafaraios.BalrondCoreOptimizer.cfg

Client or server?

BCO 0.2.0 is a client-side presentation/query optimizer. In batch/dedicated mode it deliberately skips installation of its client presentation patches.

Players can use their own local settings. For reproducible troubleshooting and benchmarks, compare clients using the same BCO build and config.

---

Recommended configuration

For normal play:

[0 General]
Enabled = true
Conservative Mode = true
Disable On Foreign Harmony Patches = true
Compatibility Recheck Seconds = 60
Visual Safety Refresh Seconds = 30
Static Visual Safety Refresh Seconds = 30

[9 Diagnostics]
Runtime Statistics = false

All individual optimization toggles default to true, but Conservative Mode overrides installation of the aggressive group until it is disabled.

Important aggressive defaults, used only when Conservative Mode permits them:

[1 Static Visuals]
ArmorStand Cloth Checks Per Second = 10

[4 Continuous Presentation]
Light Flicker Near Distance = 40
Light Flicker Mid Distance = 60
Light Flicker Far Distance = 100
Light Flicker Mid Updates Per Second = 10
Light Flicker Far Updates Per Second = 5
Light Flicker Distant Updates Per Second = 2
Light Flicker Distance Checks Per Second = 2
LightLod Distance Checks Per Second = 1
LightLod Checks Per Frame = 512
Smoke Renderer Updates Per Second = 10
Windmill Audio Updates Per Second = 10
Vagon Audio Updates Per Second = 10

[6 Memory and GC]
Smoke No-Allocation Chunk Transfers = true
Smoke Adaptive Chunk Particle Buffers = true
Smoke Initial Chunk Particle Capacity = 8

See Config/CONFIGURATION.md in the source package for the complete setting reference.

---

Diagnostics and benchmarking

For normal play keep:

Runtime Statistics = false

For testing, enable it temporarily. BCO reports interval deltas rather than only one lifetime total, which makes controlled A/B scene comparisons easier.

Recommended benchmark procedure:

1. Use the same save, character, camera position and graphics settings.
2. Let the scene settle for 30–60 seconds.
3. Measure with BCO disabled.
4. Restart and measure with BCO enabled in Conservative Mode.
5. If desired, repeat with Conservative Mode disabled.
6. Compare average FPS, frametime, 1% lows and visible spikes/stutter.
7. Check the BCO patch summary for active, delegated, disabled and effective-covered counts.
8. Verify production, visuals, smoke behavior and multiplayer state transitions.

The source package includes Diagnostics/MANUAL_TEST_PLAN.md with component-specific edge cases.

---

Frequently asked questions

Does BCO change gameplay?

It is designed not to. Production timing, dropped-item physics, structural support, combat, AI, smoke blockage and network authority remain outside the current optimizer scope.

Why can one optimization be delegated instead of active?

Another known mod may already own the same exact performance surface. When that composition has been audited, BCO can delegate the target instead of stacking two competing optimizers. Delegated targets count toward effective-covered.

Why can one optimization disable itself?

If another Harmony owner patches the exact same method and the combination has not been audited, BCO prefers vanilla/the other mod over an unproven patch-order dependency.

What happens after a Valheim update?

BCO does not globally reject a build because its MVID or raw IL hash changed. Each feature resolves its exact target signature at runtime. Missing/failed targets fall back independently to vanilla.

Do normal players need publicized assemblies?

No. Publicized assemblies are a developer/build-time dependency used to compile BCO's direct accesses to normally private Valheim members. Players install the compiled DLL.

Does BCO fix missing-prefab or corrupted ZNetScene exception loops?

Not in 0.2.0. That is a network-scene recovery problem, not one of BCO's current presentation/query optimizations. BCO intentionally leaves ZNetScene protected. Mods such as FpsProtector target that separate failure mode.

Does BCO patch WearNTear or register WearNTear RPCs?

No. WearNTear/WearNTearUpdater are protected, and BCO does not call ZNetView.Register for gameplay objects. Structural-integrity behavior remains owned by vanilla/Better Build and other dedicated systems.

Does BCO optimize dropped items?

No. ItemDrop, Floating, Rigidbody ownership and ZSyncTransform are deliberately untouched.

---

Bug reports and support

For bug reports and compatibility help:

Balrond's Den — Discord

Please include:

1. Balrond Core Optimizer version.
2. Valheim version.
3. Complete BepInEx log.
4. Full mod list/profile code.
5. Single-player, local host or dedicated-server client.
6. The exact object/action that causes the problem.
7. Whether the issue disappears when the matching BCO feature is disabled.
8. The BCO [patches] summary line.
9. For performance reports: before/after frametime or FPS measured in the same scene.

For Harmony/loading/compatibility issues, the complete log is substantially more useful than a screenshot alone.

---

Building from source

BCO uses direct access to normally private Valheim members to avoid reflection in hot paths. The source project therefore expects the appropriate Valheim publicized assemblies at build time.

This is a developer requirement only. The compiled release does not require players to install publicized assemblies.

---

Support development

Balrond Core Optimizer and Balrond's other public Valheim projects are available to the community. Support helps fund maintenance, compatibility work, profiling, documentation and future performance systems.

Support Balrond on Ko-fi

For custom mods, integrations or commissioned work:

Balrond's Den

Public bug fixes are not paywalled. Project-specific implementation, private configuration and commissioned integration may require a separate quote.