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

# Minijeux Three.js

Multijoueur three.js avec appariement : cinq minijeux de navigateur où l’appariement lance un serveur Node.js faisant autorité par partie.

Découvrez comment créer des jeux multijoueurs three.js avec appariement.

![Multijoueur Three.js avec matchmaker](https://raw.githubusercontent.com/edgegap/netcode-sample-threejs-minigames/main/docs/images/banner.jpg)

Cet exemple comprend cinq petits jeux de navigateur, un par genre, créés avec [three.js](https://threejs.org/) et de simples serveurs WebSocket Node.js. Les joueurs cliquent **Trouver une partie** sur la page, le matchmaker les regroupe et démarre un serveur dédié près d’eux, pour se connecter et jouer. Lorsque la partie est terminée, le serveur s’arrête tout seul.

Cet exemple inclut 5 mini-jeux :

* Blaster Arena : bataille générale en vue du dessus, premier à 10 éliminations. 2 à 8 joueurs, des bots remplissent jusqu’à 3 au total.
* Kart Rally : course, premier à 3 tours. 1 à 8 joueurs.
* Rocket Soccer : sport, équipes en 1v1 ou 2v2. 2 à 4 joueurs au total.
* Light Cycles : arcade, dernier survivant. 2 à 6 joueurs, des bots remplissent jusqu’à 4 au total.
* Sumo Push : jeu de fête, roi de la colline. 2 à 8 joueurs, des bots remplissent jusqu’à 4 au total.

Cet exemple montre :

* **Appariement depuis le navigateur** avec le [SDK JavaScript Edgegap](https://www.npmjs.com/package/@edgegap/sdk) (`@edgegap/sdk`) : trouvez une partie, annulez et réessayez en cas de limitation de débit, avec un seul matchmaker et un profil par jeu, y compris un profil à 2 équipes.
* **Serveurs autoritaires**: la page n’envoie que les entrées et affiche l’état qu’elle reçoit, donc les joueurs ne peuvent pas changer les règles depuis le navigateur.
* **Un serveur par partie**, a dépassé `wss://` grâce à la mise à niveau TLS. Il lit les détails de sa partie avec le SDK, et arrête son propre déploiement lorsque la partie se termine, lorsque tout le monde part ou lorsque personne ne rejoint.
* **Une seule image pour cinq jeux**: une version d’application par jeu, avec une `GAME` variable d’environnement choisissant le serveur.
* **Pas d’étape de build**: Three.js et le build navigateur du SDK se chargent depuis un CDN via une map d’importation, donc les pages sont des fichiers statiques que vous pouvez héberger partout.

{% hint style="info" %}
Voir le [dépôt d’exemple](https://github.com/edgegap/netcode-sample-threejs-minigames) pour les règles et la conception du serveur de chaque jeu, les [notes d’architecture](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/architecture.md) et un guide pour [ajouter votre propre jeu](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/adding-a-game.md).
{% endhint %}

## ✔️ Préparation

Avant de commencer, vous aurez besoin de :

* [Exemple de minijeux Three.js](https://github.com/edgegap/netcode-sample-threejs-minigames).
* [Node.js](https://nodejs.org/) 22 ou plus récent, pour exécuter les serveurs et les pages localement.
* [Docker](https://docs.docker.com/get-started/get-docker/), pour construire l’image du serveur.

☑️ Essayez d’abord les jeux en local :

{% code collapsedlinecount="10" %}

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

{% endcode %}

Cela démarre les cinq serveurs de jeu sur les ports `7771` à `7775` et sert les pages à `http://localhost:8080`. Choisissez un jeu, cliquez sur **Serveur local**, et ouvrez un deuxième onglet pour jouer contre vous-même. `npm test` joue une partie complète de chaque jeu avec deux joueurs sans interface.

## ⚡ 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) 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 %}

☑️ Augmentez la valeur de votre tag, construisez et poussez l’image contenant le serveur de jeu :

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

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

### 2. Créez les versions d’application

☑️ [Créez une application](https://app.edgegap.com/application-management/applications/list) nommé `threejs-minigames`, et une version par jeu : `blaster-v1`, `kart-v1`, `soccer-v1`, `cycles-v1` et `sumo-v1`.

☑️ Configurez chaque version d’application :

* **Image**: `registry.edgegap.com/<project>/threejs-minigames`, tag `<tag>`,
* **Identifiants du registre**: votre nom d’utilisateur et votre jeton du registre de conteneurs, afin qu’Edgegap puisse récupérer l’image,
* **Ressources**: 0,25 vCPU et 512 Mo de mémoire,
* **Port**: `7777`, nom `gameport`, protocole **WS**, avec **mise à niveau TLS** activé,
* **Variable d’environnement**: `GAME` définie sur `blaster`, `kart`, `soccer`, `cycles` ou `sumo`,
* **Durée maximale**: 30 minutes, comme filet de sécurité : les serveurs s’arrêtent d’eux-mêmes.

{% hint style="warning" %}
**mise à niveau TLS** permet aux navigateurs sur `https` pages de se connecter à `wss://<id>.pr.edgegap.net:<port>`. Edgegap termine le TLS et transfère le trafic WebSocket brut vers le port `7777`. Connectez-vous avec le FQDN, pas avec l’IP, afin que le certificat corresponde.
{% endhint %}

Variables d’environnement facultatives, sur n’importe quelle version :

* `WAIT_SECONDS` - démarre ce délai après l’arrivée du premier joueur, même s’il manque des joueurs appariés (par défaut `15`),
* `MATCH_SECONDS` - limite de temps pour la partie (par défaut selon le jeu),
* `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`),
* `REQUIRE_TICKET` - `1` refuse les joueurs dont le ticket du matchmaker ne fait pas partie de cette partie.

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

### 3. Testez un seul serveur directement

☑️ 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
EDGEGAP_API_TOKEN=<token> node edgegap/deploy.mjs threejs-minigames sumo-v1
```

{% endcode %}

Le script affiche `wss://<request_id>.pr.edgegap.net:<port>`.

☑️ Ouvrez la page `http://localhost:8080/games/sumo/?server=wss://...` dans deux onglets du navigateur et jouez. Lorsque la partie se termine, le serveur arrête son propre déploiement.

{% hint style="danger" %}
**Ne mettez jamais votre jeton API Edgegap dans une page Web ou dans l’image du serveur.** Les joueurs obtiennent des serveurs via le matchmaker, qui utilise son propre jeton sûr côté client.
{% endhint %}

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

### 4. Créez le matchmaker

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

La configuration a un profil par jeu, chacun pointant vers la version d’application de ce jeu :

* `blaster`, `kart` et `sumo` : 2 à 8 joueurs, `cycles` : 2 à 6. Après 20 secondes, un joueur qui attend seul obtient un serveur, et les bots remplissent les places vides.
* `soccer`: `team_count: 2` avec 1 ou 2 joueurs par équipe, donc 2v2 lorsque quatre joueurs attendent, sinon 1v1. Chaque ticket reçoit un `team_id`, et le serveur place chaque joueur dans son équipe.

☑️ Les jeux de navigateur appellent le matchmaker depuis la page, donc ajoutez chaque origine qui sert vos pages à `allowed_cors_origins`. La configuration autorise `http://localhost:8080`.

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

{% hint style="info" %}
Pour les profils d’équipe, commencez avec `min_team_size: 1` plutôt que de compter sur une expansion. Dans nos tests, un `team_count: 2` profil avec `min_team_size: 2` et une expansion de 20 secondes vers `1` n’a apparié que deux joueurs en attente lorsque leurs tickets étaient sur le point d’expirer.
{% endhint %}

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

### 5. Trouver une partie

☑️ Placez l’URL de l’API et le jeton d’authentification du matchmaker dans `client/config.js` (ou un `client/config.local.js`ignoré par git), ou ajoutez `?mm=<API URL>&token=<Auth Token>` à l’URL de la page.

{% hint style="success" %}
La **Le jeton d’authentification du matchmaker peut être distribué sans risque dans les clients de jeu**: il ne peut servir qu’à trouver des parties. Ce n’est pas votre jeton API Edgegap.
{% endhint %}

☑️ Exécutez `npm run web` et ouvrez le même jeu dans deux onglets. Cliquez **Trouver une partie** dans les deux en moins de 20 secondes.

Chaque onglet utilise le `GroupAgent` du SDK pour :

1. créer un groupe de matchmaking d’un joueur pour le profil du jeu, prêt immédiatement,
2. attendre avec `nextAssignment()` jusqu’à ce que le groupe soit `HOST_ASSIGNED`, ce qui contient l’adresse du serveur et `gameport`,
3. se connecter à `getConnectionUrl(assignment, "gameport")`, ce qui donne `wss://<fqdn>:<port>`, et envoyer son ID de ticket, afin que le serveur sache dans quelle équipe se trouve le joueur.

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

Un nouveau déploiement peut refuser les connexions pendant quelques secondes après `HOST_ASSIGNED`, donc le client réessaie. Le SDK réessaie automatiquement les requêtes limitées par débit (`429`) et les requêtes échouées, et **Annuler** laisse le groupe avec `stopMatchmaking()`.

🙌 Les deux joueurs sont maintenant dans la même partie, sur un serveur placé près d’eux.

☑️ Pour tester tout le parcours sans navigateur, exécutez le test de bout en bout. Il place plusieurs joueurs sans interface en file d’attente pour chaque jeu, vérifie qu’ils arrivent sur le même déploiement et jouent une partie complète, puis attend que le déploiement s’arrête tout seul :

{% code collapsedlinecount="10" %}

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

{% endcode %}

## 📦 Déployez votre jeu

* Hébergez les pages partout : ce sont des fichiers statiques sans étape de build (`index.html`, `client/`, `games/`). Ajoutez chaque origine à `allowed_cors_origins`.
* Désactivez `inspect` dans la configuration du matchmaker avant le lancement.
* Définissez `REQUIRE_TICKET=1` sur les versions d’application pour exclure les joueurs que le matchmaker n’a pas envoyés.
* Pour déployer une nouvelle version du serveur, poussez une nouvelle balise d’image et pointez chaque version d’application vers elle. Les nouvelles parties l’utilisent, et celles en cours gardent l’ancienne version.
* Pour mettre à niveau le SDK, changez sa version dans `package.json` et dans la map d’importation de chaque page de jeu, puis mettez à jour le hash d’intégrité de la map d’importation.

{% hint style="info" %}
Vous utilisez un agent de codage ? La `edgegap-threejs` compétence dans [les compétences d’agent d’Edgegap](https://github.com/edgegap/llm-agent-skills) livre le serveur et le client de cet exemple sous forme de modèles, et guide votre agent à travers les mêmes étapes pour votre propre jeu de navigateur.
{% endhint %}
