MagiCorp Valheim Tick Profiler

Server-side BepInEx diagnostic plugin for Valheim dedicated servers.

What it reports

• Effective Unity FixedUpdate rate versus configured nominal rate.
• General Update rate.
• Fixed/update gap average, p95, worst gap, and >20/>40/>100 ms stall counts.
• Process CPU use, managed memory and GC collections.
• Ranked self-time and inclusive-time for key Valheim subsystems:
  • ZNet / ZDO replication
  • ZNetScene / ZoneSystem / spawning
  • AI and Character fixed updates
  • ZSyncTransform / ZSyncAnimation
  • item drops, projectiles, ships, fish
  • building wear/support
  • smelters / loot spawners / terrain
• Optional timing of Harmony Prefix/Postfix/Finalizer methods from other loaded BepInEx plugins, including ValheimPlus.

Instrumentation uses a thread-local nested timing stack, so tracked child time is removed from tracked parent self-time. This makes the ranked selfMsPerSec field useful for identifying the actual instrumented consumer instead of simply double-counting nested calls.

Output

• BepInEx/LogOutput.log: compact periodic report.
• BepInEx/tickprofiler-latest.txt: most recent human-readable snapshot.
• BepInEx/tickprofiler-status.json: machine-readable current snapshot.

Touch BepInEx/tickprofiler.request to force an immediate snapshot. The plugin consumes and removes the request file.

Config

Created as BepInEx/config/magicorp.valheim.tickprofiler.cfg.

Important settings:

• ReportIntervalSeconds = 10
• DeepGameProfiling = true
• ProfileModHarmonyMethods = true
• TopConsumers = 12
• SpikeThresholdMs = 20

Build

Targets .NET Framework 4.8 and references the Valheim 1.0.12/BepInEx assemblies under /opt/valheim-port/reference-1.0.12 by default.

HOME=/root DOTNET_CLI_HOME=/root /opt/valheim-port/dotnet/dotnet build -c Release

The plugin does not change gameplay state. Installing or removing the DLL requires a normal BepInEx process start to load/unload it.

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.