Server Browser

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

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

    • Client Agent - полную клиентскую интеграцию для повторного использования/расширения.

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

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

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

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

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

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

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

  • Server Browser - примеры обработчиков с ручным выбором инстанса.

Server Agent

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

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

• 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

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

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

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

• onInstancesUpdate callback — отслеживание и обработка изменений списка инстансов.

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

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

• ReserveSeats чтобы создать резервирование вместимости для конкретного инстанса/слота или автоматического назначения,

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

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

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

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

• Status чтобы проверить состояние сервиса Server Browser.

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

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

🧪 Примеры

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

Автоматическое назначение

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

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

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

⚙️ Настройка

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

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

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

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

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

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

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

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

Предварительный просмотр событий, генерируемых наблюдаемым объектом Monitor :

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

Предварительный просмотр событий (действий), генерируемых наблюдаемым объектом Инстанс:

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

Предварительный просмотр событий (действий), генерируемых наблюдаемым объектом Подтверждения:

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

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

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

Предварительный просмотр событий, генерируемых наблюдаемым объектом Monitor :

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

Предварительный просмотр событий, генерируемых наблюдаемым объектом Инстансы:

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