Your game can use the real-time multiplayer API in Google Play games services to connect multiple players together in a single game session and transfer data messages between connected players. Using the real-time multiplayer API can help to simplify your game development effort because the API handles the following tasks on your behalf:
- Manages network connections to create and maintain a real-time multiplayer room (a virtual construct that enables network communication between multiple players in the same game session and lets players send data directly to one another).
- Provides a player selection user interface (UI) to invite players to join a room, look for random players for auto-matching, or a combination of both.
- Stores participant and room state information on the Google Play games services servers during the lifecycle of the real-time multiplayer game.
- Sends room invitations and updates to players. Notifications appear on all devices on which the player is logged in (unless disabled).
To learn how to implement real-time multiplayer games for your platform, see Client implementations.
Real-time multiplayer game basics
Before you design and implement your game using the real-time multiplayer API, you should familiarize yourself with the following concepts related to the typical lifecycle of a real-time multiplayer game.
Room initialization
Internally, the room sets up a peer-to-peer mesh network between participants where clients can communicate directly with each other, rather than through the Google Play games services servers.
Before a real-time multiplayer game session can be initiated on a device, the device user must be signed in to your game. The local player (that is, the user who is logged in to the device where your game is running) can then initiate a multiplayer game session by inviting friends to join the game or requesting to be auto-matched.
If your game runs on a mobile device, the real-time multiplayer API provides a default player selection UI. The UI allows players to invite their friends or select a number of auto-match opponents. This simplifies your UI coding but you can also choose to implement your player selection UI.
Based on the player selection and room configuration details (either entered by the local player through the UI or provided programmatically by your game), Google Play games services will attempt to create a room for the real-time multiplayer game session.
If the room is created successfully, Google Play games services notifies your game through a callback that is registered in your game. The local player is automatically joined as a participant in the room.
Room configuration
You must specify the number of players that you want to allow in your room. Currently, Google Play games services supports a maximum of eight players in a multiplayer game (including the player who is initiating the match).
Optionally, you might want to ensure that only players who are interested in a specific type of game variant are auto-matched to the room. For example, in a racing game, you can auto-match players who only want to play a specific racing map or difficulty level. Variants can be used to auto-match players who are interested in different play styles, such as player-vs-player (PvP) or 'capture the flag' gameplay. If there are different versions of your app, you can also use variants to ensure that only players who are on compatible versions are auto-matched.
If you want to to auto-match players who are interested in playing
specific exclusive roles in a game, you can specify this using the
exclusiveBitMask parameter.
Participants
When players initiate a multiplayer game, they can choose to invite specific people or have Google Play games services automatically select other participants randomly via auto-matching. They can also request a mix of the two (for example, one specific player and two auto-matched players).
If players choose to invite a specific person to a game, depending on their account settings, the UI they use, and the game’s scopes, they may have different people available to choose from.
In general, inviters will always be able to invite recent opponents, and will always be able to automatch players.
In the Google-supplied default UI, they will also see the “Nearby players” option.
In the Google-supplied default UI, players with discoverable profiles will see friends as well.
Note that in some cases, players may have no default invitable friends.
To invite other players, the inviter can use the search function in the player selection UI.
Auto-matching
When auto-matching, Google Play games services looks for other participants at that time who are also initiating a game and requesting to be auto-matched. Auto-match participants do not receive notifications to join a game; from their perspective, it appears as though they are individually initiating the game.
In real-time multiplayer games, auto-matched participants will appear as anonymous players to each other (even if they are known to each other).
Connected set
As players join or leave the room, Google Play games services actively attempts to create a mesh of peer-to-peer connections between all participants. This forms a connected set of participants in the room, where every player in the connected set is fully connected to the other players in the set. The connected set might consist of a subset of all players who have joined the room. If any player gets disconnected from another player in the connected set, the set is reduced to the remaining players who are still fully connected. It is up to your game to determine how to proceed if this happens.
When all the participants in a real-time room are fully connected, Google Play games services notifies through a callback. Your game can send messages to the participants who are connected to your room. This is described further in Sending game data.
In-game networking
The real-time multiplayer API is flexible enough that your game can use it to implement your own in-game network for participants over the underlying peer-to-peer network created by the Google Play games services. For example, in your game, you might want to designate a single client to act as a 'host' to establish the authoritative game data first, then transmit this data to the other connected participants through data messaging. If auto-matching is used to create the room and your game logic relies on the existence of a 'host' or 'owner' of the game, you are responsible for implementing the logic to determine who the 'host' should be.
Invitations
A mobile device user who is sent an invitation will see a notification on devices where they are logged in. Invitations are sent by Google Play games services via Google Cloud messaging.
Android device users can filter the invitations that they see by changing these settings:
- Setting the access control list permissions for who can notify them.
- Muting the app.
- Turning all mobile notifications off entirely.
If the player does not have the application installed on an Android device, they will be prompted to install the application from the Play Store. In that case, the invitation is not consumed, and the player can accept it again after installing the game.
Google Play games services notifies your game about incoming invitations through a connection bundle. From the invitation object provided by Google Play games services, your game can retrieve additional details such as the invitation creation timestamp, the invitation ID, and the player who sent the invitation.
Gameplay
Once the required number of participants for a room have been connected, the room is considered to be 'filled' and gameplay can begin. After participants join a room, your game can allow them to leave the room (effectively dropping them out of the game). However, no new players can join a room after it is 'filled' (not even to fill a spot that a participant has vacated).
In certain advanced scenarios, your game might allow connected participants to start gameplay before all pending invitations have been accepted. If your game supports this mode of gameplay, make sure to handle any participants who join the room after gameplay is underway. Take the following example: In a 3-player racing game, your game session might start the race with two players. During the race, if a third player joins the room, your game can let the newly-joined participant observe the current race as a spectator but not play as a racer. After the race is over, your game can allows all three players to participate as racers in the next round.
Event notifications
As the status of the room, its participants, or connection status of the participants change, Google Play games services will send notifications to your game. Your game can use this information to display details about who joined the room (for example, while waiting for more participants to join), or to display an option for the local player to leave the room if Google Play games services cannot find other players for auto-matching after a long wait.
Sending game data
You can use the Google Play games services to broadcast data to participants in a room, or allow participants to exchange messages with each other. Data messages can be sent using a reliable or unreliable messaging protocol provided by Google Play games services.
- Reliable messaging. With reliable messaging, data delivery, integrity, and ordering are guaranteed. You can choose to be notified of the delivery status by using a callback. Reliable messaging is suitable for sending non-time-sensitive data. You can also use reliable messaging to send large data sets where the data can be split into smaller segments, sent over the network, and then reassembled by the receiving client. Reliable messaging might have high latency. The maximum size of a reliable message that you can send is 1400 bytes.
- Unreliable messaging. The game client sends the data only once ('fire-and-forget') with no guarantee of data delivery or data arriving in order. However, integrity is guaranteed, so there is no need to add a checksum. Unreliable messaging has low latency and is suitable for sending data that is time-sensitive. Your app is responsible for ensuring that the game behaves correctly if messages are dropped in transmission or received out of order. The maximum size for an unreliable message that you can send is 1168 bytes.
Sending messages
You can send messages to participants who are connected to the room. If your game is not connected to Google Play games services or the recipient is not connected, the message will not be delivered.
To conserve message transmissions and avoid exceeding rate limits, follow these best practices for sending data:
- Send messages to only the participants who require that information, rather than broadcasting to all participants. If you are sending a broadcast message, make sure to exclude the sender participant from the list of broadcast recipients.
- If you are sending data using the reliable messaging protocol, try to keep the frequency of your message transmissions to around 50 or fewer messages per second. If you need to send data more frequently than this, we recommend that you use unreliable messaging instead.
Receiving messages
A participant can only receive messages when connected to the room.
Room closure
Your game is responsible for leaving the room (that is, disconnecting the room from Google Play games services servers) when a participant logs out of the game or exits the real-time portion of the game. Your game should also handle the scenario where all participants except the local player have left the room. When this happens, your game should disconnect the local player from the room immediately.
The room is considered 'closed' when all its participants have left the room. At this point, your game should shut down any game currently in progress, and make sure to save game data appropriately. To learn more about saving game data to Google Play, see Saved Games.
Client implementations
To learn how to implement real-time multiplayer support for your platform, see the following resources: