回填

Allow players to join matches that have already started and keep servers full as players leave.

阅读时间5 分钟

最后更新于 15 天前

回填是指在游戏开始后允许玩家加入游戏的流程。回填可以有不同的目标：

尽快开始匹配，无需玩家全部就绪。在这种情况下，Matchmaker 配置中的
```
backfill
```
属性设置为
```
true
```
，回填操作由 Matchmaker 发起。
保持匹配中的玩家人数恒定，即使有玩家中途离开。在这种情况下，游戏服务器会在创建回填工单时发起回填。

注意

即使配置中的

backfill

属性设置为

false

，当创建回填工单时，回填操作仍将正常运行。

回填流程

下图为回填流程示意图

在分配服务器后，此流程将获取分配有效负载信息和匹配结果。匹配结果包含 Matchmaker 创建的回填工单 ID 以及创建回填工单所需的重要信息。
服务器将获取 Multiplay Hosting 令牌，而游戏服务器将使用此令牌向 Matchmaker Service 进行身份验证。
游戏服务器每秒审批一次回填工单。这是向 Matchmaker Service 证明游戏服务器仍在运行的必要操作。
当有可兼容的新工单时，Matchmaker Service 会将其添加到现有的回填工单中。
将工单加入回填匹配后，游戏服务器会在下一次审批回填工单时将为该玩家工单指定服务器。
匹配到足够玩家后，游戏服务器将删除回填工单。

游戏服务器负责更新回填工单。例如，如果一名玩家离开服务器或从 Matchmaker 以外加入服务器，游戏服务器需要通过更新回填工单来通知 Matchmaker Service。当需要回填已离开游戏的玩家，而当前没有回填工单时，游戏服务器会创建新的回填工单。

注意

如果游戏服务器没有定期审批回填工单，那么 Matchmaker Service 会自动删除工单。这样可以防止非运行中游戏服务器的回填工单无故滞留。

注意

无论是因 Matchmaker Service 还是游戏服务器超时，当回填工单被删除后，未指定的工单都将回到工单池中。

创建回填工单

以下代码示例展示了如何从游戏服务器创建回填工单：

Unity SDK


// Set the Match Properties. These properties can also be found in the Allocation Payload (cf Allocation Payload)var teams = new List<Team>{                    new Team( "Red", "9c8e302e-9cf3-4ad6-a005-b2604e6851e3", new List<string>{ "c9e6857b-a810-488f-bacc-08d18d253b0a"  } ),                    new Team( "Blue", "e2d8f4fd-5db8-4153-bca7-72dfc9b2ac09", new List<string>{ "fe1a52cd-535a-4e34-bd24-d6db489eaa19"  } ),                };// Define the Players of the match with their data.var players = new List<Unity.Services.Matchmaker.Models.Player>{   new (       "c9e6857b-a810-488f-bacc-08d18d253b0a",       new Dictionary<string, object>       {           { "Team", "Red" }       }),   new (       "fe1a52cd-535a-4e34-bd24-d6db489eaa19",       new Dictionary<string, object>       {           { "Team", "Blue" }       })};var matchProperties = new MatchProperties(teams, players);var backfillTicketProperties = new BackfillTicketProperties(matchProperties);// Set options for matchmakingvar options = new CreateBackfillTicketOptions("queue", "127.0.0.1:8080", new Dictionary<string, object>(), backfillTicketProperties);// Create backfill ticketstring ticketId = await MatchmakerService.Instance.CreateBackfillTicketAsync(options);// Print the created ticket idDebug.Log(ticketId);

CURL


# Fetch a Multiplay token##fetch-a-multiplay-tokencurl --location --request POST ‘http://localhost:8086/token# Transform match properties in a base64 format##transform-match-properties-in-a-base64-formatmatchProperties=$(echo '{  "matchProperties": {    "teams": [      {        "teamName": "Red Team",        "teamId": "14f18a3e-921d-4165-90b6-ada353e186ca",        "playerIDs": [          "c9e6857b-a810-488f-bacc-08d18d253b0a"        ]      },      {        "teamName": "Blue Team",        "teamId": "5aa8ae3b-d5b6-463a-9795-9bc10210dc86",        "playerIDs": [          "fe1a52cd-535a-4e34-bd24-d6db489eaa19"        ]      }    ],    "players": [      {        "id": "c9e6857b-a810-488f-bacc-08d18d253b0a",        "customData": {          "Team": "Red"        }      },      {        "id": "fe1a52cd-535a-4e34-bd24-d6db489eaa19",        "customData": {          "Team": "Blue"        }      }    ],    "region": "05083faf-3795-47b8-a0dc-c626089c5ac9",    "backfillTicketId": "dc156067-d140-4c5e-b7d4-90ec51c8333f"  }}' | base64)# Send create backfill ticket request##send-create-backfill-ticket-requestcurl --location --request POST 'https://matchmaker.services.api.unity.com/v2/backfill' \--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \--header 'Content-Type: application/json' \--data-raw '{  "poolId": "e642781a-558f-4c56-a135-c655331cdeee”, # Information retrieved from the allocation payload  "connection": "127.0.0.1:8081",  "properties": {    "data":  "'+$matchProperties+'"  }}'

审批回填工单

在审批回填工单时，游戏服务器会通知 Matchmaker 其仍在运行，并希望从 Matchmaker 获取新工单。Unity 建议每秒审批一次回填工单。如果一段时间内没有调用回填工单审批，则 Matchmaker Service 会自动删除该工单。以下代码示例展示了如何审批回填工单：

Unity SDK


// Approve a backfill ticket// The backfill ticket retrieved as a response can then be updated to be used in the Update APIvar backfillTicket = await MatchmakerService.Instance.ApproveBackfillTicketAsync("<backfill ticket id here>");

CURL


curl --location --request POST 'https://matchmaker.services.api.unity.com/v2/backfill/{BackfillTicketId}/approvals' \--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \--header 'Content-Type: application/json'

更新回填工单

当新玩家从 Matchmaker 以外加入匹配，或玩家离开匹配时，应更新回填工单。更新回填工单后，游戏服务器将通知 Matchmaker 匹配组成已更改。以下代码示例展示了如何更新现有的回填工单：


// Retrieve the backfill information from the approve backfill callvar backfillTicket = await MatchmakerService.Instance.ApproveBackfillTicketAsync("1459800b-d463-4197-a903-f00041fdbf6f");// Add a new player to the backfill ticketvar newPlayer = new Player(   "6ebbc1f9-1c42-479c-b80d-9b6f6aa281f3",   new Dictionary<string, object>   {       { "Team", "Red" }   });backfillTicket.Properties.MatchProperties.Players.Add(newPlayer);backfillTicket.Properties.MatchProperties.Teams[0].PlayerIds.Add(newPlayer.Id);// remove a player from the backfill ticketvar playerIdToRemove = "fe1a52cd-535a-4e34-bd24-d6db489eaa19";var playerToRemove = backfillTicket.Properties.MatchProperties.Players.FirstOrDefault(p => p.Id.Equals(playerIdToRemove));backfillTicket.Properties.MatchProperties.Players.Remove(playerToRemove);backfillTicket.Properties.MatchProperties.Teams[0].PlayerIds.Remove(playerIdToRemove);await MatchmakerService.Instance.UpdateBackfillTicketAsync(backfillTicket.Id, backfillTicket);

CURL


# Fetch a Multiplay token##fetch-a-multiplay-tokencurl --location --request POST ‘http://localhost:8086/token# Transform match properties in a base64 format##transform-match-properties-in-a-base64-formatmatchProperties=$(echo '{  "matchProperties": {    "teams": [      {        "teamName": "Red Team",        "teamId": "14f18a3e-921d-4165-90b6-ada353e186ca",        "playerIDs": [          "6ebbc1f9-1c42-479c-b80d-9b6f6aa281f3",        ]      },      {        "teamName": "Blue Team",        "teamId": "5aa8ae3b-d5b6-463a-9795-9bc10210dc86",        "playerIDs": [          "fe1a52cd-535a-4e34-bd24-d6db489eaa19"        ]      }    ],    "players": [      {        "id": "6ebbc1f9-1c42-479c-b80d-9b6f6aa281f3",        "customData": {          "Team": "Red"        }      },      {        "id": "fe1a52cd-535a-4e34-bd24-d6db489eaa19",        "customData": {          "Team": "Blue"        }      }    ],    "region": "05083faf-3795-47b8-a0dc-c626089c5ac9",    "backfillTicketId": "dc156067-d140-4c5e-b7d4-90ec51c8333f"  }}' | base64)# Send update backfill ticket request##send-update-backfill-ticket-requestcurl --location --request PUT 'https://matchmaker.services.api.unity.com/v2/backfill/{BackfillTicketId}' \--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \--header 'Content-Type: application/json' \--data-raw '{  "poolId": "e642781a-558f-4c56-a135-c655331cdeee”, # Information retrieved from the allocation payload  "connection": "127.0.0.1:8081",  "properties": {    "data":  "'+$matchProperties+'"  }}'

注意

游戏服务器更新回填工单后，所有未指定的工单都将被释放到工单池中。

删除回填工单

在以下情况下，应删除回填工单：

服务器不需要新工单。
服务器即将停止运行。

以下代码示例展示了如何删除回填工单：

Unity SDK


await MatchmakerService.Instance.DeleteBackfillTicketAsync("1459800b-d463-4197-a903-f00041fdbf6f");

CURL


curl --location --request DELETE 'https://matchmaker.services.api.unity.com/v2/backfill/{BackfillTicketId}' \--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \--header 'Content-Type: application/json'

文档

引擎

服务

增长

工业

支持

Matchmaker

Matchmaker

回填

回填流程

创建回填工单

Unity SDK

CURL

审批回填工单

Unity SDK

CURL

更新回填工单

CURL

删除回填工单

Unity SDK

CURL