Lifecycle events and actions
Gameplay implementation is just one of the steps in creating a perfect game. There are many other factors that affect player experience. One of them, staying in close relation to gameplay, is maintaining the match lifetime and the currently playing squad.
If you prefer hands-on experience, check out "Match events" sample project included in Unity SDK package.
Make sure Elympics Behaviour component is attached along with your implementation of IServerHandler, IClientHandlerGuid or IBotHandler. Otherwise, the callbacks won't be called!
Starting a Match
Starting a match in Elympics is handled by the Rooms system. To start a match, you first need to be in a room. You can create a room using the following method:
ElympicsLobbyClient.Instance.RoomManager.CreateAndJoinRoom()– to create a new room and join it.
There are some room requirements to meet before starting a match:
- Room status must match the queue status, for example: team size, minimum team size filled, etc.
- All room members must be set to ready.
- Only the host can start matchmaking.
After matchmaking ends successfully, you need to call IRoom.PlayAvailableMatch() to load the gameplay scene. For more information about matchmaking, visit our matchmaking guide.
Joining a Room
In order to join an existing room, you need the Room Guid or JoinCode (this allows you to enter private rooms). To receive the Guid, you can get a list of all available rooms by using IRoomManager.ListAvailableRooms(). After you find the desired room, you can join it by using ElympicsLobbyClient.Instance.RoomManager.JoinRoom().
Reconnecting to a Match
Reconnecting to a match in Elympics is also handled by the Rooms system. First, you need to find the room you belong to in order to join it. You can do this using the RoomManager and the method IRoomManager.ListJoinedRooms() to get a list of joined rooms. When you have the desired room and the match is in progress, you can rejoin the game by using IRoom.PlayAvailableMatch().
Normally, there is no need to call IRoom.PlayAvailableMatch() manually as it is done by Elympics when matchmaking is complete. This behavior is customizable using the "Should Load Gameplay Scene After Matchmaking" checkbox in the Elympics Client editor.
Joining a match consist of three steps: establish a connection to the game server,
then perform user authentication and finally register a player in the match.
Completion of each step can be tracked by implementing the following methods from IClientHandlerGuid interface:
IClientHandlerGuid.OnConnected(TimeSynchronizationData data),IClientHandlerGuid.OnAuthenticated(string userId)–userIdbecomesnullwhen joining as a spectator,IClientHandlerGuid.OnMatchJoined(string matchId)
along with their corresponding error handlers:
IClientHandlerGuid.OnConnectingFailed(),IClientHandlerGuid.OnAuthenticatedFailed(string errorMessage),IClientHandlerGuid.OnMatchJoinedFailed(string errorMessage).
Meanwhile on the server, only one callback is executed:
IServerHandler.OnPlayerConnected(ElympicsPlayer player)
ElympicsPlayer passed here is used to distinguish a player from others in player data array passed as the only parameter of server initialization callback (described below).
Leaving a match
A match can be also left using IElympics.Disconnect(). If the match isn't ended immediately by the server, players can rejoin it.
The method above is a client-only action: make sure to call it only if IElympics.IsClient is true.
As matches with players missing have a great chance of becoming unplayable, you may want to close the server after some delay (using the action described in the next section). To make sure the server is notified about such an event, you have to implement IServerHandler.OnPlayerDisconnected(ElympicsPlayer player).
As before, received in-match player identifier can be used as an index to player data array passed in server initialization callback.
After a client disconnects from the server, it runs its IClientHandlerGuid.OnDisconnectedByClient().
Finishing a match
As non-finished games take up resources, ending a match is a crucial step. Game server lifetime is currently limited to 24 hours, so no game runs indefinitely. But surely you don't want your players to wait a whole day until they can play again. Or a 5-minute match to cost you much more than planned.
With ending a game being such an important task, SDK provides a default server handler which closes the match automatically as soon as the first player disconnects. Read more below.
The method you need to call is IElympics.EndGame(). Depending on your circumstances, you can pass an optional parameter of type ResultMatchPlayerDatas containing match results.
The inclusion of ResultMatchPlayerDatas object is essential if you want to take advantage of intelligent matchmaking (using Elo rating or machine learning) or other score-related services provided by Elympics. The data can be also passed to your backend (if configured).
ResultMatchPlayerDatas is a list of ResultMatchPlayerData. Each entry should contain data associated with the corresponding player. As there is no player ID included, you should check InitialMatchPlayerDatas received at the start of the game for the correct order.
ResultMatchPlayerData stores arbitrary byte[] GameEngineData in a format specified by developers and float[] MatchmakerData with its structure defined by Elympics. MatchmakerData must contain two elements:
- Matchmaker-compatible score. The greater this number is, the higher matchmaker rating. If your game takes a different approach (e.g. you're creating a racing game where time becomes the score), you have to transform your data appropriately.
- Game-specific score details. You can put original, unprocessed score here.
You can read more about it in the matchmaking article.
Of course, there are some situations when a match ends with no meaningful results to send to the matchmaker, e.g. not all players joined the game to begin with. In such case you should call EndGame() with no arguments.
When a match ends, the following callbacks are run on clients (in the order listed):
IClientHandlerGuid.OnMatchEnded(string matchId),IClientHandlerGuid.OnDisconnectedByServer().
"Half Remote" development mode doesn't currently support the two events listed above. However, the lifetime of a local server can be manipulated freely.
OnDisconnectedByServer is only run at the end of a match. Despite what the name may suggest, there is no possibility of kicking a player from an ongoing game.
DefaultServerHandler
As mentioned earlier, it's really important to end a game correctly. This is why Elympics prefab includes DefaultServerHandler which closes the match if any connected player leaves. It also calls EndGame() if not all players join the game in the first 30 seconds of server lifetime.
The handler outputs logs to console when players connect and disconnect and when it decides if the game should be ended.
Messages such as "Waiting for game to start" could make you think that games are started using a method analogous to EndGame(). However, that is not true. The start of a server means the start of a match.
Providing a custom implementation
If the behavior described above is not suited for your game, you can disable the built-in implementation of IServerHandler.
Before disabling DefaultServerHandler make absolutely sure at least one of your implementations of IServerHandler calls EndGame() properly.
DefaultServerHandler script checks Behaviour.isActiveAndEnabled property in every implemented IServerHandler method, so you can untick DefaultServerHandler component or the whole DefaultServerHandler object in inspector to prevent it from executing.
Alternatively you can just remove DefaultServerHandler component from DefaultServerHandler object in the instance of Elympics prefab.
When it comes to disabling script components and deactivating objects, DefaultServerHandler is an exception. All other synchronized behaviors remain unaffected by such settings unless you implement a similar explicit check in your code.
DefaultServerHandler class is a good starting point for implementing a custom server lifetime guard. After copying the code, you can modify it to suit your needs.
Other events
Initialization
When a game instance starts, an initialization callback is run with game and player data passed as the only parameter. To retrieve the data you can implement appriopriate methods of IServerHandler, IClientHandler and IBotHandler interfaces.
The data is stored as instances of InitialMatchPlayerData. The class consists of the following properties:
ElympicsPlayer Player– in-match player identifier,string UserId– globally unique player identifier,bool IsBot– information if player is a bot,double BotDifficulty– how well a bot should play (if the player is a bot),byte[] GameEngineData– optional game-specific data which you can use to provide initial settings for a match,float[] MatchmakerData– optional game and player-related data for matchmaker to learn from (if ML matchmaking is enabled).
For a server, the method is IServerHandler.OnServerInit(InitialMatchPlayerDatas initialMatchPlayerDatas). It provides not a single instance of InitialMatchPlayerData, but a list of such objects. Each object corresponds to one of match players.
For a client, you should implement IClientHandlerGuid.OnStandaloneClientInit(InitialMatchPlayerData data).
There is also IClientHandlerGuid.OnClientsOnServerInit(InitialMatchPlayerDatas data) used only in "Local Player And Bots" development mode. For convenience, it provides a list of all clients run inside the server instance.
For a bot, you can use IBotHandler.OnBotsOnServerInit(InitialMatchPlayerDatas initialMatchPlayerDatas) as running bots inside the server instance is the default option. As in the case of OnClientsOnServerInit, the method provides a list of data of all bots running in the server.
If you changed the setting, you should use OnStandaloneBotInit(InitialMatchPlayerData initialMatchPlayerData) instead.
The setting is available in Elympics Game Config:
Providing InitialMatchPlayerDatas
There are two points at which you can input GameEngineData and MatchmakerData for your game to use during the initialization process.
The first is when you call ElympicsLobbyClient.PlayOnline(). This method accepts four optional parameters, including float[] matchmakerData = null and byte[] gameEngineData = null. Check out the matchmaking article for more details.
Development modes (Debug Online Player, Half Remote and Local Players and Bots) aren't started using PlayOnline(). You need to place game engine and matchmaker data in Test players section of your Elympics Game Config instead.
The second approach requires using your own backend. The definition of needed endpoints can be found in External Game Backend integration chapter, along with instructions on how to configure the back-end address to be used by your game.
Clock synchronization
The one last callback to describe is IClientHandlerGuid.OnSynchronized(TimeSynchronizationData data). It is called every time a client synchronizes its clock with the server (using NTP protocol).
An implementation of this method can be used to track the condition of network connection using information from TimeSynchronizationData object passed as the only parameter. For example RoundTripDelay property can be displayed as "ping" in an in-game UI.