> 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/docs.edgegap.com-fr/unity/appariement.md).

# Appariement

Ce SDK est un kit de démarrage optionnel pour les utilisateurs de Unity, pouvant ê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 automatisée
  {% endcolumn %}
  {% endcolumns %}

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

{% hint style="success" %}
Ce plugin est fourni 100 % gratuitement, conformément aux Conditions générales de l’offre gratuite.
{% endhint %}

#### Exigences

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

</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 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` .

{% 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](/docs.edgegap.com-fr/unity/navigateur-de-serveurs.md) utilitaires et exemples, améliore la gestion des erreurs de matchmaking, et plus encore. Voir [Notes de version](/docs.edgegap.com-fr/docs/release-notes.md) pour la liste complète.

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

## 🍀 Démarrage

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

{% hint style="success" %}
**Nous 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](/docs.edgegap.com-fr/learn/navigateur-de-serveurs.md) et [Appariement](/docs.edgegap.com-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 intégrés à 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 points de terminaison, 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 transmettre des données.
* Fichiers d'exemple - intégrés 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](/docs.edgegap.com-fr/learn/appariement.md#simple-example).
  * [#region-picker](#region-picker "mention") - explorer l'intégration UI avec une sélection manuelle de région.

### Client de groupe

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

Une fois instancié, le **Monobehaviour parent (gestionnaire) de l'agent 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 configurera les observateurs de journalisation, en se terminant par un seul appel au point de terminaison de l'API de surveillance pour indiquer l'état de santé du service.

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

* `Balises`  pour récupérer une liste des [Balises de ping](/docs.edgegap.com-fr/learn/orchestration/ping-beacons.md),
* `MeasureBeaconsRoundTripTime`  pour fournir des mesures de ping par rapport à 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 un salon/backend tiers,
* `SetReady`  pour marquer le propriétaire du groupe et ses membres comme prêts et commencer la recherche de matchs,
* `ResumeMatchmaking`  charger un groupe mis en cache et poursuivre la recherche en cas de plantage du client,
* `StopMatchmaking`  pour supprimer le ticket (s'il n'a pas été apparié) et quitter la file d'attente,
* `Statut`  pour vérifier l'état de santé du service Server Browser.

Lorsqu'une nouvelle connexion joueur est établie, le joueur est censé envoyer son ID de ticket au serveur de jeu en utilisant votre netcode, afin de corréler les connexions avec [Analyse approfondie](/docs.edgegap.com-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 %}

## 🧪 Exemples

Commencez avec des exemples, y compris 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'affectation 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 afin qu'il convienne à toute configuration.

### Sélecteur de région

Certains joueurs (ou groupes) ont des conditions localisées particulières (telles que 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 l'implémentation de votre interface de matchmaking.

### Former un groupe

Rejoignez la file de matchmaking avec un groupe d'amis, en demandant à tous les joueurs de confirmer avant de lancer la recherche. Commencez avec une implémentation UI minimale, puis personnalisez-la selon la conception de votre jeu.

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

## ⚙️ 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 de petites ajouts ou modifications,

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

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

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

{% hint style="warning" %}
Assurez-vous de vous familiariser avec [Matchmaking en profondeur](/docs.edgegap.com-fr/learn/appariement/matchmaker-in-depth.md) concepts avant d'apporter 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 %}

### Observer les événements

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

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

<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 OK.</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>

Aperçu des é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 la jonction au groupe</code></td><td>Échec de la jonction au 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 d'en créer ou d'en rejoindre un nouveau.</td></tr><tr><td>🟢 <code>Mise à jour</code> </td><td><code>membre mis à jour [{ready}]</code></td><td>Membre mis à jour avec la nouvelle valeur Prêt.</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 passer en non-prêt une fois que le groupe a commencé à rechercher un match.</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, il a 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="/pages/94dc7141ca8181657ba0af1abea4eab9a70caf0a#backfill-match">/pages/94dc7141ca8181657ba0af1abea4eab9a70caf0a#backfill-match</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>

[^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