Créateur d’appariements Unity

Ce guide vous aidera à créer un projet Unity en utilisant le système Advanced Matchmaker d'Edgegap pour automatiser les déploiements et les connexions entre joueurs.

Ce guide utilisera le projet d'exemple open-source Tanks, disponible dans le Mirror exemple sous Assets/Mirror/Examples/Tanks. L'exemple final se trouve sur notre GitHub.

configuration du Matchmaker

Créer les composants

Pour commencer, vous devrez créer vos 3 composants Matchmaker. Pour ce projet, vous pouvez suivre notre tutoriel de composant de base ici.

Gardez à l'esprit que les composants et la configuration YAML créés avec ce tutoriel ne sont pas destinés à être utilisés en production.

Release

Local

Si vous voulez tester votre Matchmaker dans un environnement local, appliquez simplement vos paramètres Kubernetes comme mentionné à la fin du tutoriel de composant de base. Vous pouvez ensuite passer directement à la configuration du projet.

Avec Edgegap

Si vous souhaitez plutôt tester le Matchmaker dans un environnement en ligne avec Edgegap, vous devrez légèrement modifier vos composants du tutoriel précédent. Vous utiliserez les variables injectées qui sont ajoutées lors de la release au lieu de certaines valeurs codées en dur. Les changements doivent être les suivants :

Director

...
using System;

namespace director
{
  public static class Constant
  {
    static Constant()
    {
        OpenMatchMatchFunctionHost = Environment.GetEnvironmentVariable("OM_MMF_HOST");
        OpenMatchMatchFunctionPort = Int32.Parse(Environment.GetEnvironmentVariable("OM_MMF_HTTP_PORT"));
        OpenMatchBackendService = Environment.GetEnvironmentVariable("OM_BACKEND_HOST") + ':' + Int32.Parse(Environment.GetEnvironmentVariable("OM_BACKEND_HTTP_PORT"));
    }

    public static readonly string OpenMatchMatchFunctionHost;
    public static readonly int OpenMatchMatchFunctionPort;
    public static readonly string OpenMatchBackendService;

    ...
  }

  ...
}

Frontend

...

namespace front_end
{
  // Toutes les constantes utilisées dans le programme
  public static class Constant
  {
    static Constant()
    {
        OpenMatchFrontendService = Environment.GetEnvironmentVariable("OM_FRONTEND_HOST") + ':' + Int32.Parse(Environment.GetEnvironmentVariable("OM_FRONTEND_HTTP_PORT"));
    }

    public static readonly string OpenMatchFrontendService;
  }

  ...
}

Match Function

...

namespace match_function
{
  // Toutes les constantes utilisées dans le programme
  public static class Constant
  {
    static Constant()
    {
        OpenMatchQueryService = Environment.GetEnvironmentVariable("OM_QUERY_HOST") + ':' + Int32.Parse(Environment.GetEnvironmentVariable("OM_QUERY_HTTP_PORT"));
    }

    public static readonly string OpenMatchQueryService;
    public const string MatchName = "basics-match-function";
  }

  ...
}

Une fois cela fait, téléversez-les sur Edgegap, puis créez et publiez votre Matchmaker sur le tableau de bord Edgegap.

Configuration du projet

Ensuite, nous voulons modifier le projet de base Tank afin que le Matchmaker soit utilisé pour connecter les joueurs entre eux. Pour les besoins de cet exemple, nous voulons que nos joueurs choisissent le mode de match qu'ils souhaitent jouer avant de créer un ticket Matchmaker, afin que le Matchmaker connecte automatiquement 2 joueurs ayant choisi le même mode.

Avec les composants Matchmaker de base créés dans le tutoriel précédent, les modes disponibles sont mode.casual, mode.ranked, et mode.private.

Dans le projet, ouvrez la scène située sous Assets/Mirror/Examples/Tanks/Scenes. Désactivez le Network Manager HUD composant du NetworkManager gameObject, puis créez votre propre HUD pour permettre aux joueurs d'entrer un mode de jeu, de créer et supprimer un ticket lorsqu'ils ne sont pas en match, et de quitter leur match actuel lorsqu'ils le sont.

HUD hors ligne

HUD en ligne

Ensuite, vous devrez créer de nouveaux scripts dans votre projet pour gérer les requêtes envoyées au Matchmaker selon le bouton cliqué par le joueur. Votre code pour gérer les requêtes elles-mêmes devrait avoir une structure similaire à celle-ci :

Fonctions

public class MatchmakerManager : ScriptableObject
{
  //lorsque vous testez le Matchmaker localement, cette valeur devrait être http://localhost:51504
  //lorsque vous testez la release en ligne du Matchmaker, vous n'avez pas besoin de spécifier le port à la fin de l'URL
  public const string MATCHMAKER_URL = "<FRONTEND_COMPONENT_URL>";
  private readonly HttpClient _httpClient = new();
  public KcpTransport transport = (KcpTransport)NetworkManager.singleton.transport;

  /// <summary>
  /// Obtenir les données d'un ticket depuis le Matchmaker
  /// </summary>
  /// <param name="ticketId">ID du ticket</param>
  /// <returns>Données du ticket</returns>
  public async Task<Ticket> GetTicket(string ticketId)
  {
    var response = await _httpClient.GetAsync($"{MATCHMAKER_URL}/v1/tickets/{ticketId}");

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"Code d'erreur : {response.StatusCode}");
    }

    var responseContent = await response.Content.ReadAsStringAsync();
    Ticket content = JsonConvert.DeserializeObject<Ticket>(responseContent);

    return content;
  }

  /// <summary>
  /// Créer un nouveau ticket pour le Matchmaker
  /// </summary>
  /// <param name="modeTag">Mode de jeu souhaité par les joueurs</param>
  /// <returns>Données du ticket</returns>
  public async Task<Ticket> CreateTicket(string modeTag)
  {
    CreateTicketPayload objectToSerialize = new()
    {
        mode = modeTag
    };

    var jsonContent = new StringContent(JsonConvert.SerializeObject(objectToSerialize), Encoding.UTF8, "application/json");
    var response = await _httpClient.PostAsync($"{MATCHMAKER_URL}/v1/tickets", jsonContent);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"Code d'erreur : {response.StatusCode}");
    }

    var responseContent = await response.Content.ReadAsStringAsync();
    Ticket content = JsonConvert.DeserializeObject<Ticket>(responseContent);

    return content;
  }

  /// <summary>
  /// Supprimer un ticket du Matchmaker
  /// </summary>
  /// <param name="ticketId">ID du ticket</param>
  public async Task DeleteTicket(string ticketId)
  {
    var response = await _httpClient.DeleteAsync($"{MATCHMAKER_URL}/v1/tickets/{ticketId}");

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"Code d'erreur : {response.StatusCode}");
    }
  }

  /// <summary>
  /// Connecter le joueur à un match
  /// </summary>
  /// <param name="assignment">Données d'assignation du ticket</param>
  public void ConnectPlayer(Assignment assignment)
  {
    string[] networkComponents = assignment.connection.Split(':');
    NetworkManager.singleton.networkAddress = networkComponents[0];

    if (ushort.TryParse(networkComponents[1], out ushort port))
    {
        transport.port = port;
    }
    else
    {
        throw new Exception("le port n'a pas pu être analysé");
    }

    NetworkManager.singleton.StartClient();
  }

  /// <summary>
  /// Déconnecter le joueur d'un match
  /// </summary>
  public void DisconnectPlayer()
  {
    NetworkManager.singleton.StopClient();
  }
}

Classes

public class CreateTicketPayload
{
    public string mode { get; set; }
}

public class Ticket
{
    public string id { get; set; }
    public Assignment assignment { get; set; }
    public SearchFields search_fields { get; set; }
    public Dictionary<string, Extension> extensions { get; set; }
    public Dictionary<string, Extension> persistent_field { get; set; }
    public string create_time { get; set; }
}

public class SearchFields
{
    public string[] tags { get; set; }
}

public class Extension
{
    public string @type { get; set; }
    public byte[] value { get; set; }
}

public class Assignment
{
    public string connection { get; set; }
    public Dictionary<string, Extension> extensions { get; set; }
}

Quelle que soit la façon dont vous choisissez de gérer votre HUD, assurez-vous de créer votre MatchmakerManager instance dans votre Start() fonction pour garantir que le code fonctionne correctement.

Une fois que le joueur a créé un ticket, vous devrez vérifier périodiquement son statut afin d'obtenir les réelle informations dès que 2 tickets ont été appariés, car le ticket sera supprimé quelques minutes après la définition de cette valeur. Une fois que vous avez le réelle, vous pouvez connecter le joueur au match.

Construire le serveur de jeu et conteneuriser

Une fois que vous avez terminé d'ajouter les modifications de l'étape précédente au projet, vous devrez construire votre serveur de jeu et le containeriser. Tout d'abord, assurez-vous que le NetworkManager gameObject a les réglages suivants :

• Activer Auto Start Server Build dans le NetworkManager composant ;

• Définissez le port du KcpTransport composant à la même valeur que celle que vous avez utilisée pour le GameServerPort dans le composant Director.

Dans cet exemple, nous avons utilisé `7777` pour les deux valeurs.

Une fois cela fait, rendez-vous sur le Construction de l'éditeur Unity, sous Fichier -> Paramètres de compilation dans les menus supérieurs. Assurez-vous de sélectionner les bons préréglages selon votre version d'Unity.

• Avant la version 2021.2 :

  • Définir Plateforme cible vers Linux;

  • Définir Architecture vers x86_64;

  • Cochez la Server Build .

• Sinon :

  • Définir Plateforme vers Serveur dédié;

  • Définir Plateforme cible vers Linux.

Puis appuyez sur construire et sélectionnez un nouveau dossier vide nommé linux_server comme destination de fichier. Transférez le linux_server dossier dans un second dossier vide, qui sera appelé [BUILD DU SERVEUR] dossier mentionné dans ce document. Ajoutez le fichier suivant Dockerfile et boot.sh au dossier [BUILD DU SERVEUR] dossier :

Dockerfile

FROM ubuntu:bionic
MAINTAINER edgegap

ARG debian_frontend=noninteractive
ARG docker_version=17.06.0-ce

RUN apt-get update && \
apt-get install -y libglu1 xvfb libxcursor1

# Mettre à jour le CA racine pour s'assurer que les requêtes HTTPS sortantes ne échouent pas
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    update-ca-certificates && \
    apt-get clean

EXPOSE 3389/TCP
EXPOSE [PORT_JEU]/TCP
EXPOSE [PORT_JEU]/UDP

COPY linux_server/ /root/linux_server/
COPY boot.sh /boot.sh

WORKDIR /root/
ENTRYPOINT ["/bin/bash", "/boot.sh"]

Assurez-vous de remplacer les [PORT_JEU] remplissez les espaces réservés avec la même port valeur qu'avant.

boot.sh

xvfb-run --auto-servernum --server-args='-screen 0 640X480X24:32' /root/build/[VOTRE JEU].x86_64 -batchmode -nographics

Assurez-vous de remplacer les [VOTRE JEU] espace réservé avec le nom du fichier généré.

Ensuite, lancez une invite de commandes dans le [BUILD DU SERVEUR] dossier ; Exécutez les commandes Docker suivantes pour créer une image de votre build et la pousser vers un registre privé. Voir ce doc si vous souhaitez utiliser le registre privé d'Edgegap.

Utilisation de Linux

# construire l'image
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# connexion, une invite demandera le mot de passe
docker login -u '<NOM_UTILISATEUR_REGISTRE>' <URL_REGISTRE>

# ajouter une autre étiquette à votre image correspondant au registre
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# pousser l'image
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

Utilisation de cmd

# construire l'image
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# connexion, une invite demandera le mot de passe
docker login -u <NOM_UTILISATEUR_REGISTRE> <URL_REGISTRE>

# ajouter une autre étiquette à votre image correspondant au registre
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# pousser l'image
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

Utilisation de Powershell

# construire l'image
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# connexion, une invite demandera le mot de passe
docker login -u '<NOM_UTILISATEUR_REGISTRE>' <URL_REGISTRE>

# ajouter une autre étiquette à votre image correspondant au registre
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# pousser l'image
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

Déploiement sur Edgegap

Créez une nouvelle application sur le tableau de bord Edgegap avec les paramètres suivants :

• Nom de l'application : Assurez-vous qu'il s'agit du même nom que celui que vous avez utilisé pour le AppName dans le composant Director de votre Matchmaker. Doit être en minuscules.

• Image : Peut être n'importe quelle image spécifique que vous souhaitez utiliser pour reconnaître facilement votre application parmi d'autres.

• Nom de la version : Assurez-vous qu'il s'agit de la même version que celle que vous avez utilisée pour le AppVersion dans le composant Director de votre Matchmaker. Des exemples peuvent être « demo », « production », « v1 », « v2 »

• Conteneur :

  • Registre : « [URL] », où [URL] est la valeur des identifiants affichables sur la page du dépôt de conteneurs.

  • Répertoire d'image : « [PROJET]/[VOTRE JEU] », où [PROJET] et [VOTRE JEU] sont les valeurs que vous avez utilisées précédemment lors de la poussée de l'image docker.

  • Tag : « [TAG] », où [TAG] est la valeur que vous avez utilisée précédemment lors de la poussée de l'image docker.

  • Cochez « Utiliser un dépôt privé »

  • Nom d'utilisateur du registre privé : « [NOM_UTILISATEUR] », où [NOM_UTILISATEUR] est la valeur de vos identifiants.

  • Jeton du registre privé : « [TOKEN] », où [TOKEN] est la valeur de vos identifiants.

  • Exigences : Laisser tel quel.

  • Ports :

    • Cliquez sur le + Ajouter un port lien pour ajouter un nouveau port, et ajoutez les entrées suivantes :

      • [PORT_JEU] - TCP/UDP - désactiver les vérifications

      • 3389 - TCP - désactiver les Vérifications

Nous recommandons de définir un Durée maximale de jeu dans votre application également, afin que vos déploiements s'autoterminant après quelques minutes puisque le Matchmaker créera automatiquement de nouveaux déploiements lors de l'appariement des tickets.

Ceci afin de vous assurer de ne pas avoir de déploiements vides en fonctionnement trop longtemps.

Tests avec des builds client

Pour vérifier si le Matchmaker fonctionne comme prévu, vous devrez lancer le jeu sur 2 instances clientes séparées et avoir également votre release Matchmaker en cours d'exécution.

Avant de créer une build client du jeu, assurez-vous de décocher l'option Auto Start Server Build de l' NetworkManager gameObject. Ensuite, selon le type de release Matchmaker que vous testez, changez la MATCHMAKER_URL comme suit :

• Local : changez-la en "http://localhost:51504"

• Avec Edgegap : changez-la en la valeur affichée sur le tableau de bord Edgegap après avoir activé la release. Vous n'avez pas besoin de spécifier le port dans ce cas.

Ensuite, retournez dans le Construction de l'éditeur Unity, sous Fichier -> Paramètres de compilation dans les menus supérieurs. Sélectionnez la Windows, Mac, Linux plateforme et la plateforme cible correcte pour votre environnement. Ensuite, appuyez sur build et sélectionnez un nouveau dossier vide nommé client_build comme destination de fichier.

Une fois que vous lancez les deux clients (soit deux fenêtres de votre build client, soit une fenêtre de build et l'éditeur Unity), faites-les sélectionner tous les deux le même mode de jeu et créer leurs tickets. Après un court instant, les deux clients seront connectés à un serveur nouvellement déployé, dont vous pouvez voir le statut sur le tableau de bord Edgegap.

Si vous testez avec la release en ligne de votre Matchmaker, il existe actuellement un problème lié aux certificats si vous activez et désactivez votre release Matchmaker plusieurs fois par semaine ; cela empêchera les requêtes vers votre Matchmaker de fonctionner avec Unity.

Pour résoudre cela, désactivez simplement votre release, mettez-la à jour avec un nom différent, puis republiez-la. Assurez-vous ensuite que l'URL dans votre code est la bonne.