BugSplat.Godot 0.1.0

BugSplat

Crash and error reporting built for busy developers.

Introduction

BugSplat's BugSplat.Godot package provides crash and exception reporting for Godot C# projects. BugSplat provides you with invaluable insight into the issues tripping up your users. Our Godot integration collects stack traces, log files, and custom metadata so that you can fix bugs and deliver a better user experience.

Before you proceed, please make sure you have completed the following checklist:

• Sign Up as a new BugSplat user
• Log In to your account

Installation

BugSplat's BugSplat.Godot package can be added to your Godot C# project via NuGet.

dotnet add package BugSplat.Godot

This automatically pulls in the BugSplatDotNetStandard dependency. No additional packages are required.

Quick Start

Create a script that initializes BugSplat and add it as an autoload in your project.

using BugSplat.Godot;
using Godot;
using System;

public partial class BugSplatAutoload : Node
{
    private BugSplatNode _bugSplat;

    public override void _Ready()
    {
        _bugSplat = BugSplatNode.Create(
            database: "fred",
            application: "my-godot-crasher",
            version: "1.0.0"
        );

        AddChild(_bugSplat);

        GD.Print("[BugSplat] Crash reporting initialized.");
    }
}

Register the script as an autoload in Project > Project Settings... > Globals > Autoload, and unhandled exceptions will be automatically captured and posted to BugSplat.

To view your crash reports, navigate to the BugSplat Dashboard and ensure you have selected the correct database.

Configuration

After creating a BugSplatNode, you can configure the underlying client via the Client property:

_bugSplat = BugSplatNode.Create("fred", "my-godot-crasher", "1.0.0");

_bugSplat.Client.Description = "Default crash description";
_bugSplat.Client.Email = "support@bugsplat.com";
_bugSplat.Client.Key = "optional-key";
_bugSplat.Client.Notes = "additional notes";
_bugSplat.Client.User = "Fred";
_bugSplat.Client.Attachments.Add(new FileInfo("/path/to/attachment.txt"));

You can also configure BugSplatNode behavior directly:

_bugSplat.PostExceptionsInEditor = false;
_bugSplat.CaptureGodotLog = true;

Usage

Automatic Exception Capture

When a BugSplatNode is in the scene tree, it automatically hooks into AppDomain.CurrentDomain.UnhandledException and TaskScheduler.UnobservedTaskException. Any unhandled exceptions are posted to BugSplat with rate limiting (1 report per 3 seconds).

Try/Catch Reporting

Exceptions can be sent to BugSplat in a try/catch block by calling Post:

try
{
    throw new Exception("BugSplat rocks!");
}
catch (Exception ex)
{
    await _bugSplat.Post(ex);
}

Default values on the BugSplatNode can be overridden per-report with ExceptionPostOptions:

var options = new ExceptionPostOptions()
{
    Description = "a new description",
    Email = "barney@bugsplat.com",
    Key = "a new key!",
    Notes = "some new notes!",
    User = "Barney"
};

options.Attachments.Add(new FileInfo("/path/to/additional.txt"));

await _bugSplat.Post(ex, options);

Event Callbacks

You can listen for crash post results via C# events:

_bugSplat.OnCrashPosted += (response) =>
{
    GD.Print($"[BugSplat] Crash report posted: {response.StatusCode}");
};

_bugSplat.OnCrashPostError += (ex) =>
{
    GD.PrintErr($"[BugSplat] Failed to post crash: {ex.Message}");
};

Preventing Repeated Reports

By default, BugSplat prevents reports from being sent at a rate greater than 1 per every 3 seconds. You can override this by setting ShouldPostException:

_bugSplat.ShouldPostException = (ex) =>
{
    // Custom filtering logic
    return ex is not InvalidOperationException;
};

Adding System Information

You can use Attributes to attach structured system information to every crash report:

_bugSplat.Client.Attributes["os.name"] = OS.GetName();
_bugSplat.Client.Attributes["os.version"] = OS.GetVersion();
_bugSplat.Client.Attributes["locale"] = OS.GetLocale();
_bugSplat.Client.Attributes["processor.name"] = OS.GetProcessorName();
_bugSplat.Client.Attributes["processor.count"] = OS.GetProcessorCount().ToString();
_bugSplat.Client.Attributes["video.adapter.name"] = RenderingServer.GetVideoAdapterName();
_bugSplat.Client.Attributes["video.adapter.vendor"] = RenderingServer.GetVideoAdapterVendor();
_bugSplat.Client.Attributes["godot.version"] = Engine.GetVersionInfo()["string"].ToString();

Attaching Screenshots

You can capture a screenshot from the viewport and attach it to a crash report:

var image = GetViewport().GetTexture().GetImage();
var path = ProjectSettings.GlobalizePath("user://screenshot.png");
image.SavePng(path);
_bugSplat.Client.Attachments.Add(new FileInfo(path));

API

BugSplatNode

ExceptionPostOptions

Contributing

BugSplat loves open source! If you feel that this package can be improved, please open an Issue. If you have an awesome new feature you'd like to implement, we'd love to merge your Pull Request. You can also send us an email, join us on Discord, or message us via the in-app chat on bugsplat.com.