Social Events API Reference

Complete API documentation for the Social Events feature across all supported engines.

Overview

All SDKs communicate with the Shard Launcher via HTTP POST to trigger social events. The API is consistent across engines with language-appropriate naming conventions.

Endpoint

POST http://localhost:9876/api/social/trigger

Payload

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

Trigger Event

Trigger a social event to notify the Shard Launcher.

# Godot 4.x
ShardSDK.social.trigger_event("myGame_boss_defeated")

Parameter	Type	Description
`event_id`	String	Unique identifier for the social event

// Unity
ShardSDK.Social.TriggerEvent("myGame_boss_defeated");

Parameter	Type	Description
`eventId`	string	Unique identifier for the social event

// MonoGame
ShardSDK.Social.TriggerEvent("myGame_boss_defeated");

Parameter	Type	Description
`eventId`	string	Unique identifier for the social event

// GameMaker
shard_social_trigger("myGame_boss_defeated");

Parameter	Type	Description
`event_id`	string	Unique identifier for the social event

// RPG Maker MV/MZ
ShardSDK.Social.triggerEvent("myGame_boss_defeated");

Parameter	Type	Description
`eventId`	string	Unique identifier for the social event

This method is fire-and-forget. It sends the event and returns immediately without waiting for confirmation.

Configuration

All SDKs support the same configuration options:

Setting	Default	Description
`launcher_url`	`http://localhost:9876`	Shard Launcher URL
`enable_social`	`true`	Enable/disable social events

Configure in Project Settings under shard_sdk/:

# Or programmatically
ShardSDK.launcher_url = "http://localhost:9876"
ShardSDK.enable_social = true

var config = new ShardConfig
{
    LauncherUrl = "http://localhost:9876",
    EnableSocial = true
};
ShardSDK.Initialize(config);

var config = new ShardConfig
{
    LauncherUrl = "http://localhost:9876",
    EnableSocial = true
};
ShardSDK.Initialize(config);

shard_init({
    launcher_url: "http://localhost:9876",
    enable_social: true
});

Configure via Plugin Manager parameters or:

// Not typically needed - uses defaults

Error Handling

All SDKs use fire-and-forget HTTP requests 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.

Event ID Format

Event IDs are generated by the ShardKit CLI and follow this format:

{camelCaseGameName}_{8hexChars}

Examples:

myGame_e5f6g7h8
superAdventure_a1b2c3d4
dungeonCrawler_f9e8d7c6

Usage Examples

Basic Event Triggering

func _on_boss_defeated():
    ShardSDK.social.trigger_event("myGame_boss_defeated")
 
func _on_achievement_unlocked(achievement_name: String):
    var event_id = "myGame_achievement_" + achievement_name.to_lower()
    ShardSDK.social.trigger_event(event_id)

void OnBossDefeated()
{
    ShardSDK.Social.TriggerEvent("myGame_boss_defeated");
}
 
void OnAchievementUnlocked(string achievementName)
{
    var eventId = $"myGame_achievement_{achievementName.ToLower()}";
    ShardSDK.Social.TriggerEvent(eventId);
}

function on_boss_defeated() {
    shard_social_trigger("myGame_boss_defeated");
}

function on_achievement_unlocked(achievement_name) {
    var event_id = "myGame_achievement_" + string_lower(achievement_name);
    shard_social_trigger(event_id);
}

Common Event Types

// Boss encounters
"myGame_boss_defeated"
"myGame_boss_first_try"
 
// Exploration
"myGame_secret_found"
"myGame_area_complete"
 
// Achievements
"myGame_speedrun_complete"
"myGame_no_damage_run"

Engine-Specific Documentation

For detailed setup instructions, see your engine’s documentation: