Quickstart

Unreal Engine provides great multiplayer capabilities out of the box. We'll use Unreal's built-in networking to build and deploy a server-authoritative multiplayer game on top of Rivet.

This guide was built with Unreal v5.2 but should work for all Unreal 5 versions. If you run in to issues, please reach out to us on Discord.

Goals

• Deploy & distribute a multiplayer Unreal Engine dedicated game server to Rivet
• Build a basic menu screen for a multiplayer game
• How to test multiplayer games locally

Prerequisites

• Docker
• Unreal Engine 5 GitHub access
• Unreal Engine 5
  • This guide was written using Unreal Engine 5.2.1.
• About 60 GB of free space (for Unreal Engine Linux build)

FAQ

Step 1: Setup Unreal Engine project

We'll use the third-person template from Unreal Engine. All the components come with networking out of the box. These steps also apply to any other Unreal Engine games.

Authenticate with GitHub Container Registry

We need to authenticate with the GitHub Container Registry (GHCR) to be able to pull the Unreal Engine Docker image.

1. Make sure you already have Unreal Engine GitHub Access here.
2. Authenticate with these instructions.

Create project from template (or bring your own project)

1. Create a third-person template with the C++ version. We'll create a guide for using Blueprints instead of C++ soon.
2. Set Quality Preset, Starter Content, and Raytracing to anything.
3. Click Create.
4. Open the Visual Studio project by clicking Tools > Open Visual Studio.

Add server target

We need to add a target so you can compile your game as a dedicated server to run on Rivet.

Create a file at Source/MyProjectServer.Target.cs with the following. Replace MyProject with your project's name.

using UnrealBuildTool;
using System.Collections.Generic;

public class MyProjectServerTarget : TargetRules
{
	public MyProjectServerTarget(TargetInfo Target) : base(Target)
	{
		Type = TargetType.Server;
		DefaultBuildSettings = BuildSettingsVersion.V2;
		IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_1;
		ExtraModuleNames.Add("MyProject");
	}
}

Step 2: Integrate Rivet

Install Rivet CLI

curl -fsSL https://raw.githubusercontent.com/rivet-gg/cli/v1.3.4/install/unix.sh | sh

Initiate project

Run the following in your project's directory and follow the steps.

rivet init --unreal

Add dependency

Add Rivet to PrivateDependencyModuleNames in your project Source/MyProject/MyProject.Build.cs. For example:

PrivateDependencyModuleNames.AddRange(new string[] { "Rivet" });

Update AMyProjectGameMode class

We will update the game mode code to connect player connect & disconnect events to Rivet.

Update the the game MyProjectGameMdoe header & source files to look like the following. Replace MyProject with your project name.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/GameModeBase.h"

#include "RivetClient.h"
#include "RivetPlayer.h"

#include "MyProjectGameMode.generated.h"

UCLASS(minimalapi)
class AMyProjectGameMode : public AGameModeBase
{
	GENERATED_BODY()

public:
	AMyProjectGameMode();

	/** Map of player IDs to the associated Rivet player information. */
	UPROPERTY()
	TArray<URivetPlayer*> RivetPlayers;

	UPROPERTY()
	FString RivetToken;

	UPROPERTY()
	URivetClient* Rivet;

	void InitGame(const FString& MapName, const FString& Options, FString& ErrorMessage) override;
	APlayerController* Login(UPlayer* NewPlayer, ENetRole InRemoteRole, const FString& Portal, const FString& Options, const FUniqueNetIdRepl& UniqueId, FString& ErrorMessage) override;
	void Logout(AController* Exiting) override;
};

#include "MyProjectGameMode.h"
#include "MyProjectCharacter.h"
#include "UObject/ConstructorHelpers.h"
#include "GameFramework/GameSession.h"
#include "GameFramework/PlayerState.h"
#include "GenericPlatform/GenericPlatformMisc.h"
#include "Kismet/GameplayStatics.h" 

#include "MatchmakerPlayersConnected.h"
#include "MatchmakerPlayersDisconnected.h"
#include "MatchmakerLobbiesReady.h"

AMyProjectGameMode::AMyProjectGameMode()
{
	Rivet = NewObject<URivetClient>();

	// set default pawn class to our Blueprinted character
	static ConstructorHelpers::FClassFinder<APawn> PlayerPawnBPClass(TEXT("/Game/ThirdPerson/Blueprints/BP_ThirdPersonCharacter"));
	if (PlayerPawnBPClass.Class != NULL)
	{
		DefaultPawnClass = PlayerPawnBPClass.Class;
	}
}

void AMyProjectGameMode::InitGame(const FString& MapName, const FString& Options, FString& ErrorMessage)
{
	Super::InitGame(MapName, Options, ErrorMessage);

	// Set lobby as ready
	FMatchmakerLobbiesReadyRequest Req;
	FMatchmakerLobbiesReadyDelegate OnSuccess;
	FRivetHttpRequestFailDelegate OnFailure;
	Rivet->MatchmakerLobbiesReady(Req, OnSuccess, OnFailure);
}

APlayerController* AMyProjectGameMode::Login(UPlayer *NewPlayer, ENetRole InRemoteRole, const FString &Portal, const FString &Options, const FUniqueNetIdRepl &UniqueId, FString &ErrorMessage)
{
	UE_LOG(LogTemp, Warning, TEXT("Login: %s"), *Options);
	
	// Read player token option
	auto PlayerToken = UGameplayStatics::ParseOption(Options, "PlayerToken");
	if (PlayerToken.IsEmpty())
	{
		ErrorMessage = TEXT("No PlayerToken option provided");
		return nullptr;
	}
	UE_LOG(LogTemp, Warning, TEXT("Palyer token: %s"), *PlayerToken);
	
	// Create player
	auto PlayerController = Super::Login(NewPlayer, InRemoteRole, Portal, Options, UniqueId, ErrorMessage);
	if (!ErrorMessage.IsEmpty()) {
		UE_LOG(LogTemp, Warning, TEXT("Error connecting player: %s"), *ErrorMessage);
		return nullptr;
	}

	// Save the Rivet player information
	auto RivetPlayer = NewObject<URivetPlayer>();
	RivetPlayer->PlayerId = PlayerController->PlayerState->GetPlayerId();
	RivetPlayer->PlayerController = PlayerController;
	RivetPlayer->PlayerToken = PlayerToken;
	RivetPlayers.Add(RivetPlayer);

	// Send connection request
	FMatchmakerPlayersConnectedRequest Req;
	Req.PlayerToken = PlayerToken;

	FMatchmakerPlayersConnectedDelegate OnSuccess;
	OnSuccess.BindDynamic(RivetPlayer, &URivetPlayer::OnPlayerConnectedSuccess);
	
	FRivetHttpRequestFailDelegate OnFailure;
	OnFailure.BindDynamic(RivetPlayer, &URivetPlayer::OnPlayerConnectedFailure);

	Rivet->MatchmakerPlayersConnected(Req, OnSuccess, OnFailure);

	return PlayerController;
}

void AMyProjectGameMode::Logout(AController *Exiting)
{
	auto PlayerId = Exiting->PlayerState->GetPlayerId();
	auto RivetPlayer = *RivetPlayers.FindByPredicate([&](auto X) { return X->PlayerId == PlayerId; });
	if (RivetPlayer == nullptr) {
		UE_LOG(LogTemp, Error, TEXT("Could not find RivetPlayer to disconnect for player %d"), PlayerId);
		return;
	}

	UE_LOG(LogTemp, Error, TEXT("Logging out player: %d %s"), PlayerId, *RivetPlayer->PlayerToken);

	// Send connection request
	FMatchmakerPlayersDisconnectedRequest Req;
	Req.PlayerToken = RivetPlayer->PlayerToken;

	FMatchmakerPlayersDisconnectedDelegate OnSuccess;
	OnSuccess.BindDynamic(RivetPlayer, &URivetPlayer::OnPlayerDisconnectedSuccess);
	
	FRivetHttpRequestFailDelegate OnFailure;
	OnFailure.BindDynamic(RivetPlayer, &URivetPlayer::OnPlayerDisconnectedFailure);

	Rivet->MatchmakerPlayersDisconnected(Req, OnSuccess, OnFailure);
}

Restart Unreal Engine for the new C++ header to take effect.

Step 3: Build game menu UI

We will build a simple menu UI that will allow players to connect to a server. This will be the first thing players see when they start the game. We will also update the default map to be the menu UI instead of the game world.

Create the menu UI world

1. Create a new level in File -> New Level...
2. Select Empty Level
3. Click File -> Save Current Level or press Ctrl + S. Save in All/Content/Third Person/Maps and name it Entry.
4. Change the game mode by clicking the Blueprint dropdown and then clicking World Override -> Game Mode: Not overridden! -> Select GameModeBase Class -> GameModeBase - This will remove the game mode logic to create a pure menu screen

Create the menu widget

1. Open the Content Drawer
2. Open All/Content/ThirdPerson/UI
   • You may have to create this folder
3. Right-click in the content area and click User Interface -> Widget Blueprint
4. Click User Widget
5. Rename it to EntryWidget

Design menu widget

1. Open the EntryWidget you created
2. Construct the following design:

Write widget blueprint to connect to server when button is clicked

1. Create a development token by running the following command and copying the token. It should look like dev_staging.XXXX. Save this for the next step.

   rivet token create dev
   

   Command Line
2. Open the Blueprint code for the EntryWidget you created by clicking Graph in the top right corner
   • Replace MY_TOKEN with the token you just created.
3. Construct the following Blueprint:
4. Press Compile

This widget can now be used to connect a player to a server.

Add the menu widget to the entry level

1. Open the level Blueprint by clicking the Blueprint dropdown and then clicking Open Level Blueprint
2. Construct the following Blueprint:
3. Press Compile

Update the default map

Now that we have a new Entry map for the UI, we need to make it the default map.

1. Open Edit -> Project Settings...
2. Click on Maps & Modes under Projects in the sidebar
   • You can also search for "map" in the search bar
3. Change Game Default Map to /Game/ThirdPerson/Maps/Entry
4. Change Advanced > Server Default Map to /Game/ThirdPerson/Maps/ThirdPersonMap

Set up play configuration for testing multiplayer

We will configure the play settings to test the game with Rivet locally in your editor.

1. Press the three dots next to the play button and click Advanced Settings to open the Play In settings.

   

2. Scroll down to Multiplayer Options. Update the following settings:

   • Launch Separate Server: False
   • Play Net Mode: Play Standalone
   • Run Under One Process: True

3. Update the number of players to at least 2.

   

Test the game server locally

Run server

This will build & run your game server locally and run on port 7777. You must re-run this command whenever you change your server code.

rivet unreal start-server

Run client

1. Switch to the main editor
2. Validate that the Entry level is open
3. Click Play
4. Click Connect in each of the game instances created
5. You should be able to see each player running around in sync

This is using the Rivet development token to mock production APIs. This lets you test with production APIs while still using your local machine.

Step 4: Deploy to Rivet & distribute game

Deploy to Rivet

In the root of the project, run the following command:

rivet deploy -n prod

This will deploy your project to your game's production environment.

Test with remote game server locally

Now that your game is deployed to Rivet, you can test using a production environment token.

1. Create a new Public Token under your environment's Tokens tab
2. Update the token in the Entry widget blueprint where you set MY_TOKEN in the previous step.
3. Play the project and click your Connect button. Check that you are able to see the other player run around.

Your game is now up and running on Rivet!

You can see the lobbies in the Rivet dashboard. These will automatically scale up and down as players come and go.

Build & distribute client

You can now build & distribute the game client as you normally would.

Make sure to change Rivet Token to the correct Public Token for your environment when distributing builds, like we did in a previous step.

You can also use Unreal's config files to configure the token.