TurnBasedMatches

Represents a turn-based match.

For a list of methods for this resource, see the end of this page.

Resource representations

This is a JSON template for a turn-based match resource object.

{
  "kind": "games#turnBasedMatch",
  "matchId": string,
  "applicationId": string,
  "variant": integer,
  "status": string,
  "userMatchStatus": string,
  "participants": [
    {
      "kind": "games#turnBasedMatchParticipant",
      "id": string,
      "player": players Resource,
      "autoMatchedPlayer": {
        "kind": "games#anonymousPlayer",
        "displayName": string,
        "avatarImageUrl": string
      },
      "autoMatched": boolean,
      "status": string
    }
  ],
  "creationDetails": {
    "kind": "games#turnBasedMatchModification",
    "participantId": string,
    "modifiedTimestampMillis": long
  },
  "lastUpdateDetails": {
    "kind": "games#turnBasedMatchModification",
    "participantId": string,
    "modifiedTimestampMillis": long
  },
  "autoMatchingCriteria": {
    "kind": "games#turnBasedAutoMatchingCriteria",
    "minAutoMatchingPlayers": integer,
    "maxAutoMatchingPlayers": integer,
    "exclusiveBitmask": long
  },
  "data": {
    "kind": "games#turnBasedMatchData",
    "dataAvailable": boolean,
    "data": bytes
  },
  "results": [
    {
      "kind": "games#participantResult",
      "participantId": string,
      "result": string,
      "placing": integer
    }
  ],
  "inviterId": string,
  "withParticipantId": string,
  "description": string,
  "pendingParticipantId": string,
  "matchVersion": integer,
  "rematchId": string,
  "matchNumber": integer,
  "previousMatchData": {
    "kind": "games#turnBasedMatchData",
    "dataAvailable": boolean,
    "data": bytes
  }
}

Property name	Value	Description
`applicationId`	`string`	The ID of the application being played.
`autoMatchingCriteria`	`nested object`	Criteria for auto-matching players into this match.
`autoMatchingCriteria.exclusiveBitmask`	`long`	A bitmask indicating when auto-matches are valid. When ANDed with other exclusive bitmasks, the result must be zero. Can be used to support exclusive roles within a game.
`autoMatchingCriteria.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#turnBasedAutoMatchingCriteria`.
`autoMatchingCriteria.maxAutoMatchingPlayers`	`integer`	The maximum number of players that should be added to the match by auto-matching.
`autoMatchingCriteria.minAutoMatchingPlayers`	`integer`	The minimum number of players that should be added to the match by auto-matching.
`creationDetails`	`nested object`	Details about the match creation.
`creationDetails.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#turnBasedMatchModification`.
`creationDetails.modifiedTimestampMillis`	`long`	The timestamp at which they modified the match, in milliseconds since the epoch in UTC.
`creationDetails.participantId`	`string`	The ID of the participant that modified the match.
`data`	`nested object`	The data / game state for this match.
`data.data`	`bytes`	The byte representation of the data (limited to 128 kB), as a Base64-encoded string with the URL_SAFE encoding option.
`data.dataAvailable`	`boolean`	True if this match has data available but it wasn't returned in a list response; fetching the match individually will retrieve this data.
`data.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#turnBasedMatchData`.
`description`	`string`	This short description is generated by our servers based on turn state and is localized and worded relative to the player requesting the match. It is intended to be displayed when the match is shown in a list.
`inviterId`	`string`	The ID of the participant that invited the user to the match. Not set if the user was not invited to the match.
`kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#turnBasedMatch`.
`lastUpdateDetails`	`nested object`	Details about the last update to the match.
`lastUpdateDetails.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#turnBasedMatchModification`.
`lastUpdateDetails.modifiedTimestampMillis`	`long`	The timestamp at which they modified the match, in milliseconds since the epoch in UTC.
`lastUpdateDetails.participantId`	`string`	The ID of the participant that modified the match.
`matchId`	`string`	Globally unique ID for a turn-based match.
`matchNumber`	`integer`	The number of the match in a chain of rematches. Will be set to 1 for the first match and incremented by 1 for each rematch.
`matchVersion`	`integer`	The version of this match: an increasing counter, used to avoid out-of-date updates to the match.
`participants[]`	`list`	The participants involved in the match, along with their statuses. Includes participants who have left or declined invitations.
`participants[].autoMatched`	`boolean`	True if this participant was auto-matched with the requesting player.
`participants[].autoMatchedPlayer`	`nested object`	Information about a player that has been anonymously auto-matched against the requesting player. (Either `player` or `autoMatchedPlayer` will be set.)
`participants[].autoMatchedPlayer.avatarImageUrl`	`string`	The base URL for the image to display for the anonymous player.
`participants[].autoMatchedPlayer.displayName`	`string`	The name to display for the anonymous player.
`participants[].autoMatchedPlayer.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#anonymousPlayer`.
`participants[].id`	`string`	An identifier for the participant in the scope of the match. Cannot be used to identify a player across matches or in other contexts.
`participants[].kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#turnBasedMatchParticipant`.
`participants[].player`	`nested object`	Information about the player. Not populated if this player was anonymously auto-matched against the requesting player. (Either `player` or `autoMatchedPlayer` will be set.)
`participants[].status`	`string`	The status of the participant with respect to the match. Possible values are: "`PARTICIPANT_NOT_INVITED_YET`" - The participant is slated to be invited to the match, but the invitation has not been sent; the invite will be sent when it becomes their turn. "`PARTICIPANT_INVITED`" - The participant has been invited to join the match, but has not yet responded. "`PARTICIPANT_JOINED`" - The participant has joined the match (either after creating it or accepting an invitation.) "`PARTICIPANT_DECLINED`" - The participant declined an invitation to join the match. "`PARTICIPANT_LEFT`" - The participant joined the match and then left it. "`PARTICIPANT_FINISHED`" - The participant finished playing in the match. "`PARTICIPANT_UNRESPONSIVE`" - The participant did not take their turn in the allotted time. Acceptable values are: "`PARTICIPANT_DECLINED`" "`PARTICIPANT_FINISHED`" "`PARTICIPANT_INVITED`" "`PARTICIPANT_JOINED`" "`PARTICIPANT_LEFT`" "`PARTICIPANT_NOT_INVITED_YET`" "`PARTICIPANT_UNRESPONSIVE`"
`pendingParticipantId`	`string`	The ID of the participant that is taking a turn.
`previousMatchData`	`nested object`	The data / game state for the previous match; set for the first turn of rematches only.
`previousMatchData.data`	`bytes`	The byte representation of the data (limited to 128 kB), as a Base64-encoded string with the URL_SAFE encoding option.
`previousMatchData.dataAvailable`	`boolean`	True if this match has data available but it wasn't returned in a list response; fetching the match individually will retrieve this data.
`previousMatchData.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#turnBasedMatchData`.
`rematchId`	`string`	The ID of a rematch of this match. Only set for completed matches that have been rematched.
`results[]`	`list`	The results reported for this match.
`results[].kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#participantResult`.
`results[].participantId`	`string`	The ID of the participant.
`results[].placing`	`integer`	The placement or ranking of the participant in the match results; a number from one to the number of participants in the match. Multiple participants may have the same placing value in case of a type.
`results[].result`	`string`	The result of the participant for this match. Possible values are: "`MATCH_RESULT_WIN`" - The participant won the match. "`MATCH_RESULT_LOSS`" - The participant lost the match. "`MATCH_RESULT_TIE`" - The participant tied the match. "`MATCH_RESULT_NONE`" - There was no winner for the match (nobody wins or loses this kind of game.) "`MATCH_RESULT_DISCONNECT`" - The participant disconnected / left during the match. "`MATCH_RESULT_DISAGREED`" - Different clients reported different results for this participant. Acceptable values are: "`MATCH_RESULT_DISAGREED`" "`MATCH_RESULT_DISCONNECT`" "`MATCH_RESULT_LOSS`" "`MATCH_RESULT_NONE`" "`MATCH_RESULT_TIE`" "`MATCH_RESULT_WIN`"
`status`	`string`	The status of the match. Possible values are: "`MATCH_AUTO_MATCHING`" - One or more slots need to be filled by auto-matching; the match cannot be established until they are filled. "`MATCH_ACTIVE`" - The match has started. "`MATCH_COMPLETE`" - The match has finished. "`MATCH_CANCELED`" - The match was canceled. "`MATCH_EXPIRED`" - The match expired due to inactivity. "`MATCH_DELETED`" - The match should no longer be shown on the client. Returned only for tombstones for matches when sync is called. Acceptable values are: "`MATCH_ACTIVE`" "`MATCH_AUTO_MATCHING`" "`MATCH_CANCELED`" "`MATCH_COMPLETE`" "`MATCH_DELETED`" "`MATCH_EXPIRED`"
`userMatchStatus`	`string`	The status of the current user in the match. Derived from the match type, match status, the user's participant status, and the pending participant for the match. Possible values are: "`USER_INVITED`" - The user has been invited to join the match and has not responded yet. "`USER_AWAITING_TURN`" - The user is waiting for their turn. "`USER_TURN`" - The user has an action to take in the match. "`USER_MATCH_COMPLETED`" - The match has ended (it is completed, canceled, or expired.) Acceptable values are: "`USER_AWAITING_TURN`" "`USER_INVITED`" "`USER_MATCH_COMPLETED`" "`USER_TURN`"
`variant`	`integer`	The variant / mode of the application being played; can be any integer value, or left blank.
`withParticipantId`	`string`	The ID of another participant in the match that can be used when describing the participants the user is playing with.

Methods

cancel: Cancel a turn-based match.
create: Create a turn-based match.
decline: Decline an invitation to play a turn-based match.
dismiss: Dismiss a turn-based match from the match list. The match will no longer show up in the list and will not generate notifications.
finish: Finish a turn-based match. Each player should make this call once, after all results are in. Only the player whose turn it is may make the first call to Finish, and can pass in the final match state.
get: Get the data for a turn-based match.
join: Join a turn-based match.
leave: Leave a turn-based match when it is not the current player's turn, without canceling the match.
leaveTurn: Leave a turn-based match during the current player's turn, without canceling the match.
list: Returns turn-based matches the player is or was involved in.
rematch: Create a rematch of a match that was previously completed, with the same participants. This can be called by only one player on a match still in their list; the player must have called Finish first. Returns the newly created match; it will be the caller's turn.
sync: Returns turn-based matches the player is or was involved in that changed since the last sync call, with the least recent changes coming first. Matches that should be removed from the local cache will have a status of MATCH_DELETED.
takeTurn: Commit the results of a player turn.