Rooms

Represents the state of a room with multiple players.

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

Resource representations

This is a JSON template for a room resource object.

{
  "kind": "games#room",
  "roomId": string,
  "applicationId": string,
  "variant": integer,
  "status": string,
  "participants": [
    {
      "kind": "games#roomParticipant",
      "id": string,
      "player": players Resource,
      "autoMatchedPlayer": {
        "kind": "games#anonymousPlayer",
        "displayName": string,
        "avatarImageUrl": string
      },
      "autoMatched": boolean,
      "status": string,
      "clientAddress": {
        "kind": "games#roomClientAddress",
        "xmppAddress": string
      },
      "connected": boolean,
      "leaveReason": string,
      "capabilities": [
        string
      ]
    }
  ],
  "inviterId": string,
  "creationDetails": {
    "kind": "games#roomModification",
    "participantId": string,
    "modifiedTimestampMillis": long
  },
  "lastUpdateDetails": {
    "kind": "games#roomModification",
    "participantId": string,
    "modifiedTimestampMillis": long
  },
  "description": string,
  "autoMatchingCriteria": {
    "kind": "games#roomAutoMatchingCriteria",
    "minAutoMatchingPlayers": integer,
    "maxAutoMatchingPlayers": integer,
    "exclusiveBitmask": long
  },
  "roomStatusVersion": integer,
  "autoMatchingStatus": {
    "kind": "games#roomAutoMatchStatus",
    "waitEstimateSeconds": integer
  }
}

Property name	Value	Description
`applicationId`	`string`	The ID of the application being played.
`autoMatchingCriteria`	`nested object`	Criteria for auto-matching players into this room.
`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#roomAutoMatchingCriteria`.
`autoMatchingCriteria.maxAutoMatchingPlayers`	`integer`	The maximum number of players that should be added to the room by auto-matching.
`autoMatchingCriteria.minAutoMatchingPlayers`	`integer`	The minimum number of players that should be added to the room by auto-matching.
`autoMatchingStatus`	`nested object`	Auto-matching status for this room. Not set if the room is not currently in the auto-matching queue.
`autoMatchingStatus.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#roomAutoMatchStatus`.
`autoMatchingStatus.waitEstimateSeconds`	`integer`	An estimate for the amount of time (in seconds) that auto-matching is expected to take to complete.
`creationDetails`	`nested object`	Details about the room creation.
`creationDetails.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#roomModification`.
`creationDetails.modifiedTimestampMillis`	`long`	The timestamp at which they modified the room, in milliseconds since the epoch in UTC.
`creationDetails.participantId`	`string`	The ID of the participant that modified the room.
`description`	`string`	This short description is generated by our servers and worded relative to the player requesting the room. It is intended to be displayed when the room is shown in a list (that is, an invitation to a room.)
`inviterId`	`string`	The ID of the participant that invited the user to the room. Not set if the user was not invited to the room.
`kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#room`.
`lastUpdateDetails`	`nested object`	Details about the last update to the room.
`lastUpdateDetails.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#roomModification`.
`lastUpdateDetails.modifiedTimestampMillis`	`long`	The timestamp at which they modified the room, in milliseconds since the epoch in UTC.
`lastUpdateDetails.participantId`	`string`	The ID of the participant that modified the room.
`participants[]`	`list`	The participants involved in the room, 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[].capabilities[]`	`list`	The capabilities which can be used when communicating with this participant.
`participants[].clientAddress`	`nested object`	Client address for the participant.
`participants[].clientAddress.kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#roomClientAddress`.
`participants[].clientAddress.xmppAddress`	`string`	The XMPP address of the client on the Google Games XMPP network.
`participants[].connected`	`boolean`	True if this participant is in the fully connected set of peers in the room.
`participants[].id`	`string`	An identifier for the participant in the scope of the room. Cannot be used to identify a player across rooms or in other contexts.
`participants[].kind`	`string`	Uniquely identifies the type of this resource. Value is always the fixed string `games#roomParticipant`.
`participants[].leaveReason`	`string`	The reason the participant left the room; populated if the participant status is `PARTICIPANT_LEFT`. Possible values are: "`PLAYER_LEFT`" - The player explicitly chose to leave the room. "`GAME_LEFT`" - The game chose to remove the player from the room. "`ABANDONED`" - The player switched to another application and abandoned the room. "`PEER_CONNECTION_FAILURE`" - The client was unable to establish or maintain a connection to other peer(s) in the room. "`SERVER_ERROR`" - The client received an error response when it tried to communicate with the server. "`TIMEOUT`" - The client timed out while waiting for players to join and connect. "`PRESENCE_FAILURE`" - The client's XMPP connection ended abruptly. Acceptable values are: "`ABANDONED`" "`GAME_LEFT`" "`PEER_CONNECTION_FAILURE`" "`PLAYER_LEFT`" "`PRESENCE_FAILURE`" "`SERVER_CONNECTION_FAILURE`" "`SERVER_ERROR`" "`TIMEOUT`"
`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 room. Possible values are: "`PARTICIPANT_INVITED`" - The participant has been invited to join the room, but has not yet responded. "`PARTICIPANT_JOINED`" - The participant has joined the room (either after creating it or accepting an invitation.) "`PARTICIPANT_DECLINED`" - The participant declined an invitation to join the room. "`PARTICIPANT_LEFT`" - The participant joined the room and then left it. Acceptable values are: "`PARTICIPANT_DECLINED`" "`PARTICIPANT_INVITED`" "`PARTICIPANT_JOINED`" "`PARTICIPANT_LEFT`"
`roomId`	`string`	Globally unique ID for a room.
`roomStatusVersion`	`integer`	The version of the room status: an increasing counter, used by the client to ignore out-of-order updates to room status.
`status`	`string`	The status of the room. Possible values are: "`ROOM_INVITING`" - One or more players have been invited and not responded. "`ROOM_AUTO_MATCHING`" - One or more slots need to be filled by auto-matching. "`ROOM_CONNECTING`" - Players have joined and are connecting to each other (either before or after auto-matching). "`ROOM_ACTIVE`" - All players have joined and connected to each other. "`ROOM_DELETED`" - The room should no longer be shown on the client. Returned in sync calls when a player joins a room (as a tombstone), or for rooms where all joined participants have left. Acceptable values are: "`ROOM_ACTIVE`" "`ROOM_AUTO_MATCHING`" "`ROOM_CONNECTING`" "`ROOM_DELETED`" "`ROOM_INVITING`"
`variant`	`integer`	The variant / mode of the application being played; can be any integer value, or left blank.

Methods

create: Create a room. For internal use by the Games SDK only. Calling this method directly is unsupported.
decline: Decline an invitation to join a room. For internal use by the Games SDK only. Calling this method directly is unsupported.
dismiss: Dismiss an invitation to join a room. For internal use by the Games SDK only. Calling this method directly is unsupported.
get: Get the data for a room.
join: Join a room. For internal use by the Games SDK only. Calling this method directly is unsupported.
leave: Leave a room. For internal use by the Games SDK only. Calling this method directly is unsupported.
list: Returns invitations to join rooms.
reportStatus: Updates sent by a client reporting the status of peers in a room. For internal use by the Games SDK only. Calling this method directly is unsupported.