Navigateur de serveurs

Ce SDK est un kit de démarrage optionnel pour les utilisateurs de Unity, qui peut être étendu et personnalisé par la suite.

💡 Fonctionnalités

Accédez à des fonctionnalités automatisées préconçues en installant notre SDK :

• Exemples complets

• Gestion du cycle de vie

• Gestion de la capacité

• Compilateur de requêtes de filtre

• Définitions de types (C#)

• Tests locaux en développement

• Multiplateforme

• Facile à personnaliser

• Nouvelle tentative automatisée

✔️ Préparation

Le SDK Unity contient des utilitaires d’intégration facultatifs pour les déploiements, le matchmaking et le navigateur de serveurs. Ce plugin prend officiellement en charge les versions 2021.3.0f1 et ultérieures de Unity.

La dernière version du SDK Unity est 3.5.3. Tous les exemples de cette documentation sont à jour.

Ce plugin est fourni 100 % gratuitement, selon les conditions générales de l’offre Free Tier.

Prérequis

Installez un client Git (par exemple git-scm)

Un client Git est nécessaire pour que Unity puisse télécharger et installer automatiquement notre package Unity. Une fois installé, vous n’aurez pas besoin d’utiliser Git directement.

Installation

1. Ouvrez votre projet Unity,

2. Sélectionnez Fenêtre > Gestion des paquets > Gestionnaire de paquets ,

3. Cliquez sur l’ ➕ icône puis sélectionnez Ajouter un package à partir de l’URL Git... ,

4. Saisissez l’URL de notre SDK lorsque vous y êtes invité :

https://github.com/edgegap/edgegap-unity-sdk.git

1. Cliquez sur Ajouter et attendez la fin de l’installation.

Importer des exemples

Ce package inclut plusieurs exemples, destinés à être utilisés individuellement (ne combinez pas les exemples).

Sources vérifiées

C’est le seul canal officiel de distribution de ce SDK, ne faites pas confiance aux sources non vérifiées !

Mettre à jour le package

Accédez au SDK Edgegap dans le Gestionnaire de paquets Unity et cliquez sur Mettre à jour .

Les exemples importés ne sont pas mis à jour automatiquement ! Sauvegardez les valeurs de propriétés personnalisées, supprimez les scripts d’exemple actuellement utilisés dans votre scène, puis réimportez les exemples.

Certaines versions peuvent contenir des changements cassants. Cela sera indiqué par une nouvelle version MAJEURE.

Mise à jour vers la v3

Cette mise à jour inclut de nombreux nouveaux Navigateur de serveurs utilitaires et exemples, améliore la gestion des erreurs de matchmaking, et plus encore. Consultez Notes de version pour la liste complète.

La mise à jour v3 du SDK Unity inclut quelques changements cassants. Veuillez retester soigneusement votre intégration.

🍀 Mise en route

Ce guide suppose une connaissance de base des Navigateur de serveurs concepts et d’un Server Browser en fonctionnement.

Nous recommandons vivement d’importer notre exemple d’auto-attribution pour suivre le code pendant que vous lisez ce document. Vous pouvez le faire dans Unity Package Manager > Edgegap SDK > Samples .

Aperçu

Notre SDK utilise largement l’injection de dépendances et Observateur des modèles de programmation.

Ce package intègre à la fois Navigateur de serveurs et Appariement, qui peuvent être utilisés ensemble ou séparément. Vous pouvez librement réutiliser n’importe quels scripts pour vos propres forks et intégrations personnalisés.

Ce package inclut :

• Fichiers d’exécution - seront compilés et intégrés à vos builds client et serveur :

  • Utilitaires spécifiques au service :

    • Navigateur de serveurs - une intégration serveur complète à réutiliser/étendre.

    • Navigateur de serveurs - une intégration client complète à réutiliser/étendre.

    • Fonctions API - définitions des points de terminaison, gestion des erreurs et automatisations de journalisation.

    • Compilateur de filtres - utilitaires fortement typés pour créer des requêtes de filtre.

  • Spécifique au service DTO - conteneurs de données typés pour l’API Server Browser.

  • Utilitaires partagés - journalisation, HTTP, ping, observables, etc...

  • Partagé DTO - utilisé par plusieurs services Edgegap pour faire circuler les données.

• Fichiers d’exemple - intégrés et compilés UNIQUEMENT s’ils sont importés dans votre projet :

  • Navigateur de serveurs - exemples de gestionnaires avec réservations auto-attribuées,

  • Navigateur de serveurs - exemples de gestionnaires avec sélection manuelle de l’instance.

Agent serveur

La gestion du cycle de vie et de la capacité du serveur est effectuée par l’Agent serveur.

Une fois instancié, le Monobehaviour parent (gestionnaire) doit initialiser l’agent et fournir :

• onMonitorUpdate callback - observer les changements d’état du service.

• onInstanceUpdate callback - observer et réagir aux changements d’instance et de slot.

• onConfirmationsUpdate callback - observer et réagir à l’authentification fédérée.

Une fois initialisé, cet agent fournira automatiquement des validations et connectera les observateurs de journalisation, en terminant par un appel unique au point de terminaison de l’API de surveillance pour indiquer l’état du service.

Le gestionnaire de l’agent est censé prendre le contrôle et appeler les fonctions de l’agent à partir de ce point :

• DiscoverInstance pour créer l’instance serveur et les slots initiaux et lancer le heartbeat.

• DeleteInstance une fois la partie terminée / pour empêcher de nouveaux joueurs de rejoindre.

• ConfirmReservation lorsque des joueurs rejoignent, pour vérifier leur identité et l’attribution du slot.

• UpdateSlot pour mettre à jour la capacité du slot (à l’arrivée/l’abandon d’un joueur) ou modifier les métadonnées.

• UpdateInstance pour modifier les métadonnées de l’instance.

• Statut pour vérifier l’état de santé du service Server Browser.

Les confirmations et les mises à jour de slot/instance sont mis en file d’attente et effectués par lots par défaut (mode Heartbeat) afin de maximiser la scalabilité. Pour itérer plus vite pendant les tests de développement, utilisez le mode Greedy.

Lors de la mise à jour des métadonnées, tous les index doivent être définis. Pour annuler les clés non indexées, il suffit de les omettre.

L’agent maintient automatiquement un heartbeat pour garder le serveur détectable pendant son exécution. Si l’agent ne peut pas atteindre votre Server Browser pendant plusieurs heartbeats consécutifs (configurable) :

• inférieur au maximum - l’instance sera automatiquement redécouverte,

• supérieur au maximum - l’instance sera automatiquement supprimée.

Lorsqu’une nouvelle connexion de joueur est établie, le joueur est censé envoyer son ID de réservation (ID de joueur tiers) au serveur de jeu via votre netcode, afin d’effectuer la confirmation de réservation.

Une fois onConfirmationsUpdate déclenché, le gestionnaire doit effectuer des actions supplémentaires :

• appeler UpdateSlot pour réduire les places disponibles pour tous les slots avec des réservations confirmées,

• accepter ou refuser la connexion à l’aide de méthodes spécifiques au netcode.

Lorsqu’un joueur abandonne la partie, le gestionnaire est censé augmenter les places disponibles pour ce slot.

Laissez un court délai aux joueurs pour se reconnecter avant d’abandonner, en cas de plantage inattendu.

Agent client

La recherche d’instances, la pagination, le filtrage et les réservations sont effectués par l’Agent client.

Une fois instancié, le Monobehaviour parent (gestionnaire) doit initialiser l’agent et fournir :

• onMonitorUpdate callback - observer les changements d’état du service.

• onInstancesUpdate callback - observer et réagir aux changements de la liste des instances.

Une fois initialisé, cet agent fournira automatiquement des validations et connectera les observateurs de journalisation, en terminant par un appel unique au point de terminaison de l’API de surveillance pour indiquer l’état du service.

Le gestionnaire de l’agent est censé prendre le contrôle et appeler les fonctions de l’agent à partir de ce point :

• ReserveSeats pour créer une réservation de capacité pour une instance/slot particulière ou en auto-attribution.

• ListInstances pour lister les instances avec un filtre, un tri, un curseur et une taille de page spécifiques.

• GetNextPage pour récupérer davantage d’instances avec les paramètres actuels (filtres, etc.).

• RefreshList pour vider le cache et recharger la première page, ou actualiser avec un curseur spécifique.

• GetInstanceDetails pour récupérer les métadonnées de l’instance et les informations de slots pour une instance spécifique.

• Statut pour vérifier l’état de santé du service Server Browser.

Lorsqu’une nouvelle connexion de joueur est établie, le joueur est censé envoyer son ID de réservation (ID de joueur tiers) au serveur de jeu via votre netcode, afin d’effectuer la confirmation de réservation.

Enregistrez les détails de connexion dans le client ou le backend du jeu pour pouvoir vous reconnecter en cas de plantage inattendu.

🧪 Exemples

Commencez avec des exemples incluant une intégration complète et fonctionnelle pour le serveur et le client.

Auto-attribution

Utilise des réservations auto-attribuées, le client ne spécifiant que le nom de la politique. Le Server Browser choisit automatiquement une instance correspondant au filtre de la politique et un slot avec suffisamment de places.

Recherche personnalisée

Inclut une implémentation complète démontrant comment rechercher des instances et des slots, connecter les éléments de l’interface utilisateur et laisser le joueur choisir manuellement où il souhaite réserver de la capacité.

⚙️ Personnalisation

Ce SDK est destiné à être étendu et modifié, bien que certaines modifications puissent être risquées :

✅ Gestionnaire - connecter en toute sécurité les observateurs de l’interface utilisateur et effectuer de petites additions ou modifications,

⚠️ Agent - modifiez le cycle de vie et la gestion de la capacité à vos propres risques,

⚠️ API - écrivez votre propre intégration de zéro, en utilisant des utilitaires soigneusement sélectionnés.

Les gestionnaires peuvent observer tous les événements émis par les agents Serveur et Client comme décrit ci-dessous.

Assurez-vous de bien vous familiariser avec Server Browser In-Depth les concepts avant d’effectuer des personnalisations.

Si vous avez besoin d’aide, veuillez nous contacter sur Discord. Pour l’assistance aux jeux en direct, consultez notre système de tickets.

Événements serveur

L’Agent serveur émet des événements (actions) que le gestionnaire parent doit observer et consommer.

Lire les charges utiles des événements en accédant à .Current état de n’importe quel observable. 🔴 Erreur les événements contiennent le message d’erreur complet délimité par un caractère de nouvelle ligne après le message principal de l’événement.

Aperçu des événements émis par l’observable Surveiller :

Type d’action	Message de l’événement	Description
🟢 Mise à jour	sain	Tous les systèmes sont opérationnels.
🟢 Mise à jour	malsain	Problème inattendu.
🔴 Erreur	échec de récupération du moniteur	Mauvaise configuration ou problème inattendu.
🟡 Avertissement	délai d’attente de la requête plafonné au heartbeat [{timeout}]	Empêche les conditions de concurrence.

Aperçu des événements (actions) émis par l’observable Instance:

Type d’action	Message de l’événement	Description
🟢 Mise à jour	découverte	Découverte de l’instance terminée avec succès. Peut être déclenchée si l’instance a perdu la connexion à cause d’une condition temporaire et a été redécouverte.
🔴 Erreur	doublon de découverte	Une instance avec cet ID de requête est déjà découverte.
🔴 Erreur	échec de la découverte	Problème inattendu lors de la découverte.
🔵 Notification	heartbeat OK	Heartbeat terminé avec succès.
🟡 Avertissement	échec du heartbeat [{consecutive}/{maximum}]	Échec du heartbeat, le serveur n’a pas pu atteindre le Server Browser.
🔵 Notification	mise en file d’attente de la mise à jour de l’instance	Mise à jour de l’instance mise en file d’attente pour le prochain lot (heartbeat/greedy).
🟢 Mise à jour	instance mise à jour	Les métadonnées de l’instance ont été mises à jour avec succès.
🔴 Erreur	échec de mise à jour de l’instance, mise en file d’attente pour une nouvelle tentative	La mise à jour de l’instance a échoué, probablement en raison d’une limitation de débit ou d’une erreur.
🟢 Mise à jour	instance supprimée	L’instance n’est plus détectable par les joueurs.
🟢 Mise à jour	échec de suppression de l’instance (introuvable)	L’instance a peut-être expiré en raison d’un trop grand nombre de heartbeats manqués.
🔴 Erreur	échec de suppression de l’instance	Impossible de supprimer l’instance, probablement en raison d’une limitation de débit ou d’une erreur.
🔵 Notification	mise à jour du slot mise en file d’attente [{slot}]	Mise à jour de slot mise en file d’attente pour le prochain lot (heartbeat/greedy).
🟢 Mise à jour	slot mis à jour [{slot}]	La capacité en places du slot et/ou ses métadonnées ont été mises à jour avec succès.
🟡 Avertissement	l’agent a limité la mise à jour concurrente des slots	Tentative de mise à jour concurrente empêchée (condition de concurrence).
🔴 Erreur	échec de mise à jour du slot (introuvable) [{slot}]	Le slot portant ce nom n’est pas encore défini pour cette instance.
🔴 Erreur	échec de mise à jour du slot (pas assez de places) [{slot}]	La mise à jour du slot a tenté de réduire les places disponibles en dessous de zéro.
🔴 Erreur	échec de mise à jour du slot, mise en file d’attente pour une nouvelle tentative [{slot}]	La mise à jour du slot a échoué, probablement en raison d’une limitation de débit ou d’une erreur.

Aperçu des événements (actions) émis par l’observable Confirmations:

Type d’action	Message de l’événement	Description
🔵 Notification	mis en file d’attente [{player}]	Confirmation mise en file d’attente pour le prochain lot (heartbeat/greedy).
🟡 Avertissement	doublon [{player}]	Tentative de confirmation en double empêchée (déjà en file d’attente).
🟢 Mise à jour	confirmé	Réservations confirmées pour des slots individuels, incluent également les ID de joueurs expirés et inconnus que le gestionnaire doit résoudre (accepter/kick).
🔴 Erreur	échoué	Problème inattendu avec les confirmations. Vérifiez l’état du service.

Événements client

L’Agent client émet des événements (actions) que le gestionnaire parent doit observer et consommer.

Lire les charges utiles des événements en accédant à .Current état de n’importe quel observable. 🔴 Erreur les événements contiennent le message d’erreur complet délimité par un caractère de nouvelle ligne après le message principal de l’événement.

Aperçu des événements émis par l’observable Surveiller :

Type d’action	Message de l’événement	Description
🟢 Mise à jour	sain	Tous les systèmes sont opérationnels.
🟢 Mise à jour	malsain	Problème inattendu.
🔴 Erreur	échec de récupération du moniteur	Mauvaise configuration ou problème inattendu.

Aperçu des événements émis par l’observable Instances:

Type d’action	Message de l’événement	Description
🔵 Notification	places réservées	Réservation de place réussie.
🔴 Erreur	échec de réservation de places (introuvable)	Navigateur de serveurs - nom de politique introuvable (supprimé ou inactif). Navigateur de serveurs - instance ou slot introuvable.
🔴 Erreur	échec de réservation de places (capacité atteinte)	Navigateur de serveurs - la politique a atteint sa capacité maximale. Navigateur de serveurs - le slot a atteint sa capacité maximale.
🔴 Erreur	échec de réservation de places	Échec de la réservation de places, politique, ID de requête ou ID de slot possiblement invalides.
🟢 Mise à jour	liste des instances récupérée	Liste des instances récupérée avec succès.
🟢 Mise à jour	page suivante de la liste d’instances récupérée	Page suivante d’instances récupérée avec succès.
🔴 Erreur	dernière page de la liste d’instances atteinte	Impossible de récupérer la page suivante, essayez d’actualiser ou de modifier les filtres.
🔴 Erreur	échec de récupération de la page suivante de la liste d’instances	Impossible de récupérer la page suivante, probablement à cause d’un curseur invalide.
🟢 Mise à jour	détails de l’instance récupérés	Détails d’une instance listée récupérés avec succès.
🟢 Mise à jour	instance non mise en cache, insertion au début	Détails d’une instance hors de la liste actuelle récupérés.
🔴 Erreur	échec de récupération des détails de l’instance	Impossible de récupérer les détails, probablement en raison d’un ID de requête invalide.