BUTR.CrashReport

This is a library that provides detailed crash reports for .NET based games. It is currently used in the game Mount & Blade 2: Bannerlord. For more information, check out ButterLib.
Unity is supported, see the Valheim PoC as an example.

Table of Contents

• Data Provided
• Export Formats
• Examples
• Rendering Backends
• Usage
• Tools
• Versioning

Data Provided

BUTR.CrashReport analyzes the stacktrace of the exception to find the original method and any Harmony patches that were applied.
It decompiles methods - Native code (NASM syntax), IL code, IL+C# and C# code where possible.
It also gathers all currently loaded mods and their capabilities (like using Shell, FileSystem, etc).
If a plugin loader like BepInEx exists, its plugins will also be exposed.

Export Formats

• HTML - 'lite' and 'fat' versions. The 'lite' version includes the crash report data and the logs. The 'fat' version can include a minidump, a save file and a screenshot.
• ZIP - stores the JSON version of the crash report, a log file, a minidump, a save file and a screenshot.

crashreport.zip/
├── crashreport.json
├── logs.json
├── minudump.dmp
├── save.sav
└── screenshot.bmp

Examples

• HTML Lite - https://report.butr.link/05C876
• JSON of that crash report https://report.butr.link/05C876.json

Rendering Backends

• ImGui - uses Dear ImGui (cimgui) via GLFW and OpenGL
• WinForms - uses the HTML format and renders it via the WebBrowser control

Usage

Add the BUTR.CrashReport NuGet package to your project The following interfaces should be implemented:

• IAssemblyUtilities - Provides functionality related to assemblies.
• ICrashReportMetadataProvider - Provides metadata for a crash report.
• IHarmonyProvider - Provides information about Harmony patches, if there are any.
• ILoaderPluginProvider - Represents the loader plugin information.
• IModuleProvider - Provides the implementation for getting the module information.
• IModelConverter - Converts the data interfaces to models.
• IPathAnonymizer - Anonymizes paths.
• IStacktraceFilter - Represents a filter that can be used to filter out irrelevant stack trace frames from a crash report.

Refer to BUTR.CrashReport.Bannerlord.Source and Valheim.CrashReporter for implementation examples.

Add a backend

• BUTR.CrashReport.Renderer.ImGui for the ImGui backend

private static IEnumerable<LogSource> GetLogSources() { .. }
...
var crashReport = CrashReportInfo.Create(exception, metadata, ...);
var crashReportModel = CrashReportInfo.ToModel(crashReport, ...);
var logSources = GetLogSources().ToArray();
CrashReportImGui.ShowAndWait(crashReportModel, logSources, ...);

• BUTR.CrashReport.Renderer.WinForms for the WinForms backend

private static IEnumerable<LogSource> GetLogSources() { .. }
...
var crashReport = CrashReportInfo.Create(exception, metadata, ...);
var crashReportModel = CrashReportInfo.ToModel(crashReport, ...);
var logSources = GetLogSources().ToArray();
var forms = new CrashReportWinForms(crashReportModel, logSources, crashReportRendererUtilities);
forms.ShowDialog();

Tools

• BUTR.CrashReport.Tool - converts a ZIP crash report format to the HTML crash report format
• BUTR.CrashReport.Bannerlord.Parser - parses old crash reports for Bannerlord that didn't use the new Json format (pre version 13)

Versioning

The project follows semantic versioning. Only changes related to the JSON model will affect the versioning.