MagiCorp Valheim TickProfiler

TickProfiler 1.0 is a Valheim dedicated-server and client performance profiler focused on real-time tick deadlines, main-thread hitches, and safe mod attribution.

Server profiler

The dedicated-server component records:

• Effective 50 Hz FixedUpdate rate based on real wall-clock deadlines. Unity catch-up bursts never repay deadlines that were already missed.
• Correct pending-deadline accounting when a stall crosses a report boundary.
• Main Update throughput, p95/p99/worst gaps, stall count, excess wall time and cumulative hitch buckets.
• Event-correlated hitch attribution with confidence levels. Managed GC is reported as observed during a hitch rather than automatically blamed.
• Safe BepInEx plugin-loop attribution for Update, FixedUpdate and LateUpdate. TickProfiler never instruments another mod's Harmony Prefix/Postfix/Finalizer methods.
• Harmony patch-owner context for game methods, reported as involved mods rather than assumed causes.
• Runtime context including players, ZDO count, active objects, loaded/generated zones, thread count and VM network throughput.
• Process RSS/private memory, managed heap, GC collections and CPU usage.
• TickProfiler self-overhead, timed calls/sec, output queue depth and exception-stack recovery count.
• Optional 1-in-N sampling for deep/high-frequency game methods. Aggregate rates are scaled while worst-call values remain observed values.

The first 45 seconds are ignored by default so scene/world startup does not pollute runtime hitch statistics.

Hitch forensics

Significant hitches can create JSON captures under:

BepInEx/tickprofiler-forensics/

Each capture includes the hitch duration, estimated missed fixed deadlines, attribution/confidence, runtime context and the preceding performance samples. File output is serialized on a background worker so slow storage does not block the Valheim main thread.

Output

Normal output is written to:

• BepInEx/LogOutput.log
• BepInEx/tickprofiler-latest.txt
• BepInEx/tickprofiler-status.json
• BepInEx/tickprofiler-forensics/*.json for qualifying hitches

Touch BepInEx/tickprofiler.request to request an immediate full snapshot. The request file is polled at a configurable low rate rather than once per frame.

Client overlay

Install the same package on a Windows Valheim client and press F8 to toggle the overlay.

The client shows:

• Local FPS/frame-gap timing, stalls, CPU, RSS, managed memory and GC activity.
• Server effective tick rate and Update rate.
• Server runtime context and TickProfiler self-overhead.
• Top server consumers.
• Rolling five-minute client and server graphs.
• Exact server hitch-event markers at the time the hitch occurred rather than only at the next periodic snapshot.
• Snapshot age, server-side Steam transport ping for every connected player, and server/client protocol compatibility.

TickProfiler 1.0 uses protocol v2 while retaining legacy v1 hello/snapshot compatibility with 0.x clients/servers where possible. Overlay text is cached between refreshes to avoid allocating new strings every render frame.

Important server settings

Created in BepInEx/config/magicorp.valheim.tickprofiler.cfg:

• ReportIntervalSeconds = 10
• OverlayIntervalSeconds = 2
• RequestPollSeconds = 1
• StartupWarmupSeconds = 45
• DeepGameProfiling = true
• ProfilePluginLoops = true
• HotMethodSampleEveryN = 4
• TopConsumers = 12
• SpikeThresholdMs = 20
• MainThreadStallThresholdMs = 75
• WriteHitchForensics = true
• ForensicHitchThresholdMs = 100
• AnnounceHitchesInChat = true
• AnnounceHitchesInGame = false
• AnnounceHitchThresholdMs = 250
• AnnounceHitchCooldownSeconds = 10

ProfileModHarmonyMethods is retained only as a deprecated 0.x compatibility key and migrates to ProfilePluginLoops.

Validation

TickProfiler 1.0.0 is built against Valheim 1.0.14 and BepInExPack Valheim 5.4.2350.

The included core tests validate deadline accounting, Unity catch-up behavior, report-boundary pending misses, JSON escaping, hitch buckets and statistic resets. A spare-server burn test also validates controlled 100/250/500/1000 ms stalls, sustained overload and exception-stack recovery.

TickProfiler is diagnostic only and does not intentionally change gameplay state.