> 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/podbor-igrokov.md).

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

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

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

{% columns %}
{% column %}

* Полные примеры
* Автоматизация пинга
* Тикеты, группы, команды
  {% endcolumn %}

{% column width="33.33333333333333%" %}

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

{% column width="33.33333333333333%" %}

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

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

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

{% hint style="success" %}
Этот плагин предоставляется абсолютно бесплатно, в соответствии с Условиями и положениями Free Tier.
{% endhint %}

#### Требования

<details>

<summary>Установите Git-клиент (например <a href="https://git-scm.com/">git-scm</a>)</summary>

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

</details>

#### Установка

1. Откройте ваш проект Unity,
2. Выберите `Window > Package Management > Package Manager` ,
3. Нажмите на :heavy\_plus\_sign: значок и выберите `Add package from git URL...` ,
4. Введите URL нашего SDK, когда будет предложено:

{% code title="" %}

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

{% endcode %}

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

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

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

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

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

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

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

{% hint style="warning" %}
**Импортированные примеры не обновляются автоматически!** Сделайте резервную копию любых пользовательских значений свойств, удалите используемые сейчас в вашей сцене скрипты примеров и импортируйте примеры заново.
{% endhint %}

{% hint style="info" %}
Некоторые релизы могут содержать несовместимые изменения. Это будет обозначено новой MAJOR-версией.
{% endhint %}

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

Это обновление включает множество новых [Браузер серверов](/ru/unity/brauzer-serverov.md) утилит и примеров, улучшает обработку ошибок матчмейкинга и многое другое. См. [Примечания к выпуску](/ru/docs/release-notes.md) полный список.

{% hint style="warning" %}
Обновление Unity SDK v3 включает несколько несовместимых изменений. Пожалуйста, тщательно повторно протестируйте вашу интеграцию.
{% endhint %}

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

В этом руководстве предполагается базовое знание [Подбор игроков](/ru/learn/podbor-igrokov.md) концепций и запущенный Matchmaker.

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

{% embed url="<https://youtu.be/LupYTyzgz6g>" %}

### Обзор

Наш SDK активно использует [внедрение зависимостей](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection/overview#the-concept) и [Наблюдатель](https://learn.microsoft.com/en-us/dotnet/standard/events/observer-design-pattern) шаблоны программирования.

{% hint style="info" %}
Этот пакет объединяет оба [Браузер серверов](/ru/learn/brauzer-serverov.md) и [Подбор игроков](/ru/learn/podbor-igrokov.md)которые можно использовать вместе или по отдельности. Вы можете свободно повторно использовать любые сценарии для своих собственных модифицированных форков и интеграций.
{% endhint %}

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

* Файлы Runtime — будут скомпилированы и включены в сборки клиента и сервера:
  * Утилиты, специфичные для сервиса:
    * [#client-agent](#client-agent "mention") - полную клиентскую интеграцию для повторного использования/расширения.
    * Функции API — определения конечных точек, обработка ошибок и автоматизация логирования.
  * Специфичные для сервиса DTO[^1] - типизированные контейнеры данных для API матчмейкинга.
  * Общие утилиты — логирование, HTTP, ping, наблюдаемые объекты и т. д.
  * Общие DTO[^1] - используются несколькими сервисами Edgegap для передачи данных.
* Файлы примеров — включаются и компилируются ТОЛЬКО если импортированы в ваш проект:
  * [#simple-example](#simple-example "mention") - примеры обработчиков для [минимальной конфигурации](/ru/learn/podbor-igrokov.md#simple-example).
  * [#region-picker](#region-picker "mention") - изучите интеграцию UI с ручным выбором региона.

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

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

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

* `onMonitorUpdate`  callback — отслеживать изменения состояния сервиса,
* `onAssignmentUpdate`  callback — отслеживать и реагировать на изменения назначения хоста.

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

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

* `Маяки`  для получения списка доступных [Пинг-маяки](/ru/learn/orkestraciya/ping-beacons.md),
* `MeasureBeaconsRoundTripTime`  для выполнения измерений пинга для заданного набора маяков,
* `CreateGroup`  для лидера лобби, чтобы создать присоединяемую группу, в которую можно приглашать друзей,
* `JoinGroup`  для присоединения к существующей группе, используя ID группы, отправленный через сторонний лобби/backend,
* `SetReady`  чтобы отметить владельца группы и участников как готовых и начать поиск матчей,
* `ResumeMatchmaking`  загрузить кэшированную группу и продолжить поиск в случае сбоя клиента,
* `StopMatchmaking`  чтобы удалить тикет (если матч не найден) и покинуть очередь,
* `Статус`  для проверки состояния сервиса Server Browser.

Когда устанавливается новое подключение игрока, ожидается, что игрок отправит свой ID тикета на игровой сервер, используя ваш netcode, чтобы связать подключения с [Подробный обзор](/ru/learn/podbor-igrokov/matchmaker-in-depth.md#injected-variables).

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

## 🧪 Примеры

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

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

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

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

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

У некоторых игроков (или групп) есть особые локализованные условия (например, ISP[^2] блокировка, [общенациональная блокировка](#user-content-fn-3)[^3], или иные) и они могут предпочитать выбирать регион вручную, а не только по пингу.

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

### Собраться вместе

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

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

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

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

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

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

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

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

{% hint style="warning" %}
Обязательно ознакомьтесь с [Матчмейкинг в деталях](/ru/learn/podbor-igrokov/matchmaker-in-depth.md) концепциями перед внесением изменений.
{% endhint %}

{% hint style="info" %}
Если вам нужна помощь, [свяжитесь с нами через Discord](https://discord.gg/MmJf8fWjnt). Для поддержки по играм в реальном времени см. нашу [систему тикетов](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### Отслеживать события

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

{% hint style="success" %}
Читать полезные данные событий, обращаясь к  `.Current` состоянию любого наблюдаемого объекта. 🔴 `Ошибка` события содержат полное сообщение об ошибке, отделённое символом новой строки после основного сообщения события.
{% endhint %}

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

<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>не удалось получить маяки</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>Не удалось создать группу.</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>участник обновлён [{ready}]</code></td><td>Участник обновлён с новым значением Ready.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>не удалось обновить участника</code></td><td>Не удалось обновить участника группы. Нельзя снять готовность после того, как группа начала поиск матча.</td></tr><tr><td>🔵 <code>Уведомление</code></td><td><code>опрос [{consecutive}/{maximum}]</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>группа обновлена [{status}]</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>Клиент не смог удалить группу, для которой уже найден матч. Отключите покидание или <a data-mention href="/pages/4ee817820b702f68c6cecc5b9b02c79aa0da8963#backfill-match">/pages/4ee817820b702f68c6cecc5b9b02c79aa0da8963#backfill-match</a> чтобы заменить игрока.</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>

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

[^2]: [Интернет-провайдер](https://en.wikipedia.org/wiki/Internet_service_provider)

[^3]: особенно в Китае или России