> 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/threejs-minigames.md).

# Мини-игры Three.js

Многопользовательская игра на three.js с подбором игроков: пять браузерных мини-игр, где при подборе игроков для каждого матча запускается один авторитетный сервер node.js.

Узнайте, как создавать многопользовательские игры на three.js с подбором игроков.

![Многопользовательские игры на Three.js с матчмейкером](https://raw.githubusercontent.com/edgegap/netcode-sample-threejs-minigames/main/docs/images/banner.jpg)

Этот пример включает пять небольших браузерных игр, по одной на каждый жанр, созданных с использованием [three.js](https://threejs.org/) и обычных WebSocket-серверов на node.js. Игроки нажимают **Найти матч** на странице, матчмейкер объединяет их и запускает выделенный сервер рядом с ними, чтобы они могли подключиться и играть. Когда матч заканчивается, сервер сам останавливается.

Этот пример включает 5 мини-игр:

* Blaster Arena: вид сверху, режим каждый сам за себя, до 10 выбиваний. 2–8 игроков, боты добирают до 3 в сумме.
* Kart Rally: гонки, сначала нужно проехать 3 круга. 1–8 игроков.
* Rocket Soccer: спортивная игра, команды 1 на 1 или 2 на 2. Всего 2–4 игрока.
* Light Cycles: аркада, последний выживший. 2–6 игроков, боты добирают до 4 в сумме.
* Sumo Push: вечериночная игра, король горы. 2–8 игроков, боты добирают до 4 в сумме.

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

* **Подбор игроков из браузера** с [Edgegap JavaScript SDK](https://www.npmjs.com/package/@edgegap/sdk) (`@edgegap/sdk`): найти матч, отменять и повторять при ограничении по частоте запросов, с одним матчмейкером и профилем на каждую игру, включая профиль для 2 команд.
* **Авторитетные серверы**: страница только отправляет ввод и отрисовывает полученное состояние, поэтому игроки не могут изменить правила из браузера.
* **Один сервер на один матч**, достигнув более `wss://` благодаря TLS Upgrade. Он получает сведения о матче через SDK и останавливает собственное развертывание, когда матч заканчивается, когда все уходят или когда никто не подключается.
* **Одно изображение для пяти игр**: одна версия приложения на игру, с переменной окружения `GAME` выбирающей сервер.
* **Без этапа сборки**: Three.js и браузерная сборка SDK загружаются из CDN через import map, поэтому страницы — это статические файлы, которые можно разместить где угодно.

{% hint style="info" %}
См. [репозиторий с примером](https://github.com/edgegap/netcode-sample-threejs-minigames) для правил и дизайна сервера каждой игры, [заметки по архитектуре](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/architecture.md) и руководство по [добавлению своей игры](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/adding-a-game.md).
{% endhint %}

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

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

* [Пример Three.js Minigames](https://github.com/edgegap/netcode-sample-threejs-minigames).
* [Node.js](https://nodejs.org/) 22 или новее, чтобы запускать серверы и страницы локально.
* [Docker](https://docs.docker.com/get-started/get-docker/), чтобы собрать образ сервера.

☑️ Сначала попробуйте игры локально:

{% code collapsedlinecount="10" %}

```bash
npm install
npm run dev:all
```

{% endcode %}

Это запускает пять игровых серверов на портах `7771` на `7775` и обслуживает страницы по адресу `http://localhost:8080`. Выберите игру, нажмите **Локальный сервер**, и откройте вторую вкладку, чтобы играть против самого себя. `npm test` играет полный матч в каждой игре с двумя headless-игроками.

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

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

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

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

☑️ Войдите в 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
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/threejs-minigames:<tag> .
docker push registry.edgegap.com/<project>/threejs-minigames:<tag>
```

{% endcode %}

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

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

☑️ [Создайте приложение](https://app.edgegap.com/application-management/applications/list) под названием `threejs-minigames`, и одну версию на каждую игру: `blaster-v1`, `kart-v1`, `soccer-v1`, `cycles-v1` и `sumo-v1`.

☑️ Настройте каждую версию приложения:

* **Образ**: `registry.edgegap.com/<project>/threejs-minigames`, тег `<tag>`,
* **Учётные данные реестра**: имя пользователя и токен вашего Container Registry, чтобы Edgegap мог загрузить образ,
* **Ресурсы**: 0,25 vCPU и 512 МБ памяти,
* **Порт**: `7777`, имя `gameport`, протокол **WS**, с **включённым TLS Upgrade** включено,
* **Переменная окружения**: `GAME` установлена на `blaster`, `kart`, `soccer`, `cycles` или `sumo`,
* **Максимальная длительность**: 30 минут, как запасной ограничитель: серверы сами останавливаются.

{% hint style="warning" %}
**включённым TLS Upgrade** позволяет браузерам на `https` страницах подключаться к `wss://<id>.pr.edgegap.net:<port>`. Edgegap завершает TLS и пересылает обычный WebSocket-трафик на порт `7777`. Подключайтесь по FQDN, а не по IP, чтобы сертификат совпадал.
{% endhint %}

Необязательные переменные окружения, для любой версии:

* `WAIT_SECONDS` - запускать через столько времени после подключения первого игрока, даже если не хватает сопоставленных игроков (по умолчанию `15`),
* `MATCH_SECONDS` - ограничение времени на матч (по умолчанию для каждой игры),
* `FIRST_JOIN_TIMEOUT_S` - секунд до того, как сервер без подключившихся игроков остановится сам (по умолчанию `120`),
* `EMPTY_TIMEOUT_S` - через сколько секунд сервер, от которого все ушли, остановится сам (по умолчанию `30`),
* `REQUIRE_TICKET` - `1` отказывает игрокам, чей билет матчмейкера не входит в этот матч.

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

### 3. Протестируйте один сервер напрямую

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

{% code collapsedlinecount="10" %}

```bash
EDGEGAP_API_TOKEN=<token> node edgegap/deploy.mjs threejs-minigames sumo-v1
```

{% endcode %}

Скрипт выводит `wss://<request_id>.pr.edgegap.net:<port>`.

☑️ Откройте `http://localhost:8080/games/sumo/?server=wss://...` в двух вкладках браузера и играйте. Когда матч заканчивается, сервер останавливает собственное развертывание.

{% hint style="danger" %}
**Никогда не помещайте ваш токен API Edgegap в веб-страницу или в образ сервера.** Игроки получают серверы через матчмейкер, который использует собственный безопасный для клиента токен.
{% endhint %}

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

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

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

В конфигурации есть один профиль на игру, каждый указывает на версию приложения этой игры:

* `blaster`, `kart` и `sumo`: от 2 до 8 игроков, `cycles`: от 2 до 6. Через 20 секунд игрок, ожидающий в одиночку, получает сервер, а боты заполняют пустые места.
* `soccer`: `team_count: 2` с 1 или 2 игроками в каждой команде, то есть 2 на 2, когда ждут четыре игрока, иначе 1 на 1. Каждый билет получает `team_id`, и сервер распределяет каждого игрока по его команде.

☑️ Браузерные игры вызывают матчмейкер со страницы, поэтому добавьте каждый origin, который обслуживает ваши страницы, в `allowed_cors_origins`. Конфигурация допускает `http://localhost:8080`.

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

{% hint style="info" %}
Для командных профилей начните с `min_team_size: 1` вместо того чтобы полагаться на расширение. В наших тестах `team_count: 2` профиль с `min_team_size: 2` и 20-секундным расширением до `1` сопоставлял только двух ожидающих игроков, когда срок их билетов вот-вот истекал.
{% endhint %}

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

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

☑️ Поместите URL API и токен авторизации матчмейкера в `client/config.js` (или в игнорируемый git'ом `client/config.local.js`), или добавьте `?mm=<API URL>&token=<Auth Token>` к URL страницы.

{% hint style="success" %}
Правило **Токен авторизации матчмейкера безопасно включать в игровые клиенты**: его можно использовать только для поиска матчей. Это не ваш токен API Edgegap.
{% endhint %}

☑️ Запустите `npm run web` и откройте одну и ту же игру в двух вкладках. Нажмите **Найти матч** в обеих в течение 20 секунд.

Каждая вкладка использует `GroupAgent` SDK, чтобы:

1. создать группу подбора из одного игрока для профиля игры, готовую сразу же,
2. ждать с помощью `nextAssignment()` до тех пор, пока группа не станет `HOST_ASSIGNED`, который содержит адрес сервера и `gameport`,
3. подключиться к `getConnectionUrl(assignment, "gameport")`, что даёт `wss://<fqdn>:<port>`, и отправить идентификатор своего билета, чтобы сервер знал, в какой команде находится игрок.

{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, matchmaking } from "@edgegap/sdk";

const agent = new matchmaking.GroupAgent({ baseUrl: "<API URL>", authToken: "<Auth Token>" });
agent.initialize();

agent.createGroup({ profile: "sumo", attributes: {}, is_ready: true }, true);
const assignment = await agent.nextAssignment();
const url = getConnectionUrl(assignment, "gameport");
const ticketId = agent.group.current.ticket_id;
```

{% endcode %}

Новое развертывание может отвергать соединения в течение нескольких секунд после `HOST_ASSIGNED`, поэтому клиент повторяет попытку. SDK сам повторяет запросы с ограничением по частоте (`429`) и неудачные запросы, а **Отмена** оставляет группу с `stopMatchmaking()`.

🙌 Оба игрока теперь в одном матче, на сервере, размещённом рядом с ними.

☑️ Чтобы протестировать весь путь без браузера, запустите end-to-end тест. Он ставит в очередь несколько headless-игроков для каждой игры, проверяет, что они попадают на одно и то же развертывание и играют полный матч, затем ждёт, пока развертывание остановится само:

{% code collapsedlinecount="10" %}

```bash
MM_URL=<API URL> MM_TOKEN=<Auth Token> npm run e2e
```

{% endcode %}

## 📦 Поставляйте свою игру

* Размещайте страницы где угодно: это статические файлы без этапа сборки (`index.html`, `client/`, `games/`). Добавьте каждый origin в `allowed_cors_origins`.
* Выключите `inspect` в конфигурации матчмейкера перед запуском.
* Установите `REQUIRE_TICKET=1` для версий приложения, чтобы не пускать игроков, которых матчмейкер не отправил.
* Чтобы выпустить новую сборку сервера, отправьте новый тег образа и укажите на него каждую версию приложения. Новые матчи будут использовать его, а уже запущенные продолжат работать на старой сборке.
* Чтобы обновить SDK, измените его версию в `package.json` и в import map каждой страницы игры, а также обновите хэш целостности import map.

{% hint style="info" %}
Используете кодирующего агента? `edgegap-threejs` навык в [навыках агента Edgegap](https://github.com/edgegap/llm-agent-skills) поставляет сервер и клиент этого примера как шаблоны и проведёт вашего агента через те же шаги для вашей собственной браузерной игры.
{% endhint %}
