> 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/unity/navigateur-de-serveurs.md).

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

{% columns %}
{% column %}

* Exemples complets
* Gestion du cycle de vie
* Gestion de la capacité
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Compilateur de requêtes de filtre
* Définitions de types (C#)
* Tests locaux en développement
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Multiplateforme
* Facile à personnaliser
* Nouvelle tentative automatisée
  {% endcolumn %}
  {% endcolumns %}

## ✔️ Préparation

Unity SDK 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 de Unity 2021.3.0f1 et ultérieures.

{% hint style="info" %}
**La dernière version de Unity SDK est `3.5.4`**. Tous les exemples de cette documentation sont à jour.
{% endhint %}

{% hint style="success" %}
Ce plugin est fourni 100 % gratuitement, conformément aux Conditions générales du Free Tier.
{% endhint %}

#### Prérequis

<details>

<summary>Installez un client Git (par exemple <a href="https://git-scm.com/">git-scm</a>)</summary>

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

</details>

#### Installation

1. Ouvrez votre projet Unity,
2. Sélectionnez `Fenêtre > Gestion des packages > Gestionnaire de packages` ,
3. Cliquez sur l’ :heavy\_plus\_sign: 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é :

{% code title="" %}

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

{% endcode %}

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

#### Importer les exemples

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

#### Sources vérifiées

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

#### Mettre à jour le package

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

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="info" %}
Certaines versions peuvent contenir des changements incompatibles. Cela sera indiqué par une nouvelle version MAJEURE.
{% endhint %}

#### Mise à jour vers v3

Cette mise à jour inclut de nombreux nouveaux [Navigateur de serveurs](/fr/unity/navigateur-de-serveurs.md) utilitaires et exemples, améliore la gestion des erreurs de matchmaking, et plus encore. Voir [Notes de version](/fr/docs/release-notes.md) pour une liste complète.

{% hint style="warning" %}
La mise à jour v3 de Unity SDK inclut quelques changements incompatibles. Veuillez retester soigneusement votre intégration.
{% endhint %}

## 🍀 Mise en route

Ce guide suppose une connaissance de base des [Navigateur de serveurs](/fr/learn/navigateur-de-serveurs.md) concepts et d’un Server Browser en fonctionnement.

{% hint style="success" %}
**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` .
{% endhint %}

{% embed url="<https://youtu.be/P8xWrD4UCxg>" %}

### Aperçu

Notre SDK utilise largement [l’injection de dépendances](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection/overview#the-concept) et [Observateur](https://learn.microsoft.com/en-us/dotnet/standard/events/observer-design-pattern) des modèles de programmation.

{% hint style="info" %}
Ce package intègre à la fois [Navigateur de serveurs](/fr/learn/navigateur-de-serveurs.md) et [Appariement](/fr/learn/appariement.md), 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.
{% endhint %}

Ce package inclut :

* Fichiers d’exécution - seront compilés et intégrés à vos builds client et serveur :
  * Utilitaires spécifiques au service :
    * [#server-agent](#server-agent "mention") - une intégration serveur complète à réutiliser/étendre.
    * [#client-agent](#client-agent "mention") - 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[^1] - conteneurs de données typés pour l’API Server Browser.
  * Utilitaires partagés - journalisation, HTTP, ping, observables, etc...
  * Partagé DTO[^1] - 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 :
  * [#auto-assign](#auto-assign "mention") - exemples de gestionnaires avec réservations auto-attribuées,
  * [#custom-search](#custom-search "mention") - 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.

{% hint style="success" %}
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.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

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.

{% hint style="info" %}
Laissez un court délai aux joueurs pour se reconnecter avant d’abandonner, en cas de plantage inattendu.
{% endhint %}

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

{% hint style="success" %}
Enregistrez les détails de connexion dans le client ou le backend du jeu pour pouvoir vous reconnecter en cas de plantage inattendu.
{% endhint %}

## 🧪 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.

{% hint style="warning" %}
Assurez-vous de bien vous familiariser avec [Server Browser In-Depth](/fr/learn/navigateur-de-serveurs.md) les concepts avant d’effectuer des personnalisations.
{% endhint %}

{% hint style="info" %}
Si vous avez besoin d’aide, [veuillez nous contacter sur Discord](https://discord.gg/MmJf8fWjnt). Pour l’assistance aux jeux en direct, consultez notre [système de tickets](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### Événements serveur

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

{% hint style="success" %}
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.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th width="125">Type d’action</th><th width="450">Message de l’événement</th><th>Description</th></tr></thead><tbody><tr><td>🟢 <code>Mise à jour</code> </td><td><code>sain</code></td><td>Tous les systèmes sont opérationnels.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>malsain</code></td><td>Problème inattendu.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de récupération du moniteur</code></td><td>Mauvaise configuration ou problème inattendu.</td></tr><tr><td>🟡 <code>Avertissement</code></td><td><code>délai d’attente de la requête plafonné au heartbeat [{timeout}]</code></td><td>Empêche les conditions de concurrence.</td></tr></tbody></table>

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

<table data-full-width="true"><thead><tr><th width="125">Type d’action</th><th width="450">Message de l’événement</th><th>Description</th></tr></thead><tbody><tr><td>🟢 <code>Mise à jour</code> </td><td><code>découverte</code></td><td><a href="/fr/learn/navigateur-de-serveurs.md#discover-instance">Découverte de l’instance</a> 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.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>doublon de découverte</code></td><td>Une instance avec cet ID de requête est déjà découverte.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de la découverte</code></td><td>Problème inattendu lors de la découverte.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>heartbeat OK</code></td><td>Heartbeat terminé avec succès.</td></tr><tr><td>🟡 <code>Avertissement</code></td><td><code>échec du heartbeat [{consecutive}/{maximum}]</code></td><td>Échec du heartbeat, le serveur n’a pas pu atteindre le Server Browser.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>mise en file d’attente de la mise à jour de l’instance</code></td><td>Mise à jour de l’instance mise en file d’attente pour le prochain lot (heartbeat/greedy).</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>instance mise à jour</code></td><td>Les métadonnées de l’instance ont été mises à jour avec succès.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de mise à jour de l’instance, mise en file d’attente pour une nouvelle tentative</code></td><td>La mise à jour de l’instance a échoué, probablement en raison d’une limitation de débit ou d’une erreur.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>instance supprimée</code></td><td>L’instance n’est plus détectable par les joueurs.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>échec de suppression de l’instance (introuvable)</code></td><td>L’instance a peut-être expiré en raison d’un trop grand nombre de heartbeats manqués.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de suppression de l’instance</code></td><td>Impossible de supprimer l’instance, probablement en raison d’une limitation de débit ou d’une erreur.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>mise à jour du slot mise en file d’attente [{slot}]</code></td><td>Mise à jour de slot mise en file d’attente pour le prochain lot (heartbeat/greedy).</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>slot mis à jour [{slot}]</code></td><td>La capacité en places du slot et/ou ses métadonnées ont été mises à jour avec succès.</td></tr><tr><td>🟡 <code>Avertissement</code></td><td><code>l’agent a limité la mise à jour concurrente des slots</code></td><td>Tentative de mise à jour concurrente empêchée (condition de concurrence).</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de mise à jour du slot (introuvable) [{slot}]</code></td><td>Le slot portant ce nom n’est pas encore défini pour cette instance.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de mise à jour du slot (pas assez de places) [{slot}]</code></td><td>La mise à jour du slot a tenté de réduire les places disponibles en dessous de zéro.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de mise à jour du slot, mise en file d’attente pour une nouvelle tentative [{slot}]</code></td><td>La mise à jour du slot a échoué, probablement en raison d’une limitation de débit ou d’une erreur.</td></tr></tbody></table>

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

<table data-full-width="true"><thead><tr><th width="125">Type d’action</th><th width="450">Message de l’événement</th><th>Description</th></tr></thead><tbody><tr><td>🔵 <code>Notification</code></td><td><code>mis en file d’attente [{player}]</code></td><td>Confirmation mise en file d’attente pour le prochain lot (heartbeat/greedy).</td></tr><tr><td>🟡 <code>Avertissement</code></td><td><code>doublon [{player}]</code></td><td>Tentative de confirmation en double empêchée (déjà en file d’attente).</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>confirmé</code></td><td>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).</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échoué</code></td><td>Problème inattendu avec les confirmations. Vérifiez l’état du service.</td></tr></tbody></table>

### Événements client

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

{% hint style="success" %}
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.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th width="125">Type d’action</th><th width="450">Message de l’événement</th><th>Description</th></tr></thead><tbody><tr><td>🟢 <code>Mise à jour</code> </td><td><code>sain</code></td><td>Tous les systèmes sont opérationnels.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>malsain</code></td><td>Problème inattendu.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de récupération du moniteur</code></td><td>Mauvaise configuration ou problème inattendu.</td></tr></tbody></table>

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

<table data-full-width="true"><thead><tr><th width="125">Type d’action</th><th width="450">Message de l’événement</th><th>Description</th></tr></thead><tbody><tr><td>🔵 <code>Notification</code></td><td><code>places réservées</code></td><td>Réservation de place réussie.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de réservation de places (introuvable)</code></td><td><a data-mention href="#auto-assign">#auto-assign</a> - nom de politique introuvable (supprimé ou inactif).<br><a data-mention href="#custom-search">#custom-search</a> - instance ou slot introuvable.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de réservation de places (capacité atteinte)</code></td><td><a data-mention href="#auto-assign">#auto-assign</a> - la politique a atteint sa capacité maximale.<br><a data-mention href="#custom-search">#custom-search</a> - le slot a atteint sa capacité maximale.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de réservation de places</code></td><td>Échec de la réservation de places, politique, ID de requête ou ID de slot possiblement invalides.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>liste des instances récupérée</code></td><td>Liste des instances récupérée avec succès.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>page suivante de la liste d’instances récupérée</code></td><td>Page suivante d’instances récupérée avec succès.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>dernière page de la liste d’instances atteinte</code></td><td>Impossible de récupérer la page suivante, essayez d’actualiser ou de modifier les filtres.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de récupération de la page suivante de la liste d’instances</code></td><td>Impossible de récupérer la page suivante, probablement à cause d’un curseur invalide.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>détails de l’instance récupérés</code></td><td>Détails d’une instance listée récupérés avec succès.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>instance non mise en cache, insertion au début</code></td><td>Détails d’une instance hors de la liste actuelle récupérés.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de récupération des détails de l’instance</code></td><td>Impossible de récupérer les détails, probablement en raison d’un ID de requête invalide.</td></tr></tbody></table>

[^1]: Objet de transfert de données