> 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/docs/sample-projects/unity-netcodes/megacity-metro.md).

# Unity ECS Megacity Metro

Разместите Megacity Metro от Unity — шутер на Netcode for Entities для 150 игроков — на Edgegap с выделенными серверами, подбором матчей и добором игроков.

Узнайте, как размещать проекты Unity DOTS на Edgegap, используя методы из [образца Megacity Metro](https://github.com/Unity-Technologies/megacity-metro), мобильного и десктопного шутера, созданного на Netcode for Entities, с числом игроков до 150 на сервер.

Игроки нажимают **Найти матч**, [Edgegap Matchmaker](https://docs.edgegap.com/ru/learn/matchmeiking.md) запускает выделенный сервер рядом с ними, а игроки, ищущие позже, присоединяются к работающим серверам с [добором](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#backfill-match). Сервер останавливает своё развёртывание, когда никто не играет.

Этот пример показывает:

* **Unity 6000.1.0f1** проект на **Netcode for Entities** (DOTS), собранный как выделенный Linux-сервер,
* **прямое подключение** с десктопного клиента к развёртыванию, для тестирования без матчмейкера,
* **Edgegap Matchmaker** интеграция с [Edgegap Unity SDK](https://github.com/edgegap/sdk-unity-sessions-matchmaker-server-browser) - клиент ставит тикет в очередь и подключается к назначенному серверу,
* **добором** - работающие серверы держат свободные места в матчмейкере, поэтому новые игроки присоединяются к ним вместо запуска новых серверов, до 150 игроков,
* **автоостановка сервера** - сервер останавливает своё развёртывание, когда никто не присоединяется, или после того, как все ушли.

Сетевой код игры не изменён. Без URL матчмейкера, вне развёртывания Edgegap и без цели прямого подключения игра ведёт себя как в upstream.

{% hint style="info" %}
Проверено на Edgegap с десктопными клиентами Windows: развёртывание сервера, прямое подключение и матчмейкинг с добором (3 игрока на одном сервере). В мобильных релизных сборках опция Connect скрыта, поэтому телефоны используют **Найти матч**.
{% endhint %}

{% hint style="success" %}
Смотрите [EDGEGAP.md](https://github.com/edgegap/netcode-game-sample-unity-dots-ecs-mobile-megacity-metro/blob/master/EDGEGAP.md) в репозитории примера для полного списка файлов Edgegap и настроек сервера.
{% endhint %}

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

Прежде чем начать, вам понадобится:

* [Unity `6000.1.0f1`](https://unity.com/releases/unity-6) - загрузите через Unity Hub, с модулями ниже и модулем для вашей клиентской платформы (Windows Build Support (IL2CPP) для протестированного клиента),
* [проект Megacity Metro Sample](https://github.com/edgegap/netcode-game-sample-unity-dots-ecs-mobile-megacity-metro) (изменённый для Edgegap), клонированный с [Git LFS](https://git-lfs.com/) (около 415 МБ содержимого LFS).

<details>

<summary>Установите модули поддержки сборки Unity для Linux</summary>

* Используйте Unity Hub, чтобы выбрать вкладку **Устанавливает**, доступ **Настройки** и **Добавить модули** для каждой версии Unity, которую вы планируете использовать с платформой Edgegap:

<figure><img src="https://3845012722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FylRG4r8orenZrw5ijjpJ%2Fimage.png?alt=media&amp;token=fb981825-8a15-4c07-9180-0f79a6a77a91" alt=""><figcaption></figcaption></figure>

* Прокрутите вниз, чтобы выбрать и установить следующие модули Unity:
  * **Поддержка сборки для Linux (IL2CPP),**
    * **Поддержка сборки для Linux (Mono),**
    * **Поддержка сборки выделенного сервера для Linux**

<figure><img src="https://3845012722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FuXtyqoLhBOk8CZJ4WdzA%2Fimage.png?alt=media&amp;token=19e956ed-a731-420d-b911-130c334794fc" alt=""><figcaption></figcaption></figure>

</details>

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">Установите Docker Desktop (или Docker CLI)</a></summary>

* [Установите Docker Desktop из официального источника](https://www.docker.com/products/docker-desktop/) (аккаунт не требуется).
* Перезагрузите компьютер после завершения установки.

</details>

## ⚡ Развернуть и подключиться

### 1. Сборка и загрузка

☑️ Чтобы начать, вам нужно [создать бесплатную учётную запись в Edgegap](https://app.edgegap.com/auth/register). Кредитная карта не требуется.

☑️ Соберите в плагине редактора в  или через CLI:

{% tabs %}
{% tab title="Плагин Unity Servers Quickstart (рекомендуется)" %}
☑️ Выберите Tools / Edgegap / Build Linux Dedicated Server.

☑️ Завершите шаг Edgegap Plugin Containerize and Upload.
{% endtab %}

{% tab title="Интерфейс командной строки (для агентов)" %}
☑️ Закройте свой проект в Unity Editor, затем соберите выделенный Linux-сервер из корня проекта:

{% code collapsedlinecount="10" %}

```bash
Unity -batchmode -quit -buildTarget Linux64 -standaloneBuildSubtarget Server -projectPath . -executeMethod EdgegapServerBuild.Build -logFile build.log
```

{% endcode %}

{% hint style="warning" %}
Сохраните `-buildTarget Linux64 -standaloneBuildSubtarget Server`, иначе сборка контента Entities завершится ошибкой `Невозможно собрать с текущей конфигурацией`.
{% endhint %}

☑️ Найдите свои [Container Registry](https://docs.edgegap.com/ru/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) имя проекта и учётные данные, и войдите в Docker:

{% tabs %}
{% tab title="Bash (Linux)" %}

```bash
project='<REGISTRY_PROJECT>';
username='robot$<REGISTRY_ORGANIZATION_ID>+client-push';
token='<REGISTRY_TOKEN>';

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}

{% tab title="PowerShell (Windows)" %}

```powershell
$project = '<REGISTRY_PROJECT>'
$username = 'robot$<REGISTRY_ORGANIZATION_ID>+client-push'
$token = '<REGISTRY_TOKEN>'

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}
{% endtabs %}

☑️ Соберите и отправьте свой образ:

{% code collapsedlinecount="10" %}

```bash
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/megacity-metro:<tag> .
docker push registry.edgegap.com/<project>/megacity-metro:<tag>
```

{% endcode %}
{% endtab %}
{% endtabs %}

Ваша сборка сохранена в `Builds/EdgegapServer/` (около 3,4 ГБ, в основном отладочная информация Burst и папка резервной копии IL2CPP). У sample's `.dockerignore` исключает `*_BurstDebugInformation_DoNotShip` и `*_BackUpThisFolder_ButDontShipItWithYourGame`, поэтому размер вашего образа около 537 МБ.

{% hint style="danger" %}
:x: **НЕ ДЕЛАЙТЕ — не перезаписывайте существующие теги и не используйте `latest`  тег** — это приведёт к развёртыванию устаревшего кэша.\
:white\_check\_mark: **ДЕЛАЙТЕ — всегда увеличивайте номер версии в теге** и развёртывайте новую сборку.
{% endhint %}

Ваш сервер слушает на `0.0.0.0:7979` по UDP. Передавайте дополнительные аргументы сервера в `UNITY_COMMANDLINE_ARGS` переменной окружения в вашей версии приложения.

✅ Теперь вы можете перейти к следующему шагу.

### 2. Создайте версию приложения

☑️ [Создайте приложение](https://app.edgegap.com/application-management/applications/list) и версию с:

* ваш `registry.edgegap.com/<project>/megacity-metro:<tag>` образ,
* имя пользователя и токен вашего Container Registry, иначе развёртывания не смогут загрузить образ,
* ресурсы 1 vCPU и 2 ГБ памяти (проверено: у неактивного сервера использовалось около 18% CPU и 323 МБ),
* [порт](https://docs.edgegap.com/ru/learn/orkestraciya/application-and-versions.md#port-mapping) `7979`, именованный `gameport`, протокол **UDP**.

✅ Теперь вы можете перейти к следующему шагу.

### 3. Подключение напрямую

Давайте проверим, что ваш сервер работает, прежде чем добавлять матчмейкер.

☑️ [Разверните вашу версию приложения](https://app.edgegap.com/deployment-management/deployments/list) из плагина или панели управления. В журнале вашего сервера отображается `Запущено на Edgegap ... пропускаем сессии UGS`.

☑️ [Откройте сведения о новом развертывании](https://app.edgegap.com/deployment-management/deployments/list) и найдите свои уникальные одноразовые данные подключения:

* **URL хоста** в формате `780aa4260e83.pr.edgegap.net` (или IP),
* **Внешний порт** из `gameport` в формате `30854` (5 цифр, не `7979`).

☑️ Запустите десктопный клиент с этими данными:

{% code collapsedlinecount="10" %}

```bash
<client executable> -edgegapConnect <host>:<external port>
```

{% endcode %}

Вы также можете задать `EDGEGAP_CONNECT=<host>:<external port>` перед запуском клиента. При цели прямого подключения ваш клиент пропускает вход в Unity Gaming Services (UGS), поэтому проект UGS не нужен. **Найти матч** подключается к этой цели.

☑️ Найдите `[Edgegap] Подключённые игроки: 1` в журнале вашего сервера, как только ваш клиент присоединится.

✅ Теперь вы можете перейти к следующему шагу.

### 4. Создайте матчмейкер

☑️ Установите `application.name` и `application.version` в ваше приложение и версию в `matchmaker-config.json`.

В конфигурации есть один `metro` профиль с одной командой из 2–150 игроков. Два игрока, ищущие вместе, получают сервер примерно через 10 секунд после постановки в очередь, а одинокий игрок — через 30 секунд. Это подходит для тестирования; для реальных матчей увеличьте минимальное значение.

☑️ Откройте [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) на странице, нажмите **Создать матчмейкер**, загрузите `matchmaker-config.json`, затем нажмите **Создать и запустить**.

☑️ Скопируйте **API URL** и **Auth Token** после того как он покажет **ONLINE**.

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

Перезапуск матчмейкера из панели управления сохраняет его URL API и Auth Token.

✅ Теперь вы можете перейти к следующему шагу.

### 5. Найдите матч

☑️ Вставьте свой URL API и Auth Token в `Assets/Resources/EdgegapMatchmakerSettings.asset`.

{% hint style="danger" %}
**Не интегрируйте конечные точки Edgegap API в клиент игры, поскольку ваш API token предоставляет неограниченный доступ к вашей учётной записи. См.** [Интеграция](https://docs.edgegap.com/ru/docs/api/integraciya.md) **для безопасных клиентских конечных точек API и функций.**
{% endhint %}

{% hint style="info" %}
Matchmaking Auth Token ограничен только вашим матчмейкером, поэтому его безопасно включать в клиентские сборки игры.
{% endhint %}

☑️ Пересоберите ваш сервер и клиенты — клиенты читают этот asset, чтобы находить матчи, серверы читают его, чтобы создавать доборы. Отправьте новый образ сервера и укажите на него вашу версию приложения и `matchmaker-config.json` к нему.

Переопределите asset при запуске с помощью `-edgegapMatchmakerUrl`, `-edgegapMatchmakerToken` и `-edgegapMatchmakerProfile` (или `EDGEGAP_MM_URL`, `EDGEGAP_MM_TOKEN`, `EDGEGAP_MM_PROFILE`).

☑️ Запустите два клиента и нажмите **Найти матч** на обоих. Статус меняется с `Searching...` на `Матч найден, запуск сервера...`, затем ваш клиент подключается.

☑️ Запустите третьего клиента и нажмите **Найти матч** пока матч идёт. Он присоединяется к тому же серверу через добор.

🙌 Поздравляем с вашим первым развёртыванием с подбором игроков на Edgegap!

## 🔄 Жизненный цикл матча

1. Клиент ставит одиночный тикет с профилем `metro` Его `backfill_group_size` атрибут `["new", "1"]` - новый матч или одно свободное место на работающем сервере.
2. Матчмейкер запускает развёртывание рядом с игроками или сопоставляет тикет с добором с работающего сервера.
3. Клиент подключается к IP и внешнему порту сервера, затем отправляет свой ID тикета на сервер.
4. На развёртываниях матчмейкера сервер считывает матч из [`MM_*` переменных](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#injected-variables) и даёт каждому сопоставленному игроку 60 секунд на подключение. Он держит открытыми до 3 доборов, пока есть свободные места, и освобождает место, когда игрок уходит или не появляется.
5. Сервер закрывает свои доборы и останавливает своё развёртывание с `ARBITRIUM_DELETE_URL` - через 300 секунд после запуска, если ни один игрок так и не подключился, или через 60 секунд после ухода последнего игрока.

Измените эти лимиты с помощью переменных окружения в вашей версии приложения:

* `EDGEGAP_MAX_PLAYERS` - места на сервере (по умолчанию `150`),
* `EDGEGAP_MAX_OPEN_BACKFILLS` - доборы, открытые одновременно (по умолчанию `3`),
* `EDGEGAP_FIRST_PLAYER_TIMEOUT_S` - секунд до того, как сервер без подключившихся игроков остановится сам (по умолчанию `300`),
* `EDGEGAP_EMPTY_TIMEOUT_S` - секунд после ухода последнего игрока, прежде чем сервер остановится сам (по умолчанию `60`).

{% hint style="warning" %}
Если развёртывание остановлено извне (панель управления, API или максимальная длительность), сервер выходит, не закрывая свои доборы. **Пока они не истекут** (`ticket_expiration_period`, 30 секунд), **они могут отправить игрока на остановленный сервер.** Подключение этого игрока истекает, и его следующая **Найти матч** срабатывает.
{% endhint %}

Смотрите [Матчмейкинг](https://docs.edgegap.com/ru/learn/matchmeiking.md), [Подробный обзор](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md) и [Развертывания](https://docs.edgegap.com/ru/learn/orkestraciya/deployments.md) чтобы узнать больше.

## ⚠️ Известные проблемы

* Клиенты Android и iOS пока не протестированы, как и оконный плейтест на десктопе.
* Сервер записывает подключения с неизвестными ID тикетов, но всё равно пропускает их (пока без проверки тикетов).
* Vivox и вход в UGS не затронуты. Edgegap Matchmaker и пути прямого подключения их не используют.
