Integrating a game client for Realtime Servers
This topic describes how to prepare your game client to be able to join and participate in Amazon GameLift-hosted game sessions.
There are two sets of tasks needed to prepare your game client:
-
Set up your game client to acquire information about existing games, request matchmaking, start new game sessions, and reserve game session slots for a player.
-
Enable your game client to join a game session hosted on a Realtime server and exchange messages.
Find or create game sessions and player sessions
Set up your game client to find or start game sessions, request FlexMatch matchmaking, and reserve space for players in a game by creating player sessions. As a best practice, create a backend service and use it to make the direct requests to the Amazon GameLift service when triggered by a game client action. The backend service then relays relevant responses back to the game client.
-
Add the Amazon SDK to your game client, initialize an Amazon GameLift client, and configure it to use the hosting resources in your fleets and queues. The Amazon SDK is available in several languages; see the Amazon GameLift SDKs For game client services.
-
Add GameLift functionality to your backend service. For more detailed instructions, see Add Amazon GameLift to your game client and Adding FlexMatch matchmaking. The best practice is to use game session placements to create new game sessions. This method lets you take full advantage of GameLift's ability to quickly and intelligently place new game sessions, as well as use player latency data to minimize game lag. At a minimum, your backend service must be able to request new game sessions and handle game session data in response. You may also want to add functionality to search for and get information on existing game sessions, and request player sessions, which effectively reserve a player slot in an existing game session.
-
Convey connection information back to the game client. The backend service receives game session and player session objects in response to requests to the Amazon GameLift service. These objects contain information, in particular connection details (IP address and port) and player session ID, that the game client needs to connect to the game session running on a Realtime Server.
Connect to games on Realtime Servers
Enable your game client to connect directly with a hosted game session on a Realtime server and exchange messages with the server and with other players.
-
Get the Realtime Client SDK, build it, and add it to your game client project. See the README file for more information on SDK requirements and instructions on how to build the client libraries.
-
Call Client() with a client configuration that specifies the type of client/server connection to use.
-
Add the following functionality to your game client. See the Realtime Servers client API (C#) reference for more information.
-
Connect to and disconnect from a game
-
Send messages to target recipients
-
Receive and process messages
-
Join groups and leave player groups
-
-
Set up event handlers for the client callbacks as needed. See Realtime Servers client API (C#) reference: Asynchronous callbacks.
Game client examples
Basic realtime client (C#)
This example illustrates a basic game client integration with the Realtime Client SDK (C#). As shown, the example initializes a Realtime client object, sets up event handlers and implements the client-side callbacks, connects to a Realtime server, sends a message, and disconnects.
using System; using System.Text; using Aws.GameLift.Realtime; using Aws.GameLift.Realtime.Event; using Aws.GameLift.Realtime.Types; namespace Example { /** * An example client that wraps the GameLift Realtime client SDK * * You can redirect logging from the SDK by setting up the LogHandler as such: * ClientLogger.LogHandler = (x) => Console.WriteLine(x); * */ class RealTimeClient { public Aws.GameLift.Realtime.Client Client { get; private set; } // An opcode defined by client and your server script that represents a custom message type private const int MY_TEST_OP_CODE = 10; /// Initialize a client for GameLift Realtime and connect to a player session. /// <param name="endpoint">The DNS name that is assigned to Realtime server</param> /// <param name="remoteTcpPort">A TCP port for the Realtime server</param> /// <param name="listeningUdpPort">A local port for listening to UDP traffic</param> /// <param name="connectionType">Type of connection to establish between client and the Realtime server</param> /// <param name="playerSessionId">The player session ID that is assigned to the game client for a game session </param> /// <param name="connectionPayload">Developer-defined data to be used during client connection, such as for player authentication</param> public RealTimeClient(string endpoint, int remoteTcpPort, int listeningUdpPort, ConnectionType connectionType, string playerSessionId, byte[] connectionPayload) { // Create a client configuration to specify a secure or unsecure connection type // Best practice is to set up a secure connection using the connection type RT_OVER_WSS_DTLS_TLS12. ClientConfiguration clientConfiguration = new ClientConfiguration() { // C# notation to set the field ConnectionType in the new instance of ClientConfiguration ConnectionType = connectionType }; // Create a Realtime client with the client configuration Client = new Client(clientConfiguration); // Initialize event handlers for the Realtime client Client.ConnectionOpen += OnOpenEvent; Client.ConnectionClose += OnCloseEvent; Client.GroupMembershipUpdated += OnGroupMembershipUpdate; Client.DataReceived += OnDataReceived; // Create a connection token to authenticate the client with the Realtime server // Player session IDs can be retrieved using Amazon SDK for GameLift ConnectionToken connectionToken = new ConnectionToken(playerSessionId, connectionPayload); // Initiate a connection with the Realtime server with the given connection information Client.Connect(endpoint, remoteTcpPort, listeningUdpPort, connectionToken); } public void Disconnect() { if (Client.Connected) { Client.Disconnect(); } } public bool IsConnected() { return Client.Connected; } /// <summary> /// Example of sending to a custom message to the server. /// /// Server could be replaced by known peer Id etc. /// </summary> /// <param name="intent">Choice of delivery intent i.e. Reliable, Fast etc. </param> /// <param name="payload">Custom payload to send with message</param> public void SendMessage(DeliveryIntent intent, string payload) { Client.SendMessage(Client.NewMessage(MY_TEST_OP_CODE) .WithDeliveryIntent(intent) .WithTargetPlayer(Constants.PLAYER_ID_SERVER) .WithPayload(StringToBytes(payload))); } /** * Handle connection open events */ public void OnOpenEvent(object sender, EventArgs e) { } /** * Handle connection close events */ public void OnCloseEvent(object sender, EventArgs e) { } /** * Handle Group membership update events */ public void OnGroupMembershipUpdate(object sender, GroupMembershipEventArgs e) { } /** * Handle data received from the Realtime server */ public virtual void OnDataReceived(object sender, DataReceivedEventArgs e) { switch (e.OpCode) { // handle message based on OpCode default: break; } } /** * Helper method to simplify task of sending/receiving payloads. */ public static byte[] StringToBytes(string str) { return Encoding.UTF8.GetBytes(str); } /** * Helper method to simplify task of sending/receiving payloads. */ public static string BytesToString(byte[] bytes) { return Encoding.UTF8.GetString(bytes); } } }