Подбор игроков

Этот SDK — необязательный стартовый набор для пользователей Unity, который можно будет расширять и настраивать позже.

💡 Функции

• Полные примеры

• Автоматизация пинга

• Тикеты, группы, команды

• Переменные матча

• Определения типов (C#)

• Локальное тестирование разработки

• Кроссплатформенность

• Легко настраивать

• Автоматический повтор

✔️ Подготовка

Unity SDK содержит дополнительные утилиты интеграции для развертываний, подбора игроков и браузера серверов. Этот плагин официально поддерживает версии Unity 2021.3.0f1 и новее.

Последняя версия Unity SDK — 3.5.3. Все примеры в этой документации актуальны.

Этот плагин предоставляется на 100% бесплатно в соответствии с условиями и положениями Free Tier.

Требования

Установите Git-клиент (например git-scm)

Git-клиент нужен, чтобы Unity могла автоматически скачать и установить наш пакет Unity. После установки вам не нужно будет использовать git напрямую.

Установка

1. Откройте свой проект Unity,

2. Выберите Окно > Управление пакетами > Менеджер пакетов ,

3. Нажмите на ➕ значок и выберите Добавить пакет из git-URL... ,

4. Когда появится запрос, введите URL нашего SDK:

https://github.com/edgegap/edgegap-unity-sdk.git

1. Нажмите Добавить и дождитесь завершения установки.

Импортировать примеры

Этот пакет включает несколько примеров, предназначенных для использования по отдельности (не объединяйте примеры).

Проверенные источники

Это единственный официальный канал распространения этого SDK, не доверяйте непроверенным источникам!

Обновить пакет

Перейдите к Edgegap SDK в Unity Package Manager и нажмите Обновить .

Импортированные примеры не обновляются автоматически! Сделайте резервную копию всех пользовательских значений свойств, удалите скрипты примеров, которые сейчас используются в вашей сцене, и импортируйте примеры заново.

Некоторые релизы могут содержать несовместимые изменения. Это будет обозначено новой MAJOR-версией.

Обновление до v3

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

Обновление Unity SDK до v3 включает несколько несовместимых изменений. Пожалуйста, внимательно повторно протестируйте свою интеграцию.

🍀 Начало работы

Это руководство предполагает базовые знания Подбор игроков концепций и работающий Matchmaker.

Мы настоятельно рекомендуем импортировать наш простой пример чтобы следовать коду по мере чтения этого документа. Вы можете сделать это в Unity Package Manager > Edgegap SDK > Samples .

Обзор

Наш SDK активно использует внедрение зависимостей и Наблюдатель шаблоны программирования.

Этот пакет объединяет оба Браузер серверов и Подбор игроковкоторые можно использовать вместе или по отдельности. Вы можете свободно повторно использовать любые сценарии для своих собственных модифицированных форков и интеграций.

Этот пакет включает:

• Файлы времени выполнения — будут скомпилированы и включены в сборки клиента и сервера:

  • Утилиты, специфичные для сервиса:

    • Подбор игроков - полная интеграция клиента для повторного использования/расширения.

    • Функции API — определения конечных точек, обработка ошибок и автоматизация логирования.

  • Специфичные для сервиса DTO - типизированные контейнеры данных для API матчмейкинга.

  • Общие утилиты — логирование, HTTP, пинг, наблюдаемые объекты и т. д...

  • Общие DTO - используются несколькими сервисами Edgegap для передачи данных.

• Файлы примеров — включаются и компилируются ТОЛЬКО если импортированы в ваш проект:

  • Подбор игроков - примеры обработчиков для минимальной конфигурации.

  • Подбор игроков - изучите интеграцию UI с ручным выбором региона.

Клиент группы

Автоматизация пинга, управление тикетами и получение хоста выполняются Group Client.

После создания, агента родительский Monobehaviour (обработчик) должен инициализировать клиент и предоставить:

• onMonitorUpdate обратный вызов — отслеживать изменения состояния сервиса.

• onAssignmentUpdate обратный вызов — отслеживать и реагировать на изменения назначения хоста.

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

Обработчик клиента, как ожидается, возьмёт управление и вызовет функции клиента с этого момента:

• Маяки для получения списка доступных Пинг-маяки.

• MeasureBeaconsRoundTripTime для выполнения измерений пинга относительно заданного набора маяков.

• CreateGroup для лидера лобби, чтобы создать группу с возможностью присоединения, в которую можно пригласить друзей.

• JoinGroup чтобы присоединиться к существующей группе, используя ID группы, отправленный через сторонний лобби/бэкенд.

• SetReady чтобы пометить владельца группы и участников как готовых и начать поиск матчей.

• ResumeMatchmaking загрузить кэшированную группу и продолжить поиск в случае сбоя клиента.

• StopMatchmaking чтобы удалить тикет (если матч не найден) и покинуть очередь.

• Статус для проверки состояния сервиса Matchmaker.

Когда устанавливается новое подключение игрока, ожидается, что игрок отправит свой ID тикета на игровой сервер с помощью вашего netcode, чтобы сопоставить подключения с Подробный обзор.

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

Серверный агент

Серверный агент выполняет создание backfill, обнаружение назначения тикетов, обнаружение отказа от backfill и его удаления. Он также отслеживает и воссоздаёт backfill'ы, срок действия которых истёк, у которых истёк период ожидания подключения или которые были брошены — чтобы достичь желаемого размера команды.

Серверный агент отслеживает текущих подключённых игроков и автоматически включает их тикеты в новые backfill'ы, чтобы гарантировать, что игроки, добавленные через backfill, будут подбираться по правилам настроенного профиля.

После создания, агента родительский Monobehaviour (обработчик) должен инициализировать клиент и предоставить:

• onMonitorUpdate обратный вызов — отслеживать изменения состояния сервиса.

• onBackfillUpdate обратный вызов — отслеживать изменения backfill и реагировать на них.

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

Ожидается, что обработчик сервера возьмёт управление и вызовет функции клиента с этого момента:

• PlayerConnected чтобы не заменять первоначальных или добавленных через backfill игроков, которые так и не подключились.

• AbandonPlayer чтобы сообщить, что подключённый игрок покинул сервер и его нужно заменить.

• AbandonAllBackfills чтобы немедленно остановить заполнение сервера и удалить backfill'ы.

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

  • Назначенные на момент этого вызова backfill'ы всё ещё могут подключиться в пределах заданного периода ожидания.

• AbandonBackfill чтобы принудительно отменить конкретный backfill (для пользовательских реализаций обработчика).

• Статус для проверки состояния сервиса матчмейкера.

🧪 Примеры

Начните с примеров, включая полную рабочую интеграцию как для сервера, так и для клиента.

Простой пример

Включает полную реализацию жизненного цикла игрока с измерением пинга, управлением тикетами и получением назначения хоста. Демонстрирует, как читать внедрённые переменные матча на стороне сервера.

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

Выбор региона

У некоторых игроков (или групп) есть особые локальные условия (например, ISP блокировка, общенациональная блокировка, или другие) и они могут предпочесть выбирать регион вручную, а не только на основе пинга.

Изучите наш пример выбора региона и вдохновитесь им для реализации UI вашего матчмейкинга.

Собраться в группу

Присоединяйтесь к очереди матчмейкинга группой друзей, требуя подтверждения от всех игроков перед началом поиска. Начните с минимальной реализации UI, затем адаптируйте её под дизайн вашей игры.

Изучите интеграцию UI с потоком сбора в группу и обеспечьте наилучший социальный опыт.

Дозаполнение

Повторно используйте серверные ресурсы и добавляйте игроков в уже запущенные развертывания. Задайте целевой размер команды и дождитесь добавления игроков. Включает автоматический период ожидания подключения и воссоздание истёкших backfill'ов.

Настройте пример серверного обработчика для многокомандных или асимметричных составов команд.

⚙️ Настройка

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

✅ Обработчик — безопасно подключайте наблюдателей UI и вносите небольшие дополнения или изменения,

⚠️ Агент — изменяйте управление жизненным циклом игрока на свой страх и риск,

⚠️ API — пишите собственную интеграцию с нуля, используя выбранные утилиты.

Обработчики могут наблюдать любые события, создаваемые агентами Server и Client, как описано ниже.

Убедитесь, что вы хорошо знакомы с Матчмейкинг в деталях концепциями перед внесением изменений.

Если вам нужна помощь, свяжитесь с нами через Discord. Для поддержки по играм в реальном времени см. нашу систему тикетов.

События клиента

Клиент группы генерирует события (действия), которые родительский обработчик должен наблюдать и обрабатывать.

Читать полезные данные событий, обращаясь к .Current состоянию любого наблюдаемого объекта. 🔴 Ошибка события содержат полное сообщение об ошибке, отделённое символом новой строки после основного сообщения события.

Предпросмотр событий, генерируемых наблюдаемым Монитор :

Тип действия	Сообщение события	Описание
🟢 Обновление	в порядке	Все системы в норме.
🟢 Обновление	неисправно	Неожиданная проблема.
🔴 Ошибка	не удалось получить монитор	Неверная конфигурация или неожиданная проблема.
🔴 Ошибка	не удалось получить маяки	Неожиданная проблема.

Предпросмотр событий, генерируемых наблюдаемым Группа:

Тип действия	Сообщение события	Описание
🟢 Обновление	создана	Группа создана успешно.
🔴 Ошибка	не удалось создать группу	Не удалось создать группу.
🟢 Обновление	присоединился	Группа успешно присоединена.
🔴 Ошибка	не удалось присоединиться к группе	Не удалось присоединиться к группе.
🟢 Обновление	возобновлено	Группа успешно возобновлена.
🔴 Ошибка	группа не найдена	Не является участником группы или срок её действия истёк.
🔴 Ошибка	конфликт, отмените и перезапустите	Пожалуйста, отмените текущую группу, прежде чем пытаться создать/присоединиться к новой группе.
🟢 Обновление	участник обновлён [{ready}]	Участник обновлён с новым значением Ready.
🔴 Ошибка	не удалось обновить участника	Не удалось обновить участника группы. Нельзя снять готовность после того, как группа начала поиск матча.
🔵 Уведомление	опрос [{consecutive}/{maximum}]	Клиент инициировал опрос статуса группы.
🔵 Уведомление	опрос остановлен	Клиент прекратил опрос статуса тикета.
🔴 Ошибка	не удалось опросить, достигнут максимум повторных попыток	Клиент исчерпал максимум последовательных повторных попыток опроса. Проверьте состояние сервиса.
🔴 Ошибка	не удалось опросить	Клиент получил не подлежащую повтору ошибку при опросе. Проверьте состояние сервиса.
🟢 Обновление	группа обновлена [{status}]	Обнаружено изменение статуса группы во время опроса.
🟢 Обновление	отменено	Тикет удалён успешно.
🟢 Обновление	не удалось отменить (не найден)	Клиент не смог найти тикет для удаления, возможно, он истёк.
🟡 Предупреждение	не удалось отменить (уже найден матч)	Клиент не смог удалить группу с найденным матчем. Отключите отказ или Подробный обзор чтобы заменить игрока.
🔴 Ошибка	не удалось отменить	Не удалось удалить группу или участника.
🟢 Обновление	удалено	Срок действия группы истёк, локальная ссылка удалена.

События сервера

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

Текущие назначенные тикеты можно прочитать из свойства Server Agent Назначения в любое время.

Читать полезные данные событий, обращаясь к .Current состоянию любого наблюдаемого объекта. 🔴 Ошибка события содержат полное сообщение об ошибке, отделённое символом новой строки после основного сообщения события.

Предпросмотр событий, генерируемых наблюдаемым Монитор :

Тип действия	Сообщение события	Описание
🟢 Обновление	в порядке	Все системы в норме.
🟢 Обновление	неисправно	Неожиданная проблема.
🔴 Ошибка	не удалось получить монитор	Неверная конфигурация или неожиданная проблема.

Предпросмотр событий, генерируемых наблюдаемым Дозаполнение:

Тип действия	Сообщение события	Описание
🟢 Обновление	создан [{backfill}]	Backfill создан успешно.
🔴 Ошибка	не удалось создать	Неожиданная проблема с backfill. Проверьте состояние сервиса.
🔵 Уведомление	опрос [{consecutive}/{maximum}]	Опрос не удался, выполняется автоматическая повторная попытка.
🟢 Обновление	назначен [{backfill}]	Тикет успешно назначен backfill.
🔵 Уведомление	опрос остановлен	Опрос остановлен по запросу обработчика.
🔵 Уведомление	не удалось опросить (не найден) [{backfill}]	Не найдено, ссылка удаляется. Вероятнее всего, срок действия backfill истёк.
🔴 Ошибка	не удалось опросить (достигнут максимум повторных попыток) [{backfill}]	Попытки исчерпаны, backfill отменяется.
🔴 Ошибка	не удалось опросить [{backfill}]	Неожиданная проблема, ссылка удаляется.
🔵 Уведомление	отменён [{backfill}]	Backfill отменён, ссылка удаляется.
🟡 Предупреждение	не удалось отменить [{backfill}]	Отмена не удалась, ссылка удаляется.
🟢 Обновление	удалён [{backfill}]	Ссылка на backfill удалена. Backfill будет автоматически заменён, если его не остановить.
🟡 Предупреждение	не удалось удалить [{backfill}]	Ссылка на backfill не найдена, вероятно, повторный вызов.