Skip to content

Universal library for crating crash reports for a game

License

Notifications You must be signed in to change notification settings

BUTR/BUTR.CrashReport

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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

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.