MagiCorp Valheim Tick Profiler

TickProfiler is a Valheim dedicated-server performance profiler with an optional in-game client overlay.

Server profiler

The dedicated server records:

• Effective server tick rate versus the nominal 50 Hz target. Missed real-time deadlines reduce this rate and later Unity catch-up FixedUpdates do not restore it.
• Main Update throughput plus p95/p99/worst wall-clock gaps.
• Main-thread stall count, worst contiguous gap and excess wall time lost to stalls, independent of whether the cause can be attributed to managed code.
• Process CPU, managed memory and GC collections.
• Ranked self/inclusive time for networking, ZDO replication, AI, item drops, spawning, structures, terrain, production and other hot paths.
• Timing for supported Harmony Prefix/Postfix/Finalizer methods from other BepInEx plugins, including ValheimPlus.

Output is written to:

• BepInEx/LogOutput.log
• BepInEx/tickprofiler-latest.txt
• BepInEx/tickprofiler-status.json

Touch BepInEx/tickprofiler.request to force an immediate server snapshot.

Client overlay

Install the same Thunderstore package on a Windows Valheim client to enable the overlay. The client component profiles local frame/main-thread timing but does not alter gameplay.

• Press F8 to toggle the overlay.
• Shows local client frame throughput, p95/p99 frame gaps, main-thread stall count, worst gap, cause and lost wall time.
• Shows rolling 5-minute client FPS/hitch and server tick-rate/hitch graphs.
• Shows local process CPU, managed memory and GC activity.
• Shows server effective tick rate and Update rate.
• Shows server main-thread stalls, p99/worst update gaps and event-correlated cause, including exact plugin/type/method where measurable.
• Shows server CPU, memory and GC data.
• Shows the current top server-side consumers and their worst call time.
• Shows snapshot age and client-to-server ping.

The server only sends profiler snapshots to clients that announce the TickProfiler overlay. Clients without TickProfiler are unaffected.

Client settings are created under BepInEx/config/magicorp.valheim.tickprofiler.client.cfg and include toggle key, default visibility, font size, position, width, UI scale, local stall threshold and ProfilePluginMethods. UIScale = 0 automatically scales from 1x at 1080p to 2x at 4K.

Server configuration

Created as BepInEx/config/magicorp.valheim.tickprofiler.cfg. Important settings:

• ReportIntervalSeconds = 10
• DeepGameProfiling = true
• ProfileModHarmonyMethods = true
• TopConsumers = 12
• SpikeThresholdMs = 20
• MainThreadStallThresholdMs = 75
• AnnounceHitchesInChat = true broadcasts significant hitches into normal Valheim chat for connected TickProfiler clients.
• HitchChatTitle = Server controls the chat sender/title.
• AnnounceHitchesInGame = false optionally also shows a top-left HUD notification.
• AnnounceHitchesInGame = true
• AnnounceHitchThresholdMs = 250
• AnnounceHitchCooldownSeconds = 10

Compatibility

Built and validated against Valheim 1.0.12 and BepInExPack Valheim 5.4.2350. The profiler does not change gameplay state.

Changelog

1.0.3

• Removed routed-RPC RTT from the live latency display and telemetry.
• Server now samples Valheim/Steam transport ping directly from every connected player socket.
• F8 overlay shows Steam transport ping for all players, including players without the TickProfiler client overlay installed.
• Network/status JSON identifies these values as steam-transport.

1.0.2

• Client overlay now uses Valheim/Steam's native socket transport ping for the local player's displayed ping.
• Routed RPC round-trip timings are explicitly labelled as RPC/game-message latency rather than network ping.
• Removes the misleading 33/66 ms quantisation caused by Valheim update/RPC scheduling on low-latency LAN connections.

1.0.1

• Replaced Valheim GetServerPing() display with TickProfiler-owned request/reply RTT measurement.
• Added live per-player RTT to the client overlay.
• Added tickprofiler-network.json and per-player RTT to status JSON for dashboards.
• Added configurable PlayerPingIntervalSeconds with a 1 second default.

1.0.0

• Major TickProfiler redesign validated against Valheim 1.0.14.
• Fixed report-boundary deadline accounting so stalls cannot move missed FixedUpdate deadlines into the following clean report or be counted twice.
• Added background/serialized file output for status, text and forensic captures; the main thread no longer performs periodic disk writes.
• Reduced tickprofiler.request filesystem polling from every frame to a configurable low-rate poll.
• Added startup warmup and measurement-baseline reset so world/scene startup does not pollute runtime hitch, CPU or GC statistics.
• Added exception-safe plugin-loop profiling plus root-loop recovery; recovery count is exposed in self-health output.
• Added real RSS/private memory alongside managed heap memory.
• Added profiler self-overhead, timed calls/sec and output queue depth.
• Added runtime context: player count, ZDO count, active objects, loaded/generated zones, threads and VM network throughput.
• Added cumulative hitch severity buckets.
• Added confidence-labelled hitch attribution and stopped treating coincident GC as automatically causal.
• Added Harmony patch-owner context without attributing blame to patch owners.
• Added configurable 1-in-N sampling for deep/high-frequency game methods.
• Added protocol v2/version negotiation while retaining legacy v1 compatibility paths.
• Added exact hitch-event RPC markers for the client history graph.
• Added independent lightweight overlay refresh and cached client display text to reduce allocations.
• Renamed ProfileModHarmonyMethods to ProfilePluginLoops; the old key is retained for config migration.
• Added asynchronous hitch forensic JSON captures with preceding performance/runtime samples.
• Added dependency-free regression tests for tick deadlines, catch-up behavior, pending report-boundary misses, JSON escaping, hitch buckets and stat resets.
• Burn-tested on the spare Valheim 1.0.14 server using controlled 100/250/500/1000 ms stalls, sustained 8 ms/frame load, sustained 45 ms/frame overload, and an intentional plugin exception.

0.4.4

• Fixed effective server tick rate so missed real-time FixedUpdate deadlines are counted from actual wall-clock FixedUpdate gaps rather than inferred from the 30 Hz Update loop.
• Normal Unity 50 Hz physics batching on a ~30 Hz dedicated-server player loop is not penalised, while genuine 40/60/100 ms FixedUpdate gaps permanently record 1/2/4 missed deadlines.
• Effective tick rate is now capped by actual FixedUpdate throughput, so it can never report 50 Hz when fewer successful FixedUpdates ran.
• Unity catch-up bursts remain visible as raw throughput but cannot restore missed deadlines in the headline tick rate.

0.4.3

• Critical compatibility fix: TickProfiler no longer Harmony-patches other mods' Prefix/Postfix/Finalizer methods.
• Prevents early JIT/static-initializer side effects seen with Valheim Plus FurnaceDefinitions and similar mods.
• Plugin attribution remains enabled for safe BepInEx Update, FixedUpdate, and LateUpdate loops.
• Main-thread/frame stall detection, server profiling, hitch chat alerts, and 5-minute graphs are unchanged.

0.4.2

• Simplified BepInEx logger name to TickProfiler.
• Made periodic console reports a single multiline block.
• Added timestamped separators so consecutive profiles are easy to distinguish.
• Compact, aligned top-consumer table for AMP/mobile console readability.

0.4.1

• Significant hitches are broadcast through the TickProfiler client mod into normal Valheim chat for every connected TickProfiler client.
• Added AnnounceHitchesInChat and HitchChatTitle; chat broadcast defaults on with sender Server.
• Top-left HUD hitch messages are independently configurable and default off to avoid duplicate alerts.

0.4.0

• Replaced raw FixedUpdate catch-up throughput as the primary tick metric with effective tick rate based on real-time deadlines missed during main-thread stalls. Unity catch-up FixedUpdates no longer restore the displayed tick rate.
• Added per-hitch event attribution. Long-running game/mod methods are correlated with the exact hitch window and reported by plugin, type and method when they credibly explain the stall.
• Added configurable in-game server hitch notices (AnnounceHitchesInGame, AnnounceHitchThresholdMs, AnnounceHitchCooldownSeconds) including duration and detected cause.
• Added Game.CollectResources profiling to improve attribution of periodic Unity resource cleanup.
• Added client-side plugin method attribution for BepInEx Update/FixedUpdate/LateUpdate and Harmony patch methods.
• Added rolling 5-minute client graphs: local client FPS/hitch history and server effective tick-rate/hitch history.

0.3.0

• Reworked stall detection around wall-clock main-thread gaps so Unity catch-up FixedUpdate bursts can no longer hide freezes behind an apparent 50 Hz average.
• Added server main-thread stall count, worst gap, excess lost time, p99 update gap and explicit unattributed native/Unity/I/O/GC reporting.
• Added direct save-path timing for ZDOExtraData.PrepareSave and ZNet.SaveWorldAndPlayerProfiles.
• Added real client-side profiling: frame gaps, p95/p99, local main-thread stalls, lost time, process CPU, managed memory and GC counts.
• Client F8 overlay now shows local client health above the server profiler data.

0.2.4

• Fixed the client overlay on Valheim 1.0.12 by invoking non-public ZRoutedRpc.GetServerPeerID() through runtime reflection.
• Eliminates repeated MethodAccessException spam and allows the client hello/snapshot exchange to proceed.

0.2.3

• Reworked periodic server console output into a short health/stall summary plus a top-5 consumer table.
• Detailed text and JSON snapshots remain unchanged.

0.2.2

• Fixed the client overlay losing its snapshot RPC handler when Valheim replaces ZRoutedRpc during the frontend-to-world transition.
• The client now detects each new routed-RPC instance, re-registers the snapshot handler, and immediately re-announces itself to the server.

0.2.1

• Fixed the client overlay toggle on Valheim 1.0.12 by using Valheim's ZInput path instead of legacy UnityEngine.Input.
• Added explicit client RPC registration and first-snapshot diagnostics.
• Added server logging when an overlay client registers.

0.2.0

• Added an optional client-side overlay, toggled with F8 by default.
• Added server-to-client RPC snapshots for current Update/FixedUpdate rates, stalls, CPU/GC data and top consumers.
• Client component is read-only and performs no profiling.
• Server only sends profiler data to clients that have the overlay installed.
• Kept the dedicated server profiler and client UI as separate DLLs so IMGUI is never loaded by the server plugin.

0.1.0

• Initial release.
• Reports server Update and FixedUpdate rates.
• Detects frame/tick stalls and gap percentiles.
• Profiles Valheim networking, ZDO replication, AI, spawning, item drops, structures, world systems and supported Harmony mod patches.
• Writes periodic log output plus JSON and text snapshots.
• Supports on-demand snapshots using BepInEx/tickprofiler.request.