Valheim Community Patch GC

Garbage collector tuning for Valheim dedicated servers, a companion to Valheim Community Patch.

It shipped inside the Community Patch in 0.31.0 and moved out in 0.32.0. Reaching the collector's settings means reading and writing the Mono runtime's own memory, which malware scanners flag, and that should not weigh on a mod every player installs. This plugin needs only BepInEx.

What it does

Dedicated servers only; clients and listen hosts ignore it. Valheim runs Unity's incremental garbage collector, and on a busy server each collection ends in one stop-the-world pass with no time limit. On a large world that pass measured about 55 ms per GB of heap: 330 ms at 6 GB, 460 ms at 8.4 GB. A bigger heap also means fewer collections, so the total time paused stays about the same whatever the heap size. The same collection pass is where a large server can abort with Unexpected mark stack overflow.

The settings live in the Server - Garbage Collector section of BepInEx/config/MidnightsFX.ValheimCommunityPatchGC.cfg. Only the mark stack setting is on by default; setting any of them to 0 gives back the game's own value.

• GC Mark Stack Target Entries (Linux), default 4194304 (64 MiB) — grows the collector's mark stack ahead of need. The collector normally grows it only after a pass that nearly overflowed it, and a pass that does overflow it aborts the server.
• GC Free Space Divisor (Linux), default 0 (the collector's own 3) — how far the heap grows between collections. It trades pause length against frequency: lower gives fewer, longer pauses and uses more memory; higher gives shorter, more frequent ones.
• GC Time Slice Milliseconds, default 0 (the game's 3 ms) — the incremental collector's per-frame budget. On a busy server it did not change the pauses; a longer slice only lengthens the short pause that opens each collection.

The divisor and the mark stack reach the collector through symbols only the Linux server runtime exports; on a Windows server they do nothing.

Console command

vcp_gc prints the collector's current state: whether it is incremental, the time slice as Unity, Mono and the collector each see it, the divisor, the heap, the last rescan's dirty pages and the mark stack. It also changes each setting live, so the effect can be watched on a profiler:

• vcp_gc slice <ms>, vcp_gc divisor <n>, vcp_gc markstack <entries> — set and save a value; 0 restores the game's own.
• vcp_gc stats on|off (Linux) — the collector's own log: a few lines per collection with its stop-the-world times and how much it rescanned. It goes to the server's standard error (or GC_LOG_FILE, if that was set when the server started), not to the BepInEx log. Not saved.

An admin can run it remotely from their own console; that needs this plugin installed on their client too, where it does nothing else. The replies are written to the server log.

Installation

Install it on the dedicated server with a mod manager, or drop ValheimCommunityPatchGC.dll into BepInEx/plugins. It requires BepInEx and is packaged with Valheim Community Patch 0.32.0 or later as a dependency. With Community Patch 0.31.x, which has its own copy of these settings, it logs a warning and does nothing.

Settings changed in the Community Patch 0.31.0 config are not carried over; set them again in this plugin's config. The Community Patch's old Server - Garbage Collector section can be deleted.

Credit and sources

• bdwgc and Unity's fork of it and of Mono — the collector's source is the reference for these settings; no code was used.
• Iron Gate Studio — Valheim itself; no game code is redistributed.

Changelog

1.0.0

- The server garbage collector settings from Valheim Community Patch 0.31.0, as their own plugin.
  Reaching the collector's settings means reading and writing the Mono runtime's memory, which
  malware scanners flag, so they moved out of the Community Patch, which removes them in 0.32.0.
- GC Mark Stack Target Entries (Linux), default 4194304 (64 MiB): grows the collector's mark stack
  ahead of need, so a large heap is far less likely to abort the server with "Unexpected mark
  stack overflow".
- GC Time Slice Milliseconds and GC Free Space Divisor default to 0, the game's own values:
  production data showed the final pause of each collection grows with the heap (about 55 ms per
  GB), not with the slice, and a lower divisor only makes pauses longer and rarer.
- On Linux the divisor is now applied at startup; in the Community Patch 0.31.0 it only took
  effect after the next change to any garbage collector setting.
- The `vcp_gc` console command prints the collector's state and changes each setting live.
- Does nothing alongside Community Patch 0.31.x, which has its own copy of these settings.