Unreal Engine 5 Documentation has been moved to the Epic Developer Community

Playing games with your friends and meeting new players online is an important part of many online services. The Friends Interface contains features to manage a user's list of social contacts, including adding, removing, and blocking other users.

Managing Friends

Friends lists are stored on the online service's servers, and can change during a session as friends are added or removed, join and leave games and sessions, or log in and out of the service. As a result, managing these lists involves querying the server for the latest information, then caching that information and using it in your game.

Retrieving Friends Lists

The first step in dealing with a user's friends lists is generally to call ReadFriendsList , which retrieves the most up-to-date version of a named friends list belonging to a specified local user. Valid list names can be found in the EFriendsList enumerated type, and can be converted into strings by the provided ToString`function. Because it queries a remote machine, the ReadFriendsList is asynchronous and will call a delegate of type FOnReadFriendsListComplete` when complete.

Examining Friends Lists

After a successful call to ReadFriendsList retrieves and caches a list, developers can use GetFriendsList to get a copy of the list itself, or GetFriend to retrieve an individual friend from the list. In addition, a known user's FUniqueNetId can be passed to the IsFriend function to check a specified list for that user.

Inviting a Friend

The SendInvite function will send an invitation to another user, identified by that user's FUniqueNetId . Upon acceptance, the user will be added to the specified list by the online service. A delegate of type FOnSendInviteComplete will be called when this operation finishes, but this only means that the invitation has been sent (or has failed to send), not that the intended recipient has received or responded to it. Some online services may have custom user interfaces for sending invitations, and these may open automatically when SendInvite is called.

Accepting or Rejecting an Invitation

When an invitation from another user has arrived, a delegate of type FOnInviteReceivedDelegate will be called, containing the FUniqueNetId of the sender and the recipient. The invited user can then call AcceptInvite or RejectInvite to respond, specifying the name of the list where the new friend should appear. AcceptInvite uses a delegate of type FOnAcceptInviteComplete to communicate the results of the operation, while RejectInvite uses an FOnRejectInviteComplete delegate.

Deleting a Friends List

The online service can be instructed to delete a friends list through the asynchronous DeleteFriendsList function. When complete, a delegate of type FOnDeleteFriendsListComplete will be called.

Deleting a Friend

To remove a friend from a list belonging to a local user, call the DeleteFriend function. When the operation is complete, a delegate of type FOnDeleteFriendComplete will be called. It may be possible for a friend to exist in multiple lists on some online services; if this is the case, this function will only remove the friend from the specified list.

Dealing with Players Met Online

Online services often keep a separate list of players that a user has encountered recently, such as in a public gaming session, but has not added to the friends list or blocked. Like friends lists, the list of recently-met players is handled by querying the online service and then caching the list.

Retrieving the List of Recently-Met Players

The QueryRecentPlayers makes an asynchronous call to the online service, calling a delegate of type FOnQueryRecentPlayersComplete upon completion. If successful, the Friends Interface will cache the list locally.

Examining Recently-Met Players

Once a successful call to QueryRecentPlayers has retrieved the list of recently-met players, the GetRecentPlayers function will return the cached array. The individual elements of the array contain the user's data as well as a function to tell when the player was last seen online.

Managing the Block List

Many online services provide the ability for a user to prevent specific other users from contacting or playing with them through the service. The Friends Interface can retrieve and cache a list of blocked users, as well as utilize the online service's block and unblock features.

Listing Currently-Blocked Users

To retrieve the list of blocked users, call the QueryBlockedPlayers function. This function is asynchronous, and will call a delegate of type FOnQueryBlockedPlayersComplete when it completes. In addition, any changes made to the list of blocked users will result in notification through an FOnBlockListChange delegate.

Blocking and Unblocking Users

The BlockPlayer and UnblockPlayer functions will make asynchronous calls to the online service, requesting that a specific player, identified by an FUniqueNetId , be blocked or unblocked by a local player. When these operations complete, they will return success or failure information through delegates of type FOnBlockedPlayerComplete and FOnUnblockedPlayerComplete , respectively.