> 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/veb-igry/colyseus-realtime-tanks.md).

# Colyseus Realtime Tanks

Разместите многопользовательскую игру про танки на Colyseus 0.17 на Edgegap с одним выделенным сервером на матч, используя прямое подключение или матчмейкер Edgegap.

Узнайте, как размещать [Colyseus](https://colyseus.io/) серверы на Edgegap, используя техники из [Realtime Tanks](https://github.com/colyseus/realtime-tanks-demo) демо от команды Colyseus.

В примере один авторитетный сервер Colyseus и 9 клиентов, созданных на разных движках — Three.js, PlayCanvas, Construct 3, Godot, Unity, Defold, GameMaker, Haxe и MonoGame. Для каждого матча создаётся свой сервер, запускаемый рядом с игроками, и сервер сам останавливается, когда матч заканчивается.

В этом примере показано:

* **Colyseus 0.17** сервер в `linux/amd64` образе Docker, прослушивающем порт `2567`,
* **один сервер на матч** - сервер останавливает собственное развёртывание, если никто не присоединяется, если он остаётся пустым или после заданного числа раундов,
* **прямой режим** - запустите развёртывание и передайте его URL любому из 9 клиентов с `?server=` или `--server=`,
* **Edgegap Matchmaker** (необязательно) - встроено в клиенты Three.js, Unity и Godot, для веб- и десктопных сборок,
* **один порт WebSocket с TLS Upgrade** - через него проходят и HTTP-запрос матчмейкинга Colyseus, и WebSocket комнаты.

{% hint style="success" %}
См. [edgegap/README.md](https://github.com/edgegap/backend-game-sample-threejs-colyseus-tanks/blob/master/edgegap/README.md) в репозитории примера для полного списка изменённых файлов и настроек для каждого клиента.
{% endhint %}

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

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

* [Проект-пример Realtime Tanks](https://github.com/edgegap/backend-game-sample-threejs-colyseus-tanks) (изменённый для Edgegap),
* [Node.js](https://nodejs.org/), чтобы запустить сервер локально и скрипт развёртывания.

<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>

Локально сервер ведёт себя как в upstream. Из `server` папки, выполните `npm install` затем `npm run dev`.

## ⚡ Развертывание и подключение

### 1. Соберите образ сервера

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

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

☑️ Войдите в Container Registry Edgegap с помощью 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
cd server
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/realtime-tanks:v1 .
docker push registry.edgegap.com/<project>/realtime-tanks:v1
```

{% endcode %}

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

☑️ При желании сначала протестируйте образ локально. `ARBITRIUM_REQUEST_ID` заставляет его вести себя как на Edgegap — если URL для удаления не задан, самоостановка это логирует и завершает работу:

{% code collapsedlinecount="10" %}

```bash
docker run -p 2567:2567 -e ARBITRIUM_REQUEST_ID=local -e EMPTY_TIMEOUT_S=10 realtime-tanks:v1
```

{% endcode %}

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

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

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

* образ `registry.edgegap.com/<project>/realtime-tanks`, тег `v1`,
* ваше имя пользователя и токен Container Registry, чтобы Edgegap мог получить ваш образ,
* ресурсы: 0.25 vCPU и 512 МБ памяти,
* [порт](https://docs.edgegap.com/ru/learn/orkestraciya/application-and-versions.md#port-mapping) `2567`, имя `gameport`, протокол **WS**, с **включённым TLS Upgrade** включено,
* [максимальная длительность](https://docs.edgegap.com/ru/learn/orkestraciya/application-and-versions.md#safety-guardrails) 60 минут для тестирования.

{% hint style="warning" %}
**включённым TLS Upgrade** позволяет любому клиенту, включая браузерные сборки, подключаться к `wss://<id>.pr.edgegap.net:<port>`. Edgegap завершает TLS и перенаправляет обычные HTTP и WebSocket на порт `2567`, так что HTTP-запрос матчмейкинга Colyseus и WebSocket комнаты используют один порт. См. [Websockets (WS) и Secure Websockets (WSS)](https://docs.edgegap.com/ru/learn/orkestraciya/deployments.md#websockets-ws-and-secure-websockets-wss).
{% endhint %}

При желании задайте переменные окружения для версии приложения:

* `MATCH_ROUNDS` - завершать матч после такого числа выигранных раундов (по умолчанию `0`, бесконечная арена),
* `FIRST_JOIN_TIMEOUT_S` - секунд до того, как сервер без подключившихся игроков остановится сам (по умолчанию `120`),
* `EMPTY_TIMEOUT_S` - через сколько секунд сервер, от которого все ушли, остановится сам (по умолчанию `30`).

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

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

☑️ Запустите сервер рядом с вами с помощью скрипта развёртывания из примера. Ваш токен API Edgegap остаётся на вашей машине:

{% code collapsedlinecount="10" %}

```bash
cd server
EDGEGAP_API_TOKEN=<token> npm run edgegap:deploy -- realtime-tanks v1
```

{% endcode %}

Скрипт выводит `wss://<request_id>.pr.edgegap.net:<port>` и как передавать его каждому клиенту.

☑️ Передайте URL своим клиентам:

* **Three.js, PlayCanvas, Construct 3** - `?server=wss://...` в URL страницы,
* **Godot** - `--server=wss://...` (после `--` в основных аргументах запуска редактора), веб-экспорт `?server=wss://...`,
* **Unity** - `--server=wss://...` в командной строке, WebGL `?server=wss://...`, или `serverUrl` поле,
* **Defold** - HTML5 `?server=wss://...`, нативная `--config=tanks.server_url=wss://...` или `[tanks] server_url` в `game.project`,
* **GameMaker** - `--server=wss://...` в командной строке, HTML5 `?server=wss://...`,
* **Haxe** - JS `?server=wss://...`, HashLink `--server=wss://...`,
* **MonoGame** - `--server=wss://...` или `TANKS_SERVER_URL` переменная окружения.

{% hint style="danger" %}
В живой игре ваш бэкенд вызывает тот же самый [API развёртывания](https://docs.edgegap.com/ru/docs/api/vydelennye-servery.md) (`POST /v2/deployments`) когда лобби готово, и отправляет URL своим игрокам. **Никогда не помещайте токен API Edgegap в клиент игры или образ сервера.**
{% endhint %}

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

### 4. Добавьте матчмейкер (необязательно)

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

В конфигурации есть один `casual` профиль на 2–8 игроков на матч. Через 15 секунд он запускает матч с теми, кто ждёт, при наличии как минимум 2 игроков.

☑️ Добавьте каждый origin, обслуживающий вашу игру, в `allowed_cors_origins`, поскольку браузерные сборки вызывают матчмейкер со страницы (см. [CORS](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#cross-origin-resource-sharing-cors)). Конфигурация позволяет `http://localhost:5173` (Vite), `http://localhost:8060` (веб Godot) и `http://localhost:8080`.

☑️ Нажмите **Создать и запустить**. Как только ваш матчмейкер покажет **Онлайн**, скопируйте его **API URL** и **Auth Token**.

{% 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 %}

☑️ Запустите ваши клиенты с настройками матчмейкера:

* **Three.js** - `http://localhost:5173/?mm=<API URL>&mmToken=<Auth Token>`, или `VITE_MM_URL` / `VITE_MM_TOKEN` в `.env.local`,
* **Unity** - `--mm=<API URL> --mm-token=<Auth Token>`, WebGL `?mm=...&mmToken=...`, или *Edgegap Matchmaker* поля в `GameManager`,
* **Godot** - `-- --mm=<API URL> --mm-token=<Auth Token>`, веб-экспорт `?mm=...&mmToken=...`.

☑️ Откройте два клиента — для матчмейкинга требуется как минимум 2 игрока, и они могут использовать разные движки.

Каждый клиент показывает «Поиск игроков...» и подключается, как только сервер назначен. А `server` настройка всегда имеет приоритет над матчмейкером.

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

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

1. Клиент создаёт билет с `POST /tickets` в течение `casual` профиль, а затем проверяет его каждые 2 секунды с помощью `GET /tickets/{id}`.
2. Matchmaker развёртывает `realtime-tanks` рядом с игроками. Когда тикет достигает `HOST_ASSIGNED`, клиент считывает FQDN назначения и внешний порт `gameport`.
3. Клиент подключается к `wss://<fqdn>:<port>`. Только что запущенный сервер может в течение нескольких секунд отвечать 502, поэтому клиенты повторяют попытку подключения до 20 секунд (см. [Подключиться к серверу](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#connect-to-server)).
4. Вызовы сервера `ARBITRIUM_DELETE_URL` чтобы остановить собственное развёртывание, если никто не присоединился в течение `FIRST_JOIN_TIMEOUT_S`, когда все ушли на `EMPTY_TIMEOUT_S`, или когда `MATCH_ROUNDS` раунды были выиграны. Максимальная длительность версии вашего приложения служит запасным ограничителем.

Клиент матчмейкера небольшой и не имеет зависимостей, поэтому его легко перенести на другие клиенты — см. `web-threejs/src/Matchmaker.ts`, `unity/Assets/Scripts/EdgegapMatchmaker.cs` и `godot/scripts/edgegap_matchmaker.gd`.

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

## 🚀 Дальше

* **Проверяйте присоединяющихся** - развёртывания матчмейкера получают [`MM_TICKET_IDS`](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#injected-variables). Пусть клиенты передают свой ID тикета в параметрах присоединения и проверяйте его в `onAuth`, чтобы присоединиться могли только сопоставленные игроки.
* **Перед запуском** - установите `inspect` на `false` в конфигурации матчмейкера, перечислите реальные origin'ы и увеличьте максимальную длительность, чтобы она подходила для ваших матчей (см. [Перед выходом в продакшен](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#before-going-live)).

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

* Протестировано end-to-end на Edgegap с Colyseus 0.17, matchmaker 3.3.2, Godot 4.5.2 и Unity 6000.3:
  * direct - клиенты Node Colyseus и настольный клиент Godot присоединились к развёртыванию через `wss://`, и сервер сам остановился после того, как все ушли,
  * matchmaker - Three.js в браузере и настольный клиент Godot были сопоставлены с одним сервером, затем Three.js и сборка Unity для Windows.
* Construct 3, Defold, GameMaker, Haxe и PlayCanvas `server` переопределения, веб-экспорт Godot и Unity WebGL ещё не протестированы.
