DocsGodot SDKOverview

Godot SDK

Integrate the Shard SDK into your Godot 4.x project for recording, error monitoring, and social events.

Prerequisites: Godot 4.x and Shard Launcher running

Installation

Option 1: Copy the Addon

  1. Download or clone the SDK from GitHub
  2. Copy the addons/shard_sdk/ folder to your Godot project’s addons/ directory
  3. In Godot, go to Project → Project Settings → Plugins
  4. Enable the Shard SDK plugin

Option 2: Asset Library

Coming soon - The SDK will be available on the Godot Asset Library.

Quick Start

Once the plugin is enabled, the ShardSDK autoload singleton is automatically available. Access features directly:

extends Node
 
func _on_boss_defeated():
    # Trigger a recording event
    ShardSDK.recording.trigger_event("myGame_bossDefeated")
 
func _on_error(message: String, stack: String):
    # Report an error
    ShardSDK.monitor.report_error(message, stack)
 
func _on_achievement_unlocked():
    # Trigger a social event
    ShardSDK.social.trigger_event("myGame_achievementUnlocked")

Configuration

Configure the SDK via Project → Project Settings under the shard_sdk/ section:

SettingTypeDefaultDescription
launcher_urlStringhttp://localhost:9876Shard Launcher URL
enable_recordingbooltrueEnable recording triggers
enable_monitorbooltrueEnable error reporting
enable_socialbooltrueEnable social events
debug_loggingboolfalseEnable debug output

Enable debug_logging during development to see SDK activity in the Output panel.

Recording

Trigger recording events when gameplay moments occur:

# Trigger when a boss is defeated
func _on_boss_defeated():
    ShardSDK.recording.trigger_event("myGame_bossDefeated")
 
# Trigger when an achievement is unlocked
func _on_achievement_unlocked(achievement_id: String):
    ShardSDK.recording.trigger_event("myGame_" + achievement_id)

The Shard Launcher captures a clip around the trigger moment. Event IDs should be generated using the ShardKit CLI.

→ Recording Overview

Error Monitoring

Report errors and exceptions to track issues in production:

# Report a simple error
func _on_connection_failed():
    ShardSDK.monitor.report_error("Connection to server failed")
 
# Report an error with stack trace
func _on_exception(message: String):
    var stack = get_stack()
    var stack_str = ""
    for frame in stack:
        stack_str += "%s:%d in %s\n" % [frame.source, frame.line, frame.function]
    ShardSDK.monitor.report_error(message, stack_str)

→ Error Tracking Overview

Social Events

Trigger social content display in the launcher overlay:

# Trigger when entering a new area
func _on_area_entered(area_name: String):
    ShardSDK.social.trigger_event("myGame_entered_" + area_name)
 
# Trigger when completing a quest
func _on_quest_completed(quest_id: String):
    ShardSDK.social.trigger_event("myGame_quest_" + quest_id)

→ Social Events Overview

Error Handling

The SDK uses fire-and-forget HTTP calls with silent failure:

  • If the Shard Launcher is not running, calls silently fail
  • No exceptions are thrown to your game code
  • Network timeouts are handled automatically (5 second timeout)

Your game continues running normally even if the launcher is unavailable.

Project Structure

The SDK addon structure:

addons/shard_sdk/
├── plugin.cfg              # Plugin metadata
├── plugin.gd               # Editor plugin (registers autoload & settings)
├── ShardSDK.gd             # Main autoload singleton
├── recording/
│   └── RecordingService.gd # Recording trigger functionality
├── monitor/
│   └── MonitorService.gd   # Error reporting functionality
└── social/
    └── SocialService.gd    # Social event functionality

Next Steps