Découvrez comment fonctionne Edgegap

Découvrez comment fonctionne Edgegap

/

Colyseus

/

Colyseus

Déployer sur Edgegap

Publié

Publié

Publié

Colyseus : Comment intégrer et héberger des serveurs dédiés, et ajouter le Matchmaking à votre jeu multijoueur

Colyseus : Comment intégrer et héberger des serveurs dédiés, et ajouter le Matchmaking à votre jeu multijoueur

Ce guide vous montre comment héberger n'importe quel jeu multijoueur Colyseus sur les serveurs de jeu dédiés d'Edgegap, puis comment ajouter le matchmaking afin que les joueurs soient regroupés et connectés automatiquement à un serveur proche d'eux.

Une fois votre serveur de jeu conteneurisé, Edgegap le déploie à travers le monde sur plus de 615 emplacements Edge Cloud (à la demande) à partir d'un simple appel d'API, avec une facturation basée exclusivement sur l'utilisation : aucun serveur entier à louer, à provisionner ou à maintenir en fonctionnement entre les matchs. Pour les serveurs persistants à capacité réservée, Edgegap propose les Private Fleets. Le Matchmaking d'Edgegap s'appuie sur cette base et est optionnel.

Vos salons (rooms), vos schémas et vos SDK clients restent les mêmes. La configuration la plus simple, et celle testée par ce guide, attribue à chaque match son propre serveur Colyseus : Edgegap le démarre à proximité des joueurs du match et il s'arrête de lui-même lorsque le match est terminé, vous évitant ainsi d'avoir recours à PM2, à la présence Redis ou à la planification de capacité par nombre de salons. Un serveur peut également héberger plusieurs salons, par exemple un lobby et ses matchs : il s'arrête alors 30 secondes après le départ du dernier joueur, même si un salon reste ouvert. Pour les serveurs toujours actifs, utilisez les Private Fleets.

Ce guide couvre :

  1. La préparation de votre projet Colyseus, de votre compte Edgegap et d'un outil de conteneurisation

  2. La connexion de votre agent de programmation à Edgegap (optionnel)

  3. La préparation de votre serveur Colyseus pour Edgegap

  4. La conteneurisation du serveur et la création d'une version d'application

  5. Le déploiement d'un serveur de test et la connexion d'un client

  6. L'ajout du matchmaking (optionnel)

  7. L'orientation de vos autres clients vers Edgegap

  8. Le test de la boucle complète avec deux joueurs

Vous pouvez procéder de deux manières, ou les combiner :

  • Avec un agent de programmation. Connectez Claude Code, Cursor ou un autre agent au serveur MCP Edgegap et à ses compétences d'agent (skills). La compétence edgegap-colyseus apporte les modifications au serveur, écrit le Dockerfile, déploie un serveur de test et intègre le matchmaker dans vos clients. Vous gérez le tableau de bord Edgegap, les secrets et les phases de test.

  • Manuellement. Chaque étape ci-dessous fonctionne également sans agent.

Le guide utilise le fork d'Edgegap de la démo officielle Colyseus Realtime Tanks : un serveur Colyseus 0.17 et neuf clients, allant de Three.js à Unity et Godot. L'hébergement Edgegap est déjà intégré dans le fork, vous pouvez donc l'exécuter tel quel ou l'utiliser comme référence pour votre propre jeu.

Aucune carte de crédit requise. L'offre gratuite inclut les ressources nécessaires pour déployer un véritable serveur de jeu.

Aucune carte de crédit requise. L'offre gratuite inclut les ressources nécessaires pour déployer un véritable serveur de jeu.

Colyseus's Realtime Tanks demo, a multiplayer tank battle running on Edgegap dedicated game servers.

Démo Realtime Tanks de Colyseus, fonctionnant sur Edgegap

Guide étape par étape

Étapes d'intégration détaillées

1. Avant de commencer

  • Un compte Edgegap gratuit. Vérifiez votre adresse e-mail. Aucune carte de crédit n'est requise pour tester.

  • Un serveur Colyseus. Ce guide utilise Colyseus 0.17 (defineServer / defineRoom). Colyseus 0.15 et 0.16 devraient fonctionner de la même manière, avec un point d'entrée différent, mais n'ont pas été testés.

  • Node.js (version 22 recommandée) et un outil de conteneurisation, en cours d'exécution. Nous recommandons Docker Desktop.

  • Clients Unity : le client de matchmaking Unity du fork nécessite Unity 2023.1 ou Unity 6 (il utilise Awaitable).

  • Pour le parcours avec l'agent : un jeton d'API Edgegap, accessible depuis Tableau de bord → Paramètres utilisateur → Jetons. Il s'applique à l'ensemble de l'organisation, traitez-le donc comme un mot de passe : ne le placez jamais dans un client, dans l'image de votre serveur ou dans un chat.

Raccourci : lancez d'abord l'exemple. Clonez le fork Realtime Tanks, puis suivez les étapes 4 à 8 avec son dossier server/. Toutes les modifications de l'étape 3 y sont déjà incluses. Sous Windows, exécutez git config --global core.longpaths true avant de cloner : certains chemins de fichiers clients sont trop longs pour les valeurs par défaut de Windows.

2. Connectez votre agent de codage à Edgegap

Ignorez cette étape si vous faites tout manuellement.

Le serveur MCP Edgegap permet à votre agent de créer des applications et des versions, de déployer des serveurs, de lire les journaux et de générer des configurations de matchmaker sur votre compte. La compétence edgegap-colyseus lui fournit les fichiers testés avec Realtime Tanks : un module de cycle de vie, un Dockerfile, un script de déploiement, une configuration de matchmaker ainsi que des clients de matchmaker pour navigateur, Unity et Godot.

Claude Code : installez le plugin Edgegap. Il ajoute à la fois le serveur MCP et les compétences, et demande votre jeton d'API lors de l'installation (enregistré dans le gestionnaire d'identifiants de votre système) :

/plugin marketplace add edgegap/llm-agent-skills, puis /plugin install edgegap@edgegap. Redémarrez la session.

Vous souhaitez uniquement le serveur MCP, sans le plugin ? Exécutez plutôt ceci dans votre propre terminal : claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user. Ne faites pas les deux, sinon vous aurez deux serveurs edgegap.

Cursor, VS Code et les autres clients qui envoient des en-têtes : ajoutez https://mcp.edgegap.dev/mcp avec l'en-tête Authorization: token YOUR_EDGEGAP_API_TOKEN, puis installez les compétences avec npx skills add edgegap/llm-agent-skills --skill "*".

Claude Desktop : les connecteurs personnalisés ne peuvent pas envoyer l'en-tête, utilisez donc plutôt le serveur local (Node 22) : { "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }. Il demande le jeton lors de la première utilisation.

Vérifiez que cela fonctionne :

« Liste mes applications Edgegap. »

3. Préparez votre serveur Colyseus pour Edgegap

Edgegap démarre un serveur lorsqu'un match en a besoin. Seul votre jeu sait quand le match est terminé, le serveur arrête donc son propre déploiement. Sinon, un serveur vide continue de fonctionner, et d'être facturé, jusqu'à sa durée maximale.

Trois modifications, dans server/src/edgegap.ts du fork et son BattleRoom.ts :

  • Un module de cycle de vie qui s'exécute uniquement sur Edgegap (lorsque ARBITRIUM_REQUEST_ID est défini, ce que fait Edgegap à chaque déploiement). Il arrête le déploiement lorsque personne ne s'est connecté dans les 120 secondes, lorsque tout le monde est parti et que personne n'est revenu dans les 30 secondes, ou lorsque le match se termine.

  • Comptez les joueurs dans vos salles : appelez playerJoined() dans onJoin et playerLeft() lorsqu'une place est réellement libérée. Avec allowReconnection, c'est après l'échec du délai de reconnexion, pas lors de la déconnexion immédiate. La reconnexion n'a pas été testée sur Edgegap ; avec un serveur par match, un client qui se reconnecte doit enregistrer l'adresse du serveur avec son jeton de reconnexion.

  • Terminez le match si votre jeu en a un : verrouillez la salle, affichez le résultat pendant quelques secondes, faites un disconnect(), puis arrêtez. Realtime Tanks fait cela après MATCH_ROUNDS manches gagnées (par défaut 0, une arène sans fin).

Désactivez également le playground et le moniteur sur Edgegap : toute personne possédant l'adresse du serveur pourrait les ouvrir. Le fork ne les monte que lorsqu'il ne fonctionne pas sur Edgegap, ainsi npm run dev fonctionne exactement comme avant.

Avec votre agent :

« Charge la compétence edgegap, puis edgegap-colyseus. Ajoute le module de cycle de vie à mon serveur Colyseus, compte les joueurs dans chaque salle, arrête le serveur lorsqu'un match se termine et désactive le playground et le moniteur sur Edgegap. Ensuite, teste-le localement dans Docker. »

4. Conteneurisez le serveur et créez une version de l'application

Edgegap exécute des conteneurs linux/amd64. Le server/Dockerfile du fork démarre à partir de node:22-slim et exécute Node en tant que processus principal, afin que votre serveur reçoive le signal d'arrêt d'Edgegap et que Colyseus ferme proprement ses salles.

Compilez pour la plateforme d'Edgegap, même sur Apple Silicon, avec un nouveau tag pour chaque build :

cd server

docker build --platform linux/amd64 -t registry.edgegap.com/<project>/realtime-tanks:v1 .

Testez l'image localement avant de la pousser. ARBITRIUM_REQUEST_ID lui permet de se comporter comme sur Edgegap : docker run --rm -p 2567:2567 -e ARBITRIUM_REQUEST_ID=local -e EMPTY_TIMEOUT_S=10 registry.edgegap.com/<project>/realtime-tanks:v1. Un client sur ws://localhost:2567 se connecte, et 10 secondes après son départ, le conteneur se ferme.

Ensuite, exécutez docker login registry.edgegap.com avec les identifiants de la page Container Registry, puis docker push registry.edgegap.com/<project>/realtime-tanks:v1.

Créez l'application et la version dans le tableau de bord :

  • Votre image et tag, avec les identifiants du registre.

  • 0,25 vCPU et 512 Mo pour commencer.

  • Port 2567, protocole WS, nom gameport, avec l'option TLS Upgrade activée.

  • Une durée maximale de 60 minutes pendant les tests.

TLS Upgrade permet à chaque client, y compris les builds pour navigateur, de se connecter avec wss://. Edgegap gère le certificat et transfère le trafic HTTP et WebSocket standard vers le port 2567. La requête de matchmaking de Colyseus et la connexion à la salle utilisent toutes deux ce port unique.

Avec votre agent :

« Compile mon serveur Colyseus pour linux/amd64, pousse-le avec un nouveau tag et crée l'application et la version Edgegap : port 2567, protocole WS, TLS Upgrade activé, nommé gameport, 0,25 vCPU et 512 Mo, 60 minutes max. »

5. Déployez un serveur de test et connectez un client

Démarrez un serveur près de chez vous à partir du script de déploiement du fork. Votre jeton d'API reste sur votre machine :

macOS et Linux : EDGEGAP_API_TOKEN=<token> npm run edgegap:deploy -- realtime-tanks v1

Windows (PowerShell) : $env:EDGEGAP_API_TOKEN="<token>"; npm run edgegap:deploy -- realtime-tanks v1

Il affiche wss://<request_id>.pr.edgegap.net:<port>. Vous pouvez également déployer depuis le tableau de bord (Deploy, choisissez un emplacement proche de chez vous), ou demander à votre agent : « Déploie ma dernière version d'Edgegap près de chez moi, attends qu'elle soit prête et donne-moi l'adresse wss://. »

Transmettez l'adresse à un client. Dans le client Three.js, ajoutez ?server=wss://... à l'adresse de la page ; dans Godot ou un build desktop Unity, démarrez-le avec --server=wss://.... Utilisez toujours le nom d'hôte, et non l'adresse IP, sinon la vérification du certificat échouera.

Si la première tentative de connexion renvoie une erreur 502, réessayez : un serveur qui vient de démarrer peut répondre par une 502 pendant quelques secondes. Les clients du fork réessaient pendant un maximum de 20 secondes.

Lorsque le client quitte, les journaux du serveur affichent self-stop: empty for 30s et le déploiement disparaît du tableau de bord. L'offre gratuite exécute un seul déploiement à la fois.

Dans un jeu réel sans le matchmaker d'Edgegap, votre backend ou lobby appelle la même API Deploy (POST /v2/deployments) lorsqu'un groupe est prêt, et envoie l'adresse à ses joueurs. Ensuite, laissez le matchmaker s'en charger pour vous.

6. Ajouter le matchmaking

Le matchmaker d'Edgegap regroupe les joueurs, déploie votre serveur à proximité d'eux et fournit son adresse à chaque client. Les clients Three.js, Unity et Godot du fork envoient un ticket, affichent « Recherche de joueurs... » et se connectent une fois le serveur attribué. Testé sur Edgegap : Three.js dans le navigateur, Godot sur ordinateur et une version Windows Unity. Unity WebGL et l'export web Godot n'ont pas été exécutés.

  1. Partez du fichier matchmaker-config.json du fork. Son profil casual associe de 2 à 8 joueurs, et après 15 secondes, il lance une partie avec les personnes en attente (au moins 2). Définissez-y le nom et la version de votre application.

  2. Versions pour navigateur : listez chaque adresse web qui héberge votre jeu dans allowed_cors_origins, sinon le navigateur bloque les réponses du matchmaker. Le fichier autorise uniquement les serveurs de développement locaux. Excluez toute règle de latence pour les joueurs sur navigateur : les navigateurs ne peuvent pas envoyer les pings de latence utilisés par les jeux sur ordinateur.

  3. Dans le tableau de bord, ouvrez Matchmaker, sélectionnez Create Matchmaker, téléversez le fichier et sélectionnez Create and Start.

  4. Lorsqu'il affiche Online, copiez son API URL et son Auth Token. Le Auth Token est destiné à être intégré à votre jeu : il ne peut que créer et lire des tickets de matchmaking. Il ne s'agit pas de votre jeton d'API Edgegap.

  5. Fournissez-les aux clients : Three.js ?mm=<API URL>&mmToken=<Auth Token> (ou VITE_MM_URL / VITE_MM_TOKEN), Unity --mm=<API URL> --mm-token=<Auth Token> ou les champs sur GameManager, Godot -- --mm=<API URL> --mm-token=<Auth Token>. Un paramètre server a toujours la priorité sur le matchmaker.

Avec votre agent :

« En utilisant la compétence edgegap-colyseus, ajoutez le matchmaking Edgegap à mes clients : un profil casual de 2 à 8 joueurs, mes origines web dans allowed_cors_origins, et une tentative de connexion qui réessaye après l'attribution du serveur. »

Manuellement : consultez la documentation de Matchmaking.

7. Pointez vos autres clients vers Edgegap

Chaque SDK client Colyseus se connecte à la même adresse wss://. Le fork intègre le mode direct dans l'ensemble de ses neuf clients. Seuls les clients Three.js, Godot pour ordinateur de bureau et Unity Windows ont été exécutés sur Edgegap ; les paramètres ci-dessous pour les autres clients ont été écrits mais non testés :

  • Three.js, PlayCanvas, Construct 3 : ?server=wss://... dans l'adresse de la page.

  • Godot : --server=wss://... ; export web : ?server=wss://....

  • Unity : --server=wss://..., le champ serverUrl ou ?server=wss://... dans WebGL.

  • Defold : HTML5 ?server=wss://... ; natif --config=tanks.server_url=wss://....

  • GameMaker, Haxe, MonoGame : --server=wss://... (builds HTML5 et JS : ?server=wss://... ; MonoGame lit également TANKS_SERVER_URL).

Le client du matchmaker est léger et ne comporte aucune dépendance, il se porte donc facilement sur d'autres moteurs. Commencez à partir de Matchmaker.ts, EdgegapMatchmaker.cs ou edgegap_matchmaker.gd.

8. Testez la boucle complète avec deux joueurs

  1. Assurez-vous qu'aucun déploiement de test n'est toujours en cours d'exécution. Sur l'offre gratuite, un déploiement restant bloque le déploiement du matchmaker.

  2. Ouvrez deux clients avec les paramètres du matchmaker. Il peut s'agir de moteurs différents, par exemple le client Three.js dans un navigateur et une version de bureau Godot.

  3. Sélectionnez Jouer dans les deux : recherche en cours, puis tous deux atterrissent dans la même arène. Le journal du serveur affiche les deux identifiants de ticket.

  4. Quittez les deux. Trente secondes plus tard, le serveur arrête son propre déploiement et celui-ci disparaît du tableau de bord.

Avant le lancement : définissez inspect sur false dans la configuration du matchmaker, listez vos véritables origines Web, augmentez la durée maximale pour l'adapter à vos matchs et n'autorisez que les joueurs mis en correspondance (chaque déploiement mis en correspondance reçoit ses identifiants de ticket dans MM_TICKET_IDS ; vérifiez-les dans onAuth).

Sur l'offre gratuite, le matchmaker s'arrête 3 heures après chaque démarrage (redémarrez-le depuis le tableau de bord), les déploiements s'arrêtent après 60 minutes et un seul déploiement s'exécute à la fois.

Étapes suivantes

Étapes suivantes

Vous passez en production ? Demandez à votre agent d'exécuter la liste de contrôle de la compétence edgegap-launch.

Bloqué ? Demandez à votre agent de charger edgegap-troubleshoot, ou posez vos questions à notre équipe et aux autres studios sur le Discord d'Edgegap.

Questions Fréquemment Posées

Questions fréquentes sur l'hébergement de jeux Colyseus sur les serveurs dédiés d'Edgegap.

Comment héberger un serveur Colyseus ?

Empaquetez votre serveur Colyseus sous forme de conteneur avec le port 2567 exposé, puis exécutez-le sur un hôte. Sur Edgegap, chaque partie dispose de son propre serveur situé à proximité de ses joueurs, accessible via wss:// avec une mise à niveau TLS (TLS Upgrade), et le serveur s'arrête de lui-même lorsque la partie se termine.

Un serveur Colyseus peut-il exécuter plusieurs salles sur Edgegap ?

Oui. Un déploiement exécute un processus Colyseus, qui peut héberger n'importe quel nombre de salles ; il s'arrête de lui-même 30 secondes après le départ du dernier joueur. La plupart des jeux utilisent plutôt un match par déploiement, ce qui élimine le besoin de PM2, de présence Redis ou d'un équilibreur de charge.

Est-ce que Colyseus fonctionne avec Unity et Godot sur Edgegap ?

Oui. Les SDK Unity et Godot de Colyseus se connectent à l'adresse wss:// du serveur comme n'importe quel autre client. L'exemple Realtime Tanks inclut le matchmaking Edgegap pour ses clients Three.js, Unity et Godot, testé de bout en bout sur Edgegap avec des builds Three.js, Godot pour ordinateur et Unity Windows.

Comment les clients de navigateur se connectent-ils en toute sécurité à un serveur Colyseus ?

Une page servie via https:// ne peut ouvrir que des WebSockets sécurisés (wss://). Activez la mise à niveau TLS (TLS Upgrade) sur le port WS du serveur : Edgegap gère le certificat et transfère le trafic non chiffré vers Colyseus, de sorte que le serveur n'a besoin d'aucun certificat.

Ai-je besoin du système de matchmaking de Colyseus avec Edgegap ?

Colyseus gère toujours l'accès à la salle sur son serveur. Le matchmaker d'Edgegap décide quels joueurs jouent ensemble et démarre leur serveur. Vous pouvez également ignorer cette étape et faire en sorte que votre backend démarre les serveurs grâce à l'API Deploy d'Edgegap.

Clients

Découvrez les témoignages de clients qui ont intégré Edgegap

31 études de cas sont disponibles auprès de studios ayant migré d'une autre plateforme vers Edgegap.

Principales raisons pour lesquelles ils ont choisi Edgegap

Découvrez l’impact de l’orchestration automatisée des serveurs de jeu d’Edgegap pour une expérience multijoueur impeccable.

Coût

Prix

Prix

Optimisez les coûts et les performances grâce à l'orchestration hybride

Optimisez les coûts et les performances grâce à l'orchestration hybride

Optimisez les coûts et les performances grâce à l'orchestration hybride

Cloud de périphérie

À la demande

0,00115 $

/ vCPU

/ MINUTE

Facturé à la minute, uniquement à l'utilisation

Payez quand les joueurs jouent. 0 serveur actif = 0 $

Déployez des serveurs de jeu dans le monde entier, par instance, dans plus de 615 emplacements edge cloud. Sans engagement.

Ajoutez simplement une carte de crédit.

Cloud de périphérie

À la demande

0,00115 $

/ vCPU

/ MINUTE

Facturé à la minute, uniquement à l'utilisation

Payez quand les joueurs jouent. 0 serveur actif = 0 $

Déployez des serveurs de jeu dans le monde entier, par instance, dans plus de 615 emplacements edge cloud. Sans engagement.

Ajoutez simplement une carte de crédit.

Private Fleet (Bare Metal)

Capacité réservée

0,0261 $

/ vCPU

/ HEURE

Facturé mensuellement, toujours actif

280 $ par hôte/mois (tarif sur 12 mois), ou 350 $ par mois

Optimisez la rentabilité de votre serveur de jeu grâce à l'hébergement sans frais de transfert de données sortantes (egress-free) des flottes privées (Private Fleets).

Permanent, disponible 24h/24 et 7j/7, exclusif à votre studio.

Private Fleet (Bare Metal)

Capacité réservée

0,0261 $

/ vCPU

/ HEURE

Facturé mensuellement, toujours actif

280 $ par hôte/mois (tarif sur 12 mois), ou 350 $ par mois

Optimisez la rentabilité de votre serveur de jeu grâce à l'hébergement sans frais de transfert de données sortantes (egress-free) des flottes privées (Private Fleets).

Permanent, disponible 24h/24 et 7j/7, exclusif à votre studio.

Votre facture varie selon le tarif et l'utilisation, qui peuvent varier en fonction
du type de jeu, du nombre de joueurs et plus encore.

Votre facture varie selon le tarif et l'utilisation, qui peuvent varier en fonction
du type de jeu, du nombre de joueurs et plus encore.

Modélisez votre utilisation avec notre calculateur d'estimation ->

Modélisez votre utilisation avec notre calculateur d'estimation ->

Fonctionnalités et tarifs d'Edgegap : comparaison détaillée entre Edge Cloud et Private Fleets

Fonctionnalités et tarifs d'Edgegap : comparaison détaillée entre Edge Cloud et Private Fleets

COMPARER

Essai gratuit

Cloud de périphérie

Flottes privées

FONCTIONNALITÉS

Analyses et surveillance

Alertes de facturation

Cliquer pour agrandir

28 lignes de plus

Déverrouille

Les fonctionnalités sont débloquées lorsqu'une carte de crédit est ajoutée au compte.

COMPARER

Essai gratuit

Cloud de périphérie

Flottes privées

FONCTIONNALITÉS

Analyses et surveillance

Alertes de facturation

Cliquer pour agrandir

28 lignes de plus

Déverrouille

Les fonctionnalités sont débloquées lorsqu'une carte de crédit est ajoutée au compte.

COMPARER

Essai gratuit

Cloud de périphérie

Flottes privées

FONCTIONNALITÉS

Analyses et surveillance

Alertes de facturation

Cliquer pour agrandir

28 lignes de plus

Déverrouille

Les fonctionnalités sont débloquées lorsqu'une carte de crédit est ajoutée au compte.