Quicknav Quicknav
Links

- Google Play Developer Console
- Android Developers Blog
- About Android

Android Sites

- Android.com
- Android Developers
- Android Open Source Project

close

- - Get Started
  - Style
  - Patterns
  - Building Blocks
  - Downloads
  - Videos
- - Training
  - API Guides
  - Reference
  - Tools
    - Get the SDK
  - Google Services
- - Google Play
  - Publishing
  - Promoting
  - App Quality
  - Spotlight
  - Open Distribution

## Results

Loading...
public interface

# TurnBasedMultiplayer

com.google.android.gms.games.multiplayer.turnbased.TurnBasedMultiplayer

## Class Overview

Entry point for turn-based multiplayer functionality.

For more details, see the turn-based developer guide.

## Summary

Nested Classes
interface | TurnBasedMultiplayer.CancelMatchResult | Result delivered when the match has been canceled.
interface | TurnBasedMultiplayer.InitiateMatchResult | Result delivered when match has been initiated.
interface | TurnBasedMultiplayer.LeaveMatchResult | Result delivered when the player has left the match.
interface | TurnBasedMultiplayer.LoadMatchResult | Result delivered when a turn-based match has been loaded.
interface | TurnBasedMultiplayer.LoadMatchesResult | Result delivered when matches have been loaded.
interface | TurnBasedMultiplayer.UpdateMatchResult | Result delivered when match has been updated.

Public Methods
abstract PendingResult<TurnBasedMultiplayer.InitiateMatchResult> | acceptInvitation(GoogleApiClient apiClient, String invitationId) Accept an invitation for a turn-based match.
abstract PendingResult<TurnBasedMultiplayer.CancelMatchResult> | cancelMatch(GoogleApiClient apiClient, String matchId) Cancels a turn-based match.
abstract PendingResult<TurnBasedMultiplayer.InitiateMatchResult> | createMatch(GoogleApiClient apiClient, TurnBasedMatchConfig config) Create a new turn-based match for the current game.
abstract void | declineInvitation(GoogleApiClient apiClient, String invitationId) Decline an invitation for a turn-based match.
abstract void | dismissInvitation(GoogleApiClient apiClient, String invitationId) Dismiss an invitation to a turn-based match.
abstract void | dismissMatch(GoogleApiClient apiClient, String matchId) Delete a match from the server and local storage.
abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> | finishMatch(GoogleApiClient apiClient, String matchId, byte[] matchData, ParticipantResult... results) Mark a match as finished.
abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> | finishMatch(GoogleApiClient apiClient, String matchId, byte[] matchData, List<ParticipantResult> results) Mark a match as finished.
abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> | finishMatch(GoogleApiClient apiClient, String matchId) Indicate that a participant is finished with a match.
abstract Intent | getInboxIntent(GoogleApiClient apiClient) Returns an intent that will let the user see and manage any outstanding invitations and matches.
abstract int | getMaxMatchDataSize(GoogleApiClient apiClient) Gets the maximum data size per match in bytes.
abstract Intent | getSelectOpponentsIntent(GoogleApiClient apiClient, int minPlayers, int maxPlayers, boolean allowAutomatch) Returns an intent that will let the user select opponents to send an invitation to for a turn based multiplayer match.
abstract Intent | getSelectOpponentsIntent(GoogleApiClient apiClient, int minPlayers, int maxPlayers) Returns an intent that will let the user select opponents to send an invitation to for a turn based multiplayer match.
abstract PendingResult<TurnBasedMultiplayer.LeaveMatchResult> | leaveMatch(GoogleApiClient apiClient, String matchId) Leave the specified match when it is not the current player's turn.
abstract PendingResult<TurnBasedMultiplayer.LeaveMatchResult> | leaveMatchDuringTurn(GoogleApiClient apiClient, String matchId, String pendingParticipantId) Leave the specified match during the current player's turn.
abstract PendingResult<TurnBasedMultiplayer.LoadMatchResult> | loadMatch(GoogleApiClient apiClient, String matchId) Load a specified turn-based match.
abstract PendingResult<TurnBasedMultiplayer.LoadMatchesResult> | loadMatchesByStatus(GoogleApiClient apiClient, int... matchTurnStatuses) Asynchronously load turn-based matches for the current game.
abstract void | registerMatchUpdateListener(GoogleApiClient apiClient, OnTurnBasedMatchUpdateReceivedListener listener) Register a listener to intercept incoming match updates for the currently signed-in user.
abstract PendingResult<TurnBasedMultiplayer.InitiateMatchResult> | rematch(GoogleApiClient apiClient, String matchId) Create a rematch of a previously completed turn-based match.
abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> | takeTurn(GoogleApiClient apiClient, String matchId, byte[] matchData, String pendingParticipantId) Update a match with new turn data.
abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> | takeTurn(GoogleApiClient apiClient, String matchId, byte[] matchData, String pendingParticipantId, List<ParticipantResult> results) Update a match with new turn data.
abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> | takeTurn(GoogleApiClient apiClient, String matchId, byte[] matchData, String pendingParticipantId, ParticipantResult... results) Update a match with new turn data.
abstract void | unregisterMatchUpdateListener(GoogleApiClient apiClient) Unregisters this client's match update listener, if any.

## Public Methods

#### public abstract PendingResult<TurnBasedMultiplayer.InitiateMatchResult> acceptInvitation (GoogleApiClient apiClient, String invitationId)

Accept an invitation for a turn-based match. This changes the current player's participant status to `STATUS_JOINED`.

After this call returns successfully, it will be the calling player's turn in the match. At this point, the player may take their first turn by calling `takeTurn(GoogleApiClient, String, byte[], String)`.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
invitationId | The ID of the invitation to be accepted.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract PendingResult<TurnBasedMultiplayer.CancelMatchResult> cancelMatch (GoogleApiClient apiClient, String matchId)

Cancels a turn-based match. Once this call succeeds, the match will be removed from local storage. Note that this will cancel the match completely, forcing it to end for all players involved. See `leaveMatch(GoogleApiClient, String)` for a different alternative.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | The ID of the match to cancel.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract PendingResult<TurnBasedMultiplayer.InitiateMatchResult> createMatch (GoogleApiClient apiClient, TurnBasedMatchConfig config)

Create a new turn-based match for the current game. If the provided `TurnBasedMatchConfig` includes automatch parameters, the server will attempt to find any previously created matches that satisfy these parameters and join the current player into the previous match. If no suitable match can be found, a new match will be created.

After this call returns successfully, it will be the calling player's turn in the new match. At this point, the player may take their first turn by calling `takeTurn(GoogleApiClient, String, byte[], String)`.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
config | The configuration parameters for the match to create.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract void declineInvitation (GoogleApiClient apiClient, String invitationId)

Decline an invitation for a turn-based match.

Note that this will cancel the match for the other participants and remove the match from the caller's local device.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
invitationId | The ID of the invitation to decline.

#### public abstract void dismissInvitation (GoogleApiClient apiClient, String invitationId)

Dismiss an invitation to a turn-based match. Dismissing an invitation will not change the state of the match for the other participants.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
invitationId | The ID of the invitation to dismiss.

#### public abstract void dismissMatch (GoogleApiClient apiClient, String matchId)

Delete a match from the server and local storage. Dismissing a match will not change the state of the match for the other participants, but dismissed matches will never be shown to the dismissing player again.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | The ID of the match to dismiss.

#### public abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> finishMatch (GoogleApiClient apiClient, String matchId, byte[] matchData, ParticipantResult... results)

Mark a match as finished. This should be called when the match is over and all participants have results to be reported (if appropriate). Note that the last client to update a match is responsible for calling finish on that match.

On the last turn of the match, the client should call this method instead of `takeTurn(GoogleApiClient, String, byte[], String)`.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to finish.
matchData | Data representing the new state of the match after this update. Limited to a maximum of `getMaxMatchDataSize(GoogleApiClient)` bytes.
results | List of `ParticipantResult` objects for this match. The client which calls `finishMatch` is responsible for reporting the results for all appropriate participants in the match. Not every participant is required to have a result, but providing results for participants who are not in the match is an error.

##### Returns

- `PendingResult` to access the data when available.

##### See Also

- `takeTurn(GoogleApiClient, String, byte[], String)`

#### public abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> finishMatch (GoogleApiClient apiClient, String matchId, byte[] matchData, List<ParticipantResult> results)

Mark a match as finished. This should be called when the match is over and all participants have results to be reported (if appropriate). Note that the last client to update a match is responsible for calling finish on that match.

On the last turn of the match, the client should call this method instead of `takeTurn(GoogleApiClient, String, byte[], String)`.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to finish.
matchData | Data representing the new state of the match after this update. Limited to a maximum of `getMaxMatchDataSize(GoogleApiClient)` bytes.
results | List of `ParticipantResult` objects for this match. The client which calls `finishMatch` is responsible for reporting the results for all appropriate participants in the match. Not every participant is required to have a result, but providing results for participants who are not in the match is an error.

##### Returns

- `PendingResult` to access the data when available.

##### See Also

- `takeTurn(GoogleApiClient, String, byte[], String)`

#### public abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> finishMatch (GoogleApiClient apiClient, String matchId)

Indicate that a participant is finished with a match. This will not change the data of the match, but it will transition the match into state `MATCH_STATUS_COMPLETE` if the match is not already in that state. This method is most commonly used to report that a participant has finished any post-processing steps the game might have and has seen their results in the match.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to finish.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract Intent getInboxIntent (GoogleApiClient apiClient)

Returns an intent that will let the user see and manage any outstanding invitations and matches. Note that this must be invoked using `startActivityForResult(Intent, int)` so that the identity of the calling package can be established.

If the user canceled the result will be `RESULT_CANCELED`. If the user selected an invitation or a match to accept, the result will be `RESULT_OK` and the data intent will contain the selected invitation/match as a parcelable extra in the extras. Based on the type of the match, the result will include either `EXTRA_TURN_BASED_MATCH` or `EXTRA_INVITATION`.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.

##### Returns

- An `Intent` that can be started to view the match inbox.

#### public abstract int getMaxMatchDataSize (GoogleApiClient apiClient)

Gets the maximum data size per match in bytes. Guaranteed to be at least 128 KB. May increase in the future.

If the service cannot be reached for some reason, this will return `STATUS_CLIENT_RECONNECT_REQUIRED`. In this case, no further operations should be attempted until after the client has reconnected.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.

##### Returns

- The maximum data size per match in bytes.

#### public abstract Intent getSelectOpponentsIntent (GoogleApiClient apiClient, int minPlayers, int maxPlayers, boolean allowAutomatch)

Returns an intent that will let the user select opponents to send an invitation to for a turn based multiplayer match. Note that this must be invoked with `startActivityForResult(Intent, int)`, so that the identity of the calling package can be established.

The number of players passed in should be the desired number of additional players to select, not including the current player. So, for a game that can handle between 2 and 4 players, `minPlayers` would be 1 and `maxPlayers` would be 3.

If the user canceled, the result will be `RESULT_CANCELED`. If the user selected players, the result will be `RESULT_OK`, and the data intent will contain the selected player IDs in `EXTRA_PLAYERS` and the minimum and maximum numbers of additional auto-match players in `EXTRA_MIN_AUTOMATCH_PLAYERS` and `EXTRA_MAX_AUTOMATCH_PLAYERS` respectively. The player IDs in `EXTRA_PLAYERS` will include only the other players selected, not the current player.

If the `allowAutomatch` parameter is set to false, the UI will not display an option for selecting automatch players. Set this to false if your game does not support automatching.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
minPlayers | The minimum number of players to select (not including the current player).
maxPlayers | The maximum number of players to select (not including the current player).
allowAutomatch | Whether or not to display an option for selecting automatch players.

##### Returns

- An `Intent` that can be started to display the player selector.

##### See Also

- `createMatch(GoogleApiClient, TurnBasedMatchConfig)`

#### public abstract Intent getSelectOpponentsIntent (GoogleApiClient apiClient, int minPlayers, int maxPlayers)

Returns an intent that will let the user select opponents to send an invitation to for a turn based multiplayer match. Note that this must be invoked with `startActivityForResult(Intent, int)`, so that the identity of the calling package can be established.

The number of players passed in should be the desired number of additional players to select, not including the current player. So, for a game that can handle between 2 and 4 players, `minPlayers` would be 1 and `maxPlayers` would be 3.

If the user canceled, the result will be `RESULT_CANCELED`. If the user selected players, the result will be `RESULT_OK`, and the data intent will contain the selected player IDs in `EXTRA_PLAYERS` and the minimum and maximum numbers of additional auto-match players in `EXTRA_MIN_AUTOMATCH_PLAYERS` and `EXTRA_MAX_AUTOMATCH_PLAYERS` respectively. The player IDs in `EXTRA_PLAYERS` will include only the other players selected, not the current player.

This method is the equivalent of calling `getSelectOpponentsIntent(GoogleApiClient, int, int, boolean)` with the `allowAutomatch` parameter set to true.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
minPlayers | The minimum number of players to select (not including the current player).
maxPlayers | The maximum number of players to select (not including the current player).

##### Returns

- An `Intent` that can be started to display the player selector.

##### See Also

- `createMatch(GoogleApiClient, TurnBasedMatchConfig)`

#### public abstract PendingResult<TurnBasedMultiplayer.LeaveMatchResult> leaveMatch (GoogleApiClient apiClient, String matchId)

Leave the specified match when it is not the current player's turn. If this takes the match to fewer than two participants, the match will be canceled.

See `leaveMatchDuringTurn(GoogleApiClient, String, String)` for the form of the API to call during the current player's turn.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to leave.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract PendingResult<TurnBasedMultiplayer.LeaveMatchResult> leaveMatchDuringTurn (GoogleApiClient apiClient, String matchId, String pendingParticipantId)

Leave the specified match during the current player's turn. If this takes the match to fewer than two participants, the match will be canceled. The provided `pendingParticipantId` will be used to determine which participant should act next. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

See `leaveMatch(GoogleApiClient, String)` for the form of the API to call when it is not the current player's turn.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to leave.
pendingParticipantId | ID of the participant who will be set to pending after this update succeeds, or `null` to wait for additional automatched players (if possible).

##### Returns

- `PendingResult` to access the data when available.

#### public abstract PendingResult<TurnBasedMultiplayer.LoadMatchResult> loadMatch (GoogleApiClient apiClient, String matchId)

Load a specified turn-based match.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | The ID of the match to retreive.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract PendingResult<TurnBasedMultiplayer.LoadMatchesResult> loadMatchesByStatus (GoogleApiClient apiClient, int... matchTurnStatuses)

Asynchronously load turn-based matches for the current game. Matches with any specified turn status codes will be returned.

Valid turn status values are `MATCH_TURN_STATUS_INVITED`, `MATCH_TURN_STATUS_MY_TURN`, `MATCH_TURN_STATUS_THEIR_TURN`, or `MATCH_TURN_STATUS_COMPLETE`. Note that if your game implements both turn-based and real-time multiplayer, requesting `MATCH_TURN_STATUS_INVITED` will return invitations for both turn-based matches and real-time matches.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchTurnStatuses | List of turn statuses to request.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract void registerMatchUpdateListener (GoogleApiClient apiClient, OnTurnBasedMatchUpdateReceivedListener listener)

Register a listener to intercept incoming match updates for the currently signed-in user. If a listener is registered by this method, the incoming match update will not generate a status bar notification as long as this client remains connected.

Note that only one match update listener may be active at a time. Calling this method while another match update listener was previously registered will replace the original listener with the new one.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
listener | The listener that is called when a match update is received. The listener is called on the main thread.

#### public abstract PendingResult<TurnBasedMultiplayer.InitiateMatchResult> rematch (GoogleApiClient apiClient, String matchId)

Create a rematch of a previously completed turn-based match. The new match will have the same participants as the previous match. Note that only one rematch may be created from any single completed match, and only by a player that has already called Finish on the match. It is only valid to call this if `canRematch()` return true - calling this method any other time will result in an error.

After this call returns successfully, it will be the calling player's turn in the new match. At this point, the player may take their first turn by calling `takeTurn(GoogleApiClient, String, byte[], String)`.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | The ID of the previous match to re-create.

##### Returns

- `PendingResult` to access the data when available.

#### public abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> takeTurn (GoogleApiClient apiClient, String matchId, byte[] matchData, String pendingParticipantId)

Update a match with new turn data. The participant that is passed in as the pending participant will be notified that it is their turn to take action. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

For the final turn of the match, there is no need to call this method. Instead, call `finishMatch(GoogleApiClient, String)` directly.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to update.
matchData | Data representing the new state of the match after this update. Limited to a maximum of `getMaxMatchDataSize(GoogleApiClient)` bytes.
pendingParticipantId | ID of the participant who will be set to pending after this update succeeds, or `null` to wait for additional automatched players (if possible).

##### Returns

- `PendingResult` to access the data when available.

##### See Also

- `finishMatch(GoogleApiClient, String)`

#### public abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> takeTurn (GoogleApiClient apiClient, String matchId, byte[] matchData, String pendingParticipantId, List<ParticipantResult> results)

Update a match with new turn data. The participant that is passed in as the pending participant will be notified that it is their turn to take action. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

Note that players will not receive invitations for matches until this method is called. An invitation will be sent to a player the first time they are set as the pending participant of a match.

For the final turn of the match, there is no need to call this method. Instead, call `finishMatch(GoogleApiClient, String)` directly.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to update.
matchData | Data representing the new state of the match after this update. Limited to a maximum of `getMaxMatchDataSize(GoogleApiClient)` bytes.
pendingParticipantId | ID of the participant who will be set to pending after this update succeeds, or `null` to wait for additional automatched players (if possible).

results

Optional list of `ParticipantResult` objects for this match. Note that the results reported here should be final - if results reported later conflict with these values, the returned value will indicate a conflicted result by returning `MATCH_RESULT_DISAGREED`. This is most useful for cases where a participant knows their results early. For example, a single elimination game where participants are eliminated as the game continues might wish to specify results for the eliminated participants here.

##### Returns

- `PendingResult` to access the data when available.

##### See Also

- `finishMatch(GoogleApiClient, String)`

#### public abstract PendingResult<TurnBasedMultiplayer.UpdateMatchResult> takeTurn (GoogleApiClient apiClient, String matchId, byte[] matchData, String pendingParticipantId, ParticipantResult... results)

Update a match with new turn data. The participant that is passed in as the pending participant will be notified that it is their turn to take action. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

Note that players will not receive invitations for matches until this method is called. An invitation will be sent to a player the first time they are set as the pending participant of a match.

For the final turn of the match, there is no need to call this method. Instead, call `finishMatch(GoogleApiClient, String)` directly.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
matchId | ID of the match to update.
matchData | Data representing the new state of the match after this update. Limited to a maximum of `getMaxMatchDataSize(GoogleApiClient)` bytes.
pendingParticipantId | ID of the participant who will be set to pending after this update succeeds, or `null` to wait for additional automatched players (if possible).

results

Optional list of `ParticipantResult` objects for this match. Note that the results reported here should be final - if results reported later conflict with these values, the returned value will indicate a conflicted result by returning `MATCH_RESULT_DISAGREED`. This is most useful for cases where a participant knows their results early. For example, a single elimination game where participants are eliminated as the game continues might wish to specify results for the eliminated participants here.

##### Returns

- `PendingResult` to access the data when available.

##### See Also

- `finishMatch(GoogleApiClient, String)`

#### public abstract void unregisterMatchUpdateListener (GoogleApiClient apiClient)

Unregisters this client's match update listener, if any. Any new match updates will generate status bar notifications as normal.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.