Cómo agrupar mazos de un juego de cartas en arquetipos

Un arquetipo es un grupo de mazos que comparten las mismas cartas definitorias. Dos mazos pueden tener cartas de apoyo distintas y aun así jugarse de la misma manera, así que comparar arquetipos en lugar de mazos individuales muestra qué estrategias son fuertes.

Para mostrar cómo se ve eso, armamos un juego de cartas de ejemplo con 12 cartas y 600 partidas en dos versiones, 1.0.0 y 1.1.0. Cada mazo tiene seis cartas. La versión 1.1.0 bajó el ataque de una carta Legendary llamada Ember Dragon de 8 a 6.

Game Stats AI llama personajes a las cartas, así que las cartas se envían al endpoint de personajes, y la configuración de arquetipos usa filtros de personaje.

Paso 1: elige un token

Las cartas y las partidas pueden venir del cliente del juego o de un servidor de partidas propio. Usa un token server si las envía un servidor, o un token client si las envía el cliente del juego. Crea el token en Configuración > Tokens de API, donde también encuentras el id de tu cuenta.

Los ejemplos de abajo usan curl con ambos valores en variables de entorno:

export GAMESTATS_TOKEN=your_api_token
export ACCOUNT_ID=your_account_id

Paso 2: envía tus cartas

Envía cada carta al endpoint de personajes con la versión en la que aparece por primera vez. El external_id es el id que tu juego usa para la carta, name es lo que muestran los informes, y character_attributes contiene las propiedades de la carta:

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 y version_name son obligatorios. Los arquetipos se construyen a partir de los atributos, así que incluye el atributo por el que quieres agrupar. En el ejemplo es rarity, con los valores Common, Rare, Epic y Legendary.

Cuando un parche cambia una carta, envía esa carta otra vez con el nuevo version_name. Las cartas que no vuelves a enviar conservan los atributos de la versión anterior. Para la versión 1.1.0, el ejemplo envía Ember Dragon otra vez con "attack": 6.

Paso 3: envía las imágenes de las cartas (opcional)

Los informes muestran cada arquetipo con las imágenes de sus cartas. Para agregar una imagen, súbela al endpoint de imágenes de personajes después de que exista la carta:

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"

Una carta sin imagen se muestra con la primera letra de su nombre.

Paso 4: envía cada partida

Cuando termine una partida, envíala al endpoint de partidas. Cada jugador lleva un valor win y uno loss de 1 o 0, y un evento de partida por cada carta de su mazo:

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"}
        ]
      }
    ]
  }'

Una respuesta 201 significa que la partida fue aceptada. Los jugadores, las versiones y los tipos de evento se crean la primera vez que se usan. El external_id identifica la partida, así que enviar la misma partida otra vez la actualiza en lugar de contarla dos veces.

Los eventos de partida de cada jugador forman el mazo de ese jugador en la partida.

Paso 5: elige qué cartas definen un arquetipo

Activa el módulo Archetypes en Configuración > Módulos de juego. Luego abre Configuración > Archetype Configurations, selecciona Nuevo, marca Active y selecciona Agregar filtro de personaje. Elige el atributo y los valores que hacen que una carta sea definitoria. El ejemplo usa rarity con Epic y Legendary:

El arquetipo de un mazo es el conjunto de sus cartas que cumplen los filtros. Con este filtro:

• Un mazo con Ember Dragon y ninguna otra carta Epic o Legendary pertenece al arquetipo Ember Dragon.
• Un mazo con Ember Dragon y Stone Golem, una carta Epic, pertenece a otro arquetipo, Ember Dragon y Stone Golem.
• Un mazo con solo cartas Common y Rare se agrupa en Sin personajes definitorios.

Cuando agregas más de un filtro, una carta tiene que cumplir todos los filtros para contar. Dentro de un mismo filtro, basta con que cumpla cualquiera de los valores seleccionados.

Los atributos se leen según la versión de cada partida. Si un parche cambia la rareza de una carta, los mazos de esa versión pueden pertenecer a un arquetipo distinto al de antes.

Al guardar la configuración se agrupan los mazos de las partidas que ya enviaste, y las partidas nuevas se agrupan a medida que llegan. La agrupación se ejecuta en segundo plano, así que los arquetipos pueden tardar unos minutos en aparecer. Si cambias los filtros después, todos los mazos se agrupan otra vez, como máximo una vez cada 10 minutos.

Paso 6: crea un informe de arquetipos

En Informes > Nuevo informe, elige Informe de arquetipos, ponle una etiqueta y agrega tres métricas de partida:

Agrega Win Rate primero: el gráfico del informe muestra la primera métrica. Pon su precisión numérica en 1 para mostrar un decimal, y marca Use for sorting para ordenar los arquetipos de la tasa de victoria más alta a la más baja.

Paso 7: compara las dos versiones

El informe abre filtrado a tu versión más reciente, y cada valor muestra cuánto cambió frente a la versión anterior:

En el juego de ejemplo, los arquetipos quedan mucho más parejos en 1.1.0:

Los mazos Ember Dragon bajaron 10.4 puntos y ya no están en el primer lugar del informe. Los mazos con Ember Dragon y Stone Golem bajaron 4.0 puntos. Los mazos Stone Golem fueron los que más subieron, 9.8 puntos, y ahora todos los arquetipos con cartas definitorias están entre el 50% y el 53%.

Para revisar una versión anterior, elígela en los filtros y el informe la compara con la versión anterior a ella, si existe. Selecciona más de una versión para verlas combinadas, sin los valores de cambio.

Si haces seguimiento de personajes individuales en lugar de mazos, Tasa de victoria por personaje en un juego de pelea crea el mismo tipo de informe para cada personaje.