Spécification d'attributs avec vos tickets

Les règles déterminent quels tickets sont mis en correspondance, en fonction des attributs spécifiés par les joueurs. Ces attributs peuvent être spécifiés de deux façons :

Dans la requête de création de ticket
Dans l’entité du joueur

Ce tutoriel décrit comment spécifier ces attributs.

Spécification dans la requête de création de ticket

Pour les règles configurées avec le type d’attribut « Utilisateur », les attributs sont spécifiés dans une requête CreateMatchmakingTicket, avec l’entité du joueur, à l’intérieur d’un DataObject d’attributs.

POST https://{{TitleId}}.playfabapi.com/Match/CreateMatchmakingTicket
{
    "Creator": {
        "Entity": {
            "Id": "A8140AB9109712B",
            "Type": "title_player_account",
            "TypeString": "title_player_account"
        },
        "Attributes": {
            "DataObject": {
                "mu": 16.0,
                "sigma": 1.8,
                "nestExample": {
                    "exp": 1500
                }
            }
        }
    },
    "MembersToMatchWith": [],
    "GiveUpAfterSeconds": 2,
    "QueueName": "SkillRuleQueue"
}

Voici un exemple de configuration de file d’attente avec une DifferenceRule. Cette règle contient un chemin et une source d’attribut qui récupèrent la valeur 16.0, spécifiée par la requête CreateMatchmakingTicket ci-dessus.

"MatchmakingQueue": {
    "Name": "SkillRuleQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": false,
    "Rules": [
        {
            "Type": "DifferenceRule",
            "Difference": 3,
            "MergeFunction": "Average",
            "Attribute": {
                "Path": "mu",
                "Source": "User"
            },
            "AttributeNotSpecifiedBehavior": "MatchAny",
            "Weight": 1,
            "Name": "SkillRule",
            "SecondsUntilOptional": 10
        }
    ]
}

Les règles peuvent parcourir le DataObject à l’aide d’un JSON Path. Remplacer le champ Path par “nestExample.exp” amènerait la règle à utiliser la valeur 1500 pour le ticket créé ci-dessus.

Spécification au moyen des entités joueur

Pour les règles dont le type d’attribut est « Entité joueur », les attributs sont spécifiés au moyen d’un appel distinct à l’API SetObjects. Cela permet de stocker des données pour un utilisateur, plutôt que le titre ait à les spécifier à chaque appel de création de ticket. Cela peut être plus pertinent pour des valeurs qui persistent pour un utilisateur, ou que l’on ne peut pas confier aux utilisateurs le soin de soumettre. Un exemple de cet appel SetObjects est présenté ci-dessous.

POST https://{{TitleID}}.playfabapi.com/Object/SetObjects
{
    "Objects": [
        {
            "ObjectName": "playerSkill",
            "DataObject": {
                "skillDetail": {
                    "mu": 16.0,
                    "sigma": 2.0
                }
            }
        }
    ],
    "Entity": {
        "Id": "A8140AB9109712B",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
    }
}

Une file d’attente avec la configuration suivante récupérerait la valeur 16.0 pour l’utiliser dans sa règle DifferenceRule, lorsqu’un ticket est créé avec ce joueur.

Dans le champ Path, le premier élément après la racine est l’ObjectName, ce qui vous permet de choisir l’objet stocké à référencer.

"MatchmakingQueue": {
    "Name": "PlayerEntityRuleQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": false,
    "Rules": [
        {
            "Type": "DifferenceRule",
            "Difference": 1,
            "MergeFunction": "Average",
            "Attribute": {
                "Path": "$.playerSkill.skillDetail.mu",
                "Source": "PlayerEntity"
            },
            "AttributeNotSpecifiedBehavior": "MatchAny",
            "Weight": 1,
            "Name": "SkillRule",
            "SecondsUntilOptional": 10
        }
    ]
}

Formats spéciaux

La plupart des règles utilisent des attributs de type chaîne ou numérique, qui sont simplement ces valeurs au format JSON. Les règles qui nécessitent la transmission d’attributs plus complexes sont répertoriées ci-dessous.

Règle de sélection de région

Une règle de sélection de région nécessite un tableau de mesures de latence conforme au schéma spécifié. L’exemple suivant présente le format d’attribut attendu pour une règle de sélection de région, accompagné des deux attributs utilisés dans l’exemple de requête CreateMatchmakingTicket à titre de comparaison.

POST https://{{TitleId}}.playfabapi.com/Match/CreateMatchmakingTicket
{
    "Creator": {
        "Entity": {
            "Id": "A8140AB9109712B",
            "Type": "title_player_account",
            "TypeString": "title_player_account"
        },
        "Attributes": {
            "DataObject": {
                "mu": 16.0,
                "sigma": 1.8,
                "Latencies": [
                    {
                        "region": "EastUs",
                        "latency": 150
                    },
                    {
                        "region": "WestUs",
                        "latency": 400
                    }
                ]
            }
        }
    },
    "MembersToMatchWith": [],
    "GiveUpAfterSeconds": 2,
    "QueueName": "ServerEnabledQueue"
}

Dans cet exemple, Latencies doit correspondre au champ référencé par le champ Path de la règle. Un exemple de règle qui utiliserait le champ Latencies est inclus dans la file d’attente ci-dessous.

"MatchmakingQueue": {
    "Name": "ServerEnabledQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": true,
    "BuildId": "88b3e315-829c-4b6d-9872-74f427ad5331",
    "Rules": [
        {
            "Type": "RegionSelectionRule",
            "MaxLatency": 1000,
            "Path": "Latencies",
            "Weight": 1,
            "Name": "RegionRule",
            "SecondsUntilOptional": 60
        }
    ]
}

Lorsque vous utilisez la règle de sélection de région pour une file d’attente dont l’allocation de serveur est activée, les régions doivent être des régions Azure valides. Vous trouverez la liste des régions Azure valides ici.

XBOX Services

PlayFab

Spécification dans la requête de création de ticket

Spécification au moyen des entités joueur

Formats spéciaux

Règle de sélection de région

​Spécification dans la requête de création de ticket

​Spécification au moyen des entités joueur

​Formats spéciaux

​Règle de sélection de région

Spécification dans la requête de création de ticket

Spécification au moyen des entités joueur

Formats spéciaux

Règle de sélection de région