> 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/fr/docs/sample-projects/jeux-web/colyseus-realtime-tanks.md).

# Colyseus Realtime Tanks

Hébergez un jeu de chars multijoueur Colyseus 0.17 sur Edgegap avec un serveur dédié par partie, en utilisant une connexion directe ou le système de matchmaking Edgegap.

Découvrez comment héberger [Colyseus](https://colyseus.io/) des serveurs sur Edgegap en utilisant les techniques du [Realtime Tanks](https://github.com/colyseus/realtime-tanks-demo) exemple de l'équipe Colyseus.

L'exemple comprend un serveur Colyseus faisant autorité et 9 clients créés avec différents moteurs - Three.js, PlayCanvas, Construct 3, Godot, Unity, Defold, GameMaker, Haxe et MonoGame. Chaque partie dispose de son propre serveur, lancé près de ses joueurs, et le serveur s'arrête de lui-même lorsque la partie est terminée.

Cet exemple montre :

* **Colyseus 0.17** serveur dans un `linux/amd64` image Docker, à l’écoute sur le port `2567`,
* **un serveur par partie** - le serveur arrête son propre déploiement lorsque personne ne se joint, lorsqu'il reste vide, ou après un nombre défini de manches,
* **mode direct** - démarrez un déploiement et transmettez son URL à l'un des 9 clients avec `?server=` ou `--server=`,
* **Matchmaker Edgegap** (facultatif) - intégré aux clients Three.js, Unity et Godot, pour les versions web et desktop,
* **un port WebSocket avec mise à niveau TLS** - transportant à la fois la requête HTTP de matchmaking Colyseus et le WebSocket de la salle.

{% hint style="success" %}
Voir [edgegap/README.md](https://github.com/edgegap/backend-game-sample-threejs-colyseus-tanks/blob/master/edgegap/README.md) dans le dépôt d'exemple pour la liste complète des fichiers modifiés et des paramètres par client.
{% endhint %}

## ✔️ Préparation

Avant de commencer, vous aurez besoin de :

* [projet d'exemple Realtime Tanks](https://github.com/edgegap/backend-game-sample-threejs-colyseus-tanks) (modifié pour Edgegap),
* [Node.js](https://nodejs.org/), pour exécuter le serveur localement et le script de déploiement.

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">Installez Docker Desktop (ou Docker CLI)</a></summary>

* [Installez Docker Desktop à partir de la source officielle](https://www.docker.com/products/docker-desktop/) (aucun compte requis).
* Redémarrez votre ordinateur après avoir terminé l'installation.

</details>

En local, le serveur se comporte comme la version amont. Depuis le `serveur` dossier, exécutez `npm install` puis `npm run dev`.

## ⚡ Déployer et connecter

### 1. Construire l’image du serveur

☑️ Pour commencer, vous devrez [créer un compte gratuit sur Edgegap](https://app.edgegap.com/auth/register). Aucune carte de crédit requise.

☑️ Trouvez votre [Container Registry](https://docs.edgegap.com/fr/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) nom du projet et identifiants.

☑️ Connectez-vous au registre de conteneurs d’Edgegap avec Docker, en utilisant le nom de projet de votre registre, votre nom d’utilisateur et votre jeton :

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

☑️ Construisez et poussez l'image de votre serveur :

{% 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: **À ÉVITER — écraser les tags existants ou utiliser `latest`  tag** — cela déploiera un cache obsolète.\
:white\_check\_mark: **À FAIRE — toujours incrémenter votre tag de version** et déployer la nouvelle version.
{% endhint %}

☑️ Facultativement, testez d'abord votre image en local. `ARBITRIUM_REQUEST_ID` lui fait se comporter comme sur Edgegap - sans URL de suppression définie, l'auto-arrêt l'enregistre et quitte :

{% code collapsedlinecount="10" %}

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

{% endcode %}

✅ Vous pouvez maintenant passer à l’étape suivante.

### 2. Créer une version d’application

☑️ [Créez une application](https://app.edgegap.com/application-management/applications/list) nommé `realtime-tanks`, et une version nommée `v1` avec :

* image `registry.edgegap.com/<project>/realtime-tanks`, tag `v1`,
* votre nom d’utilisateur et jeton du registre de conteneurs, afin qu’Edgegap puisse extraire votre image,
* ressources 0,25 vCPU et 512 Mo de mémoire,
* [port](https://docs.edgegap.com/fr/learn/orchestration/application-and-versions.md#port-mapping) `2567`, nommé `gameport`, protocole **WS**, avec **mise à niveau TLS** activé,
* [durée maximale](https://docs.edgegap.com/fr/learn/orchestration/application-and-versions.md#safety-guardrails) 60 minutes pour les tests.

{% hint style="warning" %}
**mise à niveau TLS** permet à chaque client, y compris les builds navigateur, de se connecter à `wss://<id>.pr.edgegap.net:<port>`. Edgegap termine TLS et transmet HTTP en clair et WebSocket vers le port `2567`, afin que la requête HTTP de matchmaking Colyseus et le WebSocket de la salle partagent un seul port. Voir [Websockets (WS) et Websockets sécurisés (WSS)](https://docs.edgegap.com/fr/learn/orchestration/deployments.md#websockets-ws-and-secure-websockets-wss).
{% endhint %}

Facultativement, définissez des variables d’environnement sur votre version d’application :

* `MATCH_ROUNDS` - terminez la partie après ce nombre de manches gagnées (par défaut `0`, une arène sans fin),
* `FIRST_JOIN_TIMEOUT_S` - secondes avant qu’un serveur que personne n’a rejoint ne s’arrête de lui-même (par défaut `120`),
* `EMPTY_TIMEOUT_S` - nombre de secondes avant qu’un serveur dont tout le monde est parti s’arrête tout seul (par défaut `30`).

✅ Vous pouvez maintenant passer à l’étape suivante.

### 3. Connexion directe

☑️ Démarrez un serveur près de vous avec le script de déploiement de l’exemple. Votre jeton API Edgegap reste sur votre machine :

{% code collapsedlinecount="10" %}

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

{% endcode %}

Le script affiche `wss://<request_id>.pr.edgegap.net:<port>` et comment le transmettre à chaque client.

☑️ Transmettez l'URL à vos clients :

* **Three.js, PlayCanvas, Construct 3** - `?server=wss://...` dans l'URL de la page,
* **Godot** - `--server=wss://...` (après `--` dans les arguments d'exécution principaux de l'éditeur), exportation web `?server=wss://...`,
* **Unity** - `--server=wss://...` en ligne de commande, WebGL `?server=wss://...`, ou le `serverUrl` champ,
* **Defold** - HTML5 `?server=wss://...`, natif `--config=tanks.server_url=wss://...` ou `[tanks] server_url` dans `game.project`,
* **GameMaker** - `--server=wss://...` en ligne de commande, HTML5 `?server=wss://...`,
* **Haxe** - JS `?server=wss://...`, HashLink `--server=wss://...`,
* **MonoGame** - `--server=wss://...` ou `TANKS_SERVER_URL` variable d'environnement.

{% hint style="danger" %}
Dans une partie en direct, votre backend appelle le même [API de déploiement](https://docs.edgegap.com/fr/docs/api/serveurs-dedies.md) (`POST /v2/deployments`) lorsqu'un lobby est prêt et envoie l'URL à ses joueurs. **Ne mettez jamais votre jeton API Edgegap dans un client de jeu ou une image de serveur.**
{% endhint %}

🙌 Félicitations pour votre premier déploiement sur Edgegap !

### 4. Ajouter le Matchmaker (facultatif)

☑️ Ouvrez la page [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) page du tableau de bord, cliquez sur **Créer**, et téléversez `edgegap/matchmaker-config.json` depuis l’exemple.

La configuration contient un seul `casual` profil pour 2 à 8 joueurs par partie. Après 15 secondes, il démarre une partie avec tous les joueurs en attente, avec au moins 2 joueurs.

☑️ Ajoutez chaque origine qui sert votre jeu à `allowed_cors_origins`, car les builds navigateur appellent le matchmaker depuis la page (voir [CORS](https://docs.edgegap.com/fr/learn/matchmaking/matchmaker-in-depth.md#cross-origin-resource-sharing-cors)). La configuration permet `http://localhost:5173` (Vite), `http://localhost:8060` (Godot web) et `http://localhost:8080`.

☑️ Cliquez sur **Créer et démarrer**. Une fois que votre matchmaker affiche **En ligne**, copiez son **URL API** et **jeton d’authentification**.

{% hint style="danger" %}
**N'intégrez pas les points de terminaison de l'API Edgegap dans le client du jeu, car votre jeton d'API fournit un accès illimité à votre compte. Voir** [Intégration](https://docs.edgegap.com/fr/docs/api/integration.md) **pour des points de terminaison et des fonctions d'API sécurisés destinés au client.**
{% endhint %}

{% hint style="info" %}
Le jeton d'authentification du matchmaking est limité à votre matchmaker uniquement, il est donc sûr de l'inclure dans les clients du jeu.
{% endhint %}

☑️ Démarrez vos clients avec les paramètres du matchmaker :

* **Three.js** - `http://localhost:5173/?mm=<API URL>&mmToken=<Auth Token>`, ou `VITE_MM_URL` / `VITE_MM_TOKEN` dans `.env.local`,
* **Unity** - `--mm=<API URL> --mm-token=<Auth Token>`, WebGL `?mm=...&mmToken=...`, ou *Matchmaker Edgegap* champs dans `GameManager`,
* **Godot** - `-- --mm=<API URL> --mm-token=<Auth Token>`, exportation web `?mm=...&mmToken=...`.

☑️ Ouvrez deux clients - le matchmaking nécessite au moins 2 joueurs, et ils peuvent utiliser des moteurs différents.

Chaque client affiche « Recherche de joueurs... » et se connecte une fois qu'un serveur lui est attribué. Un `serveur` paramètre a toujours priorité sur le matchmaker.

🙌 Félicitations pour votre premier déploiement avec matchmaking sur Edgegap !

## 🔄 Cycle de vie de la partie

1. Le client crée un ticket avec `POST /tickets` pendant `casual` profil, puis le vérifie toutes les 2 secondes avec `GET /tickets/{id}`.
2. Le matchmaker déploie `realtime-tanks` près des joueurs. Lorsque le ticket atteint `HOST_ASSIGNED`, le client lit le FQDN et le port externe de l'attribution `gameport`.
3. Le client rejoint `wss://<fqdn>:<port>`. Un serveur tout juste démarré peut répondre 502 pendant quelques secondes, donc les clients réessaient de se connecter pendant jusqu'à 20 secondes (voir [Se connecter au serveur](https://docs.edgegap.com/fr/learn/matchmaking/matchmaker-in-depth.md#connect-to-server)).
4. Appels du serveur `ARBITRIUM_DELETE_URL` pour arrêter son propre déploiement lorsque personne n'a rejoint dans un délai de `FIRST_JOIN_TIMEOUT_S`, lorsque tout le monde est parti pendant `EMPTY_TIMEOUT_S`, ou lorsque `MATCH_ROUNDS` des manches ont été remportées. La durée maximale de votre version d'application sert de filet de sécurité.

Le client du matchmaker est léger et sans dépendances, il se porte donc facilement vers d'autres clients - voir `web-threejs/src/Matchmaker.ts`, `unity/Assets/Scripts/EdgegapMatchmaker.cs` et `godot/scripts/edgegap_matchmaker.gd`.

Voir [Matchmaking](https://docs.edgegap.com/fr/learn/matchmaking.md) et [Déploiements](https://docs.edgegap.com/fr/learn/orchestration/deployments.md) pour en savoir plus.

## 🚀 Aller plus loin

* **Valider les joueurs qui rejoignent** - les déploiements du matchmaker obtiennent [`MM_TICKET_IDS`](https://docs.edgegap.com/fr/learn/matchmaking/matchmaker-in-depth.md#injected-variables). Faites passer aux clients l'identifiant de leur ticket dans les options de connexion et vérifiez-le dans `onAuth`, afin que seuls les joueurs appariés puissent rejoindre.
* **Avant le lancement** - définissez `inspect` à `false` dans votre configuration de matchmaker, listez vos véritables origines et augmentez la durée maximale pour qu'elle corresponde à vos parties (voir [Avant la mise en production](https://docs.edgegap.com/fr/learn/matchmaking/matchmaker-in-depth.md#before-going-live)).

## ⚠️ Problèmes connus

* Testé de bout en bout sur Edgegap avec Colyseus 0.17, matchmaker 3.3.2, Godot 4.5.2 et Unity 6000.3 :
  * direct - les clients Node Colyseus et le client Godot de bureau ont rejoint un déploiement via `wss://`, et le serveur s'est arrêté de lui-même après le départ de tous,
  * matchmaker - Three.js dans le navigateur et le client Godot de bureau ont été appariés sur un seul serveur, puis Three.js et une version Windows de Unity.
* Construct 3, Defold, GameMaker, Haxe et PlayCanvas `serveur` les remplacements, l'exportation web Godot et Unity WebGL ne sont pas encore testés.
