Браузер серверов

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

💡 Возможности

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

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

• Управление жизненным циклом

• Управление вместимостью

• Компилятор фильтрующих запросов

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

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

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

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

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

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

Unity SDK содержит дополнительные утилиты интеграции для Deployments, Matchmaking и Server Browser. Этот плагин официально поддерживает версии Unity 2021.3.0f1 и новее.

Этот плагин предоставляется абсолютно бесплатно, в соответствии с Условиями и положениями Free Tier.

Требования

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

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

Установка

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

2. Выберите Window > Package Management > Package Manager ,

3. Нажмите на ➕ значок и выберите Add package from 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 включает несколько несовместимых изменений. Пожалуйста, тщательно повторно протестируйте вашу интеграцию.

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

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

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

Обзор

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

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

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

• Файлы runtime — будут скомпилированы и объединены с вашими клиентскими и серверными сборками:

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

    • Server Agent - полная серверная интеграция для повторного использования/расширения,

    • Браузер серверов - полная клиентская интеграция для повторного использования/расширения,

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

    • Компилятор фильтров — строго типизированные утилиты для построения фильтрующих запросов.

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

  • Общие утилиты — логирование, HTTP, ping, observables и т. д...

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

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

  • Браузер серверов - примеры обработчиков с автоматически назначаемыми резервациями,

  • Браузер серверов - примеры обработчиков с ручным выбором экземпляра.

Server Agent

Управление жизненным циклом и вместимостью сервера выполняется Server Agent.

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

• onMonitorUpdate callback — отслеживать изменения состояния сервиса,

• onInstanceUpdate callback — отслеживать изменения экземпляра и слотов и реагировать на них,

• onConfirmationsUpdate callback — отслеживать и обрабатывать федеративную аутентификацию.

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

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

• DiscoverInstance для создания первоначального Server Instance и слотов и запуска heartbeat,

• DeleteInstance когда матч завершится / чтобы предотвратить присоединение новых игроков,

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

• UpdateSlot для обновления вместимости слота (при присоединении/уходе игрока) или изменения метаданных,

• UpdateInstance для изменения метаданных экземпляра,

• Status для проверки состояния службы Server Browser.

Подтверждения и обновления слотов/экземпляров по умолчанию ставятся в очередь и выполняются пакетами (режим Heartbeat), чтобы максимизировать масштабируемость. Чтобы быстрее проходить итерации во время тестирования разработки, используйте режим Greedy.

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

Агент автоматически поддерживает heartbeat, чтобы сервер оставался доступным для обнаружения во время работы. Если агент не может связаться с вашим Server Browser в течение нескольких последовательных heartbeat (настраивается):

• меньше максимума — экземпляр будет автоматически обнаружен повторно,

• больше максимума — экземпляр будет автоматически удалён.

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

Как только onConfirmationsUpdate срабатывает, обработчик должен выполнить дополнительные действия:

• вызвать UpdateSlot чтобы уменьшить число доступных мест для любых слотов с подтверждёнными резервациями,

• принять или отклонить подключение с помощью методов, специфичных для netcode.

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

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

Клиентский агент

Поиск экземпляров, пагинация, фильтрация и резервации выполняются Client Agent.

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

• onMonitorUpdate callback — отслеживать изменения состояния сервиса,

• onInstancesUpdate callback — отслеживать изменения списка экземпляров и реагировать на них.

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

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

• ReserveSeats для создания резервации вместимости для конкретного экземпляра/слота или автоназначения,

• ListInstances для получения списка экземпляров с заданным фильтром, порядком, курсором и размером страницы,

• GetNextPage для получения дополнительных экземпляров с текущими параметрами (фильтры и т. д.),

• RefreshList для очистки кэша и загрузки первой страницы или обновления с определённым курсором,

• GetInstanceDetails для получения метаданных экземпляра и информации о слотах для конкретного экземпляра,

• Status для проверки состояния службы Server Browser.

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

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

🧪 Примеры

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

Автоназначение

Использует резервации с автоназначением, при этом клиент указывает только имя политики. Server Browser автоматически выбирает экземпляр, соответствующий фильтру политики, и слот с достаточным числом мест.

Пользовательский поиск

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

⚙️ Настройка

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

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

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

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

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

Обязательно ознакомьтесь с Подробно о Server Browser концепциями перед внесением изменений.

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

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

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

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

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

Тип действия	Сообщение события	Описание
🟢 Обновление	здорово	Все системы в норме.
🟢 Обновление	нездорово	Неожиданная проблема.
🔴 Ошибка	не удалось получить монитор	Неверная конфигурация или неожиданная проблема.
🟡 Предупреждение	тайм-аут запроса ограничен heartbeat [{timeout}]	Предотвращает состояния гонки.

Предпросмотр событий (действий), генерируемых observable Экземпляр:

Тип действия	Сообщение события	Описание
🟢 Обновление	обнаружен	Обнаружение экземпляра успешно завершено. Может быть вызвано, если экземпляр потерял соединение из-за временной проблемы и был обнаружен повторно.
🔴 Ошибка	дублирование обнаружения	Экземпляр с этим Request ID уже обнаружен.
🔴 Ошибка	обнаружение не удалось	Неожиданная проблема при обнаружении.
🔵 Уведомление	heartbeat ok	Heartbeat успешно завершён.
🟡 Предупреждение	heartbeat failed [{consecutive}/{maximum}]	Heartbeat не удался, сервер не смог связаться с Server Browser.
🔵 Уведомление	обновление экземпляра поставлено в очередь	Обновление экземпляра поставлено в очередь для следующего пакета (heartbeat/greedy).
🟢 Обновление	экземпляр обновлён	Метаданные экземпляра успешно обновлены.
🔴 Ошибка	не удалось обновить экземпляр, постановка в очередь на повтор	Не удалось обновить экземпляр, возможно, из-за ограничения частоты запросов или ошибки.
🟢 Обновление	экземпляр удалён	Экземпляр больше не доступен для обнаружения игроками.
🟢 Обновление	не удалось удалить экземпляр (не найден)	Срок действия экземпляра мог истечь из-за слишком большого числа пропущенных heartbeat.
🔴 Ошибка	не удалось удалить экземпляр	Не удалось удалить экземпляр, возможно, из-за ограничения частоты запросов или ошибки.
🔵 Уведомление	обновление слота поставлено в очередь [{slot}]	Обновление слота поставлено в очередь для следующего пакета (heartbeat/greedy).
🟢 Обновление	слот обновлён [{slot}]	Вместимость мест слота и/или метаданные успешно обновлены.
🟡 Предупреждение	агент ограничил параллельное обновление слота	Предотвращена попытка параллельного обновления (состояние гонки).
🔴 Ошибка	не удалось обновить слот (не найден) [{slot}]	Слот с таким именем ещё не определён для этого экземпляра.
🔴 Ошибка	не удалось обновить слот (недостаточно мест) [{slot}]	При обновлении слота была попытка уменьшить доступные места ниже нуля.
🔴 Ошибка	не удалось обновить слот, постановка в очередь на повтор [{slot}]	Не удалось обновить слот, возможно, из-за ограничения частоты запросов или ошибки.

Предпросмотр событий (действий), генерируемых observable Подтверждения:

Тип действия	Сообщение события	Описание
🔵 Уведомление	поставлено в очередь [{player}]	Подтверждение поставлено в очередь для следующего пакета (heartbeat/greedy).
🟡 Предупреждение	дубликат [{player}]	Предотвращена попытка дублирующего подтверждения (уже в очереди).
🟢 Обновление	подтверждено	Подтверждённые резервации для отдельных слотов; также включает просроченные и неизвестные ID игроков, которые обработчик должен разрешить (принять/кикнуть).
🔴 Ошибка	не удалось	Неожиданная проблема с подтверждениями. Проверьте состояние сервиса.

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

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

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

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

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

Предпросмотр событий, генерируемых observable Экземпляры:

Тип действия	Сообщение события	Описание
🔵 Уведомление	места зарезервированы	Резервация места выполнена успешно.
🔴 Ошибка	не удалось зарезервировать места (не найдено)	Браузер серверов - имя политики не найдено (удалено или неактивно). Браузер серверов - экземпляр или слот не найдены.
🔴 Ошибка	не удалось зарезервировать места (достигнута вместимость)	Браузер серверов - политика достигла максимальной вместимости. Браузер серверов - слот достиг максимальной вместимости.
🔴 Ошибка	не удалось зарезервировать места	Не удалось зарезервировать места, возможно, из-за неверной политики, Request ID или ID слота.
🟢 Обновление	список экземпляров получен	Список экземпляров получен успешно.
🟢 Обновление	следующая страница списка экземпляров получена	Следующая страница экземпляров получена успешно.
🔴 Ошибка	достигнута последняя страница списка экземпляров	Не удалось получить следующую страницу, попробуйте обновить или изменить фильтры.
🔴 Ошибка	не удалось получить следующую страницу списка экземпляров	Не удалось получить следующую страницу, возможно, из-за неверного курсора.
🟢 Обновление	сведения об экземпляре получены	Сведения об экземпляре из списка получены успешно.
🟢 Обновление	экземпляр не закэширован, добавление в начало	Получены сведения об экземпляре вне текущего списка.
🔴 Ошибка	не удалось получить сведения об экземпляре	Не удалось получить сведения, возможно, из-за неверного Request ID.