Friends sample

Before continuing, download and install the Unity Hub and a supported version of the Unity Editor. The Friends service supports the following Unity Editor versions:

  • Version 2021 or later
    • Supports UI Toolkit and Unity GUI
  • Version 2020.3 or later
    • Supports Unity GUI

Download the sample project

Download the Friends sample project from GitHub and open it in a supported version of the Unity Editor. You’ll want to have the sample project open while you enable the Friends service.

Enable the Friends service

  1. Log into the Unity Cloud Dashboard. If you don’t already have an account, refer to Get started with Unity Gaming Services (UGS).
  2. Go to Products > Friends.
  3. Select Launch.
  4. If you haven’t already added your payment information, the Unity Cloud Dashboard might prompt you to add your payment information. Friends is a pay as you go service with a free tier.
  5. Continue onto the Setup Guide, which walks you through setting up your Friends project.

Note: You can skip this step if you've already linked your project through the Unity Engine. You can also link your project after enabling the Friends service.

  1. Follow the instructions at Link your project in the Unity Editor.
  2. Select Next in the Setup guide.

Install the Friends package

  1. You can use Unity Editor version 2021 or later or version 2020.3 or later. Select the version you want to use in the Setup guide on the Unity Cloud Dashboard, then follow the instructions.
  2. When you’re finished, select Next in the Setup guide.

Turn Friends on

  1. Activate Friends by toggling the button in the Setup guide to On. Once activated, players can send friend requests to other players and build a friends list.
  2. Select Finish.

Note: If you meet any conflicts with other services, deactivate the Friends service. You can turn Friends on or off at any time.

Running the sample in-Editor

Use the following instructions to set the sample up locally:

  1. Launch the Unity Hub.
  2. Select Open > Add project from disk.
  3. Select the sample project location on your local disk, then select Add Project.
  4. The sample project will appear listed in the Unity Hub with the correct Editor version. Double-click the project to open it. You might have to wait several minutes for Unity to launch the project.

Drag and dropping the assets into your project

This sample works as a plug-in to your project. It gets you up and running with Friends in no time at all!

Get the assets

Either drag the entire Assets/FriendsSample/ folder from the sample project into your project, or export the folder as a .unitypackage.

Resolving dependencies

This project depends on two non-standard Unity package dependencies:

  • Friends Service SDK
    • Get this by going to the Package Manager (Window > Package manager)
    • Hit the little + Icon in the top left corner of the window and select Add package from Git URL or Add package by name.
    • Type in :
  • TextMesh Pro Essential Resources
    • Get this by going to Window > Textmesh Pro > Import TMP Essential Resources

Using the sample assets

For 2020.3, the sample supports Canvas-Style UI and for 2021.1+, the sample supports UIToolkit style UI. Study the sample scenes to view the Hierarchy and general setup. You can also drag the RelationshipsManager into any scene and the UI will display it and work.

Play with the sample project

At this point, you have the sample project open in the Unity Editor. It’s time to interact with the sample.

Note: If you haven’t already, log into the Unity Editor and link your Unity project before continuing.

The sample project consists of a simple user interface that allows you to interact with the Friends service and perform actions such as:

Use the following table as a reference for the meaning of buttons and user interface elements.

Button nameDescription
Decline(×)Decline a friend request
Accept (✔)Accept a friend request
Block (-)Block a player
UnblockRemove a player from your Block list
RemoveRemove a player from your Friend list
Friends listA list of all the players you’re friends with
Block listA list of all the players you’ve blocked
Friend Request ListA list of incoming friend requests

Start the project

You must start the sample Scene before you can interact with the sample user interface.

  1. From the Project tab, select Assets > Scenes.
  2. Double-click the FriendsSampleUGUI scene or the FriendsSampleUIToolkit scene.
  3. Start the scene by entering the Play mode in the Unity Editor.

After the scene launches, the sample Friends user interface will display.

Testing the project

To test this project alone, you must have the Unity Editor open and a build of the project open.

  1. Open the Build Settings (File > Build Settings).
  2. Select a build to the platform of your choice. (Tested on Windows and macOS.)
  3. Make sure one of the sample Scenes is the top scene included.
  4. When complete, run the Build and Editor at the same time.

Send a friend request

You can send a friend request to another player using the player’s ID and the Add Friend button.

  1. Copy the Player ID from the project.
  2. Switch to a build of the project.
  3. Select the Add Friend button.
  4. Paste the ID of Project Player into the ID field, then select Add.
  5. Go back to the Unity Editor.
  6. Select the Friend Request List button.
  7. Accept or Ignore the friend request from Build Player.

Block a player

If a player has blocked you, they will appear as offline to you. If you block a player, they will appear in your block list.

There are two ways to block another player: from your friends list and from your friend request inbox.

Block a player from your friends list:

  1. Select the Friends list button.
  2. Select the Block (-) button next to the name of the player you want to block.

Block a player who sent you a friend request:

  1. Select the Friend Request list button.
  2. Select the Block (-) button next to the name of the player you want to block.

You can view and unblock blocked players in your block list.

Unblock a player

You can unblock a player by viewing your block list, then selecting the Unblock button next to the player’s name.

Remove a friend

You can remove a friend from your friends list by selecting the Remove friend button next to the player’s name in your friends list.

  1. Select the Friends list button.
  2. Select the Remove friend button.

Set your presence status

You can set your presence status by selecting the down arrow next to your current status, then selecting the new status. For example, to change your status from ONLINE to BUSY:

INVISIBLE is a special status, that makes you appear offline to all your friends.

  1. Select the down arrow next to ONLINE.
  2. Select BUSY.

Set your Activity status

You can set your activity status by selecting the text to the right of the Presence dropdown. For example, you can set custom statuses based on the player's activity in the game they're currently playing.

  1. Select the In Friends Menu text. This is the default activity status
  2. Type a new message, then press the Enter key. After pressing the Enter key, users on your friend list can see the updated activity status.

Note: The Friends service doesn't automatically save presence or activity when the user goes offline. To support persisting the same presence or activity when logging back on, save the presence or activity locally or via a data storage service like Cloud Save.

View your friends list

You can view your friends list by selecting the Friends List button.

View your request list

You can view your friend request list by selecting the Request list button.

View your block list

You can view your block list by selecting the Block list button.