Regrouper les decks d'un jeu de cartes en archétypes

Un archétype est un groupe de decks qui partagent les mêmes cartes déterminantes. Deux decks peuvent avoir des cartes de soutien différentes et se jouer de la même façon : comparer des archétypes plutôt que des decks individuels montre donc quelles stratégies sont fortes.

Pour montrer à quoi cela ressemble, nous avons créé un jeu de cartes d'exemple avec 12 cartes et 600 matchs répartis sur deux versions, 1.0.0 et 1.1.0. Chaque deck contient six cartes. La version 1.1.0 a réduit l'attaque d'une carte Legendary nommée Ember Dragon de 8 à 6.

Game Stats AI appelle les cartes des personnages : les cartes sont donc envoyées à l'endpoint des personnages, et les paramètres d'archétype utilisent des filtres de personnage.

Étape 1 : choisir un token

Les cartes et les matchs peuvent venir du client du jeu ou d'un serveur de matchs que vous gérez. Utilisez un token serveur si c'est un serveur qui les envoie, ou un token client si c'est le client du jeu. Créez le token dans Paramètres > Tokens API, où vous trouverez aussi l'identifiant de votre compte.

Les exemples ci-dessous utilisent curl avec ces deux valeurs dans des variables d'environnement :

export GAMESTATS_TOKEN=your_api_token
export ACCOUNT_ID=your_account_id

Étape 2 : envoyer vos cartes

Envoyez chaque carte à l'endpoint des personnages, avec la version dans laquelle elle apparaît pour la première fois. Le external_id est l'identifiant que votre jeu utilise pour la carte, name est le nom affiché dans les rapports, et character_attributes contient les propriétés de la carte :

curl -i -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/characters" \
  -H "Authorization: Bearer $GAMESTATS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ember_dragon",
    "name": "Ember Dragon",
    "version_name": "1.0.0",
    "character_attributes": {"rarity": "Legendary", "element": "Fire", "attack": 8}
  }'

external_id, name et version_name sont obligatoires. Les archétypes sont construits à partir des attributs : incluez donc celui que vous voulez utiliser pour regrouper les decks. Dans l'exemple, il s'agit de rarity, avec les valeurs Common, Rare, Epic et Legendary.

Quand un patch modifie une carte, renvoyez cette carte avec le nouveau version_name. Les cartes que vous ne renvoyez pas conservent leurs attributs de la version précédente. Pour la version 1.1.0, l'exemple renvoie Ember Dragon avec "attack": 6.

Étape 3 : envoyer les images des cartes (facultatif)

Les rapports représentent chaque archétype par les images de ses cartes. Pour ajouter une image, envoyez-la à l'endpoint des images de personnages une fois la carte créée :

curl -i -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/character_images" \
  -H "Authorization: Bearer $GAMESTATS_TOKEN" \
  -F "character_external_id=ember_dragon" \
  -F "image=@ember_dragon.png"

Une carte sans image est représentée par la première lettre de son nom.

Étape 4 : envoyer chaque match

À la fin d'un match, envoyez-le à l'endpoint des matchs. Chaque joueur reçoit une valeur win et une valeur loss égales à 1 ou 0, ainsi qu'un événement de match pour chaque carte de son deck :

curl -i -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/matches" \
  -H "Authorization: Bearer $GAMESTATS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "match_110_42",
    "version_name": "1.1.0",
    "match_at": "2026-10-04T18:20:00Z",
    "match_players": [
      {
        "username": "player_3e8",
        "match_attributes": {"win": 1, "loss": 0},
        "match_events": [
          {"character_external_id": "ember_dragon", "event_type_name": "in_deck"},
          {"character_external_id": "flame_imp", "event_type_name": "in_deck"},
          {"character_external_id": "spark_beetle", "event_type_name": "in_deck"},
          {"character_external_id": "moss_troll", "event_type_name": "in_deck"},
          {"character_external_id": "pebble_crab", "event_type_name": "in_deck"},
          {"character_external_id": "gust_hawk", "event_type_name": "in_deck"}
        ]
      },
      {
        "username": "player_40d",
        "match_attributes": {"win": 0, "loss": 1},
        "match_events": [
          {"character_external_id": "tide_serpent", "event_type_name": "in_deck"},
          {"character_external_id": "storm_caller", "event_type_name": "in_deck"},
          {"character_external_id": "river_sprite", "event_type_name": "in_deck"},
          {"character_external_id": "mist_frog", "event_type_name": "in_deck"},
          {"character_external_id": "gust_hawk", "event_type_name": "in_deck"},
          {"character_external_id": "breeze_moth", "event_type_name": "in_deck"}
        ]
      }
    ]
  }'

Une réponse 201 signifie que le match a été accepté. Les joueurs, les versions et les types d'événements sont créés à la première utilisation. Le external_id identifie le match : renvoyer le même match le met à jour au lieu de le compter deux fois.

Les événements de match de chaque joueur forment le deck de ce joueur pour le match.

Étape 5 : choisir les cartes qui définissent un archétype

Activez le module Archetypes dans Paramètres > Modules de jeu. Ouvrez ensuite Paramètres > Archetype Configurations, sélectionnez Nouveau, cochez Active, puis sélectionnez Ajouter un filtre de personnage. Choisissez l'attribut et les valeurs qui font d'une carte une carte déterminante. L'exemple utilise rarity avec Epic et Legendary :

L'archétype d'un deck est l'ensemble de ses cartes qui correspondent aux filtres. Avec ce filtre :

• Un deck avec Ember Dragon et aucune autre carte Epic ou Legendary appartient à l'archétype Ember Dragon.
• Un deck avec Ember Dragon et Stone Golem, une carte Epic, appartient à un archétype distinct, Ember Dragon et Stone Golem.
• Un deck qui ne contient que des cartes Common et Rare est regroupé sous « Aucun personnage déterminant ».

Quand vous ajoutez plusieurs filtres, une carte doit correspondre à tous les filtres pour être prise en compte. Au sein d'un même filtre, il suffit qu'elle corresponde à l'une des valeurs sélectionnées.

Les attributs sont lus dans la version de chaque match. Si un patch modifie la rareté d'une carte, les decks de cette version peuvent appartenir à un archétype différent de celui d'avant.

L'enregistrement de la configuration regroupe les decks des matchs déjà envoyés, et les nouveaux matchs sont regroupés à leur arrivée. Le regroupement s'exécute en arrière-plan : les archétypes peuvent donc mettre quelques minutes à apparaître. Si vous modifiez les filtres plus tard, tous les decks sont regroupés à nouveau, au plus une fois toutes les 10 minutes.

Étape 6 : créer un rapport d'archétypes

Dans Rapports > Nouveau rapport, choisissez Rapport d'archétypes, donnez-lui un libellé et ajoutez trois métriques de match :

Ajoutez Win Rate en premier : le graphique du rapport affiche la première métrique. Réglez sa précision numérique sur 1 pour afficher une décimale, et cochez Use for sorting pour classer les archétypes du taux de victoire le plus élevé au plus bas.

Étape 7 : comparer les deux versions

Le rapport s'ouvre filtré sur votre dernière version, et chaque valeur indique son évolution par rapport à la version précédente :

Dans le jeu d'exemple, les archétypes sont beaucoup plus proches les uns des autres en 1.1.0 :

Les decks Ember Dragon ont perdu 10,4 points et ne sont plus en tête du rapport. Les decks qui contiennent à la fois Ember Dragon et Stone Golem ont perdu 4,0 points. Les decks Stone Golem ont le plus progressé, de 9,8 points, et tous les archétypes avec des cartes déterminantes se situent désormais entre 50 % et 53 %.

Pour examiner une version plus ancienne, choisissez-la dans les filtres : le rapport la compare avec la version précédente, s'il y en a une. Sélectionnez plusieurs versions pour les voir combinées, sans les valeurs d'évolution.

Si vous suivez des personnages individuels plutôt que des decks, Taux de victoire par personnage dans un jeu de combat crée le même type de rapport pour chaque personnage.