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êtes à l'emploi en installant notre SDK :

• Exemples complets

• Gestion du cycle de vie

• Gestion de capacité

• Compilateur de requêtes de filtre

• Définitions de types (C#)

• Tests de développement local

• Multiplateforme

• Facile à personnaliser

• Nouvelle tentative automatique

✔️ Préparation

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

Ce plugin est fourni 100 % gratuitement, conformément aux Conditions générales de l’offre gratuite.

Exigences

Installez un client Git (par exemple git-scm)

Un client Git est nécessaire pour permettre à Unity de télécharger et d’installer automatiquement notre package Unity. Vous n’aurez pas besoin d’utiliser git directement une fois qu’il sera installé.

Installation

1. Ouvrez votre projet Unity,

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

3. Cliquez sur l’ ➕ icône et sélectionnez Ajouter un package à partir d’une 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 que l’installation soit terminée.

Importer les exemples

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

Sources vérifiées

Il s’agit du seul canal de distribution officiel pour ce SDK, ne faites pas confiance aux sources non vérifiées !

Mettre à jour le package

Accédez au SDK Edgegap dans Unity Package Manager et cliquez sur Mettre à jour .

Les exemples importés ne sont pas mis à jour automatiquement ! Sauvegardez toutes 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 incompatibles. Cela sera indiqué par une nouvelle version MAJEURE.

Mise à jour vers 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. Voir Notes de version pour la liste complète.

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

🍀 Premiers pas

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

Nous vous recommandons vivement d'importer notre exemple d'assignation automatique pour suivre le code en lisant ce document. Vous pouvez le faire dans Unity Package Manager > Edgegap SDK > Samples .

Vue d'ensemble

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 comprend :

• Fichiers d'exécution - seront compilés et inclus dans 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 de points de terminaison, gestion des erreurs et automatisations de journalisation.

    • Compilateur de filtres - utilitaires fortement typés pour construire 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és par plusieurs services Edgegap pour transmettre des données.

• Fichiers d'exemple - inclus et compilés UNIQUEMENT s'ils sont importés dans votre projet :

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

  • Navigateur de serveurs - exemples de gestionnaires avec choix manuel de l'instance.

Agent serveur

La gestion du cycle de vie et de la capacité du serveur sont effectuées 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 seul appel 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 initiale et les slots et lancer le heartbeat,

• DeleteInstance une fois le match terminé / 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 (lorsqu'un joueur rejoint/quitte) ou modifier les métadonnées,

• UpdateInstance pour modifier les métadonnées de l'instance,

• Status pour vérifier l'état du service Server Browser.

Les confirmations et les mises à jour de slot/instance sont mises en file d'attente et effectuées par lots par défaut (mode Heartbeat) pour maximiser la scalabilité. Pour itérer plus rapidement 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 désactiver 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 à l'aide de 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 ayant des réservations confirmées,

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

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

Accordez un court délai aux joueurs pour se reconnecter avant d'abandonner en cas de crash 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 seul appel 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 une assignation automatique,

• 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 des slots pour une instance spécifique,

• Status pour vérifier l'état 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 à l'aide de 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 vous reconnecter en cas de crash inattendu.

🧪 Exemples

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

Assignation automatique

Utilise des réservations attribuées automatiquement, 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 disposant d'un nombre de places suffisant.

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 conçu pour être étendu et modifié, bien que certaines modifications puissent être risquées :

✅ Gestionnaire - connectez en toute sécurité les observateurs de l'interface utilisateur et effectuez de petites additions ou modifications,

⚠️ Agent - modifiez la gestion du cycle de vie et de la capacité à vos risques et périls,

⚠️ API - écrivez votre propre intégration à partir 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 vous familiariser avec Server Browser en profondeur concepts avant d'apporter 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 du serveur

L'agent serveur émet des événements (actions) que le gestionnaire parent peut 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 OK.
🟢 Mise à jour	malsain	Problème inattendu.
🔴 Erreur	échec de la récupération du moniteur	Mauvaise configuration ou problème inattendu.
🟡 Avertissement	délai d'attente de la requête limité au heartbeat [{timeout}]	Évite les conditions de course.

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 en raison 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.
🔵 Notifier	heartbeat OK	Le heartbeat s'est terminé avec succès.
🟡 Avertissement	échec du heartbeat [{consecutive}/{maximum}]	Échec du heartbeat, le serveur n'a pas pu atteindre Server Browser.
🔵 Notifier	mise à jour de l'instance mise en file d'attente	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 la mise à jour de l'instance, mise en file d'attente pour une nouvelle tentative	Échec de la mise à jour de l'instance, possiblement 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 la 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 la suppression de l'instance	Échec de la suppression de l'instance, possiblement en raison d'une limitation de débit ou d'une erreur.
🔵 Notifier	mise à jour du slot mise en file d'attente [{slot}]	Mise à jour du slot mise en file d'attente pour le prochain lot (heartbeat/greedy).
🟢 Mise à jour	slot mis à jour [{slot}]	La capacité des places du slot et/ou les métadonnées ont été mises à jour avec succès.
🟡 Avertissement	l'agent a limité la mise à jour concurrente du slot	Tentative de mise à jour concurrente empêchée (condition de course).
🔴 Erreur	échec de la mise à jour du slot (introuvable) [{slot}]	Un slot portant ce nom n'est pas encore défini pour cette instance.
🔴 Erreur	échec de la mise à jour du slot (places insuffisantes) [{slot}]	La mise à jour du slot a tenté de réduire les places disponibles en dessous de zéro.
🔴 Erreur	échec de la mise à jour du slot, mise en file d'attente pour une nouvelle tentative [{slot}]	Échec de la mise à jour du slot, possiblement 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
🔵 Notifier	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, inclut également les ID de joueur expirés et inconnus à résoudre par le gestionnaire (accepter/exclure).
🔴 Erreur	échoué	Problème inattendu avec les confirmations. Vérifiez l'état du service.

Événements du client

L'agent client émet des événements (actions) que le gestionnaire parent peut 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 OK.
🟢 Mise à jour	malsain	Problème inattendu.
🔴 Erreur	échec de la 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
🔵 Notifier	places réservées	Réservation de places réussie.
🔴 Erreur	échec de la réservation de places (introuvable)	Navigateur de serveurs - nom de politique introuvable (supprimée ou inactive). Navigateur de serveurs - instance ou slot introuvable.
🔴 Erreur	échec de la 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 la réservation de places	Échec de la réservation de places, possiblement en raison d'une politique, d'un ID de requête ou d'un ID de slot invalide.
🟢 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 des instances récupérée	Page suivante des instances récupérée avec succès.
🔴 Erreur	dernière page de la liste des instances atteinte	Échec de récupération de la page suivante, essayez d'actualiser ou de modifier les filtres.
🔴 Erreur	échec de récupération de la page suivante de la liste des instances	Échec de récupération de la page suivante, possiblement en raison 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, ajout en tête	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	Échec de récupération des détails, possiblement en raison d'un ID de requête invalide.