RimWorks.RimObs.Library 2.9.1

RimObs: RimWorld performance profiler and lag diagnostics

<img src="https://raw.githubusercontent.com/RimWorks/rimworld-observability-collector/main/About/ModIcon.png" alt="RimObs icon" width="96" align="right">

Find out which mod is eating your TPS. RimObs profiles a running RimWorld colony and records where every tick goes: timed sections, counters, gauges, histograms, GC events, allocation samples, and Harmony patch conflicts. An out-of-process collector aggregates the data, serves a dashboard, and exports diagnostic bundles.

Unlike Dubs Performance Analyzer, which shows a live readout for the session you are in, RimObs stores every session in a local database. Play once with a mod and once without, then diff the two hotspot tables and load orders to see what actually moved. Any session exports as a speedscope profile, and the collector exposes a Prometheus endpoint.

Mod authors register their own named sections and metrics, which land in the same dashboard as the game's.

Full documentation -->

For mod authors

Add the library:

dotnet add package RimWorks.RimObs.Library

Instrument a tick:

using RimWorks.RimObs.Api;

private static readonly SectionHandle Tick =
    Obs.Profile.RegisterSection("tick");

public void Tick() {
    using (Obs.Profile.Measure(Tick)) {
        // ... your work ...
    }
}

Section names are auto-prefixed with your mod's packageId. See the Quickstart for the full path from zero to dashboard.

For players

Subscribe to the Workshop item your other mods declare as a dependency. The collector launches automatically with the game and opens the dashboard in your browser. See Installation.

Documentation

• Mod-author quickstart
• Profile API and Metrics API
• Declarative profiling.xml
• Hot-path discipline
• Wire protocol and Local HTTP API
• Architecture

For contributors

The repo deliberately spans three .NET targets because each piece runs in a different host.

Test projects (RimObs.Library.Tests/, RimObs.Collector.Tests/) are net8.0 xUnit hosts; they exercise the library logic that is RimWorld-independent.

Root layout

The non-obvious neighbors at the repo root exist because this is both a RimWorld mod and a multi-project .NET solution:

• About/: RimWorld mod metadata (About.xml, Preview.png, loadFolders.xml).
• Assemblies/: RimWorld's deploy directory. RimObs.Library builds straight here.
• RimObs.slnx: single solution so Rider/VS resolve RimObs.Wire from both net472 and net10.0 consumers.
• Makefile + make.ps1: see make build, make test, make publish-collector.
• docs/wiki/: source for the wiki. Edit here, not on the wiki site; CI mirrors on push to main.

Quick start

make build              # SPA + full solution
make test               # xUnit suites
make watch              # collector hot-reload at :17654
make publish-collector  # self-contained binaries for win/linux/osx

Conventions

• Hot-path discipline for RimObs.Library is mandatory: zero allocation, exception-safe, no locks, no Task/async on the steady path. See Hot-path discipline for the full rules.
• Wire protocol is MessagePack with per-batch schema_version. Default port 17654 for HTTP and UDP in standalone mode; the first free port at or above 25950 when launched from the game. See Wire protocol.

More modding tools from RimWorks

License

MIT. See LICENSE.