PlayLink

The progression in a real game

Party  ──►  Lobby     ──►  Session   ──►  Gameplay
(group)    (configure)    (match)        (level)

Friends form a party that persists across matches. They enter a lobby to pick mode and map. When ready, the lobby host creates a session and everyone joins it. The host then ServerTravels to the gameplay map; clients ClientTravel along to the host's listen server.

Lobby, metadata bulletin board

Backed by an OSS object (Steam Lobby, EOS Lobby) that stores key/value pairs: name, max players, custom flags (region=eu, mode=ranked), chat. Members read/write metadata and exchange messages. Settings round-trip via OnLobbySettingsChanged + OnUpdateSessionComplete.

A lobby has no IP, no port, no NetDriver. You cannot ClientTravel to a lobby, there is nothing on the wire to connect to. Use lobbies to wait for friends, configure match rules, decide what to play next, and hold pre-game chat.

Party, cross-game social grouping

"I'm queueing with these three people, drag us together wherever we go." Parties span sessions, lobbies, and even sequential matches, they survive a match ending so the same group can re-queue without losing its membership.

Implementation differs per backend. Steam has no native parties; PlayLink ships UPlayLinkLobbyPartyService, a presence-true OSS session named PlayLinkParty that stands in for a party. EOS has a real IOnlineParty service planned as a sibling plugin (PlayLinkEOSParty). Either way the public API stays the same.

A party also has no network endpoint. Parties don't host gameplay, they track who's grouped together so when a match starts, the matchmaker pulls everyone into the same session. Use parties to persist a friend group across multiple matches.

Session, the actual game match

Backed by an OSS session and a UE listen-server NetDriver. A session has an IP:port. JoinSession returns a connect string that APlayerController::ClientTravel hands to the engine's net layer; the client lands on the host. This is the only one of the three where "transport me to the host's level" is a meaningful operation.

When to pick which

Backend coverage

Minimal C++ wiring

// In your subsystem header
UFUNCTION()
void HandleFriendsListUpdated(int32 LocalUserNum, EPlayLinkResult Result);

UFUNCTION()
void HandleLobbyCreated(EPlayLinkResult Result, FPlayLinkLobbyHandle Handle);

// In Initialize
UGameInstance* GI = GetGameInstance();
UPlayLinkFriendsSubsystem* Friends = GI->GetSubsystem<UPlayLinkFriendsSubsystem>();
UPlayLinkLobbySubsystem*   Lobby   = GI->GetSubsystem<UPlayLinkLobbySubsystem>();

Friends->OnFriendsListUpdated.AddDynamic(this, &UMySocialSubsystem::HandleFriendsListUpdated);
Lobby->OnLobbyCreated.AddDynamic(this, &UMySocialSubsystem::HandleLobbyCreated);

// Refresh friends and host a 4-player lobby
Friends->RefreshFriendsList(0);
Lobby->Action_HostLobby(0, 4, false);

Querying readiness

UPlayLinkSubsystem* Router = GI->GetSubsystem<UPlayLinkSubsystem>();
if (Router->IsReady())
{
    EPlayLinkBackend Backend = Router->GetBackend();
    UE_LOG(LogTemp, Log, TEXT("PlayLink active: %s"),
        *UEnum::GetValueAsString(Backend));
}

Login event

Automatic rich-presence writes

Identity subscribes to lobby/session/party lifecycle events and writes the local user's OSS rich presence automatically. The platform's friends list reflects the player's current state ("In Lobby", "In Match", etc.) without project-side glue code.

Override the status string mid-match by calling SetLocalUserPresence(LocalUserNum, State, StatusString) directly, useful for richer presence like "In Arena 4, 12/20". The next lifecycle event will re-apply the auto-state unless auto-writes are disabled.

; DefaultEngine.ini, disable automatic presence writes
[PlayLink]
bAutoWritePresence=False

Falls back gracefully on backends without a presence interface (Null OSS, some EOS configs): the cached state is still readable via GetLocalUserPresence so projects can drive UI off it without OSS support.

Events

Sending invites

Each domain has its own send-invite verb on the friends subsystem. Pass the target friend's UserId; PlayLink routes to the active OSS invite interface for that domain.

Accepting invites

When OnInviteReceived fires, hand the FPlayLinkInvite back to AcceptInvite(). PlayLink dispatches based on Kind, joining the right lobby, session, or party, and broadcasts the destination's join event when the join completes.

// Bind once
Friends->OnInviteReceived.AddDynamic(this, &UMySocialSubsystem::HandleInvite);

// Handler, accept everything for now; real UI would prompt the user
void UMySocialSubsystem::HandleInvite(FPlayLinkInvite Invite)
{
    Friends->AcceptInvite(0, Invite);
}

Handling failures (project-side)

Every PlayLink async op surfaces an EPlayLinkResult on its completion delegate (OnInviteAccepted, OnSessionJoined, OnLobbyJoined, etc.). The plugin ships a broad classification of failures, enough to drive generic UI flows, but does not enumerate every backend-specific cause.

These cover the shape of failure, enough to show "couldn't join (full)" vs "couldn't join (permission denied)" vs "couldn't join (no network)". Beyond this, the realities of online platforms include many platform-specific failure modes that PlayLink intentionally does not enumerate:

Why this design: every backend names failures differently and adds new failure modes over time (Steam updates, EOS feature additions, console certification requirements). Pinning PlayLink's enum to every possible backend code would make the plugin a maintenance treadmill chasing OSS releases. Instead PlayLink commits to a stable, shape-classified surface and lets projects extract finer-grained failure semantics from the platform layer they actually ship on.

How projects extract more detail:

1. Inspect LogPlayLink for the native OSS error string PlayLink prints alongside each Failed_BackendError.
2. For richer fidelity, subscribe to your OSS's native error delegates directly (e.g. IOnlineSubsystem::OnConnectionStatusChanged, Steam's SteamServersConnectFailure, EOS's EOS_Connect_OnAuthExpirationCallback), they live alongside PlayLink and don't conflict.
3. Map backend codes to project-specific user-facing strings ("update your game" / "this server isn't available in your region" / "your friend doesn't own this game") in your UI layer.

// Generic PlayLink handler covers 80% of UI cases
void UMySocialSubsystem::HandleSessionJoined(EPlayLinkResult Result, FPlayLinkSessionHandle Handle, FString ConnectString)
{
    switch (Result)
    {
        case EPlayLinkResult::Success:             ClientTravel(ConnectString); break;
        case EPlayLinkResult::Failed_Full:         ShowToast("Session is full"); break;
        case EPlayLinkResult::Failed_NotLoggedIn:  ShowLoginPrompt(); break;
        case EPlayLinkResult::Failed_Network:      ShowToast("Network error, check connection"); break;
        case EPlayLinkResult::Failed_BackendError: ShowToast("Could not join (see log)"); break;
        default:                                  ShowToast("Could not join"); break;
    }
}

// Project can layer backend-specific refinement on top:
case EPlayLinkResult::Failed_BackendError:
    if (Router->GetBackend() == EPlayLinkBackend::Steam)
    {
        // Inspect SteamAPI directly for the last error if needed
    }
    break;

Lifecycle

State events

Lifecycle

State events

Lifecycle

State events

Ticket lifecycle

Submit one ticket per matchmaking attempt. The subsystem broadcasts status transitions through OnStatusChanged as the service moves through the state machine, and a single final outcome through OnCompleted.

Idle  ──►  Searching  ──►  Found  ──►  Joining  ──►  Completed
                       │
                       ├──►  Hosting  ──►  Completed
                       │
                       ├──►  Failed
                       │
                       └──►  Cancelled

FPlayLinkMatchmakingTicket

Default service, UPlayLinkSessionSearchMatchmaker

Shipped as the fallback when no [PlayLink] MatchmakingServiceClass=... is set in DefaultGame.ini. Implements:

1. FindSessions filtered by the first GameModeTag and the bLanOnly flag
2. Picks the best candidate, lowest ping with at least PartySize open slots
3. JoinSession on the chosen result
4. If no candidate appears within MaxWaitSeconds:
   • bFallbackToHost=true: creates a new advertised session with the ticket's first GameModeTag as its GameMode attribute
   • bFallbackToHost=false: surfaces Failed_Timeout

Minimal C++ usage

UPlayLinkMatchmakingSubsystem* MM = GI->GetSubsystem<UPlayLinkMatchmakingSubsystem>();

MM->OnStatusChanged.AddDynamic(this, &ThisClass::HandleStatus);
MM->OnCompleted.AddDynamic(this, &ThisClass::HandleCompleted);

FPlayLinkMatchmakingTicket Ticket;
Ticket.GameModeTags = { TEXT("Ranked"), TEXT("Solo") };
Ticket.PartySize = 1;
Ticket.MaxWaitSeconds = 60.0f;
Ticket.bFallbackToHost = true;

MM->StartMatchmaking(0, Ticket);

Swapping the strategy

Subclass UPlayLinkMatchmakingServiceBase and override the pure-virtual StartMatchmaking / CancelMatchmaking / GetStatus / GetEstimatedWaitSeconds. Point the config entry at your subclass:

[PlayLink]
MatchmakingServiceClass=/Script/MyGame.MyEloMatchmaker

The subsystem instantiates the configured class at Initialize and forwards every BP-callable function to it. Project code keeps calling the same UPlayLinkMatchmakingSubsystem API, only the strategy underneath changes.

End-to-end flow

UPlayLinkDevWidgetBase travel API

The dev widget caches the connect string from the most recent successful OnSessionJoined and exposes BlueprintCallable wrappers. Subclass the widget in your project (or call the C++ directly), no need for BP graphs to reach Get World or Get Game Mode.

Connect string lifecycle

OnSessionJoined hands the resolved connect string back through the third delegate parameter. The dev widget caches it on success only, failed joins clear the cache so a stale URL can't fire later. OnSessionDestroyed also clears the cache: a destroyed session's URL belongs to a session that no longer exists.

// Bind once during init
SessionSubsystem->OnSessionJoined.AddDynamic(this, &UMyClass::HandleJoined);

// Capture and travel
void UMyClass::HandleJoined(EPlayLinkResult Result, FPlayLinkSessionHandle Handle, FString ConnectString)
{
    if (Result == EPlayLinkResult::Success && !ConnectString.IsEmpty())
    {
        GetOwningPlayer()->ClientTravel(ConnectString, ETravelType::TRAVEL_Absolute, false);
    }
}

Public surface

Events

Buffered-write pattern

Writes go to the local cache instantly; the backend round-trip happens on Flush. This matches how most projects want to track stats, increment per-event, persist on match end or interval.

UPlayLinkStatsSubsystem* Stats = GI->GetSubsystem<UPlayLinkStatsSubsystem>();

// During gameplay, cheap, local-only
Stats->IncrementStatInt(0, TEXT("stat_kills"), 1);
Stats->SetStatFloat(0, TEXT("stat_best_combo_time"), 12.4f);

// On match end, persist to backend
Stats->OnStatsFlushed.AddDynamic(this, &ThisClass::HandleStatsFlushed);
Stats->FlushStats(0);

Public surface

Pairing with Achievements

Stats hold the counter; Achievements hold the unlock state, two different concerns that pair naturally:

// Track the counter
Stats->IncrementStatInt(0, TEXT("stat_total_kills"), 1);

// Check threshold against the local cache
if (Stats->GetStatInt(0, TEXT("stat_total_kills")) >= 100)
{
    Achievements->UnlockAchievement(0, TEXT("ACH_KILL_100"));
}

Public surface

FPlayLinkLeaderboardEntry

Each fetch returns an array of these, sorted by Rank ascending.

Minimal usage

UPlayLinkLeaderboardsSubsystem* LB = GI->GetSubsystem<UPlayLinkLeaderboardsSubsystem>();
LB->OnLeaderboardFetched.AddDynamic(this, &ThisClass::HandleLeaderboardFetched);

// On match end, push the score
LB->SubmitScore(0, TEXT("lb_weekly_kills"), MyMatchKills);

// On opening the leaderboard UI
LB->FetchRange(0, TEXT("lb_weekly_kills"), 0, 100);

Available nodes

When to use async actions vs. delegate binding

Both APIs are first-class. Pick based on the flow you're building:

Console exec commands

Drop the in-game console (~) and run any of these. They auto-register on every UCheatManager creation, so they're available on the standard player controller.

Debug panel

The dev panel ships as a UMG widget at /PlayLink/WBP_PlayLinkDevWidget. PlayLinkOpen spawns it on the local player controller and switches input mode to UI-only with the cursor visible, same pattern as a pause menu. Esc closes the panel via NativeOnKeyDown; no per-project BP wiring needed for the dismiss shortcut.

The panel renders one card per subsystem (Backend, Identity, Friends, Lobby, Session, Party, Event Log). The C++ base class UPlayLinkDevWidgetBase exposes BP-pure getters for every subsystem's state and BlueprintImplementableEvent refresh hooks designers override to repopulate cards. Project authors can subclass UPlayLinkDevWidgetBase in their own project to customize the layout and point Project Settings → Plugins → PlayLink Dev → Dev Widget Class at the subclass.

Event log subsystem

UPlayLinkDevSubsystem subscribes to every PlayLink delegate and rolls a 256-entry circular buffer of FPlayLinkDevLogEntry structs (timestamp, source enum, severity, message). The dev panel binds to OnLogEntryAdded and renders log lines as they land. PlayLinkDumpLog prints the captured buffer to the engine log; PlayLinkClearLog resets it.