This class is deprecated.
Real-time multiplayer and Turn-based multiplayer support is being shut down on March 31,
2020. See Multiplayer
deprecation
A client to interact with turn based multiplayer.
Nested Class Summary
class | TurnBasedMultiplayerClient.MatchOutOfDateApiException | Indicates that the local match state was out of date. |
Inherited Field Summary
Public Method Summary
Task<TurnBasedMatch> |
acceptInvitation(String
invitationId)
Returns a
Task
which asynchronously accepts an invitation and loads a
TurnBasedMatch .
|
Task<String> |
cancelMatch(String matchId)
Returns a
Task
which asynchronously cancels a turn-based match and loads a match ID.
|
Task<TurnBasedMatch> |
createMatch(TurnBasedMatchConfig
config)
Returns a
Task
which asynchronously loads a
TurnBasedMatch that represents a created turn-based match for the
current game.
|
Task<Void> |
declineInvitation(String
invitationId)
Returns a
Task
which asynchronously declines an invitation for a turn-based match.
|
Task<Void> |
dismissInvitation(String
invitationId)
Returns a
Task
which asynchronously dismisses an invitation to a turn-based match.
|
Task<Void> |
dismissMatch(String matchId)
Returns a
Task
which asynchronously deletes a match from the server and local storage.
|
Task<TurnBasedMatch> |
finishMatch(String matchId)
Returns a
Task
which asynchronously finishes a match and loads a
TurnBasedMatch .
|
Task<TurnBasedMatch> |
finishMatch(String matchId,
byte[] matchData,
ParticipantResult... results)
Returns a
Task
which asynchronously marks a match as finished and loads a
TurnBasedMatch .
|
Task<TurnBasedMatch> |
finishMatch(String matchId,
byte[] matchData, List<ParticipantResult>
results)
Returns a
Task
which asynchronously marks a match as finished and loads a
TurnBasedMatch .
|
Task<Intent> | |
Task<Integer> |
getMaxMatchDataSize()
Returns a
Task
which asynchronously loads the maximum match data size in bytes.
|
Task<Intent> |
getSelectOpponentsIntent(int minPlayers, int maxPlayers, boolean
allowAutomatch)
|
Task<Intent> |
getSelectOpponentsIntent(int minPlayers, int maxPlayers)
|
Task<Void> |
leaveMatch(String matchId)
Returns a
Task
which asynchronously leaves the specified match when it is not the current
player's turn.
|
Task<Void> |
leaveMatchDuringTurn(String matchId,
String
pendingParticipantId)
Returns a
Task
which asynchronously leaves the specified match during the current player's
turn.
|
Task<AnnotatedData<TurnBasedMatch>> |
loadMatch(String matchId)
Returns a
Task
which asynchronously loads an annotated
TurnBasedMatch with a specified matchId.
|
Task<AnnotatedData<LoadMatchesResponse>> |
loadMatchesByStatus(int invitationSortOrder, int[] matchTurnStatuses)
Returns a
Task
which asynchronously load turn-based matches for the current game, and returns
an annotated
LoadMatchesResponse object on success.
|
Task<AnnotatedData<LoadMatchesResponse>> |
loadMatchesByStatus(int[] matchTurnStatuses)
Returns a
Task
which asynchronously loads turn-based matches for the current game, and returns
an annotated
LoadMatchesResponse object on success.
|
Task<Void> |
registerTurnBasedMatchUpdateCallback(TurnBasedMatchUpdateCallback
callback)
Returns a
Task
which asynchronously registers a callback to intercept incoming match updates
for the currently signed-in user.
|
Task<TurnBasedMatch> |
rematch(String matchId)
Returns a
Task
which asynchronously loads a
TurnBasedMatch that represents a created rematch of a previously
completed turn-based match.
|
Task<TurnBasedMatch> |
takeTurn(String matchId,
byte[] matchData, String
pendingParticipantId)
Returns a
Task
which asynchronously updates a match with new turn data and loads a
TurnBasedMatch .
|
Task<TurnBasedMatch> |
takeTurn(String matchId,
byte[] matchData, String
pendingParticipantId,
ParticipantResult... results)
Returns a
Task
which asynchronously updates a match with new turn data and loads a
TurnBasedMatch .
|
Task<TurnBasedMatch> |
takeTurn(String matchId,
byte[] matchData, String
pendingParticipantId, List<ParticipantResult>
results)
Returns a
Task
which asynchronously updates a match with new turn data and loads a
TurnBasedMatch .
|
Task<Boolean> |
unregisterTurnBasedMatchUpdateCallback(TurnBasedMatchUpdateCallback
callback)
Returns a
Task
which asynchronously unregisters this client's match update callback, if any,
and loads the result.
|
Inherited Method Summary
Public Methods
public Task<TurnBasedMatch> acceptInvitation (String invitationId)
Returns a Task
which
asynchronously accepts an invitation and loads a
TurnBasedMatch
. 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(String, byte[], String)
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
invitationId | The ID of the invitation to be accepted. |
---|
public Task<String> cancelMatch (String matchId)
Returns a Task
which
asynchronously cancels a turn-based match and loads a match ID. 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(String)
for a different alternative.
Required Scopes: SCOPE_GAMES_LITE
Parameters
matchId | The ID of the match to cancel. |
---|
public Task<TurnBasedMatch> createMatch (TurnBasedMatchConfig config)
Returns a Task
which
asynchronously loads a
TurnBasedMatch
that represents a created turn-based match for the current
game. If the provided
TurnBasedMatchConfig
includes auto-match 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(String, byte[], String)
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
config | The configuration parameters for the match to create. |
---|
public Task<Void> declineInvitation (String invitationId)
Returns a Task
which
asynchronously declines 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 Scopes: SCOPE_GAMES_LITE
Parameters
invitationId | The ID of the invitation to decline. |
---|
public Task<Void> dismissInvitation (String invitationId)
Returns a Task
which
asynchronously dismisses an invitation to a turn-based match. Dismissing an invitation
will not change the state of the match for the other participants.
Required Scopes: SCOPE_GAMES_LITE
Parameters
invitationId | The ID of the invitation to dismiss. |
---|
public Task<Void> dismissMatch (String matchId)
Returns a Task
which
asynchronously deletes 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 Scopes: SCOPE_GAMES_LITE
Parameters
matchId | The ID of the match to dismiss. |
---|
public Task<TurnBasedMatch> finishMatch (String matchId)
Returns a Task
which
asynchronously finishes a match and loads a
TurnBasedMatch
. This will not change the data of the match, but it will
transition the match into the state of
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.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
matchId | ID of the match to finish. |
---|
public Task<TurnBasedMatch> finishMatch (String matchId, byte[] matchData, ParticipantResult... results)
Returns a Task
which
asynchronously marks a match as finished and loads a
TurnBasedMatch
. 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(String, byte[], String)
.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
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() 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. |
public Task<TurnBasedMatch> finishMatch (String matchId, byte[] matchData, List<ParticipantResult> results)
Returns a Task
which
asynchronously marks a match as finished and loads a
TurnBasedMatch
. 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(String, byte[], String)
.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
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() 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. |
public Task<Intent> getInboxIntent ()
Returns a Task
which
asynchronously loads 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.
The returned Task
can fail with a RemoteException
.
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 Scopes: SCOPE_GAMES_LITE
public Task<Integer> getMaxMatchDataSize ()
Returns a Task
which
asynchronously loads the maximum match data size 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 -1.
Required Scopes: SCOPE_GAMES_LITE
public Task<Intent> getSelectOpponentsIntent (int minPlayers, int maxPlayers, boolean allowAutomatch)
Returns a Task
which
asynchronously loads 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 returned Task
can fail with a RemoteException
.
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.
Players may be preselected by specifying a list of player IDs in the EXTRA_PLAYER_IDS
extra on the returned intent.
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_PLAYER_IDS
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_PLAYER_IDS
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 Scopes: SCOPE_GAMES_LITE
Parameters
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. See
createMatch(TurnBasedMatchConfig) |
public Task<Intent> getSelectOpponentsIntent (int minPlayers, int maxPlayers)
Returns a Task
which
asynchronously loads 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 returned Task
can fail with a RemoteException
.
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.
Players may be preselected by specifying a list of player IDs in the EXTRA_PLAYER_IDS
extra on the returned intent.
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_PLAYER_IDS
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_PLAYER_IDS
will include only the other players selected, not the current player.
This method is the equivalent of calling
getSelectOpponentsIntent(int, int, boolean)
with the
allowAutomatch
parameter set to true
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
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). See
createMatch(TurnBasedMatchConfig) |
public Task<Void> leaveMatch (String matchId)
Returns a Task
which
asynchronously leaves 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(String, String)
for the form of the API to call during
the current player's turn.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
matchId | ID of the match to leave. |
---|
public Task<Void> leaveMatchDuringTurn (String matchId, String pendingParticipantId)
Returns a Task
which
asynchronously leaves 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(String)
for the form of the API to call when it is not the
current player's turn.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
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). |
public Task<AnnotatedData<TurnBasedMatch>> loadMatch (String matchId)
Returns a Task
which
asynchronously loads an annotated
TurnBasedMatch
with a specified matchId.
Required Scopes: SCOPE_GAMES_LITE
Parameters
matchId | The ID of the match to retrieve. |
---|
public Task<AnnotatedData<LoadMatchesResponse>> loadMatchesByStatus (int invitationSortOrder, int[] matchTurnStatuses)
Returns a Task
which
asynchronously load turn-based matches for the current game, and returns an annotated
LoadMatchesResponse
object on success. 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.
release()
should be called to release resources after usage.
Required Scopes: SCOPE_GAMES_LITE
Parameters
invitationSortOrder | How to sort the returned invitations. Must be either
SORT_ORDER_MOST_RECENT_FIRST or
SORT_ORDER_SOCIAL_AGGREGATION . |
---|---|
matchTurnStatuses | List of turn statuses to request. |
public Task<AnnotatedData<LoadMatchesResponse>> loadMatchesByStatus (int[] matchTurnStatuses)
Returns a Task
which
asynchronously loads turn-based matches for the current game, and returns an annotated
LoadMatchesResponse
object on success. 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.
release()
should be called to release resources after usage.
Required Scopes: SCOPE_GAMES_LITE
Parameters
matchTurnStatuses | List of turn statuses to request. |
---|
public Task<Void> registerTurnBasedMatchUpdateCallback (TurnBasedMatchUpdateCallback callback)
Returns a Task
which
asynchronously registers a callback to intercept incoming match updates for the
currently signed-in user. If a callback 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 callback may be active at a time. Calling this method while another match update callback was previously registered will replace the original listener with the new one.
Required Scopes: SCOPE_GAMES_LITE
Parameters
callback | The callback that is called when a match update is received. The callback is called on the main thread. |
---|
public Task<TurnBasedMatch> rematch (String matchId)
Returns a Task
which
asynchronously loads a
TurnBasedMatch
that represents a created 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
finishMatch(String)
. It is only valid to call this if
canRematch()
returned true
; calling this method an 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(String, byte[], String)
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
matchId | The ID of the previous match to re-create. |
---|
public Task<TurnBasedMatch> takeTurn (String matchId, byte[] matchData, String pendingParticipantId)
Returns a Task
which
asynchronously updates a match with new turn data and loads a
TurnBasedMatch
. The participant that is passed in as the pending participant
will be notified that it is their turn to take an 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(String)
directly.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
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() 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). |
public Task<TurnBasedMatch> takeTurn (String matchId, byte[] matchData, String pendingParticipantId, ParticipantResult... results)
Returns a Task
which
asynchronously updates a match with new turn data and loads a
TurnBasedMatch
. 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(String)
directly.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
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() 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; you can specify the eliminated
participants here. |
public Task<TurnBasedMatch> takeTurn (String matchId, byte[] matchData, String pendingParticipantId, List<ParticipantResult> results)
Returns a Task
which
asynchronously updates a match with new turn data and loads a
TurnBasedMatch
. 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 auto-match slots available 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(String)
directly.
If the local match state was out of date, the Task
will fail
with
TurnBasedMultiplayerClient.MatchOutOfDateApiException
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
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() 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. |
public Task<Boolean> unregisterTurnBasedMatchUpdateCallback (TurnBasedMatchUpdateCallback callback)
Returns a Task
which
asynchronously unregisters this client's match update callback, if any, and loads the
result. The result will be true
if the callback was unregistered and
false
if this callback wasn't registered previously or is already
unregistered. Any new match updates will generate status bar notifications as
normal.
Required Scopes: SCOPE_GAMES_LITE