开始使用
注意：根据《数字服务法案》(DSA) 的规定，如果 Unity 采取的行动会对客户的终端用户产生影响，Unity 必须通知这些终端用户。为了遵循这一要求，如果使用的 Unity Gaming Services（Unity 游戏服务）(UGS) 产品依赖于 Unity Authentication 服务，则必须集成通知 API。
如需有关 DSA 的更多信息，请参阅《数字服务法案》- 合规性更新。
为了使游戏合规，请参阅 DSA 通知。
本指南将分步概要讲述如何安装 Matchmaker SDK、启用 Matchmaker、创建第一个匹配工单以及创建 Multiplay Hosting 分配。
先决条件
要开始使用 Matchmaker，您需要执行以下操作：
配置托管方式
在启用 Matchmaker 之前，请初始化 Multiplay Hosting 或由 Unity 提供的客户端托管解决方案。请参阅开始使用 Multiplay Hosting、开始使用 Relay 和分布式授权快速入门。
安装 Matchmaker SDK
要安装最新的 Unity Matchmaker 包，请执行以下操作：
- 在 Unity 编辑器中，导航到 Window（窗口）> Package Manager（包管理器）。
- 在 **Package Manager（包管理器）**中搜索以下包：
- 对于 Unity 6 及更高版本：
com.unity.services.multiplayer - 对于 Unity 2022 LTS 及更低版本：
com.unity.services.matchmaker
- 对于 Unity 6 及更高版本：
- 选择相应的包，然后选择 Install（安装）。
请参阅 Package Manager（包管理器）文档，了解更多信息。
设置 Matchmaker
您可以通过 Unity Cloud Dashboard 设置和管理 Matchmaker。
- 访问 cloud.unity.com。
- 从侧边栏中选择 **Products（产品）**选项卡。
- 在 Gaming Services（游戏服务）> Multiplayer 下，转到 Matchmaker，然后选择 Launch（启动）。
首次启动 Matchmaker 时，系统会将 Matchmaker 添加到侧边栏的 **Shortcuts（快捷方式）**部分，并会打开 **Overview（概览）**页面。
创建队列和池
- 选择 Create a Queue（创建队列）。为第一个队列选择名称，然后在匹配工单上设置最大玩家人数。单击 Create（创建）。
- 选择 Create a Pool（创建池）。为池选择名称。选择在上一步中创建的队列。为工单设置超时值。单击 Next（下一步）。
- 选择您的托管类型：
- 如果您使用 Multiplay Hosting，请首先在下拉菜单中选择 Multiplay Hosting，然后选择配置 Multiplay Hosting 时创建的 **Fleet（机群）**和 Build Configuration（版本配置）。
- 如果您使用 Unity 提供的客户端托管解决方案，请在下拉菜单中选择 Client Hosting（客户端托管）。
- 单击 Next（下一步）。
定义所需的规则以定义在向队列和池发送工单时创建的匹配。选择 JSON，然后复制并粘贴以下代码块：
{
"Name": "Test",
"MatchDefinition": {
"Teams": [
{
"Name": "Main team",
"TeamCount": {
"Min": 1,
"Max": 1
},
"PlayerCount": {
"Min": 1,
"Max": 5
}
}
],
"MatchRules": []
},
"BackfillEnabled": false
}使用以上代码可创建一个包含 1 - 5 名玩家的队伍。
- 单击 Logic Builder（逻辑构建器），然后从下拉菜单中选择一个地区，将其设置为 Default QoS Region（默认 QoS 地区）。
- 单击页面底部的 Create（创建）。
现在，Matchmaker 已配置完成。您可以在 Matchmaker 部分的菜单中单击 **Queues（队列）**以查看创建好的队列和池。
创建 Matchmaking 工单
现在，Matchmaker 已配置完成，我们可以创建并发送工单来请求 Multiplay Hosting 分配：
Unity SDK
var players = new List<Unity.Services.Matchmaker.Models.Player>
{
new ("Player1", new Dictionary<string, object>())
};
// Set options for matchmaking
var options = new CreateTicketOptions(
"Default", // The name of the queue defined in the previous step,
new Dictionary<string, object>());
// Create ticket
var ticketResponse = await MatchmakerService.Instance.CreateTicketAsync(players, options);
// Print the created ticket id
Debug.Log(ticketResponse.Id);CURL
# Fetch anonymous token
curl -X POST -H "ProjectId: <projectId>" https://player-auth.services.api.unity.com/v1/authentication/anonymous
# Call the create ticket endpoint
curl -X POST -H "Authorization: Bearer <TOKEN>" \
-H 'Content-Type: application/json' \
--data-raw '{
"queueName": "Default",
"attributes": {},
"players": [{
"id": "Player 1",
"customData": {}
}]
}' \
'https://matchmaker.services.api.unity.com/v2/tickets'REST API
https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/createTicket
轮询工单状态
创建工单后，客户会使用创建工单时返回的工单 ID 进行轮询，以获取工单状态。
在向匹配指定工单并分配服务器后，Matchmaker 会向工单状态响应中添加服务器信息。
Unity SDK
MultiplayAssignment assignment = null;
bool gotAssignment = false;
do
{
//Rate limit delay
await Task.Delay(TimeSpan.FromSeconds(1f));
// Poll ticket
var ticketStatus = await MatchmakerService.Instance.GetTicketAsync("<ticket id here>");
if (ticketStatus == null)
{
continue;
}
//Convert to platform assignment data (IOneOf conversion)
if (ticketStatus.Type == typeof(MultiplayAssignment))
{
assignment = ticketStatus.Value as MultiplayAssignment;
}
switch (assignment?.Status)
{
case MultiplayAssignment.StatusOptions.Found:
gotAssignment = true;
break;
case MultiplayAssignment.StatusOptions.InProgress:
//...
break;
case MultiplayAssignment.StatusOptions.Failed:
gotAssignment = true;
Debug.LogError("Failed to get ticket status. Error: " + assignment.Message);
break;
case MultiplayAssignment.StatusOptions.Timeout:
gotAssignment = true;
Debug.LogError("Failed to get ticket status. Ticket timed out.");
break;
default:
throw new InvalidOperationException();
}
} while (!gotAssignment);CURL
# Call the poll ticket status endpoint with same anonymous token as for the creation
curl -X GET -H "Authorization: Bearer <TOKEN>" \
--header 'Content-Type: application/json' \
'https://matchmaker.services.api.unity.com/v2/tickets/status?id=<TICKETID>'REST API
https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/getTicketStatus
匹配结果
分配服务器后，即可在服务器端获取使用有效负载分配得到的匹配结果。
匹配结果包括关于应进入匹配的不同玩家及其数据和队伍分布的信息。
此代码仅适用于由 Multiplay Hosting 分配的服务器。
Unity SDK
var payloadAllocation = await MultiplayService.Instance.GetPayloadAllocationFromJsonAs<MatchmakingResults>();Note：请使用 server.json 文件获取服务器的分配 UUID。
您需要安装 Multiplay Hosting SDK 才能访问匹配结果
CURL
curl -X GET http://localhost:8086/payload/<allocation_uuid>