OddSockets Unreal Engine SDK Documentation

Quick Start C++ API Blueprint API Examples Full Documentation Compliance Guide

📋 Overview

The OddSockets Unreal Engine SDK provides seamless real-time messaging integration with full Blueprint support and native C++ API. Built following the JavaScript SDK pattern for consistent behavior across all platforms.

🎯 Blueprint Integration

Full visual scripting support with Blueprint nodes for all operations including connection management, channel subscriptions, and message publishing.

⚡ C++ API

Native C++ integration with Actor-based architecture, automatic lifecycle management, and comprehensive event system.

🔄 Auto-Reconnection

Intelligent reconnection with exponential backoff, session stickiness, and automatic worker assignment.

👥 Presence & History

Real-time user presence tracking, message history, and state management with Blueprint-friendly data structures.

🚀 Quick Start

1. Installation

Copy the OddSockets plugin to your project's Plugins directory
Add the plugin to your .uproject file
Regenerate project files and compile

2. Basic Setup

// In your actor's header file
UCLASS()
class MYGAME_API AMyGameActor : public AActor
{
    GENERATED_BODY()

protected:
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "OddSockets")
    AOddSocketsClient* OddSocketsClient;

    UFUNCTION()
    void OnConnected();

    UFUNCTION()
    void OnChannelMessage(const FOddSocketsChannelMessageData& MessageData);
};
            

// In your actor's implementation
void AMyGameActor::BeginPlay()
{
    Super::BeginPlay();

    // Spawn OddSockets client
    OddSocketsClient = GetWorld()->SpawnActor<AOddSocketsClient>();

    // Configure the client
    FOddSocketsConfig Config;
    Config.ApiKey = TEXT("your-api-key-here");
    Config.UserId = TEXT("player-123");
    Config.bAutoConnect = true;

    // Initialize and connect
    OddSocketsClient->Initialize(Config);
    OddSocketsClient->OnConnected.AddDynamic(this, &AMyGameActor::OnConnected);
    OddSocketsClient->ConnectAsync();
}
            

💻 C++ API Reference

AOddSocketsClient

Main client class for connecting to OddSockets platform.

Key Methods:

Initialize(Config) - Initialize client with configuration
ConnectAsync() - Connect to OddSockets platform
GetChannel(ChannelName) - Get or create a channel
PublishBulkAsync(Messages) - Publish multiple messages

Events:

OnConnected - Fired when successfully connected
OnDisconnected - Fired when disconnected
OnError - Fired when an error occurs
OnWorkerAssigned - Fired when assigned to a worker

UOddSocketsChannel

Channel class for pub/sub messaging operations.

Key Methods:

SubscribeAsync(Options) - Subscribe to channel
PublishAsync(Message, Options) - Publish a message
GetHistoryAsync(Options) - Get message history
GetPresenceAsync() - Get current presence

// Channel usage example
void AMyGameActor::OnConnected()
{
    UOddSocketsChannel* GameChannel = OddSocketsClient->GetChannel(TEXT("game-lobby"));
    
    FOddSocketsSubscriptionOptions Options;
    Options.MaxHistory = 50;
    Options.bEnablePresence = true;
    
    GameChannel->OnMessage.AddDynamic(this, &AMyGameActor::OnChannelMessage);
    GameChannel->SubscribeAsync(Options);
}
            

🎨 Blueprint API

Blueprint Integration

The OddSockets SDK provides full Blueprint support with visual nodes for all operations:

Available Blueprint Nodes:

Spawn OddSockets Client Actor - Create client instance
Initialize - Configure client with settings
Connect Async - Establish connection
Get Channel - Access or create channels
Subscribe Async - Subscribe to channel messages
Publish Async - Send messages to channels
Get Presence Async - Retrieve user presence
Get History Async - Fetch message history

Blueprint Events:

On Connected - Connection established
On Message - Message received
On Presence Change - User joined/left
On Error - Error occurred

Blueprint Workflow:

Spawn OddSockets Client Actor
Create OddSockets Config struct
Set API Key and configuration
Call Initialize with config
Bind to On Connected event
Call Connect Async
In On Connected: Get Channel and Subscribe

📚 Examples

Chat System

// Chat manager implementation
void AChatManager::JoinChatRoom(const FString& RoomName)
{
    ChatChannel = OddSocketsClient->GetChannel(RoomName);
    
    FOddSocketsSubscriptionOptions Options;
    Options.MaxHistory = 50;
    Options.bEnablePresence = true;
    
    ChatChannel->OnMessage.AddDynamic(this, &AChatManager::OnChatMessage);
    ChatChannel->OnPresenceChange.AddDynamic(this, &AChatManager::OnPresenceChange);
    
    ChatChannel->SubscribeAsync(Options);
}

void AChatManager::SendChatMessage(const FString& Message)
{
    if (ChatChannel && ChatChannel->IsSubscribed())
    {
        FString ChatJson = FString::Printf(
            TEXT("{\"type\":\"chat\",\"message\":\"%s\",\"timestamp\":\"%s\"}"), 
            *Message, *FDateTime::UtcNow().ToIso8601()
        );
        
        ChatChannel->PublishAsync(ChatJson, FOddSocketsPublishOptions());
    }
}
            

Multiplayer Game State

// Game state synchronization
void AGameStateSyncer::SyncPlayerPosition(const FVector& Position, const FRotator& Rotation)
{
    if (GameChannel && GameChannel->IsSubscribed())
    {
        FString PositionJson = FString::Printf(
            TEXT("{\"type\":\"position\",\"x\":%.2f,\"y\":%.2f,\"z\":%.2f,\"pitch\":%.2f,\"yaw\":%.2f,\"roll\":%.2f}"),
            Position.X, Position.Y, Position.Z, Rotation.Pitch, Rotation.Yaw, Rotation.Roll
        );
        
        GameChannel->PublishAsync(PositionJson, FOddSocketsPublishOptions());
    }
}
            

⚙️ Configuration

FOddSocketsConfig Structure

USTRUCT(BlueprintType)
struct FOddSocketsConfig
{
    // Required Settings
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Required Settings")
    FString ApiKey; // Your OddSockets API key

    // Optional Settings
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Optional Settings")
    FString UserId; // User identifier (auto-generated if empty)

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Optional Settings")
    bool bAutoConnect = true; // Automatically connect on initialization

    // Connection Settings
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Connection Settings")
    int32 ReconnectAttempts = 5; // Maximum reconnection attempts

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Connection Settings")
    int32 Timeout = 10; // Connection timeout in seconds

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Connection Settings")
    int32 HeartbeatInterval = 30; // Heartbeat interval in seconds

    // Logging
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Logging")
    EOddSocketsLogLevel LogLevel = EOddSocketsLogLevel::Info;
};
            

🔧 Troubleshooting

Common Issues

Connection Fails - Verify API key and network connectivity
Messages Not Received - Check subscription status and message size (32KB limit)
Blueprint Compilation Errors - Ensure plugin is enabled and project files regenerated

Debug Logging

Enable detailed logging by setting the log level to Debug in your configuration:

Config.LogLevel = EOddSocketsLogLevel::Debug;

🎮 OddSockets Unreal Engine SDK

📋 Overview

🎯 Blueprint Integration

⚡ C++ API

🔄 Auto-Reconnection

👥 Presence & History

🚀 Quick Start

1. Installation

2. Basic Setup

💻 C++ API Reference

AOddSocketsClient

Key Methods:

Events:

UOddSocketsChannel

Key Methods:

🎨 Blueprint API

Blueprint Integration

Available Blueprint Nodes:

Blueprint Events:

Blueprint Workflow:

📚 Examples

Chat System

Multiplayer Game State

⚙️ Configuration

FOddSocketsConfig Structure

🔧 Troubleshooting

Common Issues

Debug Logging

🤝 Support & Resources