Get started with Relay

Attention: The Digital Services Act (DSA) requires Unity to notify our customers’ end users if Unity takes an action that impacts those end users under the DSA. To comply with this requirement, if you use Unity Gaming Services (UGS) products that rely on the Unity Authentication Service, you must integrate the notification API.

For more information on DSA, refer to the Digital Services Act - compliance update.

To make your game compliant, refer to DSA notifications.

Read the following sections to learn how to set up a Relay project and how to use the Relay sample project. If you haven’t already, visit Get started with UGS to learn how to work with the Unity Cloud Dashboard.

Note: Binding, and other interactions done through a Relay server, are handled using a networking solution such as UTP or NGO. NGO is higher level and uses UTP under the hood.

Set up a Relay project

Relay is a PAYG (pay as you go) service with a free tier. If you exceed the free tier monthly usage limit, you must enter payment information to keep full access to Relay and any other services.

Prerequisites

To get started with Relay, you need to do the following:

Set up Relay

You can set up and manage Relay through the Unity Cloud Dashboard:

  1. Go to cloud.unity.com.
  2. Select the Products tab from the sidebar.
  3. Under Gaming Services > Multiplayer, go to Relay and select Launch.

When you launch Relay for the first time, this adds Relay to the Shortcuts section on the sidebar and opens the Overview page.

Link your Relay project in the Unity Editor

  1. Open your project in the Unity Engine and navigate to Edit > Project Settings.
  2. From the Project Settings window, go to the Services tab.
  3. Select Use an existing Unity project ID and link to the Unity Cloud Dashboard project displayed in the Setup guide.
  4. After the project links successfully, you're ready to move on to the next step of the integration process.

Install the Relay package

  1. In Unity, navigate to Window > Package Manager.
  2. From the Package Manager, search or scroll to find the “Relay” package within the Unity Registry.
  3. Select the package and click the Install button.

Check out the Simple Relay sample to learn how to interact with the sample project.

Relay with Netcode for Game Objects

Using Relay with Netcode for GameObjects is a simple use case. Check out Relay with Netcode for GameObjects to learn more.

Simple Relay sample

The Simple Relay sample is an example project that exercises the Relay SDK. The project provides a simple user interface (UI) with buttons, and is intended for manual testing of the SDK. To try the sample project, follow the steps below.

Note: The Simple Relay sample only demonstrates what the standalone Relay SDK does, which doesn't include binding to a server. The standalone Relay SDK makes HTTP API calls to the Relay backend service to create allocations and join codes, and it doesn't affect the client’s network connections.

Import the Simple Relay sample project

  1. Open a Relay project with the Unity Editor (version 2020.3). If you don’t have a Relay project set up yet, check out Set up a Relay project.

  2. Open the Package Manager and navigate to the Relay package.

  3. Expand the Samples section.

  4. Select Import to import the Simple Relay sample project.

  5. Now that you have imported the Simple Relay sample project, you can open it as a scene. It's located within the current project under Assets/Samples/Relay/1.0.1-pre.3/Simple Relay Sample.

  6. Select File > Open Scene.

  7. Navigate to the Simple Relay sample scene.

Continue onto Use the Simple Relay sample to learn how to use it.

Use the Simple Relay sample

  1. Sign into the Unity Editor.

  2. Go to Account > Sign in…

  3. Selecting the Sign in button opens the Unity Cloud Dashboard in a browser window. Make sure you’re signed into the same account with the Relay-enabled project.

  4. Link a project to the Simple Relay sample.

  5. Select Edit > Project Settings…

  6. Select Use an existing Unity project ID.

  7. Select the organization and the project.

  8. Select Link project ID.

  9. If successful, your project ID appears under Unity Project ID.

Start the Simple Relay sample

  1. Select the Play button to start the sample.

  2. Go through and select each of the buttons within the sample in order:

    1. Sign In (Anonymously) uses Unity’s Anonymous authentication to sign into Relay. This generates a player ID.
    2. Get Regions lists all the regions in which a Relay server is available.
    3. Create Relay creates a Relay allocation and returns the host allocation ID.
    4. Get Join Code generates a join code for the host to share with other players.
    5. Join Relay joins the Relay allocation and returns a player allocation ID.
Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.