com.google.android.gms.games.multiplayer
,com.google.android.gms.games.multiplayer.turnbased
, andcom.google.android.gms.games
packages.TurnBasedMultiplayerClient
object. You can do this by calling theGames.getTurnBasedMultiplayerClient()
method and passing in theactivity and the GoogleSignInAccount
for the current player. To learn how toretrieve the player account information, seeSign-in in Android Games.TurnBasedMultiplayerClient
class makes use of the Google Playservices Task
class to return results asynchronously. To learn more aboutusing tasks to manage threaded work, see theTasks API developer guide.TurnBasedMatch
object to your game; this object is updated and shared asynchronously with allparticipants over the lifecycle of the turn-based match.TurnBasedMatchConfig.Builder
to set the match configuration data in aTurnBasedConfigObject
.TurnBasedMultiplayerClient.createMatch()
and pass in theTurnBasedConfigObject
you created. If auto-matching is specified, Google Play games services will attempt to matchplayers to an existing game; for more details, seeImplementing auto-matching.TurnBasedMultiplayerClient.getSelectOpponentsIntent()
method and use the intent it returns tostart an activity.onActivityResult()
callback to construct a TurnBasedMatchConfig
object using the criteria provided by the user. The TurnBasedMatchConfig
object defines the characteristics of the match that the user wants to play. Google Play games servicesuses this configuration data to determine whether to build a new match or to auto-match the user toan existing game.TurnBasedMatchConfig
object that you pass to TurnBasedMultiplayerClient.createMatch()
.setVariant()
method. Your game can also use the exclusiveBitMask
parameter increateAutoMatchCriteria()
to pair auto-matched players who are interested in playing specific exclusiveroles in a game.TurnBasedMultiplayerClient.createMatch()
callis successful, Google Play games services returns a Task
object which asynchronously loads a TurnBasedMatch
instance.getData()
method on the TurnBasedMatch
instance.null
value, this indicates that the game data isuninitialized because no player has taken a turn yet (that is, the currentplayer is the first player in this match). Your game can initialize the game data andstore it in a byte array. The size of the game data must be less than the sizereturned by TurnBasedMultiplayerClient.getMaxMatchDataSize()
.The data size returned is guaranteed to be at least 128 KB.null
value, this indicates that the game hasalready started and the game data is already initialized, so make sure yourgame does not reinitialize the data.TurnBasedMultiplayerClient.takeTurn()
now. If your initialstate is based on a random value (for example, a card game where the playerstarts with a random hand) and your game does not callTurnBasedMultiplayerClient.takeTurn()
to persist thedata to Google's servers, the player could keep restarting the first turn totry to get a better starting position.TurnBasedMultiplayerClient.takeTurn()
. Your game can specify the next player'sparticipant ID, or specify null
to let Google Play games servicesfind a player for auto-matching. Your game can let match participants take turns evenwhen not all invited players have joined or when there are auto-match slotsstill available. To get players into gameplay faster, your game should let playerstake their turn as soon as they join. When you callTurnBasedMultiplayerClient.takeTurn()
, Google Play games services sends anotification to the pending participant and updates the turndata on all participants' devices asynchronously.getData()
before you let the player perform game actions.TurnBasedMultiplayerClient.createMatch()
and requestsauto-matching, Google Play games services first attempts to match the player to anexisting game.TurnBasedMultiplayerClient.takeTurn()
andpass in null
in the pendingParticipantId
parameter.TurnBasedMultiplayerClient.getInboxIntent()
method, then use the intent itreturns to start an activity.TurnBasedMultiplayerClient.takeTurn()
toupdate the match data and pass the turn to another participant.TurnBasedMatchUpdateCallback
to your activity. Wheneverthe match is updated following a player's turn, your activity is notified viathe TurnBasedMatchUpdateCallback.onTurnBasedMatchedReceived()
method.TurnBasedMatch
object to verify this.getStatus()
.A result of MATCH_STATUS_ACTIVE
indicates that the match is active.getTurnStatus()
. A result of MATCH_TURN_STATUS_MY_TURN
indicates that it is now the user's turn.getData()
and render your game accordingly.null
.TurnBasedMultiplayerClient.takeTurn()
to update theGoogle Play games services with the latest game data and pass the turnto the pending participant. If the update is successful, Google Play games servicessends a notification to the pending participant to inform them that it's theirturn.TurnBasedMultiplayerClient.getMaxMatchDataSize()
. The data size returned isguaranteed to be at least 128 KB.TurnBasedMultiplayerClient.takeTurn()
and pass in your game state dataas the matchData
parameter.TurnBasedMultiplayerClient.takeTurn()
. Make sure to specifythe current player as the pending participant by using the same participant IDas in the last call to TurnBasedMultiplayerClient.takeTurn()
. If successful,the call stores the game data in Google’s servers but does not generate a newturn notification.TurnBasedMultiplayerClient.finishMatch()
to upload the user’s game data and signal to the other participants that thematch is over. When your game invokes this method for the first time during a match,it must be during the user's turn. The match then appears under theCompleted Matches category in the user's match list UI.TurnBasedMultiplayerClient.finishMatch()
for the first time in the match, your game cannot callTurnBasedMultiplayerClient.takeTurn()
again in this match.Google Play games services sends a notification to all othermatch participants to inform them that the match is over. These participantssee this match under Your Turn category in their respective match list UIs.At this point, your game can call TurnBasedMultiplayerClient.finishMatch()
for these participants to save their final game data. Invoking this method alsomoves the match to the Completed Matches category in the participant’s matchlist UI.TurnBasedMultiplayerClient.leaveMatch()
orTurnBasedMultiplayerClient.leaveMatchDuringTurn()
. When a participant leavesa match, the match can still continue with otherparticipants as long as these conditions are met:TurnBasedMultiplayerClient.leaveMatchDuringTurn()
. In this case, the matchreverts to the MATCH_STATUS_AUTO_MATCHING
state and another player can take over theplace of the participant who left.TurnBasedMultiplayerClient.cancelMatch()
.After calling this method, your game cannot callTurnBasedMultiplayerClient.takeTurn()
again in this match; the match nowappears under the Completed Matches category in the match list UI.TurnBasedMultiplayerClient.dismissMatch()
.TurnBasedMultiplayerClient.loadMatchesByStatus()
.getCompletedMatches()
to get a TurnBasedMatchBuffer
that contains a list of matches in the MATCH_TURN_STATUS_COMPLETE
state.MATCH_STATUS_EXPIRED
state.STATUS_UNRESPONSIVE
state, it indicates that this player has let the game expire.TurnBasedMultiplayerClient.rematch()
.Your game can only invoke this method when the match state isMATCH_STATUS_COMPLETE
and no other participants have requested a rematch. If the call is successful,Google Play games services sends invitation notifications to all rematched opponents.Intent
extra in the onActivityResult()
callback of the match inbox activity. If your gameneeds to initialize game data for the new match, make sure to use the matchobject returned in theonActivityResult()
callback.