Unity 匹配器

本指南将帮助您使用 Edgegap 的高级 Matchmaker 系统创建 Unity 项目，以自动化部署和玩家之间的连接。

本指南将使用开源示例项目 Tanks，可在 Mirror 示例的 Assets/Mirror/Examples/Tanks下找到。最终示例可以在我们的 GitHub.

Matchmaker 设置

创建组件

首先，您需要创建 3 个 Matchmaker 组件。对于此项目，您可以按照我们的基础组件教程进行操作 这里.

请记住，本教程创建的组件和 YAML 配置不适合用于生产环境。

发布

本地

如果您想在本地环境中测试 Matchmaker，只需按照基础组件教程结尾处提到的内容应用您的 Kubernetes 设置。然后您可以直接跳到 项目设置.

使用 Edgegap

如果您想在 Edgegap 的在线环境中测试 Matchmaker，则需要对上一教程中的组件进行少许修改。您将使用在发布期间注入的变量，而不是一些硬编码的值。更改应如下所示：

Director

...
下面是该通用未修改脚本（取自 Bolt 文档）的样子：

namespace director
{
  public static class Constant
  {
    static Constant()
    {
        OpenMatchMatchFunctionHost = Environment.GetEnvironmentVariable("OM_MMF_HOST");
        OpenMatchMatchFunctionPort = Int32.Parse(Environment.GetEnvironmentVariable("OM_MMF_HTTP_PORT"));
        OpenMatchBackendService = Environment.GetEnvironmentVariable("OM_BACKEND_HOST") + ':' + Int32.Parse(Environment.GetEnvironmentVariable("OM_BACKEND_HTTP_PORT"));
    }

    public static readonly string OpenMatchMatchFunctionHost;
    public static readonly int OpenMatchMatchFunctionPort;
    public static readonly string OpenMatchBackendService;

    ...
  }

  ...
}

Frontend

...

namespace front_end
{
  // 程序中使用的所有常量
  public static class Constant
  {
    static Constant()
    {
        OpenMatchFrontendService = Environment.GetEnvironmentVariable("OM_FRONTEND_HOST") + ':' + Int32.Parse(Environment.GetEnvironmentVariable("OM_FRONTEND_HTTP_PORT"));
    }

    public static readonly string OpenMatchFrontendService;
  }

  ...
}

Match Function

...

namespace match_function
{
  // 程序中使用的所有常量
  public static class Constant
  {
    static Constant()
    {
        OpenMatchQueryService = Environment.GetEnvironmentVariable("OM_QUERY_HOST") + ':' + Int32.Parse(Environment.GetEnvironmentVariable("OM_QUERY_HTTP_PORT"));
    }

    public static readonly string OpenMatchQueryService;
    public const string MatchName = "basics-match-function";
  }

  ...
}

完成后，将它们上传到 Edgegap，然后在 Edgegap 控制面板上创建并发布您的 Matchmaker。

项目设置

接下来，我们要修改基础坦克项目，使 Matchmaker 用于将玩家连接在一起。对于本示例，我们希望玩家在创建 Matchmaker 票据之前选择他们想玩的比赛模式，这样 Matchmaker 会自动将选择相同模式的 2 名玩家配对。

使用上一教程创建的基础 Matchmaker 组件，可用的模式为 mode.casual, mode.ranked，以及 mode.private.

在项目中，打开位于 Assets/Mirror/Examples/Tanks/Scenes下的场景。禁用 Network Manager HUD 组件的 NetworkManager gameObject，然后创建您自己的 HUD，以允许玩家输入游戏模式，在未匹配时创建和删除票据，并在已匹配时退出当前比赛。

离线 HUD

在线 HUD

然后，您需要在项目中创建新的脚本来管理根据玩家点击的按钮发送哪些请求。用于管理请求本身的代码结构应类似于：

函数

public class MatchmakerManager : ScriptableObject
{
  // 在本地测试 Matchmaker 时，此值应为 http://localhost:51504
  // 在测试 Matchmaker 的在线发布时，不需要在 URL 末尾指定端口
  public const string MATCHMAKER_URL = "<FRONTEND_COMPONENT_URL>";
  private readonly HttpClient _httpClient = new();
  public KcpTransport transport = (KcpTransport)NetworkManager.singleton.transport;

  /// <summary>
  /// 从 Matchmaker 获取票据的数据
  /// </summary>
  /// <param name="ticketId">票据的 ID</param>
  /// <returns>票据数据</returns>
  public async Task<Ticket> GetTicket(string ticketId)
  {
    var response = await _httpClient.GetAsync($"{MATCHMAKER_URL}/v1/tickets/{ticketId}");

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"Error code: {response.StatusCode}");
    }

    var responseContent = await response.Content.ReadAsStringAsync();
    Ticket content = JsonConvert.DeserializeObject<Ticket>(responseContent);

    return content;
  }

  /// <summary>
  /// 为 Matchmaker 创建新票据
  /// </summary>
  /// <param name="modeTag">玩家希望进入的游戏模式</param>
  /// <returns>票据数据</returns>
  public async Task<Ticket> CreateTicket(string modeTag)
  {
    CreateTicketPayload objectToSerialize = new()
    {
        mode = modeTag
    };

    var jsonContent = new StringContent(JsonConvert.SerializeObject(objectToSerialize), Encoding.UTF8, "application/json");
    var response = await _httpClient.PostAsync($"{MATCHMAKER_URL}/v1/tickets", jsonContent);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"Error code: {response.StatusCode}");
    }

    var responseContent = await response.Content.ReadAsStringAsync();
    Ticket content = JsonConvert.DeserializeObject<Ticket>(responseContent);

    return content;
  }

  /// <summary>
  /// 从 Matchmaker 删除票据
  /// </summary>
  /// <param name="ticketId">票据的 ID</param>
  public async Task DeleteTicket(string ticketId)
  {
    var response = await _httpClient.DeleteAsync($"{MATCHMAKER_URL}/v1/tickets/{ticketId}");

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"Error code: {response.StatusCode}");
    }
  }

  /// <summary>
  /// 将玩家连接到比赛
  /// </summary>
  /// <param name="assignment">票据的分配数据</param>
  public void ConnectPlayer(Assignment assignment)
  {
    string[] networkComponents = assignment.connection.Split(':');
    NetworkManager.singleton.networkAddress = networkComponents[0];

    if (ushort.TryParse(networkComponents[1], out ushort port))
    {
        transport.port = port;
    }
    else
    {
        throw new Exception("port couldn't be parsed");
    }

    NetworkManager.singleton.StartClient();
  }

  /// <summary>
  /// 将玩家从比赛中断开连接
  /// </summary>
  public void DisconnectPlayer()
  {
    NetworkManager.singleton.StopClient();
  }
}

类

public class CreateTicketPayload
{
    public string mode { get; set; }
}

public class Ticket
{
    public string id { get; set; }
    public Assignment assignment { get; set; }
    public SearchFields search_fields { get; set; }
    public Dictionary<string, Extension> extensions { get; set; }
    public Dictionary<string, Extension> persistent_field { get; set; }
    public string create_time { get; set; }
}

public class SearchFields
{
    public string[] tags { get; set; }
}

public class Extension
{
    public string @type { get; set; }
    public byte[] value { get; set; }
}

public class Assignment
{
    public string connection { get; set; }
    public Dictionary<string, Extension> extensions { get; set; }
}

无论您选择如何管理 HUD，请确保在 MatchmakerManager 实例在您的 Start() 函数中创建，以确保代码正常工作。

玩家创建票据后，您需要定期检查其状态，以便在两个票据被匹配时尽快获取 分配 信息，因为票据在该值设置后几分钟内会被删除。一旦您有了 分配，您就可以将玩家连接到比赛。

构建游戏服务器与容器化

完成上一步对项目的修改后，您需要构建游戏服务器并将其容器化。首先，确保 NetworkManager gameObject 具有以下设置：

• 启用 Auto Start Server Build 在 NetworkManager 组件；

• 将 端口 的值，将 KcpTransport 将组件的值设置为您在 Matchmaker 的 Director 组件中使用的相同值 GameServerPort

在本示例中，我们为两个值都使用了 `7777`。

完成后，转到 Build Unity 编辑器的界面，在 File -> Build Settings 顶端菜单中。请确保根据你的 Unity 版本选择正确的预设。

• 2021.2 之前的版本：

  • 设置 目标平台 转向 Linux;

  • 设置 架构 转向 x86_64;

  • 勾选 Server Build 选项时，动态注入环境变量。

• 否则：

  • 设置 平台 转向 Dedicated Server;

  • 设置 目标平台 转向 Linux.

然后点击构建，并选择一个名为 linux_server 作为文件目标位置。将本文档中的 linux_server 文件夹转移到第二个空文件夹中，在本文档中将其称为 [SERVER BUILD] 文件夹传输过去。向 Dockerfile 与 boot.sh 文件夹添加以下 [SERVER BUILD] 文件：

Dockerfile

FROM ubuntu:bionic
MAINTAINER edgegap

ARG debian_frontend=noninteractive
ARG docker_version=17.06.0-ce

RUN apt-get update && \
apt-get install -y libglu1 xvfb libxcursor1

# 更新根 CA 以确保出站 HTTPS 请求不会失败
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    update-ca-certificates && \
    apt-get clean

EXPOSE 3389/TCP
EXPOSE [GAME PORT]/TCP
EXPOSE [GAME PORT]/UDP

COPY linux_server/ /root/linux_server/
COPY boot.sh /boot.sh

WORKDIR /root/
ENTRYPOINT ["/bin/bash", "/boot.sh"]

请确保将 [GAME PORT] 将占位符替换为与之前相同的 端口 值。

boot.sh

xvfb-run --auto-servernum --server-args='-screen 0 640X480X24:32' /root/build/[YOUR GAME].x86_64 -batchmode -nographics

请确保将 [YOUR GAME] 将占位符替换为生成文件的名称。

然后，在 [SERVER BUILD] 文件夹；运行以下 Docker 命令以创建构建的镜像并将其推送到私有注册表。参见 此文档 如果您想使用 Edgegap 的私有注册表。

在 Linux 上使用

# 构建镜像
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# 登录，随后会提示输入密码
docker login -u '<REGISTRY_USERNAME>' <REGISTRY_URL>

# 为镜像添加另一个与仓库对应的标签
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# 推送镜像
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

使用 cmd

# 构建镜像
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# 登录，随后会提示输入密码
docker login -u <REGISTRY_USERNAME> <REGISTRY_URL>

# 为镜像添加另一个与仓库对应的标签
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# 推送镜像
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

使用 Powershell

# 构建镜像
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# 登录，随后会提示输入密码
docker login -u '<REGISTRY_USERNAME>' <REGISTRY_URL>

# 为镜像添加另一个与仓库对应的标签
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# 推送镜像
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

部署到 Edgegap

在 Edgegap 仪表板上使用以下设置创建一个新应用：

• 应用名称：确保它与您在 Matchmaker 的 AppName Director 组件中使用的名称相同。必须为小写字母。

• 镜像：可以是任何您想用来在众多应用中轻松识别该应用的图片。

• 版本名称：确保它与您在 Matchmaker 的 AppVersion Director 组件中使用的版本相同。示例可以是“demo”、“production”、“v1”、“v2”

• Container：

  • Registry：“[URL]”，其中 [URL] 是你可以在容器仓库页面显示的凭据中的值。

  • Image repository：“[PROJECT]/[YOUR GAME]”，其中 [PROJECT] 和 [YOUR GAME] 是你之前推送 docker 镜像时使用的值。

  • Tag：“[TAG]”，其中 [TAG] 是你之前推送 docker 镜像时使用的值。

  • 勾选“Using a private repository”

  • Private registry username：“[USERNAME]”，其中 [USERNAME] 是你凭据中的值。

  • Private registry token：“[TOKEN]”，其中 [TOKEN] 是你凭据中的值。

  • Requirements：保持默认。

  • Ports：

    • 点击 + Add port 链接以添加新端口，并添加以下条目：

      • [GAME PORT] - TCP/UDP - 禁用验证

      • 3389 - TCP - 关闭 Verifications

我们建议在您的应用中设置一个 游戏最长时长 ，以便部署在几分钟后自我终止，因为 Matchmaker 在匹配票据时会自动创建新的部署。

这样可以确保不会长时间运行任何空闲部署。

使用客户端构建进行测试

为了查看 Matchmaker 是否按预期工作，您需要在两个独立的客户端实例上启动游戏，并让您的 Matchmaker 发布也在运行。

在创建游戏的客户端构建之前，请确保取消选中 Auto Start Server Build gameObject 的 NetworkManager 选项。然后，根据您正在测试的 Matchmaker 发布类型，将 MATCHMAKER_URL 更改为以下值：

• 本地 ：将其更改为 "http://localhost:51504"

• 使用 Edgegap ：更改为在启用发布后 Edgegap 仪表板上显示的值。在这种情况下，您不需要指定端口。

然后，回到顶部菜单中的 Build Unity 编辑器的界面，在 File -> Build Settings 。选择 Windows、Mac、Linux 平台以及适合您环境的正确 目标平台 。然后按构建并选择一个名为 client_build 的新空文件夹作为文件目标。

一旦您启动两个客户端（可以是两个客户端构建窗口，或一个构建窗口和 Unity 编辑器），让它们都选择相同的 与以下相关的变化： 并创建它们的票据。过了一会儿，两个客户端都会连接到新部署的服务器，您可以在 Edgegap 仪表板上查看其状态。

如果您正在测试 Matchmaker 的在线发布，目前存在一个证书相关问题：如果您每周多次启用和禁用 Matchmaker 发布，可能会导致对 Matchmaker 的请求在 Unity 中无法工作。

为了解决此问题，只需禁用发布，用不同的名称更新它，然后重新发布。之后请确保检查代码中的 URL 是否正确。