> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ru/unity/server-browser.md).

# Server Browser

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

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

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

{% columns %}
{% column %}

* Полные примеры
* Управление жизненным циклом
* Управление вместимостью
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Компилятор фильтровых запросов
* Определения типов (C#)
* Локальное тестирование разработки
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Кроссплатформенность
* Легко настраивать
* Автоматический повтор
  {% endcolumn %}
  {% endcolumns %}

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

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

Это руководство предполагает базовые знания [Server Browser](/ru/learn/server-browser.md) концепций и запущенный Server Browser.

{% hint style="success" %}
**Мы настоятельно рекомендуем импортировать наш пример Auto-Assign** чтобы следовать коду по мере чтения этого документа. Сделать это можно в `Unity Package Manager > Edgegap SDK > Samples` .
{% endhint %}

### Обзор

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

* Файлы времени выполнения — будут скомпилированы и включены в ваши клиентские и серверные сборки:
  * Утилиты, специфичные для сервиса:
    * [#server-agent](#server-agent "mention") - полную серверную интеграцию для повторного использования/расширения.
    * [#client-agent](#client-agent "mention") - полную клиентскую интеграцию для повторного использования/расширения.
    * Функции API — определения конечных точек, обработка ошибок и автоматизация логирования.
    * Компилятор фильтров — строго типизированные утилиты для построения фильтровых запросов.
  * Специфичные для сервиса DTO[^1] - типизированные контейнеры данных для Server Browser API.
  * Общие утилиты — логирование, HTTP, ping, наблюдаемые объекты и т. д...
  * Общие DTO[^1] - используются несколькими сервисами Edgegap для передачи данных.
* Файлы примеров — включаются и компилируются ТОЛЬКО если импортированы в ваш проект:
  * [#auto-assign](#auto-assign "mention") - примеры обработчиков с автоматически назначаемыми резервированиями,
  * [#custom-search](#custom-search "mention") - примеры обработчиков с ручным выбором инстанса.

### Server Agent

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

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

* `onMonitorUpdate`  callback — отслеживание изменений состояния сервиса,
* `onInstanceUpdate`  callback — отслеживание и обработка изменений инстанса и слотов,
* `onConfirmationsUpdate`  callback — отслеживание и обработка федеративной аутентификации.

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

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

* `DiscoverInstance`  чтобы создать начальный Server Instance и слоты и запустить heartbeat,
* `DeleteInstance`  когда матч завершится / чтобы предотвратить присоединение новых игроков,
* `ConfirmReservation`  когда игроки подключаются, чтобы проверить их личность и назначение слота,
* `UpdateSlot`  чтобы обновить вместимость слота (при присоединении/уходе игрока) или изменить метаданные,
* `UpdateInstance`  чтобы изменить метаданные инстанса,
* `Status`  чтобы проверить состояние сервиса Server Browser.

{% hint style="success" %}
Подтверждения и обновления слотов/инстансов **по умолчанию ставятся в очередь и выполняются пакетами** (режим Heartbeat) для максимальной масштабируемости. Чтобы быстрее итеративно тестировать разработку, используйте режим Greedy.
{% endhint %}

{% hint style="warning" %}
**При обновлении метаданных все индексы должны быть определены.** Чтобы сбросить неиндексированные ключи, просто не указывайте их.
{% endhint %}

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

* меньше максимума — инстанс будет автоматически обнаружен снова,
* больше максимума — инстанс будет автоматически удалён.

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

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

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

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

{% hint style="info" %}
Дайте игрокам короткий промежуток времени на повторное подключение перед уходом, на случай неожиданных сбоев.
{% endhint %}

### Client Agent

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

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

* `onMonitorUpdate`  callback — отслеживание изменений состояния сервиса,
* `onInstancesUpdate`  callback — отслеживание и обработка изменений списка инстансов.

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

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

* `ReserveSeats`  чтобы создать резервирование вместимости для конкретного инстанса/слота или автоматического назначения,
* `ListInstances`  чтобы вывести список инстансов с заданным фильтром, сортировкой, курсором и размером страницы,
* `GetNextPage`  чтобы получить больше инстансов с текущими параметрами (фильтры и т. д.),
* `RefreshList`  чтобы очистить кэш и загрузить первую страницу заново, либо обновить с заданным курсором,
* `GetInstanceDetails`  чтобы получить метаданные инстанса и информацию о слотах для конкретного инстанса,
* `Status`  чтобы проверить состояние сервиса Server Browser.

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

{% hint style="success" %}
Сохраните данные подключения в клиенте или игровом бэкенде, чтобы переподключиться в случае неожиданного сбоя.
{% endhint %}

## 🧪 Примеры

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

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

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

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

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

## ⚙️ Настройка

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

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

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

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

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

{% hint style="warning" %}
Обязательно ознакомьтесь с [Server Browser In-Depth](/ru/learn/server-browser.md) концепциями перед внесением изменений.
{% endhint %}

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

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

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

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="450">Сообщение события</th><th>Описание</th></tr></thead><tbody><tr><td>🟢 <code>Обновление</code> </td><td><code>исправен</code></td><td>Все системы в порядке.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>неисправен</code></td><td>Неожиданная проблема.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось получить монитор</code></td><td>Неверная настройка или неожиданная проблема.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>таймаут запроса ограничен heartbeat [{timeout}]</code></td><td>Предотвращает состязательные условия.</td></tr></tbody></table>

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

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="450">Сообщение события</th><th>Описание</th></tr></thead><tbody><tr><td>🟢 <code>Обновление</code> </td><td><code>обнаружен</code></td><td><a href="/pages/6c642f50ebd48e5f939d86627dadcc55f732cc5c#discover-instance">Обнаружение инстанса</a> успешно завершено. Может сработать, если инстанс потерял соединение из-за временной проблемы и был обнаружен повторно.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>дублирование обнаружения</code></td><td>Инстанс с этим ID запроса уже обнаружен.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось обнаружить</code></td><td>Неожиданная проблема при обнаружении.</td></tr><tr><td>🔵 <code>Уведомление</code></td><td><code>heartbeat в порядке</code></td><td>Heartbeat успешно завершён.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>heartbeat не удался [{consecutive}/{maximum}]</code></td><td>Heartbeat не удался, сервер не смог связаться с Server Browser.</td></tr><tr><td>🔵 <code>Уведомление</code></td><td><code>обновление инстанса поставлено в очередь</code></td><td>Обновление инстанса поставлено в очередь на следующий пакет (heartbeat/greedy).</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>инстанс обновлён</code></td><td>Метаданные инстанса успешно обновлены.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось обновить инстанс, постановка в очередь на повтор</code></td><td>Не удалось обновить инстанс, возможно из-за ограничения частоты запросов или ошибки.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>инстанс удалён</code></td><td>Инстанс больше не может быть обнаружен игроками.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>не удалось удалить инстанс (не найден)</code></td><td>Срок действия инстанса мог истечь из-за слишком большого числа пропущенных heartbeat'ов.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось удалить инстанс</code></td><td>Не удалось удалить инстанс, возможно из-за ограничения частоты запросов или ошибки.</td></tr><tr><td>🔵 <code>Уведомление</code></td><td><code>обновление слота поставлено в очередь [{slot}]</code></td><td>Обновление слота поставлено в очередь на следующий пакет (heartbeat/greedy).</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>слот обновлён [{slot}]</code></td><td>Вместимость мест слота и/или метаданные успешно обновлены.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>агент ограничил одновременное обновление слота</code></td><td>Предотвращена попытка одновременного обновления (состязательное условие).</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось обновить слот (не найден) [{slot}]</code></td><td>Слот с таким именем ещё не определён для этого инстанса.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось обновить слот (недостаточно мест) [{slot}]</code></td><td>При обновлении слота была предпринята попытка уменьшить число доступных мест ниже нуля.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось обновить слот, постановка в очередь на повтор [{slot}]</code></td><td>Не удалось обновить слот, возможно из-за ограничения частоты запросов или ошибки.</td></tr></tbody></table>

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

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="450">Сообщение события</th><th>Описание</th></tr></thead><tbody><tr><td>🔵 <code>Уведомление</code></td><td><code>поставлено в очередь [{player}]</code></td><td>Подтверждение поставлено в очередь на следующий пакет (heartbeat/greedy).</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>дубликат [{player}]</code></td><td>Предотвращена попытка дублирующего подтверждения (уже в очереди).</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>подтверждено</code></td><td>Подтверждены резервирования для отдельных слотов; также включают просроченные и неизвестные ID игроков, которые обработчик должен разрешить (принять/кикнуть).</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось</code></td><td>Неожиданная проблема с подтверждениями. Проверьте состояние сервиса.</td></tr></tbody></table>

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

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

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

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="450">Сообщение события</th><th>Описание</th></tr></thead><tbody><tr><td>🟢 <code>Обновление</code> </td><td><code>исправен</code></td><td>Все системы в порядке.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>неисправен</code></td><td>Неожиданная проблема.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось получить монитор</code></td><td>Неверная настройка или неожиданная проблема.</td></tr></tbody></table>

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

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="450">Сообщение события</th><th>Описание</th></tr></thead><tbody><tr><td>🔵 <code>Уведомление</code></td><td><code>места зарезервированы</code></td><td>Резервирование мест успешно.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось зарезервировать места (не найдено)</code></td><td><a data-mention href="#auto-assign">#auto-assign</a> - имя политики не найдено (удалено или неактивно).<br><a data-mention href="#custom-search">#custom-search</a> - инстанс или слот не найден.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось зарезервировать места (достигнута вместимость)</code></td><td><a data-mention href="#auto-assign">#auto-assign</a> - политика достигла максимальной вместимости.<br><a data-mention href="#custom-search">#custom-search</a> - слот достиг максимальной вместимости.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось зарезервировать места</code></td><td>Не удалось зарезервировать места, возможно из-за неверной политики, ID запроса или ID слота.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>список инстансов получен</code></td><td>Список инстансов успешно получен.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>получена следующая страница списка инстансов</code></td><td>Следующая страница инстансов успешно получена.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>достигнута последняя страница списка инстансов</code></td><td>Не удалось получить следующую страницу, попробуйте обновить или изменить фильтры.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось получить следующую страницу списка инстансов</code></td><td>Не удалось получить следующую страницу, возможно из-за неверного курсора.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>сведения об инстансе получены</code></td><td>Сведения о перечисленном инстансе успешно получены.</td></tr><tr><td>🟢 <code>Обновление</code> </td><td><code>инстанс не кэширован, добавляется в начало</code></td><td>Получены сведения об инстансе вне текущего списка.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось получить сведения об инстансе</code></td><td>Не удалось получить сведения, возможно из-за неверного ID запроса.</td></tr></tbody></table>

[^1]: Объект передачи данных


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edgegap.com/ru/unity/server-browser.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.