Game Trace Godot SDK

Analytics SDK for Game Trace — event tracking for indie games. This GDScript addon provides automatic batching, session management, device context capture, and persistent client IDs for Godot 4.x projects.

Requirements

• Godot 4.0 or later
• GDScript

Installation

Option A: Godot Asset Library (recommended)

1. In the Godot editor, go to the AssetLib tab at the top.
2. Search for GameTrace.
3. Click Download and then Install.

Option B: Manual from GitHub

1. Clone or download this repository:

   git clone https://github.com/game-trace/gametrace-godot.git
   

2. Copy addons/gametrace/ into your Godot project's root directory so the path is res://addons/gametrace/.

Setup

After copying the files:

1. Open your Godot project.
2. Go to Project > Project Settings > Autoload.
3. Click the folder icon and select res://addons/gametrace/game_trace.gd.
4. Set the name to GameTrace.
5. Click Add.

Quick Start

func _ready():
    var config = GameTraceConfig.new()
    config.api_key = "your-api-key"
    config.project_id = "your-project-id"
    config.endpoint = "https://gametrace.io/api/v1/events"
    GameTrace.initialize(config)

    # Track events
    GameTrace.track("game_start", {"difficulty": "normal"})
    GameTrace.track("level_complete", {"level": 1, "score": 4200})

    # Identify a known player (optional)
    GameTrace.identify("player-123")

    # Cleanup (auto-called when the window closes)
    GameTrace.shutdown()

Configuration

Pass a GameTraceConfig resource to initialize().

Property	Type	Default	Description
api_key	String	""	Required. Your project API key.
project_id	String	""	Required. Your project ID.
endpoint	String	"https://gametrace.io/api/v1/events"	Game Trace API endpoint URL.
flush_interval	float	5.0	Seconds between automatic flushes.
batch_size	int	20	Events per batch. Flush triggers at this count.
max_queue_size	int	1000	Max queued events. Oldest dropped when full.
auto_capture	bool	true	Auto-capture device/engine context.
debug	bool	false	Log activity to the Godot console.

Methods

initialize(config)

Set up the SDK with your credentials. Call once in _ready().

var config = GameTraceConfig.new()
config.api_key = "your-api-key"
config.project_id = "your-project-id"
config.endpoint = "https://gametrace.io/api/v1/events"
GameTrace.initialize(config)

track(event_name, properties?)

Queue an analytics event. Events are batched and sent automatically.

GameTrace.track("item_purchased", {"item_id": "sword_01", "price": 500})

identify(client_id)

Override the auto-generated client ID with a known player identifier. Persisted across sessions.

GameTrace.identify("player-123")

flush()

Immediately send all queued events. Connect to flush_completed for the result.

GameTrace.flush()

shutdown()

Flush remaining events, stop timers, and prevent further tracking. Called automatically when the game window closes.

GameTrace.shutdown()

get_client_id() / get_session_id()

print(GameTrace.get_client_id())   # "550e8400-e29b-..."
print(GameTrace.get_session_id())  # "6ba7b810-9dad-..."

is_initialized()

Returns true after a successful initialize() call.

Signals

Signal	Description
flush_completed(result: Dictionary)	Emitted after each flush. result has success, accepted (or error).
event_tracked(event_name: String)	Emitted each time track() is called.
error_occurred(message: String)	Emitted on SDK errors.

GameTrace.flush_completed.connect(func(result):
    if result.success:
        print("Sent %d events" % result.accepted)
)

Features

Auto Batching

Events are queued in memory and sent in batches. A flush triggers when:

• The queue reaches batch_size events (default 20)
• The flush_interval timer fires (default every 5 seconds)
• You call flush() or shutdown()
• The game window is closed

If the queue exceeds max_queue_size (default 1000), the oldest events are dropped.

Persistence

The client ID is stored at user://gametrace.cfg using Godot's ConfigFile. This means the same player is recognized across game launches. If the file cannot be created, a new ID is generated each time.

Auto-Capture Context

When auto_capture is enabled (the default), each event includes:

Field	Source
platform	OS.get_name() — Windows, macOS, Linux, Android, iOS, Web
userAgent	Engine.get_version_info() — e.g. Godot/4.3.0.stable
screenWidth	DisplayServer.screen_get_size().x
screenHeight	DisplayServer.screen_get_size().y
language	OS.get_locale_language()
timezone	Time.get_time_zone_from_system()
deviceType	Derived from OS — desktop or mobile

Automatic Shutdown

The SDK listens for NOTIFICATION_WM_CLOSE_REQUEST and automatically flushes remaining events when the player closes the game window.

License

MIT