Godot 4 Plugin

The Forge Logger plugin for Godot 4 integrates bug reporting and runtime diagnostics directly into your game. Sessions are created automatically on startup, bug reports can be triggered programmatically or via an in-game popup, and all data is sent to the Forge Logger backend.

Features

Automatic session creation on game start (linked to build version and platform)
Programmatic bug reports with title, description, severity, tags, and custom data
User-facing in-game report popup (show_report_popup())
Log file and screenshot upload via pre-signed URLs
Offline retry queue – failed requests are retried on the next launch
Unclean-shutdown recovery – reports queued before an unclean exit are resent on the next run (no crash stack-trace capture)

Installation

Copy the addons/forge_logger directory from this repository into the addons/ folder of your Godot project.
In the Godot editor open Project → Project Settings → Plugins and enable Forge Logger.
Configure the plugin under Project Settings → forge_logger/:

Setting	Description
`base_url`	Ingest API base URL, e.g. `https://ingest.forgelogger.dev`.
`project_id`	UUID of your project (from the web dashboard or API).
`api_key`	Your project’s logger token (`flg_…`) from Project → Tokens. Required for the hosted backend; leave empty only for self-hosted backends without auth.
`game_name`	Name shown in the dashboard next to reports.
`game_version`	Semantic version string, e.g. `1.0.0`.
`build_hash`	Git commit hash or build identifier.
`environment`	`development`, `staging`, or `production`.
`enable_logs`	Attach the Godot log file to each report.
`enable_screenshot`	Capture a screenshot automatically with each report. Off by default.
`auto_start_session`	Start a session immediately on launch (recommended).

Usage

Automatic session start

When auto_start_session is enabled the plugin calls start_session() as part of its _ready() lifecycle. No extra code is needed.

To start a session manually (when auto_start_session is off):

await ForgeLogger.start_session()

Programmatic bug report

ForgeLogger.capture_bug({
    "title": "Player stuck in wall",
    "description": "Dash caused collision lock near checkpoint 3",
    "severity": "high",
    "tags": ["movement", "collision"],
    "custom_data": {
        "scene": get_tree().current_scene.name,
        "player_position": str(player.global_position),
    }
})

ForgeLogger.show_report_popup()

This opens a built-in UI where the player can describe the bug. The plugin collects the form data and submits a report automatically.

Utilities

# Retry all requests that failed while offline
ForgeLogger.retry_queued()
 
# Verify connectivity to the backend
await ForgeLogger.check_health()

Plugin Structure

You do not need to understand the internals to use the plugin, but knowing where things live helps if you want to extend it:

File	Purpose
`forge_logger.gd`	Autoload singleton – the public API surface.
`session_manager.gd`	Creates and tracks the current session; on the next launch after an unclean exit, retries queued reports (no crash capture).
`upload_manager.gd`	Collects log files and manages pre-signed upload URLs.
`report_builder.gd`	Assembles the report payload from all collected data.
`http_client.gd`	Low-level HTTP wrapper around the REST API.

Custom Integration

ForgeLoggerHttpClient can be used independently of the autoload singleton. This is useful if you want to send custom events or query data:

var client := ForgeLoggerHttpClient.new()
client.configure("https://ingest.forgelogger.dev", "<TOKEN>")
 
# Available methods:
# client.start_session(project_id, payload)
# client.create_upload(project_id, payload)
# client.submit_report(project_id, payload)
# client.list_reports(project_id)
# client.get_events(project_id, session_id)
# client.post_events(project_id, events_array)
# client.check_health()

Best Practices

Enrich reports – always provide title, description, severity, and custom_data (scene name, checkpoint, player position). Detailed reports are much easier to reproduce.
Do not hard-code api_key – load it from an environment variable or an encrypted store. Committed API keys can be rotated but the history remains in git.
Use environment setting – tag builds as development / staging / production so reports are easy to filter in the dashboard.

For endpoint details and examples in other languages see the API Reference. To poke at the same endpoints by hand, grab the Postman & Bruno collections.