Матчмейкер Unity

Это руководство поможет вам создать проект Unity с использованием системы Advanced Matchmaker от Edgegap для автоматизации развертываний и соединений между игроками.

В этом руководстве будет использован открытый пример проекта Tanks, доступно в Mirror примере в разделе Assets/Mirror/Examples/Tanks. Окончательный пример можно найти на нашей GitHub.

Настройка Matchmaker

Создайте компоненты

Для начала вам нужно создать 3 компонента Matchmaker. Для этого проекта вы можете следовать нашему базовому руководству по компонентам здесь.

Имейте в виду, что компоненты и конфигурация YAML, созданные по этому руководству, не предназначены для использования в продакшене.

Релиз

Локально

Если вы хотите протестировать Matchmaker в локальной среде, просто примените настройки Kubernetes, как упоминалось в конце базового руководства по компонентам. Затем вы можете перейти к разделу настройка проекта.

С Edgegap

Если вы хотите протестировать Matchmaker в онлайн-среде с Edgegap, вам нужно немного изменить ваши компоненты из предыдущего руководства. Вы будете использовать внедрённые переменные, которые добавляются во время релиза, вместо некоторых жёстко заданных значений. Изменения должны быть следующими:

Director

...
using System;

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, затем создайте и выпустите ваш Matchmaker на панели управления Edgegap.

Настройка проекта

Далее мы хотим изменить базовый проект Tank так, чтобы для соединения игроков использовался Matchmaker. В рамках этого примера мы хотим, чтобы наши игроки выбирали режим матча, в который они хотят играть, до создания тикета Matchmaker, чтобы Matchmaker автоматически соединял 2 игроков, выбравших один и тот же режим.

С базовыми компонентами Matchmaker, созданными по предыдущему руководству, доступные режимы: mode.casual, mode.ranked, и mode.private.

В проекте откройте сцену, расположенную в Assets/Mirror/Examples/Tanks/Scenes. Отключите Network Manager HUD Relay GUI NetworkManager объект gameObject, затем создайте свой собственный HUD, чтобы позволить игрокам вводить игровой режим, создавать и удалять тикет, когда они не находятся в матче, и выходить из текущего матча, когда находятся в нём.

Оффлайн HUD

Онлайн HUD

Затем вам нужно создать новые скрипты в вашем проекте для управления тем, какие запросы отправляются в Matchmaker в зависимости от того, какую кнопку нажимает игрок. Ваш код для управления самими запросами должен иметь похожую структуру:

Функции

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($"Код ошибки: {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($"Код ошибки: {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($"Код ошибки: {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("не удалось распарсить порт");
    }

    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() чтобы убедиться, что код работает корректно.

После того как игрок создал тикет, вам нужно периодически проверять его статус, чтобы получить назначение как только 2 тикета будут сопоставлены, потому что тикет будет удалён через несколько минут после того, как это значение будет установлено. Получив назначениевы можете подключить игрока к матчу.

Сборка игрового сервера и контейнеризация

После того как вы завершите добавление изменений из предыдущего шага в проект, вам нужно собрать игровой сервер и контейнеризировать его. Сначала убедитесь, что у NetworkManager объекта gameObject следующие настройки:

• Включить Auto Start Server Build в NetworkManager компонент;

• Установите port в KcpTransport компонент на то же значение, которое вы использовали для GameServerPort в компоненте Director.

В этом примере мы использовали `7777` для обоих значений.

После этого перейдите к Экран сборки в Unity Editor, в меню Файл -> Параметры сборки в верхних меню. Убедитесь, что выбрали правильные пресеты в зависимости от вашей версии Unity.

• До версии 2021.2:

  • Установите Целевую платформу к Linux;

  • Установите Архитектуру к x86_64;

  • Отметьте Server Build опции.

• В противном случае:

  • Установите Платформа к Выделенный сервер;

  • Установите Целевую платформу к 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] заполнители тем же 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 со следующими настройками:

• Имя приложения: Убедитесь, что это то же имя, которое вы использовали для AppName в компоненте Director вашего Matchmaker. Должно быть в нижнем регистре.

• Изображение: Может быть любая конкретная картинка, которую вы хотите использовать, чтобы легко распознавать ваше приложение среди других.

• Имя версии: Убедитесь, что это та же версия, которую вы использовали для AppVersion в компоненте Director вашего Matchmaker. Примеры: «demo», «production», «v1», «v2»

• Контейнер:

  • Реестр: «[URL]», где [URL] — значение из учётных данных, которые можно отобразить на странице репозитория контейнеров.

  • Репозиторий образа: «[PROJECT]/[YOUR GAME]», где [PROJECT] и [YOUR GAME] — значения, которые вы использовали ранее при отправке образа Docker.

  • Тег: «[TAG]», где [TAG] — значение, которое вы использовали ранее при отправке образа Docker.

  • Отметьте «Используется приватный репозиторий»

  • Имя пользователя приватного реестра: «[USERNAME]», где [USERNAME] — значение из ваших учётных данных.

  • Токен приватного реестра: «[TOKEN]», где [TOKEN] — значение из ваших учётных данных.

  • Требования: Оставьте как есть.

  • Порты:

    • Нажмите на ссылку + Добавить порт чтобы добавить новый порт, и добавьте следующие записи:

      • [GAME PORT] - TCP/UDP - отключите Verifications

      • 3389 - TCP - отключить проверки

Мы также рекомендуем установить Максимальная длительность игры в вашем приложении, чтобы ваши развертывания автоматически завершались через несколько минут, поскольку Matchmaker будет автоматически создавать новые при сопоставлении тикетов.

Это необходимо, чтобы убедиться, что у вас не запущены пустые развертывания слишком долго.

Тестирование с клиентскими сборками

Чтобы убедиться, что Matchmaker работает как задумано, вам нужно запустить игру на 2 отдельных клиентских экземплярах и также запустить релиз вашего Matchmaker.

Перед созданием клиентской сборки игры убедитесь, что сняли галочку с опции Auto Start Server Build у объекта NetworkManager gameObject. Затем, в зависимости от того, какой релиз Matchmaker вы тестируете, измените MATCHMAKER_URL на следующее:

• Локально : измените на «http://localhost:51504"

• С Edgegap : измените на значение, показанное на панели Edgegap после включения релиза. В этом случае вам не нужно указывать порт.

Затем вернитесь в Экран сборки в Unity Editor, в меню Файл -> Параметры сборки в верхних меню. Выберите платформу Windows, Mac, Linux и правильную целевую платформу для вашей среды. Затем нажмите «Build» и выберите новую пустую папку под названием client_build в качестве места назначения файла.

После запуска обоих клиентов (либо два окна вашей клиентской сборки, либо одно окно сборки и редактор Unity) пусть оба выберут один и тот же режимом игры и создадут свои тикеты. Спустя короткое время оба клиента будут подключены к недавно развернутому серверу, статус которого вы можете увидеть на панели Edgegap.

Если вы тестируете с онлайн-релизом вашего Matchmaker, в настоящее время есть проблема с сертификатами, если вы включаете и отключаете релиз Matchmaker несколько раз в неделю; это приведёт к тому, что запросы к вашему Matchmaker не будут работать с Unity.

Чтобы исправить это, просто отключите ваш релиз, обновите его с другим именем, затем выпустите его снова. После этого обязательно проверьте, что URL в вашем коде правильный.