Specifying attributes with your tickets
Rules determine which tickets are matched, based on the attributes specified by players. These attributes can be specified in two ways, either:
- Within the create ticket request
- In the player's entity
This tutorial describes how to specify those attributes.
Specifying within the create ticket request
For rules configured with the attribute type "User", attributes are specified in
a CreateMatchmakingTicket
request, alongside the player entity inside of an attributes DataObject
.
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"
}
Below is an example queue configuration with a DifferenceRule
. This rule
contains an attribute path and source that will pick up the value 16.0,
specified by the CreateMatchmakingTicket
request above.
"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
}
]
}
Note
Rules can navigate through the DataObject
with a JSON Path. Replacing the Path field with "nestExample.exp" would cause the rule to use the value 1500 for the ticket created above.
Specifying through player entities
For rules with the attribute type "Player Entity", attributes are specified through a separate call to the SetObjects
API.
This allows data to be stored for a user, rather than the title needing to specify it on each create ticket call.
This may make more sense for values that persist for a user, or that users cannot be trusted to submit. An example of this SetObjects
call is shown below.
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"
}
}
A queue with the following configuration would retrieve the value 16.0 for use in its DifferenceRule
rule, when a ticket is created with this player.
Note
In the Path
field, the first item after the root is the ObjectName
, allowing you to choose which stored object to reference.
"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
}
]
}
Special formats
Most rules use attributes that are either strings or numeric, and are simply those values in JSON format. Rules that require more complex attributes to be passed in are listed below.
Region Selection rule
A Region Selection rule requires an array of latency measurements with the specified schema. The following example is the expected attribute format for a region selection rule, shown alongside the two attributes used in the CreateMatchmakingTicket
request example for comparison.
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"
}
In this example, Latencies
must match the field referenced by the Path
field in the rule. An example of a rule which would use the Latencies
field is included in the queue below.
"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
}
]
}
Note
When using the region selection rule for a queue that has server allocation enabled, the regions must be valid Azure Regions. You can find the list of valid Azure Regions here.