Kaartspeldecks groeperen in archetypes

Een archetype is een groep decks die dezelfde bepalende kaarten delen. Twee decks kunnen verschillen in hun ondersteunende kaarten en toch op dezelfde manier spelen, dus als je archetypes vergelijkt in plaats van losse decks, zie je welke strategieën sterk zijn.

Om te laten zien hoe dat eruitziet, hebben we een voorbeeldkaartspel opgezet met 12 kaarten en 600 matches verdeeld over twee versies, 1.0.0 en 1.1.0. Elk deck heeft zes kaarten. Versie 1.1.0 verlaagde de aanval van een Legendary-kaart genaamd Ember Dragon van 8 naar 6.

Game Stats AI noemt kaarten personages, dus kaarten gaan naar het characters-endpoint, en de archetype-instellingen gebruiken personagefilters.

Stap 1: kies een token

Kaarten en matches kunnen uit de gameclient komen of van een matchserver die je zelf beheert. Gebruik een server-token als een server ze verstuurt, of een client-token als de gameclient dat doet. Maak het token aan bij Instellingen > API-tokens, waar je ook je account-id vindt.

De voorbeelden hieronder gebruiken curl met beide waarden in omgevingsvariabelen:

export GAMESTATS_TOKEN=your_api_token
export ACCOUNT_ID=your_account_id

Stap 2: verstuur je kaarten

Stuur elke kaart naar het characters-endpoint, met de versie waarin die voor het eerst voorkomt. De external_id is het id dat je game voor de kaart gebruikt, name is wat de rapporten tonen, en character_attributes bevat de eigenschappen van de kaart:

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 en version_name zijn verplicht. Archetypes worden opgebouwd uit de attributen, dus neem het attribuut op waarop je wilt groeperen. In het voorbeeld is dat rarity, met de waarden Common, Rare, Epic en Legendary.

Wanneer een patch een kaart verandert, stuur je die kaart opnieuw met de nieuwe version_name. Kaarten die je niet opnieuw verstuurt, houden hun attributen uit de eerdere versie. Voor versie 1.1.0 verstuurt het voorbeeld Ember Dragon opnieuw met "attack": 6.

Stap 3: verstuur kaartafbeeldingen (optioneel)

De rapporten tonen elk archetype als de afbeeldingen van de kaarten erin. Om een afbeelding toe te voegen, upload je die naar het endpoint voor personageafbeeldingen nadat de kaart bestaat:

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"

Een kaart zonder afbeelding wordt getoond als de eerste letter van de naam.

Stap 4: verstuur elke match

Stuur een match naar het matches-endpoint zodra die afgelopen is. Elke speler krijgt een win- en een loss-waarde van 1 of 0, en één match-event voor elke kaart in zijn 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"}
        ]
      }
    ]
  }'

Een 201-antwoord betekent dat de match is geaccepteerd. Spelers, versies en eventtypes worden aangemaakt bij het eerste gebruik. De external_id identificeert de match, dus als je dezelfde match opnieuw verstuurt, wordt die bijgewerkt in plaats van dubbel geteld.

De match-events van elke speler vormen het deck van die speler voor de match.

Stap 5: kies welke kaarten een archetype bepalen

Zet de module Archetypes aan bij Instellingen > Spelmodules. Open daarna Instellingen > Archetype Configurations, selecteer Nieuw, vink Active aan en selecteer Personagefilter toevoegen. Kies het attribuut en de waarden die van een kaart een bepalende kaart maken. Het voorbeeld gebruikt rarity met Epic en Legendary:

Het archetype van een deck is de verzameling kaarten in dat deck die aan de filters voldoen. Met dit filter:

• Een deck met Ember Dragon en geen andere Epic- of Legendary-kaart hoort bij het archetype Ember Dragon.
• Een deck met Ember Dragon en Stone Golem, een Epic-kaart, hoort bij een apart archetype Ember Dragon en Stone Golem.
• Een deck met alleen Common- en Rare-kaarten wordt gegroepeerd onder Geen bepalende personages.

Als je meer dan één filter toevoegt, moet een kaart aan elk filter voldoen om mee te tellen. Binnen één filter is het genoeg als de kaart een van de geselecteerde waarden heeft.

Attributen worden gelezen in de versie van elke match. Als een patch de zeldzaamheid van een kaart verandert, kunnen decks uit die versie bij een ander archetype horen dan ervoor.

Wanneer je de configuratie opslaat, worden de decks uit de matches die je al hebt verstuurd gegroepeerd, en nieuwe matches worden gegroepeerd zodra ze binnenkomen. Het groeperen gebeurt op de achtergrond, dus het kan een paar minuten duren voordat de archetypes verschijnen. Als je de filters later wijzigt, wordt elk deck opnieuw gegroepeerd, hoogstens eens per 10 minuten.

Stap 6: bouw een archetyperapport

Kies bij Rapporten > Nieuw rapport voor Archetyperapport, geef het een label en voeg drie wedstrijdmetrieken toe:

Voeg Win Rate als eerste toe: de grafiek van het rapport toont de eerste metriek. Zet het aantal decimalen op 1 om één decimaal te tonen, en vink Use for sorting aan om de archetypes te sorteren van de hoogste winrate naar de laagste.

Stap 7: vergelijk de twee versies

Het rapport opent gefilterd op je nieuwste versie, en bij elke waarde staat hoeveel die veranderd is ten opzichte van de versie ervoor:

In het voorbeeldkaartspel liggen de archetypes in 1.1.0 veel dichter bij elkaar:

De winrate van het archetype Ember Dragon daalde 10.4 punten, en het staat niet langer bovenaan het rapport. Decks met zowel Ember Dragon als Stone Golem daalden 4.0 punten. Het archetype Stone Golem steeg het meest, 9.8 punten, en elk archetype met bepalende kaarten ligt nu tussen 50% en 53%.

Wil je een oudere versie bekijken, kies die dan in de filters: het rapport vergelijkt die met de versie ervoor, als die bestaat. Selecteer meer dan één versie om ze gecombineerd te zien, zonder de veranderingen.

Houd je losse personages bij in plaats van decks, dan bouwt Winrates per personage bijhouden in een vechtgame hetzelfde soort rapport voor elk personage.