RimWorks.RimLogging 3.0.4

RimLogging: RimWorld log viewer and bug report sharing

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

Read your RimWorld log inside the game. Filter it down to the red error you care about, then share it as a link with one click. RimLogging is also a structured logging framework for RimWorld 1.6+ mods. It replaces vanilla Verse.Log and UnityEngine.Debug.Log with one filterable pipeline. Every dependent mod shares it.

If you have used HugsLib's publish-log button, this covers the same job. HugsLib uploads the whole file as one wall of text and hands you a link. RimLogging lets you narrow to one channel and one level first, then sends what is left with your mod list attached.

• Hierarchical channels (XML defs or transient) with prefix-based resolution.
• Serilog-style templated messages plus anonymous-object structured context.
• Six levels: Trace, Debug, Info, Warn, Error, Fatal.
• Multi-sink output (Verse writeback, rolling text/NDJSON files, in-memory) with a plugin sink API.
• Lock-free MPSC queue with a background drain; synchronous bypass for Error / Fatal.
• Three-pane in-game log viewer with a channel tree and an expression filter DSL. The detail pane docks to the bottom, docks to the right, or pops out into its own window.
• A Roslyn analyzer in the NuGet package that flags leftover Verse.Log calls at build time.

Install

As a Steam Workshop dependency (recommended for shipped mods): end users install the Workshop mod once and every consumer mod shares one dll. Declare it in your About/About.xml:

<modDependencies>
    <li>
        <packageId>RimWorks.RimLogging</packageId>
        <displayName>RimLogging</displayName>
        <steamWorkshopUrl>steam://url/CommunityFilePage/REPLACE_WITH_WORKSHOP_ID</steamWorkshopUrl>
    </li>
</modDependencies>
<loadAfter>
    <li>RimWorks.RimLogging</li>
</loadAfter>

Or bundle it from NuGet. The build copies the dll, and its System.Text.Json runtime dependencies, into your mod's Assemblies/, so you don't need the Workshop dependency:

dotnet add package RimWorks.RimLogging

Usage

using RimWorks.RimLogging;

// Templated message with positional args.
Log.Info("colony {Name} founded at {Tile}", colony.Name, colony.Tile);

// Structured context from an anonymous object.
Log.Warn("low food", new { pawn, days_left = 2 });

// Exceptions: pass the exception first, or fold it into the context.
Log.Error(ex, "save failed");

// Tick-loop throttling: once ever, or at most once per interval. The key is global.
Log.WarnOnce("no-power", "the reactor has no power");
Log.WarnEvery("no-power", TimeSpan.FromMinutes(1), "the reactor still has no power");

// Timing: logs the message with an elapsed_ms context value when the block closes.
using (Log.Timed("worldgen")) { GenerateWorld(); }

// Explicit channel.
Log.Info("Cosmere.Roshar.Surgebinding", "bond formed", new { spren = spren.Label });

// Explicit channel + templated args: pass an explicit array so the channel
// overload is selected (a bare trailing value binds as structured context).
Log.Info("Cosmere.Roshar.Surgebinding", "bond formed with {Spren}", new object?[] { spren.Label });

The first string argument is the channel only when a later argument disambiguates the overload; Log.Info("text", arg) treats "text" as the message. Formatting is lazy: if no registered sink accepts the entry's level, the template is never rendered.

Docs

• Channels: ChannelDef XML, field reference, prefix resolution, built-in channels.
• Filter DSL: grammar and examples for the viewer's filter box.
• Custom sinks: the ILogSink API, SinkDef XML, built-in sinks.
• Verse.Log analyzer: the RIMLOG001 and RIMLOG002 build warnings, and what to call instead.
• Settings and bug bundles: the mod settings page and the share-bundle payload.
• Bundle upload worker: the Cloudflare Worker behind bug-report uploads.

Contributing

See CONTRIBUTING.md for build commands, commit conventions, and translation notes.

More modding tools from RimWorks

MIT licensed.