Server Browser

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#)

• Test local de développement

• Multiplateforme

• Facile à personnaliser

• Nouvelle tentative automatisée

✔️ Préparation

🍀 Démarrage

Ce guide suppose une connaissance de base des Server Browser concepts et d'un Server Browser opérationnel.

Nous vous recommandons vivement d'importer notre exemple d'auto-attribution pour suivre le code au fil de la lecture de ce document. Vous pouvez le faire dans Unity Package Manager > Edgegap SDK > Samples .

Aperçu

Ce package comprend :

• Fichiers d'exécution - seront compilés et inclus dans vos builds client et serveur :

  • Utilitaires spécifiques au service :

    • Server Browser - une intégration serveur complète à réutiliser/étendre,

    • Server Browser - 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é par plusieurs services Edgegap pour faire circuler les données.

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

  • Server Browser - des gestionnaires d'exemple avec réservations auto-attribuées,

  • Server Browser - des gestionnaires d'exemple avec choix manuel de l'instance.

Agent serveur

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

Une fois instancié, le MonoBehaviour parent (gestionnaire) de l'agent doit initialiser l'agent et fournir :

• onMonitorUpdate callback - observer les changements de santé 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, pour terminer par un simple appel au point de terminaison de l'API de surveillance afin d'indiquer l'état de santé du service.

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

• DiscoverInstance pour créer l'instance serveur initiale et les slots, puis lancer le heartbeat,

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

• ConfirmReservation lorsque des joueurs rejoignent, afin de vérifier leur identité et l'attribution du slot,

• UpdateSlot pour mettre à jour la capacité du slot (lors de l'arrivée du joueur ou de son abandon) ou modifier les métadonnées,

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

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

Les confirmations et les mises à jour de slot/instance sont en file d'attente et effectuées par lots par défaut (mode Heartbeat) afin de 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 indices doivent être définis. Pour supprimer les clés non indexées, omettez-les simplement.

L'agent maintient automatiquement un heartbeat pour garder le serveur découvrable pendant son fonctionnement. Si l'agent ne peut pas joindre votre Server Browser pendant plusieurs heartbeats consécutifs (configurable) :

• moins que le maximum - l'instance sera automatiquement redécouverte,

• plus que le 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 joueur tiers) au serveur de jeu en utilisant 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 le nombre de sièges disponibles pour tout slot 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 le nombre de sièges disponibles pour ce slot.

Laissez un court délai aux joueurs pour se reconnecter avant l'abandon 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) de l'agent doit initialiser l'agent et fournir :

• onMonitorUpdate callback - observer les changements de santé 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, pour terminer par un simple appel au point de terminaison de l'API de surveillance afin d'indiquer l'état de santé du service.

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

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

• ListInstances pour lister les instances avec un filtre, un ordre, 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 sur les slots pour une instance spécifique,

• Status 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 joueur tiers) au serveur de jeu en utilisant votre netcode, afin d'effectuer la confirmation de réservation.

Enregistrez les détails de connexion dans le client ou le backend du jeu afin de 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 disposant d'un nombre de sièges suffisant.

Recherche personnalisée

Inclut une implémentation complète démontrant comment rechercher des instances et des slots, connecter les éléments d'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 - connectez en toute sécurité les observateurs de l'interface utilisateur et effectuez de petites ajouts ou modifications,

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

⚠️ API - écrivez votre propre intégration depuis zéro, en utilisant des utilitaires 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 les concepts de Server Browser en profondeur avant d'apporter des personnalisations.

Événements serveur

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

Aperçu des événements émis par l'observable Surveillance :

Type d'action	Message d'événement	Description
🟢 Mise à jour	sain	Tous les systèmes sont opérationnels.
🟢 Mise à jour	non sain	Problème inattendu.
🔴 Erreur	échec de récupération de la surveillance	Mauvaise configuration ou problème inattendu.
🟡 Avertissement	le délai d'attente de la requête a été 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 d'événement	Description
🟢 Mise à jour	découverte	Découverte d'instance terminée avec succès. Peut être déclenchée si l'instance a perdu la connexion en raison d'une condition temporaire puis a été redécouverte.
🔴 Erreur	découverte en double	Une instance avec cet ID de requête est déjà découverte.
🔴 Erreur	échec de 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 Server Browser.
🔵 Notification	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	Métadonnées de l'instance mises à jour avec succès.
🔴 Erreur	échec de mise à jour de l'instance, mise en file d'attente pour 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écouvrable 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	Échec de la suppression de l'instance, possiblement 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 du slot mise en file d'attente pour le prochain lot (heartbeat/greedy).
🟢 Mise à jour	slot mis à jour [{slot}]	Capacité de sièges du slot et/ou métadonnées 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}]	Un slot avec ce nom n'est pas encore défini pour cette instance.
🔴 Erreur	échec de mise à jour du slot (sièges insuffisants) [{slot}]	La mise à jour du slot a tenté de réduire le nombre de sièges disponibles en dessous de zéro.
🔴 Erreur	échec de mise à jour du slot, mise en file d'attente pour 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 d'é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, inclut aussi les ID de joueurs expirés et inconnus que le gestionnaire doit résoudre (accepter/exclure).
🔴 Erreur	échec	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.

Aperçu des événements émis par l'observable Surveillance :

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

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

Type d'action	Message d'événement	Description
🔵 Notification	sièges réservés	Réservation de sièges réussie.
🔴 Erreur	échec de réservation de sièges (introuvable)	Server Browser - nom de politique introuvable (supprimée ou inactive). Server Browser - instance ou slot introuvable.
🔴 Erreur	échec de réservation de sièges (capacité atteinte)	Server Browser - politique a atteint la capacité maximale. Server Browser - slot a atteint la capacité maximale.
🔴 Erreur	échec de réservation de sièges	Échec de la réservation de sièges, politique, ID de requête ou ID de slot probablement 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, probablement 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, probablement en raison d'un ID de requête invalide.