Skip to main content

Read the friends list

You can access a user's friends list through the friends interface. The user must be a local user that's signed in.

Reading the friends list​

Before you can get a list of friends, you need to call ReadFriendsList. Before you call ReadFriendsList for the first time, the cached friends list will be empty.

When you call ReadFriendsList, the plugin fetches and unifies friends as outlined in the cross-platform friends overview.

First, get the online friends interface:

#include "OnlineSubsystem.h"
#include "OnlineSubsystemUtils.h"
#include "Interfaces/OnlineFriendsInterface.h"

// ...

IOnlineSubsystem *Subsystem = Online::GetSubsystem(this->GetWorld());
IOnlineFriendsPtr Friends = Subsystem->GetFriendsInterface();

Then, call ReadFriendsList and pass a delegate to run on completion:

Friends->ReadFriendsList(
    0 /* LocalUserNum */,
    TEXT("") /* ListName, unused by EOS */,
    FOnReadFriendsListComplete::CreateUObject(this, &UMyClass::OnReadComplete)
);

// ...

void UMyClass::OnReadComplete(int32 LocalUserNum, bool bWasSuccessful, const FString& ListName, const FString& ErrorStr)
{
    // Check bWasSuccessful; if it's true, you can now call GetFriendsList.
}

Getting the cached friends list​

Once ReadFriendsList has completed successfully, you can then call GetFriendsList:

TArray<TSharedRef<FOnlineFriend>> FriendsArr;
Friends->GetFriendsList(
    0 /* LocalUserNum */,
    TEXT("") /* ListName, unused by EOS */,
    FriendsArr /* OutFriends */
);
for (const auto& Friend : FriendsArr)
{
    // Access the friend via Friend.
}

Getting a friend's user attributes​

To display information about a particular friend, refer to the User attributes documentation for what fields are available.

Getting a friend's presence information​

You can use the GetPresence function on FOnlineFriend to read the friend's current presence information:

// For example:
if (Friend->GetPresence().Status.State == EOnlinePresenceState::Online)
{
    // ...
}
info

For Epic Games friends, you'll need to query for presence information in order to keep the presence information up-to-date. This is not required for delegated subsystems like Steam.

Getting a single friend​

If you already know the user ID of a friend, you can call GetFriend to receive information about just that friend, rather than receiving a copy of the full friends list:

TSharedPtr<FOnlineFriend> Friend = Friends->GetFriend(
    0 /* LocalUserNum */,
    FriendUserId /* FriendId */,
    TEXT("") /* ListName, unused by EOS */);
if (Friend.IsValid())
{
    // Friend is valid and on the friends list.
}

Checking if another user is a friend or has a pending invite​

If you want to know if a given user ID is on the friends list, you can call IsFriend. Please note that this function will return true if the target user ID is on the friends list at all; this includes pending inbound and outbound friend invites:

if (Friends->IsFriend(
    0 /* LocalUserNum */,
    TargetUserId /* FriendId */,
    TEXT("") /* ListName, unused by EOS */))
{
    // Target user is either a friend, has been invited to our friends list, or sent
    // us an invite to their friends list.   
}

Receive notifications when friends change​

A user's friend list can change without invoking any methods; this can happen for several reasons:

  • They've modified their friends list on the local platform (such as Steam) or one of their local platform friend's changed presence status
  • They've received a friend invite from another EOS user
  • Their invite to another EOS user has been accepted or rejected
  • An EOS user on their friend list deleted them from their friends list

The full list of implemented events in EOS Online Subsystem are:

  • OnFriendsChange: Raised whenever the friends list data you would get from GetFriendsList changes. You should use this event to synchronise friends list changes back to your game's user interface.
  • OnInviteReceived: Raised whenever an EOS user invites a local user to their cross-platform friends list.
  • OnInviteAccepted: Raised whenever an EOS user accepts an invite that a local user sent to them.
  • OnInviteRejected: Raised whenever an EOS user rejects an invite that a local user sent to them.
  • OnFriendRemoved: Raised whenever an EOS user removes a local user from their friends list.
  • OnBlockListChange: Raised whenever a local user's "blocked players" list changes.
  • OnRecentPlayersAdded: Raised whenever a local user's "recent players" list changes. This can happen without calling AddRecentPlayers, as the plugin automatically tracks other users seen on multiplayer servers.

For example, to watch for friend change events:

FDelegateHandle Handle = Friends->AddOnFriendsChangeDelegate_Handle(
    0 /* LocalUserNum */,
    FOnFriendsChangeDelegate::CreateUObject(this, &UMyClass::OnFriendsListChange));
// You can use `Handle` later to call `Friends->ClearOnFriendsChangeDelegate_Handle(0, Handle)`
// if you want to unregister the event handler.

// ...

void UMyClass::OnFriendsListChange()
{
    // The friends list has changed.
}

Because OnFriendsChange is registered per local user, you might want to register it for all possible local users and include the local user number as a parameter when the event fires:

for (int32 LocalUserNum = 0; LocalUserNum < MAX_PLAYERS; LocalUserNum++)
{
    FDelegateHandle Handle = Friends->AddOnFriendsChangeDelegate_Handle(
        LocalUserNum,
        FOnFriendsChangeDelegate::CreateUObject(this, &UMyClass::OnFriendsListChange, LocalUserNum /* This captures the local user num as a user parameter */));
    // Store `Handle` in a map if you want to later unregister the event.
}

// ...

void UMyClass::OnFriendsListChange(int32 LocalUserNum /* This is passed from the capture; it doesn't come from the event callback */)
{
    // The friends list has changed.
}