TurnBasedMatches

表示回合制对局。

有关此类资源的方法列表，请参阅本页面的结尾部分。

资源表示形式

这是回合制匹配资源对象的 JSON 模板。

{
  "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
  }
}
属性名称 值 说明 备注
applicationId string 所播放的应用的 ID。
autoMatchingCriteria nested object 将玩家自动匹配到此匹配条件。
autoMatchingCriteria.exclusiveBitmask long 一个位掩码，表示自动匹配何时有效。与其他独占位掩码执行 AND 运算时，结果必须为零。可用于支持游戏中的专属角色。
autoMatchingCriteria.kind string 此资源类型的唯一标识。值始终是固定字符串 games#turnBasedAutoMatchingCriteria。
autoMatchingCriteria.maxAutoMatchingPlayers integer 应通过自动匹配功能添加到对局中的玩家数量上限。
autoMatchingCriteria.minAutoMatchingPlayers integer 应通过自动匹配功能添加到比赛中的玩家人数下限。
creationDetails nested object 有关匹配创建的详细信息。
creationDetails.kind string 此资源类型的唯一标识。值始终是固定字符串 games#turnBasedMatchModification。
creationDetails.modifiedTimestampMillis long 修改匹配操作的时间戳，以从公元纪年开始计算的毫秒数表示。
creationDetails.participantId string 修改匹配的参与者 ID。
data nested object 此比赛的数据 / 游戏状态。
data.data bytes 数据的字节表示形式（上限为 128 kB），采用采用 网址_Safe 编码选项的 Base64 编码字符串表示。
data.dataAvailable boolean 如果此匹配项有可用数据，但未在列表响应中返回，则为 true；单独提取此匹配项将检索此数据。
data.kind string 此资源类型的唯一标识。值始终是固定字符串 games#turnBasedMatchData。
description string 此简短说明由我们的服务器根据回合状态生成，并经过本地化并措辞相对于请求比赛的玩家。匹配会在列表中显示时显示。
inviterId string 邀请用户参加比赛的参与者的 ID。如果用户未受邀加入对局，则未设置此参数。
kind string 此资源类型的唯一标识。值始终是固定字符串 games#turnBasedMatch。
lastUpdateDetails nested object 上次匹配的匹配的详细信息。
lastUpdateDetails.kind string 此资源类型的唯一标识。值始终是固定字符串 games#turnBasedMatchModification。
lastUpdateDetails.modifiedTimestampMillis long 修改匹配操作的时间戳，以从公元纪年开始计算的毫秒数表示。
lastUpdateDetails.participantId string 修改匹配的参与者 ID。
matchId string 基于回合制对局的全局唯一 ID。
matchNumber integer 一系列重赛中的比赛编号。对于第一次匹配，将设置为 1，并且对于每次重新匹配将递增 1。
matchVersion integer 此匹配项的版本：越来越高的计数器，用于避免过时的匹配项更新。
participants[] list 比赛参与者及其状态。包含已离开或拒绝邀请的参与者。
participants[].autoMatched boolean 如果此参与者与发出请求的玩家自动匹配，则为 True。
participants[].autoMatchedPlayer nested object 匿名与请求玩家匹配的玩家的相关信息。（系统将设置 player 或 autoMatchedPlayer。）
participants[].autoMatchedPlayer.avatarImageUrl string 要为匿名玩家显示的图片的基准网址。
participants[].autoMatchedPlayer.displayName string 要为匿名玩家显示的名称。
participants[].autoMatchedPlayer.kind string 此资源类型的唯一标识。值始终是固定字符串 games#anonymousPlayer。
participants[].id string 匹配范围内的参与者的标识符。不能用于跨场匹配或其他情境来识别玩家。
participants[].kind string 此资源类型的唯一标识。值始终是固定字符串 games#turnBasedMatchParticipant。
participants[].player nested object 播放器的相关信息。如果此玩家已自动与发出请求的玩家自动匹配，则系统不会填充。（系统将设置 player 或 autoMatchedPlayer。）
participants[].status string 参与者相对于对局的状态。
可能的值包括：
  • “PARTICIPANT_NOT_INVITED_YET”- 参与者已受邀加入对局，但对方尚未发送邀请；对方轮到对方时，系统会发送邀请。
  • “PARTICIPANT_INVITED”- 参与者已受邀加入对局，但尚未回复。
  • “PARTICIPANT_JOINED”- 参与者已加入对局（无论是在创建对局还是接受邀请）。
  • “PARTICIPANT_DECLINED”- 参与者拒绝了加入比赛的邀请。
  • “PARTICIPANT_LEFT”- 参与者加入了对局，然后退出了。
  • “PARTICIPANT_FINISHED”- 参与者已结束比赛。
  • “PARTICIPANT_UNRESPONSIVE”- 参与者没有在规定时间内轮流学习。


可接受的值：
  • “PARTICIPANT_DECLINED”
  • “PARTICIPANT_FINISHED”
  • “PARTICIPANT_INVITED”
  • “PARTICIPANT_JOINED”
  • “PARTICIPANT_LEFT”
  • “PARTICIPANT_NOT_INVITED_YET”
  • “PARTICIPANT_UNRESPONSIVE”
pendingParticipantId string 正在转向的参与者的 ID。
previousMatchData nested object 上一个匹配项的数据 / 游戏状态；仅设置为第一次回合。
previousMatchData.data bytes 数据的字节表示形式（上限为 128 kB），采用采用 网址_Safe 编码选项的 Base64 编码字符串表示。
previousMatchData.dataAvailable boolean 如果此匹配项有可用数据，但未在列表响应中返回，则为 true；单独提取此匹配项将检索此数据。
previousMatchData.kind string 此资源类型的唯一标识。值始终是固定字符串 games#turnBasedMatchData。
rematchId string 此匹配项的重新匹配的 ID。仅针对已重新匹配且已完成的匹配设置。
results[] list 系统报告的匹配结果。
results[].kind string 此资源类型的唯一标识。值始终是固定字符串 games#participantResult。
results[].participantId string 参与者的 ID。
results[].placing integer 参与者在匹配结果中的排名或排名；从 1 到参与者的数量。如果是某种类型，则多个参与者的布置值可能相同。
results[].result string 这场比赛的参与者结果。
可能的值包括：
  • “MATCH_RESULT_WIN”- 参与者获胜。
  • “MATCH_RESULT_LOSS”- 参与者输掉了比赛。
  • “MATCH_RESULT_TIE”- 参与者已配对。
  • “MATCH_RESULT_NONE”- 比赛没有获胜（没有人赢或者输掉了这种游戏）。
  • “MATCH_RESULT_DISCONNECT”- 参与者在比赛期间断开连接 / 离开。
  • “MATCH_RESULT_DISAGREED”- 不同的客户为此参与者报告了不同的结果。


可接受的值：
  • “MATCH_RESULT_DISAGREED”
  • “MATCH_RESULT_DISCONNECT”
  • “MATCH_RESULT_LOSS”
  • “MATCH_RESULT_NONE”
  • “MATCH_RESULT_TIE”
  • “MATCH_RESULT_WIN”
status string 匹配状态。
可能的值包括：
  • “MATCH_AUTO_MATCHING”- 有一个或多个槽需要通过自动匹配功能进行填充；只有在填充空档后才能建立匹配。
  • “MATCH_ACTIVE”- 比赛已开始。
  • “MATCH_COMPLETE”- 对局已结束。
  • “MATCH_CANCELED”- 比赛已取消。
  • “MATCH_EXPIRED”- 匹配已因无效而过期。
  • “MATCH_DELETED”- 匹配项不应再显示在客户端上。仅在调用同步时针对 tombstone 返回。


可接受的值：
  • “MATCH_ACTIVE”
  • “MATCH_AUTO_MATCHING”
  • “MATCH_CANCELED”
  • “MATCH_COMPLETE”
  • “MATCH_DELETED”
  • “MATCH_EXPIRED”
userMatchStatus string 匹配中当前用户的状态。源自匹配类型、匹配状态、用户的参与者状态，以及比赛的待处理参与者。
可能的值包括：
  • “USER_INVITED”- 用户已受邀加入对局，但尚未回复。
  • “USER_AWAITING_TURN”- 用户正在等待其轮到。
  • “USER_TURN”- 用户在匹配中采取了一项操作。
  • “USER_MATCH_COMPLETED”- 比赛已结束（已结束、已取消或已过期）。


可接受的值：
  • “USER_AWAITING_TURN”
  • “USER_INVITED”
  • “USER_MATCH_COMPLETED”
  • “USER_TURN”
variant integer 所播放应用的变体 / 模式；可以是任何整数值，也可以留空。
withParticipantId string 匹配中的其他参与者的 ID，可用于说明用户正在玩游戏的参与者。

方法

取消
取消回合制对局。
create
创建回合制对局。
下降
拒绝回合制对局邀请。
关闭
在对局列表中拒绝回合制对局。匹配视频不会再显示在列表中，并且不会生成通知。
完成
完成回合制对局。所有玩家都应在收到所有结果后执行此调用一次。只有轮流玩的玩家可以首次调用 Finish，并传入最终匹配状态。
get
获取回合制比赛数据。
join
加入回合制对局。
离开
如果当前轮到的玩家不是回合制对局，则不取消该对局。
离开
在当前玩家回合中不考虑回合制对局，而不取消回合制。
list
返回玩家参与或参与的回合制对局。
重赛
创建之前由同一位参与者完成的重赛。只能由列表中仍在比赛中的玩家调用；该玩家必须先调用“完成”。返回新创建的匹配；这轮调用将会轮到您。
sync
返回玩家自上次同步调用以来发生或曾经参与的回合制对局，最近更改最先发生。应从本地缓存中移除的匹配项的状态为 MATCH_DELETED。
takeTurn
提交玩家回合的结果。