Receptionist

The following instructions cover Windows and macOS operating systems unless otherwise stated.

Use the Receptionist connection workflow in the following cases:

  • To connect server-worker instances to local or cloud deployments. In this case, you must always use the Receptionist.
  • To connect client-worker instances to local deployments for debugging without authentication.

ClientTravel

To connect a client-worker instance to a deployment from an offline state, you must use ClientTravel. You can implement ClientTravel with a PIE client, in code, and on the command line.

PIE

Connect a client-worker instance to a local deployment

When you start a Play In Editor (PIE) client-worker instance from the Unreal Editor, the client-worker instance automatically attempts to connect to a local deployment on your machine using the Receptionist, and using the IP address 127.0.0.1 by default. This is useful for quick editing and debugging. To change the IP address in the Unreal Editor, from the GDK toolbar:

  1. Select the dropdown next to the Start Deployment button
  2. Make sure that Connect to a local deployment is selected
  3. In the Local Deployment IP field, enter the IP address of the machine running your local deployment

When SpatialOS Networking is enabled, worker instances wait for the Unreal Editor to start a local deployment before attempting to connect. If you want to disable this functionality (for example, if you want to start a deployment outside the Unreal Editor), clear the Auto-start local deployment option in the SpatialOS Editor Settings.

Connect a client-worker instance to a cloud deployment

You can connect your PIE client-worker instances to a cloud deployment using spatial cloud connect external. This means you can quickly iterate on changes without having to repeatedly build out your client-worker instances. Use spatial cloud connect external to set up a direct connection from your local machine to your cloud deployment using the Receptionist.

  1. Open a terminal window, navigate to <Your Game Folder>/spatial, and run the following command:
spatial cloud connect external <deployment name> --listening_address 127.0.0.1

The connection is ready when you see The receptionist proxy is available on port 7777.

  1. Now open your game in the Unreal Editor. Go to Settings > Project Settings > SpatialOS GDK for Unreal > Editor Settings > Launch and make sure that Auto-start local deployment is cleared.
  2. From the GDK toolbar, select Play.

ServerTravel

To test ServerTravel in local deployments using PIE, set up your Unreal Editor to disable running a single process and to enable playing as a client-worker instance. To do this:

  1. In your Unreal Editor, navigate to Editor > Editor Preferences > Level Editor > Play > Multiplayer Options and clear Use Single Process to disable it.
  2. In the same menu, locate Editor Multiplayer Mode and select Play As Client.

Travel URL

To connect to a deployment using ClientTravel and the Receptionist, call APlayerController::ClientTravel and specify the local deployment IP of the host machine and the port that the deployment is running on. For example:

FString TravelURL = TEXT("127.0.0.1:7777");
PlayerController->ClientTravel(TravelURL, TRAVEL_Absolute, false /*bSeamless*/);

Refer to the Map travel URL options section for all possible URL options.

Command-line arguments

By default, outside Play In Editor (PIE), client-worker instances can connect to a deployment only when specific IP address parameters are included as command-line arguments. The Receptionist connects worker instances to a deployment by specifying the host IP and port of the deployment. When you specify these parameters in command-line arguments when you start a client-worker instance, the client-worker instance connects automatically via the Receptionist.

This means you can implement your own connection workflow, whether that is through a login screen, a connected lobby, or something else. You can specify IP address parameters on the command line in the same way as in native Unreal, with the first argument being the connection IP address.

There is an example of how to automatically connect a client-worker instance to a deployment using the Receptionist in the LaunchClient.bat script which you can find in the Example Project repository.


2020-07-14 Restructure page content
2020-06-15 Page added with editorial review

Updated about a year ago


Receptionist


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.