This topic is for advanced users only. Before reading this page, make sure you are familiar with the Unreal documentation on Map travel.
In native Unreal
ClientTravel is the process of changing which map (or Level - see Unreal documentation) a client currently has loaded. It is also used to connect to a server or change servers.
In the GDK
In the GDK you can use
ClientTravel to connect to a SpatialOS deployment, where that connection is to a local deployment or a cloud deployment. You can also change the current SpatialOS deployment the client is connected to.
By specifying a URL as the first command line parameter when launching a client you can automatically connect clients to a deployment. There are two options available in SpatialOS, the receptionist flow for local deployments and the locator flow for cloud deployments. Alternatively you can connect from an offline client to a deployment in-game by using APlayerController::ClientTravel (OpenLevel in blueprints).
Please refer to the Map Travel URL options section for all possible SpatialOS URL options.
Using Receptionist - Local Deployments
The Receptionist is a SpatialOS service which allows you to connect to a deployment using the host IP and port of the SpatialOS deployment. You can specify these parameters in command line arguments when booting a client and you will connect automatically via receptionist. An example of the receptionist being used to automatically connect a client on boot can be found in the
LaunchClient.bat script found in our UnrealGDKExampleProject.
To connect to a deployment using
ClientTravel and the receptionist flow, simply call
APlayerController::ClientTravel with the receptionist IP of the host machine and the port the SpatialOS deployment is running on. For example:
FString TravelURL = TEXT("127.0.0.1:7777"); PlayerController->ClientTravel(TravelURL, TRAVEL_Absolute, false /*bSeamless*/);
Using Locator - Cloud Deployments
The Locator is a SpatialOS service which allows you to connect to cloud deployments.
Experimental: You can use
ClientTravelto change which cloud deployment a client is connected to. This functionality is experimental and requires you to write your own authorization code.
Using the locator flow is very similar to using the receptionist, except with different URL options. You must add the
locator option, and specify the appropriate options. The
locator workflow makes use of the new Authentication flow.
Locator: Add the options
login. For more information about the options, see Map Travel URL options.
FURL TravelURL; TravelURL.Host = TEXT("locator.improbable.io"); TravelURL.AddOption(TEXT("locator")); TravelURL.AddOption(TEXT("playeridentity=MY_PLAYER_IDENTITY_TOKEN")); TravelURL.AddOption(TEXT("login=MY_LOGIN_TOKEN")); PlayerController->ClientTravel(TravelURL.ToString(), TRAVEL_Absolute, false /*bSeamless*/);
ServerTravelis on the roadmap but is not currently supported.
Default connection flows
Play In Editor Clients
Launching a PIE client from the editor will automatically attempt to connect to a local SpatialOS deployment on your machine by using the receptionist flow. It uses the URL
127.0.0.1 This is for quick editing and debugging purposes.
By default in the editor and when Spatial Networking is enabled clients and servers will automatically wait for a local SpatialOS deployment to be started by the editor before attempting to connect. If you wish to disable this functionality (e.g. if you want to start a deployment outside of the editor) you can change the “Auto-start local deployment” option in the SpatialOS Editor Settings.
With built clients
By default, outside of PIE, clients do not connect to a SpatialOS deployment unless specific URL parameters are included as command-line arguments, not specifying a URL will result in an offline client. This is so you can implement your own connection flow, whether that be through an offline login screen, a connected lobby, etc. You can specify URL parameters at the command-line the same way as native Unreal with the first argument being the URL to use to travel to.
To connect a client to a deployment from an offline state, you must use
LaunchClient.bat helper script (which we have provided with the UnrealGDKExampleProject) already includes the local host IP
127.0.0.1 which means client launched this way will attempt to connect automatically using the receptionist flow.
With the SpatialOS Launcher
When launching a client from the SpatialOS Console using the Launcher, the client will connect to the running SpatialOS cloud deployment by default. It has the
Locator parameters required to connect to said deployment included as command-line arguments. When these
Locator arguments are present, client will attempt to connect automatically. Please note the launcher login tokens are only valid for 15 minutes.
Please see the Map Travel URL options section for a list of all URL options that can be used with SpatialOS.
2019-07-31 Page updated with limited editorial review: Updated to match current connection flows. Removed ServerTravel
2019-06-13 Page updated with limited editorial review: Added Locator information