> 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/appariement.md).

# Appariement

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

## 💡 Fonctionnalités

{% columns %}
{% column %}

* Exemples complets
* Automatisation du ping
* Tickets, groupes, équipes
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Variables de match
* Définitions de types (C#)
* Tests de développement local
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Multiplateforme
* Facile à personnaliser
* Nouvelle tentative automatique
  {% 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 %}

## 🍀 Démarrage

Ce guide suppose une connaissance de base de [Appariement](/fr/learn/appariement.md) des concepts et d'un Matchmaker en cours d'exécution.

{% hint style="success" %}
**Nous vous recommandons vivement d'importer notre exemple simple** pour suivre le code au fil de votre lecture de ce document. Vous pouvez le faire dans `Unity Package Manager > Edgegap SDK > Samples` .
{% endhint %}

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

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

* Fichiers d'exécution - seront compilés et inclus dans vos builds client et serveur :
  * Utilitaires spécifiques au service :
    * [#client-agent](#client-agent "mention") - une intégration client complète à réutiliser/étendre.
    * Fonctions API - définitions des endpoints, gestion des erreurs et automatisations de journalisation.
  * Spécifiques au service DTO[^1] - conteneurs de données typés pour l'API de matchmaking.
  * Utilitaires partagés - journalisation, HTTP, ping, observables, etc...
  * Partagés DTO[^1] - utilisés 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 :
  * [#simple-example](#simple-example "mention") - des gestionnaires d'exemple pour un [configuration minimale](/fr/learn/appariement.md#simple-example).
  * [#region-picker](#region-picker "mention") - explorez l'intégration UI avec la sélection manuelle de la région.

### Client de groupe

**Automatisation du ping, gestion des tickets et récupération de l'hôte** sont effectuées par le Client de groupe.

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

* `onMonitorUpdate`  callback - observer les changements d'état de santé du service.
* `onAssignmentUpdate`  callback - observer et réagir aux changements d'affectation de l'hôte.

Une fois initialisé, ce client fournira automatiquement des validations et connectera les observateurs de journalisation, en terminant par un seul appel au point de terminaison de monitoring pour indiquer l'état de santé du service.

Le gestionnaire du client est censé prendre la main et appeler les fonctions du client à partir de ce point :

* `Balises`  pour récupérer une liste des [Balises de ping](/fr/learn/orchestration/ping-beacons.md).
* `MeasureBeaconsRoundTripTime`  pour fournir des mesures de ping sur un ensemble donné de balises.
* `CreateGroup`  pour permettre au leader du salon de créer un groupe rejoignable, auquel des amis peuvent être invités.
* `JoinGroup`  pour rejoindre un groupe existant à l'aide de l'ID du groupe envoyé via le salon / backend tiers.
* `SetReady`  pour marquer le propriétaire du groupe et ses membres comme prêts et commencer la recherche de parties.
* `ResumeMatchmaking`  charger un groupe mis en cache et reprendre la recherche au cas où le client aurait planté.
* `StopMatchmaking`  pour supprimer le ticket (s'il n'a pas été apparié) et quitter la file d'attente.
* `État`  pour vérifier l'état de santé du service Matchmaker.

Lorsqu'une nouvelle connexion de joueur est établie, le joueur est censé envoyer l'ID de son ticket au serveur de jeu en utilisant votre netcode, afin de corréler les connexions avec [Analyse approfondie](/fr/learn/appariement/matchmaker-in-depth.md#injected-variables).

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

## Agent serveur

L'Agent serveur effectue **la création de backfill, la détection de l'attribution des tickets, la détection de l'abandon et de la suppression des backfills. Il suit également et recrée les backfills qui ont expiré, dont le délai de grâce de connexion s'est écoulé ou qui ont été abandonnés - afin d'atteindre la taille d'équipe souhaitée**.

L'Agent serveur garde une trace des joueurs actuellement connectés et inclut automatiquement leurs tickets dans les nouveaux backfills afin de garantir que les joueurs ajoutés via backfill seront appariés selon les règles du profil configuré.

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

* `onMonitorUpdate`  callback - observer les changements d'état de santé du service.
* `onBackfillUpdate` callback - observer les changements de backfill et réagir.

Une fois initialisé, ce client fournira automatiquement des validations et connectera les observateurs de journalisation, en terminant par un seul appel au point de terminaison de monitoring pour indiquer l'état de santé du service.

Le gestionnaire serveur est censé prendre la main et appeler les fonctions du client à partir de ce point :

* `PlayerConnected`  pour éviter de remplacer les joueurs initiaux ou ajoutés via backfill qui ne se sont jamais connectés.
* `AbandonPlayer`  pour signaler qu'un joueur connecté a quitté le serveur et doit être remplacé.
* `AbandonAllBackfills`  pour arrêter immédiatement le backfill du serveur et supprimer les backfills.
  * Cette méthode doit être appelée avant l'arrêt de votre serveur. Les joueurs déjà assignés à ce moment-là doivent rejoindre à nouveau le matchmaking, car le serveur est en cours d'arrêt.
  * Les backfills attribués au moment de cet appel peuvent encore se connecter pendant le délai de grâce configuré.
* `AbandonBackfill`  pour abandonner de force un backfill spécifique (implémentations de gestionnaire personnalisées).
* `État`  pour vérifier l'état de santé du service de matchmaking.

## 🧪 Exemples

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

### Exemple simple

Inclut une implémentation complète du cycle de vie du joueur avec mesure du ping, gestion des tickets et récupération de l'attribution de l'hôte. Montre comment lire les variables de match injectées côté serveur.

Modifiez les attributs de matchmaking pour étendre facilement cet exemple à n'importe quelle configuration.

### Sélecteur de région

Certains joueurs (ou groupes) ont des conditions localisées particulières (comme FAI[^2] blocage, [blocage à l'échelle du pays](#user-content-fn-3)[^3], ou autre) et peuvent préférer choisir une région manuellement plutôt qu'en se basant uniquement sur le ping.

Examinez notre exemple de Sélecteur de région et inspirez-vous-en pour votre implémentation d'UI de matchmaking.

### Faire groupe

Rejoignez la file d'attente du matchmaking avec un groupe d'amis, en exigeant que tous les joueurs confirment avant de lancer la recherche. Commencez avec une implémentation UI minimale, puis personnalisez-la pour le design de votre jeu.

Explorez l'intégration UI avec le flux de constitution de groupe et offrez la meilleure expérience sociale possible.

### Backfill

Réutilisez la capacité du serveur et ajoutez des joueurs aux déploiements en cours. Définissez la taille cible de l'équipe et attendez que des joueurs soient ajoutés. Inclut un délai de grâce de connexion automatisé et la recréation des backfills expirés.

Personnalisez l'exemple de gestionnaire serveur pour des compositions d'équipes multi-équipe ou asymétriques.

## ⚙️ Personnalisation

Ce SDK est conçu pour être étendu et modifié, bien que certaines modifications puissent être risquées :

✅ Gestionnaire - connecter en toute sécurité les observateurs de l'UI et effectuer des ajouts ou modifications mineurs,

⚠️ Agent - modifiez la gestion du cycle de vie des joueurs à 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.

{% hint style="warning" %}
Assurez-vous de vous familiariser avec [Matchmaking en profondeur](/fr/learn/appariement/matchmaker-in-depth.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 client

Le Client de groupe émet des événements (actions) que le gestionnaire parent peut observer et exploiter.

{% 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 %}

Prévisualisez les événements émis par l'observable `Moniteur` :

<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>non sain</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>Erreur</code></td><td><code>échec de récupération des balises</code></td><td>Problème inattendu.</td></tr></tbody></table>

Prévisualisez les événements émis par l'observable `Groupe`:

<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>créé</code></td><td>Groupe créé avec succès.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de création du groupe</code></td><td>Échec de la création du groupe.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>rejoint</code></td><td>Groupe rejoint avec succès.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de rejoindre le groupe</code></td><td>Échec de rejoindre le groupe.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>repris</code></td><td>Groupe repris avec succès.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>groupe introuvable</code></td><td>Pas membre du groupe, ou groupe expiré.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>conflit, abandonnez et redémarrez</code></td><td>Veuillez abandonner le groupe actuel avant d'essayer de créer/rejoindre un nouveau groupe.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>membre mis à jour [{ready}]</code></td><td>Membre mis à jour avec une nouvelle valeur Ready.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de la mise à jour du membre</code></td><td>Échec de la mise à jour du membre du groupe. Impossible de ne plus être prêt après que le groupe a commencé à rechercher une partie.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>interrogation [{consecutive}/{maximum}]</code></td><td>Le client a lancé l'interrogation de l'état du groupe.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>interrogation arrêtée</code></td><td>Le client a arrêté l'interrogation de l'état du ticket.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de l'interrogation, nombre maximal de tentatives atteint</code></td><td>Le client a épuisé le nombre maximal de tentatives d'interrogation consécutives. Vérifiez l'état du service.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de l'interrogation</code></td><td>Le client a reçu une erreur non réessayable lors de l'interrogation. Vérifiez l'état du service.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>groupe mis à jour [{status}]</code></td><td>Changement d'état du groupe détecté pendant l'interrogation.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>abandonné</code></td><td>Ticket supprimé avec succès.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>échec de l'abandon (introuvable)</code></td><td>Le client n'a pas pu trouver le ticket à supprimer, peut-être expiré.</td></tr><tr><td>🟡 <code>Avertissement</code></td><td><code>échec de l'abandon (déjà apparié)</code></td><td>Le client n'a pas pu supprimer un groupe apparié. Désactivez l'abandon ou <a data-mention href="/fr/learn/appariement/matchmaker-in-depth.md#backfill-match">Analyse approfondie</a> pour remplacer le joueur.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de l'abandon</code></td><td>Échec de la suppression du groupe ou de l'adhésion.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>supprimé</code></td><td>Le groupe a expiré, la référence locale a été supprimée.</td></tr></tbody></table>

### Événements serveur

L'Agent serveur émet des événements (actions) que le gestionnaire parent peut observer et exploiter. L'émission de ces événements par l'Agent serveur n'est initialisée que dans l' [#backfill](#backfill "mention") exemple.

{% hint style="info" %}
Les tickets actuellement attribués peuvent être lus à partir de la propriété de l'Agent serveur `Attributions`  à tout moment.
{% endhint %}

{% 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 %}

Prévisualisez les événements émis par l'observable `Moniteur` :

<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>non sain</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>

Prévisualisez les événements émis par l'observable `Backfill`:

<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>créé [{backfill}]</code></td><td>Backfill créé avec succès.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de la création</code></td><td>Problème inattendu avec le backfill. Vérifiez l'état du service.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>interrogation [{consecutive}/{maximum}]</code></td><td>L'interrogation a échoué, nouvelle tentative automatique.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>attribué [{backfill}]</code></td><td>Ticket attribué au backfill avec succès.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>interrogation arrêtée</code></td><td>L'interrogation a été arrêtée à la demande du gestionnaire.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>échec de l'interrogation (introuvable) [{backfill}]</code></td><td>Introuvable, suppression de la référence. Le backfill a très probablement expiré.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de l'interrogation (nombre maximal de tentatives atteint) [{backfill}]</code></td><td>Tentatives épuisées, abandon du backfill.</td></tr><tr><td>🔴 <code>Erreur</code></td><td><code>échec de l'interrogation [{backfill}]</code></td><td>Problème inattendu, suppression de la référence.</td></tr><tr><td>🔵 <code>Notification</code></td><td><code>abandonné [{backfill}]</code></td><td>Backfill abandonné, suppression de la référence.</td></tr><tr><td>🟡 <code>Avertissement</code></td><td><code>échec de l'abandon [{backfill}]</code></td><td>L'abandon a échoué, suppression de la référence.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>supprimé [{backfill}]</code></td><td>Référence de backfill supprimée. Le backfill sera remplacé automatiquement s'il n'est pas arrêté.</td></tr><tr><td>🟡 <code>Avertissement</code></td><td><code>échec de la suppression [{backfill}]</code></td><td>Référence de backfill introuvable, probablement un appel en double.</td></tr></tbody></table>

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

[^2]: [Fournisseur d'accès à Internet](https://en.wikipedia.org/wiki/Internet_service_provider)

[^3]: notamment la Chine ou la Russie