Your game can use the real-time multiplayer API in 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 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).
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.
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 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 in that player's Google+ circles to join the game or requesting to be auto-matched.
If your game runs on a mobile device, the real-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),
Play Games services will attempt to create a room for the real-time
multiplayer game session.
If the room is created successfully, Play Games services notifies your game through a callback (in Android) or delegate (in iOS) that is registered in your game. The local player is automatically joined as a participant in the room.
You must specify the number of players that you want to allow in your room. Currently, 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
When players initiate a multiplayer game, they can choose to invite specific people or have Games services automatically select other participants randomly via auto-matching. They can also request a mix of the two (for example, one specific player from their circles, and two auto-matched players).
If players choose to invite a specific person to a game, the invitee can be
any user with a Google+ account. However, if the inviter is using the default
player selection UI to select invitees, the UI only lists people that are in
the inviter's Google+ circles and people that inviter recently played with. To
invite players from outside the inviter's circles, the inviter can use the
search function in the player selection UI.
An auto-match participant does not have to be a contact in the local player's circles. When auto-matching, Games services simply 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 the they are in each others' Google + circles).
As players join or leave the room, 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, Play Games services notifies through a callback (in Android) or delegate (in iOS). Your game can send messages to the participants who are connected to your room. This is described further in Sending game data.
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 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.
A mobile device user who is sent an invitation will see a notification on devices where they are logged in. Invitations are sent by Play Games services via Google Cloud messaging to Android devices, and through the Apple Push Notification service (APNS) to iOS devices.
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.
iOS device users can filter the invitations that they see by changing these settings:
- Setting the access control list permissions for who can notify them.
- Disabling iOS push notifications for the game.
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.
Play Games services notifies your game about incoming invitations through a connection bundle (in Android) or delegate (in iOS). From the invitation object provided by 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.
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.
As the status of the room, its participants, or connection status of the participants change, 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 Play Games services cannot find other players for auto-matching after a long wait.
Sending game data
You can use the 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 Play Games services. For finer-grain control of data communications in your Android game, you can also implement socket-style messaging with Games services. Socket communication is not supported on iOS.
- 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.
- Socket-based messaging. Supported on Android only. The game client sends and receives messages as a stream of bytes through a socket-like interface. You can use socket-based messaging in lieu of unreliable messaging to send data with real-time dependency while using socket programming semantics. Socket-based messaging can be low latency, but your app must take care to close open sockets that are no longer used. The maximum packet size for an unfragmented message, excluding its internal protocol header, is 1168 bytes.
You can send messages to participants who are connected to the room. If your game is not connected to 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.
A participant can only receive messages when connected to the room.
If your game uses socket-based messaging, note that it may receive data from
more than one socket
write operation at a time. It is up to your
game to parse the inbound stream from the socket. To simplify this task, you
can use a delimiter or implement the socket messages using a fixed field size.
Your game is responsible for leaving the room (that is, disconnecting the room from 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 Cloud save for Games services.
- To learn how to implement real-time multiplayer games for the Android platform, see Developing a Real-time Multiplayer Game in Android.
- To learn how to implement real-time multiplayer games for the iOS platform, see Developing a Real-time Multiplayer Game in iOS.
- To download source code for fully functioning sample games that use the real-time multiplayer API, see the Downloads page.