Turn-based Multiplayer

In a turn-based multiplayer game, a single shared state is passed between multiple players, and only one player has permission to modify the shared state at a time. Players take turns asynchronously according to an order of play determined by the game. Your game can use the turn-based multiplayer API provided by Google Play games services to manage the following tasks:

  • Invite players to join a turn-based multiplayer match, look for random players to be automatically matched to your game, or a combination of both. Google Play games services allows you to host up to eight participants in a match.

  • Store participant and match state information on Google's servers and share updated match data asynchronously with all participants over the lifecycle of the turn-based match.

  • Send match invitation and turn notifications to players. Notifications appear on all devices on which the player is logged in (unless disabled).

To learn how to implement turn-based multiplayer games for your platform, see Client implementations.

Turn-based match basics

A turn-based match is a gaming session with multiple participants who take consecutive turns to update the game data during the match. Matches must be initiated by a player who is signed-in to Google Play games services. Your game can use the turn-based multiplayer API to join up to eight players together in a match, including the initiating player and any auto-matched players. Matches take place asynchronously and participants do not need to be simultaneously connected to Google Play games services to play.

A turn-based multiplayer match contains these key properties:

  • Participants. A user can become a participant in a turn-based match by initiating a match, joining a match by accepting an invitation, or being auto-matched into a game. Your game can retrieve the participant IDs for all players in a match.

  • Game data. Game-specific data for this match. As a match progresses, the current player can modify and store the game data on Google's servers. The other participants can then retrieve and update this data on their turn. Your game must store the game data in an appropriate format for the device platform. For example, on Android, you must store this data in a byte array and the size of the data must not exceed 128 KB.

  • Match state. A match can fall into one of the following states: ACTIVE, AUTO_MATCHING, COMPLETE, CANCELED, and EXPIRED, depending on participant and game actions during the match. The state of a match is managed by Google Play games services. Your game can check the match state to determine whether a match can proceed, whether players can join by auto-match, and if the match is over (and if it completed normally or ended because of some user action).

Participants

If your game runs on a mobile device, the turn-based multiplayer API provides a default player selection UI. The UI allows players to invite friends or select a number of auto-match opponents. This simplifies your UI coding but you can also choose to implement your own player selection UI.

The participants in a turn-based match can fall into one of these categories:

  • Initiating player. An initiating player who starts a turn-based game can invite other players to join a match, or request to be auto-matched to random users. The initiating player can also request a mix of the two (for example, invite a specific friend, and get two auto-matched players).

  • Auto-matched players. Auto-matched players do not receive notifications to join a match; from their perspective, it appears that they are the ones initiating the match. Auto-match players do not need to be socially connected to the other players.

  • Invited players. Users who are invited to a match will receive invitation notifications on their device, as long their notification settings permit it. To learn more about how users can modify their notification settings by using the Google Play Games app, see Gaming with Google Play Games. Once the user accepts a match invitation, the user is joined to the match as a participant.

If players choose to invite a specific person to a game, they can invite 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 circled friends as well, independent of whether they have the PLUS_LOGIN scope.

  • Using the getInvititablePlayers() method, games that have requested the PLUS_LOGIN scope will get circled friends in the return values, independent of whether they have a discoverable profile.

In some cases, players may have no default invitable friends.

Turn-taking

The basic flow for turn-taking is as follows:

  1. If the player initiated a match, check to see if the game data is null. If so, the client should initialize this data as needed by your game. For example, you might need to initialize the starting positions for players in a strategy game or initialize the first hand for players in a card game.

  2. Let the current player perform their normal turn.

  3. Update the match. On Android, call takeTurn(). On iOS, the equivalent method is takeTurnWithNextParticipantId:.

    In your method call, pass in the following information:

    • The state of the match, after the current player performs the turn.
    • The player to take the next turn. To learn more about specifying the next player, see Specifying the order of play.
  4. Repeat steps 2-3 until the match is completed, or until the game ends some other way.

Specifying the order of play

The order of play is determined by the design of your game. The turn-based multiplayer API provided by the Google Play games services allows your game to flexibly specify the order of play during a match.

When updating the match, your game can assign one of these players to take the next turn:

  • The current player who just took a turn.

  • Another player who has been invited to join the match, or who has already joined the match.

  • An auto-match player who has not joined the match (if there are vacant auto-match slots open). In this case, the match is suspended until a player joins.

For example, in a 2-player turn-based match, your game might randomly pick one player to take the first turn, then subsequently switch to the other player for the next turn, and so on.

Notifications

If you are using the turn-based multiplayer APIs on mobile devices, Google Play games services sends these types of notifications:

  • Match invitation. Players receive this notification when they have been invited to join a match and are assigned to play their first turn by the game.

  • Turn notification. Players receive this notification when they have already joined the match and the game assigns them to be the next player.

  • Match event notification. Game clients that are joined to the same match receive these notifications whenever a match event occurs (for example, when a match is initiated, updated, or, canceled).

On Android and iOS devices, you can bring up the match list user interface provided by the Google Play games services SDK to allow players to view the list of all matches that they are participating in.

Match states

The following table lists the possible states of a turn-based match:

Match State Description
ACTIVE Indicates that a new match is created and your game can let match participants take their turns.
AUTO_MATCHING This state indicates that there are still empty auto-match slots available and your game is waiting for an auto-matched player to join. Your game cannot let other match participants take turns while the match is in this state.
COMPLETE Indicates that a match has been played to completion (for example, a player has won the match). Once a player signals that the game is finished, Google Play games services sends a notification to all match participants to inform them that the match is over. Players have a chance to save their final game data but may not modify the game state further.
CANCELED Indicates that a match ended before its normal completion. This might occur, for example, if a user who was invited to the match declined the invitation or if a participant explicitly cancels the match. Google Play games services allows participants to cancel the match at any point after joining a match (if you game interface supports this action).
EXPIRED Indicates that a match has expired. A match expires when a user does not respond to an invitation or turn notification for two weeks. A match also expires in one day if there is an empty auto-match slot available but Google Play games services cannot find a user to auto-match.
State diagram for turn-based matches
Figure 1: Overview of turn-based multiplayer match states

The callouts in Figure 1 describe how transitions occur between match states:

  • A: After the first player takes a turn, your game can specify a pending participant to take the next turn. If the pending participant is not null, Google Play games services sends a turn notification to the pending participant, and the match stays in ACTIVE state.

  • B: The match is played to completion. Each participant can retrieve the match data but may not modify the game state further.

  • C: This transition occurs when a player declines the match invitation, a participant cancels the match, or a participant leaves the match with only one other participant remaining.

  • D: A player does not respond to a match or turn notification for two weeks. For example, this might occur when a player dismisses the match from the match user interface.

  • E: The match transitions from AUTO_MATCHING to ACTIVE state whenever a player joins by auto-match. Conversely, the match transitions from ACTIVE to AUTO_MATCHING when you specify null as the pending participant. You might do this when you want to suspend the match until a new player joins by auto-match. There must be at least one empty auto-match slot available. A match in AUTO-MATCHING state stays in the same state if a match participant leaves the match but there are still other participants remaining.

  • F: This transition occurs when Google Play games services cannot find a player to auto-match after a day.

  • G: This transition occurs when the game is waiting for auto-match players to join and a match participant cancels the match.

Client implementations

To learn how to implement turn-based multiplayer support for your platform, see the following resources:

Send feedback about...

Play Games Services
Play Games Services