Godot SDK API Reference

Complete API documentation for the Shard Godot SDK.

ShardSDK

Autoload singleton providing access to all SDK services. Automatically registered when the plugin is enabled.

Properties

Usage

# Access via the autoload singleton
ShardSDK.recording.trigger_event("myGame_a1b2c3d4")
ShardSDK.monitor.report_error("Something went wrong")
ShardSDK.social.trigger_event("myGame_a1b2c3d4")

Configuration Options

Configure via Project → Project Settings under shard_sdk/:

RecordingService

Service for triggering recording events. Access via ShardSDK.recording.

Methods

trigger_event(event_id: String) -> void

Triggers a recording event in the Shard Launcher.

Parameters:

• event_id (String): The event ID to trigger (e.g., "myGame_a1b2c3d4")

Example:

# Trigger a recording event
ShardSDK.recording.trigger_event("myGame_bossDefeated")

HTTP Request:

• Endpoint: POST /api/recording/trigger
• Payload:

{
  "eventId": "myGame_bossDefeated",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Notes:

• Fire-and-forget: Does not block game execution
• Silent failure: No exceptions if launcher unavailable
• Empty event IDs are ignored with a warning (if debug logging enabled)

MonitorService

Service for reporting errors and diagnostics. Access via ShardSDK.monitor.

Methods

report_error(message: String, stack_trace: String = "") -> void

Reports an error to the Shard Launcher.

Parameters:

• message (String): Error or diagnostic message
• stack_trace (String, optional): Stack trace information, defaults to empty string

Example:

# Report a simple error
ShardSDK.monitor.report_error("Player position invalid")
 
# Report an error with stack trace
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("Unexpected state", stack_str)

HTTP Request:

• Endpoint: POST /api/monitor/report
• Payload:

{
  "message": "Player position invalid",
  "stackTrace": "",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Notes:

• Fire-and-forget: Does not block game execution
• Silent failure: No exceptions if launcher unavailable
• Empty messages are ignored with a warning (if debug logging enabled)

SocialService

Service for triggering social events. Access via ShardSDK.social.

Methods

trigger_event(event_id: String) -> void

Triggers a social event in the Shard Launcher.

Parameters:

• event_id (String): The event ID to trigger (e.g., "myGame_a1b2c3d4")

Example:

# Trigger a social event
ShardSDK.social.trigger_event("myGame_achievementUnlocked")

HTTP Request:

• Endpoint: POST /api/social/trigger
• Payload:

{
  "eventId": "myGame_achievementUnlocked",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Notes:

• Fire-and-forget: Does not block game execution
• Silent failure: No exceptions if launcher unavailable
• Empty event IDs are ignored with a warning (if debug logging enabled)

HTTP Behavior

All SDK methods use fire-and-forget HTTP POST requests:

Timestamp Format

All payloads include an ISO 8601 timestamp in UTC:

YYYY-MM-DDTHH:MM:SS.sssZ

Example: 2024-01-15T10:30:00.123Z