Docs / Quick start - Unreal

Quick start - Unreal

Connect an Unreal Engine 5 project to a running Asobi server. The SDK is a C++ runtime plugin (AsobiSDK, UE 5.4+); every call is also BlueprintCallable. No server yet? Run the server quickstart first.

1. Install the plugin

  • Clone into your project's Plugins/ folder: git clone https://github.com/widgrensit/asobi-unreal.git Plugins/AsobiSDK.
  • Regenerate project files, then enable Asobi SDK under Edit -> Plugins -> Networking.
  • Add "AsobiSDK" to PublicDependencyModuleNames in your module's Build.cs.

2. Auth, connect, queue

There is no subsystem or singleton - you create the objects yourself with NewObject and keep them in UPROPERTY fields so they aren't garbage-collected. Auth is two steps: get a REST token, then authenticate the socket with it.

#include "AsobiClient.h"
#include "AsobiAuth.h"
#include "AsobiMatchmaker.h"
#include "AsobiWebSocket.h"

// 1. HTTP client + guest auth
Client = NewObject<UAsobiClient>(this);
Client->SetBaseUrl(TEXT("http://localhost:8084"));

Auth = NewObject<UAsobiAuth>(this);
Auth->Init(Client);
FOnAsobiAuthResponse OnAuth;
OnAuth.BindDynamic(this, &UMyClass::HandleAuth);
Auth->Guest(DeviceId, DeviceSecret, OnAuth); // DeviceSecret: your base64 >=32 bytes

// 2. On auth -> open the socket (note ws:// scheme + /ws path)
void UMyClass::HandleAuth(bool bOk, const FAsobiAuthTokens& Tokens) {
    WebSocket = NewObject<UAsobiWebSocket>(this);
    WebSocket->OnConnected.AddDynamic(this, &UMyClass::HandleWsConnected);
    WebSocket->OnMatchMatched.AddDynamic(this, &UMyClass::OnInMatch);
    WebSocket->OnMatchState.AddDynamic(this, &UMyClass::OnState);
    WebSocket->Connect(TEXT("ws://localhost:8084/ws"));
}

// 3. On socket open -> authenticate it, then queue the matchmaker
void UMyClass::HandleWsConnected() {
    WebSocket->Authenticate(Client->GetAuthToken());

    Matchmaker = NewObject<UAsobiMatchmaker>(this);
    Matchmaker->Init(Client);
    FOnAsobiMatchmakerResponse OnMm;
    OnMm.BindDynamic(this, &UMyClass::HandleMm);
    Matchmaker->Add(TEXT("default"), TArray<FString>{ Client->GetPlayerId() }, OnMm);
}

Then send input each tick with WebSocket->SendMatchInput(DataJson) and read state on the OnMatchState delegate. The whole flow is Blueprint-callable too.

Core API

  • UAsobiAuth::Guest(DeviceId, DeviceSecret, Cb) - also Register, Login; callback delivers FAsobiAuthTokens.
  • UAsobiWebSocket::Connect(Url) then Authenticate(Token).
  • UAsobiMatchmaker::Add(Mode, Party, Cb) - or UAsobiWebSocket::JoinMatch(MatchId) for a specific match.
  • UAsobiWebSocket::SendMatchInput(DataJson); delegates OnMatchMatched, OnMatchJoined, OnMatchState.

Gotchas

  • Point the socket at ws://.../ws. A frequent slip is connecting to http://localhost:8084 instead of ws://localhost:8084/ws.
  • Two-step auth. After Connect, call Authenticate(Client->GetAuthToken()) on OnConnected. Send a periodic SendHeartbeat() or the server drops you with 1008 idle_auth_timeout.
  • Hold references. Keep the client, auth, matchmaker, and socket in UPROPERTY fields (the demo parks them on the UGameInstance) or they're GC'd mid-session.

What's next