How to Add In-Game Bug Reporting to Your Godot Project

This getting started Godot guide walks you through the setup process step by step. Godot has become the engine of choice for a growing wave of indie developers, and for good reason. It is lightweight, open source, and getting better with every release. But one area where Godot projects often fall behind is post-launch observability. Your players are hitting bugs you never see. This guide walks you through adding Bugnet to your Godot project so you can capture crash logs, screenshots, and detailed bug reports directly from your running game.

By the end of this tutorial, you will have a fully working in-game bug reporter that captures device information automatically, lets players describe issues in their own words, and pipes everything into your Bugnet dashboard where you can triage and resolve issues without ever asking a player to "send their log files."

Step 1: Install the Bugnet Addon

The Bugnet SDK for Godot ships as a standard addon. You can grab it from the Bugnet SDKs page or clone it directly from the repository. Either way, the result is a folder that goes into your project's addons directory.

Copy the bugnet folder into your project so the structure looks like this:

your-project/
  addons/
    bugnet/
      sdk.gd
      reporter.gd
      capture.gd
      plugin.cfg
  scenes/
  scripts/
  project.godot

If you prefer the command line, you can do this from your project root:

# From your Godot project root
cp -r ~/Downloads/bugnet-godot-sdk/bugnet addons/bugnet

Once the files are in place, open your project in the Godot editor. Navigate to Project → Project Settings → Plugins and you should see Bugnet listed. Enable it. This registers the SDK classes so they are available throughout your project.

Step 2: Set Up the Autoload

Bugnet needs to run persistently across scene changes, which means it should be configured as an Autoload (singleton). Go to Project → Project Settings → Autoload, click the folder icon, and select res://addons/bugnet/sdk.gd. Name the node Bugnet.

Your Autoload tab should now show:

Node Name:  Bugnet
Path:       res://addons/bugnet/sdk.gd
Enabled:    On

This ensures the Bugnet singleton is available everywhere in your project as a global reference. You can access it from any script without needing to preload or instantiate anything manually.

Step 3: Initialize the SDK

With the autoload in place, you need to initialize the SDK with your project credentials. The best place to do this is in your main game script or a dedicated initialization scene that runs before anything else. Create or open your main script and add the following:

# Autoload → Project Settings
extends Node
const BN = preload("res://addons/bugnet/sdk.gd")

func _ready():
  BN.init({
    "api_key": "YOUR_API_KEY",
    "game_id": "YOUR_GAME_ID",
    "auto_logs": true,
    "auto_screenshots": true,
    "capture_device_info": true,
  })

Replace YOUR_API_KEY and YOUR_GAME_ID with the values from your Bugnet dashboard. You will find them under Project Settings → SDK Keys after creating a project.

Here is what each configuration option does:

• auto_logs — Automatically captures engine warnings, errors, and crash stack traces. These are attached to every bug report so you never have to ask players to dig through log files.
• auto_screenshots — Takes a viewport screenshot at the moment a report is triggered. Players see exactly what they were looking at, and so do you.
• capture_device_info — Collects OS version, GPU model, display resolution, and available memory. This metadata is invaluable for reproducing hardware-specific bugs.

Step 4: Configure a Report Trigger

Now that the SDK is initialized, you need to give players a way to actually file a report. Bugnet supports several trigger methods out of the box. Choose the one that fits your game best.

Keyboard shortcut is the most common approach for desktop games. Add this to your initialization:

func _ready():
  BN.init({
    "api_key": "YOUR_API_KEY",
    "game_id": "YOUR_GAME_ID",
    "auto_logs": true,
    "trigger": "keyboard",
    "trigger_key": "F8",
  })

When the player presses F8, the Bugnet overlay appears with a form where they can describe the issue. The screenshot and logs are captured automatically in the background.

Shake detection works well for mobile exports. Set "trigger": "shake" and the SDK will listen for accelerometer input to open the reporter. For button-based triggers, you can place a UI element anywhere in your scene and call the SDK directly:

# Attached to a "Report Bug" button
func _on_report_button_pressed():
  Bugnet.show_reporter()

This opens the same overlay UI. You have full control over when and how the reporting flow is presented to the player.

Step 5: Submit Reports Programmatically

Sometimes you want to file a bug report without player interaction. This is useful for capturing crashes, unhandled exceptions, or specific error conditions that your code detects at runtime. The SDK exposes a submit_report method for exactly this:

# Manually submit a bug report with context
func _on_error_detected(error_msg: String):
  var report = {
    "title": "Auto-detected error",
    "description": error_msg,
    "severity": "critical",
    "tags": ["auto-report", "crash"],
    "metadata": {
      "scene": get_tree().current_scene.name,
      "player_pos": str(player.global_position),
    },
  }
  Bugnet.submit_report(report)

# Hook into Godot's error handling
func _ready():
  BN.init({
    "api_key": "YOUR_API_KEY",
    "game_id": "YOUR_GAME_ID",
    "auto_logs": true,
    "on_crash": _on_error_detected,
  })

The metadata dictionary accepts any key-value pairs you want. Common additions include the current scene name, player coordinates, inventory state, or quest progress. The more context you attach, the faster you can reproduce and fix the issue on your end.

What Gets Captured Automatically

Once the SDK is running, every report—whether player-initiated or programmatic—automatically includes:

• Crash logs and stack traces from Godot's error output, including warnings that occurred in the minutes leading up to the report.
• A viewport screenshot captured at the exact moment the report is triggered, so you see what the player sees.
• Device information including OS name and version, GPU renderer string, display resolution, available system memory, and the Godot engine version.
• Session context such as how long the player has been in the current session, which scene they are in, and their framerate at the time of the report.

All of this appears in your Bugnet dashboard, organized by project. Reports are automatically grouped when they share the same stack trace, so you see unique issues rather than a flood of duplicate entries.

"We shipped our first Godot game with Bugnet integrated from day one. Within the first weekend we caught a physics desync that only happened on Linux with dual monitors. We never would have found that on our own."

Tips for Getting the Most Out of Bugnet

Test the integration before you ship. Run your game, press your trigger key, and submit a test report. Verify it appears in your dashboard with a screenshot and device info attached. This takes thirty seconds and saves you from discovering a misconfigured API key after launch.

Use tags to categorize reports. When submitting programmatic reports, include tags like "rendering", "audio", or "save-system" to make filtering easier in the dashboard. Players tend to describe bugs vaguely; tags let your code add precision.

Attach scene-specific metadata. The current scene name, player position, and recent actions are the three pieces of context that most often make the difference between a bug you can reproduce in five minutes and one that takes five hours. Pass them in the metadata dictionary whenever possible.

Enable auto_logs in development too. Bugnet is not just for production. Running it during playtesting means your testers do not need to copy-paste log output. Every report they file includes the full error trail automatically.

Five minutes of setup. Every crash captured.