Realtime Multiplayer

Realtime multiplayer in ChilliConnect is provided by integration with Photon. A full example is available from our realtime TicTacToe tutorial.

Photon

Photon is a global cross platform multiplayer game backend for synchronous and asynchronous games. Room-based games are hosted in cloud to provide low latency and shortest round-trip times for players worldwide. ChilliConnect integrates with Photon through a custom authenticator - enabling you to identify players, and listen to game events using Photon Webhook callbacks. The Photon SDK is availabile to download from the Photon website.

Authentication Flow

To identify players that connect to Photon ChilliConnect provides a custom authentication process that can be setup as follows.

1. The game calls ChilliConnect to get a PhotonAccessToken.
2. The game calls Photon Connect with the token.
3. Photon verifies the token with ChilliConnect.
4. Photon returns success or failure to the game.

Authentication Setup

In the Photon dashboard navigate to Manage and Custom Server under Authentication.

Enter the Authentication URL as https://connect.chilliconnect.com/1.0/multiplayer/photon/authenticate and select the option Reject all clients if not available. Click Create and unselect the option Allow anonymous clients to connect, independently of configured providers. Your application should look something like this;

Authentication in-game Implementation

Get a time-limited token from ChilliConnect GeneratePhotonAccessToken specifying your Photon App ID;

Multiplayer multiplayer = m_chilliConnect.Multiplayer;
var photonAppId = "<your Photon App ID>";

Action<GeneratePhotonAccessTokenRequest, GeneratePhotonAccessTokenResponse> successCallback = (GeneratePhotonAccessTokenRequest request, GeneratePhotonAccessTokenResponse response) =>
{
    var photonAccessToken = response.PhotonAccessToken;
};

Action<GeneratePhotonAccessTokenRequest, GeneratePhotonAccessTokenError> errorCallback = (GeneratePhotonAccessTokenRequest request, GeneratePhotonAccessTokenError error) =>
{
    Debug.LogError(error.ErrorDescription);
};

multiplayer.GeneratePhotonAccessToken(photonAppId, successCallback, errorCallback);

Call Photon Connect with the time-limited access token named PhotonAccessToken.

PhotonNetwork.AuthValues = new AuthenticationValues();
PhotonNetwork.AuthValues.AuthType = CustomAuthenticationType.Custom;
PhotonNetwork.AuthValues.AddAuthParameter("PhotonAccessToken", "<token returned from ChilliConnect>");
PhotonNetwork.ConnectUsingSettings("1.0");

Photon will then verify the access token with ChilliConnect, and will return success or failure as a response to the Connect call.

Webhooks

Photon webhooks are event-driven HTTP callbacks which can be used to add functionality such as, allowing players to rejoin games and to persist player and game data. Each Photon webhook is defined by its own triggers, data and destination path. With ChilliConnect you are able to write CloudCode Scripts that get triggered by these events.

1. Game interacts with Photon.
2. Upon a Photon event being triggered configured webhooks call ChilliConnect Cloud Code Scripts.
3. For some calls, the webhook response affects the Photon response to the game.

Webhook Setup

Go to your game in the ChilliConnect dashboard and select the Settings tab. Generate and note your Photon Webhook Token.

From the Photon dashboard select Manage for your application, and Create a new Webhook under Webhooks. Select Webhooks v1.2b from the type drop down, and fill in the BaseUrl with;

https://connect.chilliworks.dev/1.0/photon/callback/<your game token>

Ensure there is no trailing slash on the BaseUrl setting.

Under CustomHttpHeaders enter the following JSON snippet, with your Photon Webhook Token.

{"Photon-Webhook-Token": "<your Photon Webhook Token>"}

Alongside any of the event names enter the ChilliConnect Cloud Code Script Key that you wish to be triggered. For example below, a Cloud Code Script with Key PHOTON_JOIN will be triggered on PathJoin.

Webhook Script

A Photon Callback is a type of Cloud Code Script, see the Cloud Code guide for full details on writing Cloud Code Scripts.

When creating a Script select Photon Callback type, and then the Photon event that the script will be triggered upon. Available Photon events are;

• PathCreate - Called when a new room is created or when its state needs to be loaded from external service.
• PathClose - Called when a room is removed from Photon servers memory. If IsPersistent is set to true the room state is sent.
• PathJoin - Called when a player joins a room when it is in Photon servers memory.
• PathLeave - Called when a player leaves the room.
• PathEvent - Called when the client raises an event in the room with the web flag HttpForward set.
• PathGameProperties - Called when the client sets a room or a player property with the web flag HttpForward set.

Note PathEvent and PathGameProperties only trigger webhooks when the HttpForward is set when raising the event.

ChilliConnect provides convenient wrappers for receiving these events and accessing the information passed in the request. The Photon event data is available to your script on the ChilliConnect.Photon.Request object. For example to get the NickName from the request;

var PhotonNickName = ChilliConnect.Photon.Request.NickName;

Details of the data sent by Photon as part of each event is available in the Photon documentation.

Photon Webhooks are expected to return a formatted response. ChilliConnect provides an object ChilliConnect.Photon.Response that provides helper methods for this use. This response object should be returned at any exit point of your Cloud Script.

ChilliConnect.Photon.Response
Method	Description
setResponseCode( code )	Sets the ResultCode of the response. Typically success - 0, see the Photon Documentation.
setMessage( message )	Sets the Message of the response.
setState( state )	Sets the State of the response. State is used for the PathCreate event see the Photon Documentation.

Response methods can be chained and default to a success response with an empty message.

As an example webhook we will write a script that will take in three common Photon Request Variables, store them against the player data then return a successful Photon response.

ChilliConnect.Logger.info("Player Save Match Data Started.");

//get data from the Photon request
var appVersion = ChilliConnect.Photon.Request.AppVersion;
var region = ChilliConnect.Photon.Request.Region;
var gameId = ChilliConnect.Photon.Request.GameID;

//ensure got the needed data
if(!appVersion || !region || !gameId  ){
    //issue a Photon response that an error occurred
    return ChilliConnect.Photon.Response.setResponseCode(2).setMessage("Expected Photon Data is missing from the Request");
}

//save to PlayerData
try {
    ChilliConnect.CloudData.setPlayerData("PhotonApplicationVersion", appVersion);
    ChilliConnect.CloudData.setPlayerData("PhotonGameRegion", region);
    var gameIdLock = ChilliConnect.CloudData.setPlayerData("PhotonLastGameID", gameId);
}
catch( e)
{
    ChilliConnect.Logger.warn("An Error has occured when setting PlayerData, please check the data from Photon.");
    ChilliConnect.Logger.error("Error:" + e );
}

ChilliConnect.Logger.info("Operation Completed.");

//issue a success Photon response
return ChilliConnect.Photon.Response.setMessage("GameID Lock: " + gameIdLock.WriteLock);

Our integration with Photon pairs a best in class websocket connection with ChilliConnect's best in class game back end, providing everything needed to run reliable, scalable, realtime multiplayer games.