Version: en

Contracts - Config File

warning

This documentatin is now deprecated. If you are using Matchmaker Self Serve though UDash contact us directly to get access to the new documentation

Main Contract#

{
"Matchmaking":{...},
"Multiplay":{...}
}
FieldDescriptionType
matchmakingConfiguration for continuously running matchmaking.object
multiplayMultiplayer information matchmaking uses to allocate game servers. This field is optional. If no multiplay config is specified, the config still results in running the matchmaking logic. However, no server is allocated for the proposed matches.MultiplayConfig

Matchmaking Field#

{
"Name":"{Config-File-Name}",
"TargetFunction": {"Name":"standard"},
"Pools":{...},
"Config":{...}
}
FieldDescriptionType
nameConfiguration for continuously running matchmaking.string
TargetFunction.NameCurrently only supports "standard" and "rule-based" ("standard-function" is valid but deprecated). The value is case insensitive and the lowercase representation of the name will be used in the matchmaker.string
PoolsContains the different attributes used to isolate ticket population.Dictionary<string, PoolFilter[]]>
ConfigConfigurable properties that manage the matchmaking logic. (required)object

Pools#

{
"Pools": {
"standard": [
{
"Attribute": "platform",
"Max": 3.0,
"Min": 0.0
},
{
"Attribute": "build",
"Max": 1000.0,
"Min": 0.0
}
]
}
}
FieldDescriptionType
standardAn array of attributes to be used to isolate the ticket population.List<Attribute>
AttributeThe name of the attribute.string
MaxThe maximum value possible for this attribute.double
MinThe minimum value possible for this attribute.double

Currently only supports the standard pool. Ticket query information that the match logic uses to look for players that meet its criteria.

PoolFilter#
{
"attribute": "skill",
"min": 0,
"max": 3000,
"segmentation": {
"DistributionType": "Normal",
"SegmentBehaviorType": "BucketCount",
"Value": 10,
"Stddev": 750
}
}
FieldDescriptionType
attributeThe name of the indexable attribute on the ticket to query on. Filters are currently intersecting only.string
minThe min range (inclusive) for the double field.double
maxThe max range (exclusive) for the double field.

Note: When min==max, max is made inclusive to allow for the finding of single values. For example, using "min":1, "max":1 matches the interval [1,1] (both min and max are inclusive), and using "min":1, "max":3 matches the interval [1, 3) (min inclusive, max exclusive).
double
segmentationA method for automatically generating non-intersecting filters from a basic filter. See the documentation on segmentation and scale.object
distributionTypeA description of the curve estimating the shape of the population for the given attribute. Currently supports Normal and Uniform. See the documentation on segmentation and scale.string
segmentBehaviorTypeThe method to subdivide the curve described in the distributionType. Current options are TargetPercentage, BucketSize, and BucketCount. See the documentation on segmentation and scale.string
ValueThe target for the segmentBehaviorType. For example, the value for the behavior type BucketCount is the number of buckets that are used to break the filters into. See the documentation on segmentation and scale.integer
StddevThe standard deviation value that is required by the Normal distribution type. This is ignored with other distribution types.number

Rule-based Config#

{
"Name": "",
"DefaultQoSRegion": "REGION_ID",
"MatchDefinition": {...},
"DefaultScore": 0.0,
"TicketTimeoutMs": 10000.0,
"BackfillEnabled": false
}
FieldDescriptionTypeDefault Value
NameA friendly name for this configuration.string---
DefaultQoSRegionDefault Multiplay region ID.string---
MatchDefinitionConfigurable properties for the different teams in the game.object---
DefaultScoreAn arbitrary score for games generated by this configuration. This field is useful when creating multiple configurations. (Optional)double0.0
TicketTimeoutMsThe number of milliseconds before a ticket will be timed out. (Optional).double60 seconds
BackfillEnabledWhether to enable backfill support (requires DGS support, see Backfill Sample). (Optional).booleanfalse
MatchDefinition#
{
"Teams": [
{
"Name": "Hunters",
"TeamCount": {
"Min": 1.0,
"Max": 1.0
},
"PlayerCount": {
"Min": 3.0,
"Max": 4.0
},
"TeamRules": [ { Rule1 }, { Rule2 }, ... ]
},
{
"Name": "Monsters",
"TeamCount": {
"Min": 1.0,
"Max": 1.0
},
"PlayerCount": {
"Min": 3.0,
"Max": 4.0
},
"TeamRules": [ { Rule1 }, { Rule2 }, ... ]
}
],
"MatchRules": [ { Rule1 }, { Rule2 }, ... ]
}
FieldDescriptionType
TeamsA list of teams in a game.List<object>
MatchRulesA list of rules that apply in the Match level. Refer to the Rules Page for more informationList<object>
Teams[x].NameThe team name.string
Teams[x].TeamCountThe number of teams of this type in a game. Imagine a game that has 2 hunter teams and 1 monsters team.object
Teams[x].PlayerCountThe number of players allowed in this team.object
Teams[x].TeamRulesA list of rules that apply in the Team level for this specific team. Refer to the Rules Page for more informationList<object>

Standard Config#

{
"Name": "",
"QoSConfig":{...},
"TeamRules":{...},
"DefaultScore": 0.0,
"MinTicketAgeMs": 1000.0,
"MinBackfillTicketAgeMs": 0.0,
"TicketTimeoutMs": 10000.0,
"BackfillEnabled": false,
"IgnoreIncompatibleTickets": false
}
FieldDescriptionTypeDefault Value
NameA friendly name for this configuration.string---
QoSConfigConfigurable properties for QoS.object---
TeamRulesConfigurable properties for the different teams in the game.object---
DefaultScoreAn arbitrary score for games generated by this configuration. This field is useful when creating nested configurations. (Optional)double0.0
MinTicketAgeMsThe minimum number of milliseconds before a ticket can be considered for a match. (Optional).double0.0
MinBackfillTicketAgeMsThe minimum number of milliseconds before a backfill ticket can be considered for a match. (Optional).double0.0
TicketTimeoutMsThe number of milliseconds before a ticket will be timed out. (Optional).double
BackfillEnabledWhether to enable backfill support (requires DGS support, see Backfill Tutorial). (Optional).booleanfalse
IgnoreIncompatibleTicketsWhether or not a ticket should be assigned an error if it is incompatible with this config. Using this field is important to prevent a config assigning an error to a ticket that might be valid for a different config. (Optional).booleanfalse
caution

Enabling the IgnoreIncompatibleTickets flag will mean that reporting for incompatible tickets is lost. We recommend that TicketTimeoutMs be used when this field is set to false to avoid having tickets live forever.

QoSConfig#
{
"DefaultQoSRegion": "",
"MaxPacketLoss": {
"Value": 0.1
},
"MaxLatency": {
"Value": 200.0
},
"TopResultsToConsider": 1.0,
"GroupByStrategy": 1
}
FieldDescriptionType
DefaultQoSRegionThe Default QoS Region to use when the GroupByStrategy is set to 1 (Group By Default Region). (Required when GroupByStrategy = 1).string
MaxPacketLossThe maximum packet loss allowed for a ticket to be considered. (Required when GroupByStrategy = 0).object
MaxLatencyThe maximum latency allowed for a ticket to be considered. (Required when GroupByStrategy = 0).object
TopResultsToConsiderThe maximum number of results to consider when GroupByStrategy is set to 0 (Group By Best Region). (Required when GroupByStrategy = 0).double
GroupByStrategyThe grouping strategy for QoS.Valid values:
0 (Groups By Best Region)
1 (Groups By Default Region set in config file)
TeamRules#
{
"Teams": [
{
"Name": "Hunters",
"TeamCount": {
"Min": 1.0,
"Max": 1.0
},
"PlayerCount": {
"Min": 3.0,
"Max": 4.0
}
},
{
"Name": "Monsters",
"TeamCount": {
"Min": 1.0,
"Max": 1.0
},
"PlayerCount": {
"Min": 3.0,
"Max": 4.0
},
"AllowPartialMatchesAfterMs": 5000
}
]
}
FieldDescriptionType
TeamsA list of teams in a game.List<object>
Teams[x].NameThe team name.string
Teams[x].TeamCountThe number of teams of this type in a game. Imagine a game that has 2 hunter teams and 1 monsters team.object
Teams[x].PlayerCountThe number of players allowed in this team.object
Teams[x].AllowPartialMatchesAfterMsThe minimum age of all tickets at which partially full matches are created. (Optional)double
caution

Using a value greater than 0 for the AllowPartialMatchesAfterMs will not generate a match with the minimum specified PlayerCount unless the youngest ticket is older than the value specified. This setting will ensure a larger number of players in teams, with the caveat of longer time to match.

MultiplayConfig#

{
"Profile": "profileId",
"Access": "accessKey",
"Secret": "secretKey",
"FleetId": "fleetId"
}
FieldDescriptionType
ProfileThe Multiplay profile. This is typically associated with a build image revision, hardware specifications, server-side game configs, and resource definitions.string
AccessThe Multiplay access key. An AWS Access Key that is generated following Multiplay guidance.string
SecretThe Multiplay secret key. An AWS Secret Key that is generated following Multiplay guidance.string
FleetIdThe ID of the Multiplay fleet to allocate into.string

ValidationErrorResponse#

[
{
"ResultCode": "badFilterRange",
"Message": "Pool default' Filter mode has an invalid value range (Max < Min)",
},
{...}
]
FieldDescriptionType
ResultCodeA result code.string
MessageA message that describes which component of the config was invalid.string

Full Config Example#

In the following example, the matchmaking logic is configured to make proposals that have two teams of 3-4 players each.

{
"Matchmaking":{
"Name":"",
"TargetFunction": {
"Name": "standard"
},
"Pools":{
"standard": [
{
"Attribute": "attr0",
"Max": 1000,
"Min": 0.0
},
{
"Attribute": "attr1",
"Max": 1000.0,
"Min": 0.0
}
]
},
"Config":{
"Name": "",
"QoSConfig":{
"DefaultQoSRegion": "",
"MaxPacketLoss": {
"Value": 0.1
},
"MaxLatency": {
"Value": 200.0
},
"TopResultsToConsider": 1.0,
"GroupByStrategy": 0
},
"TeamRules":{
"Teams": [
{
"Name": "team0",
"TeamCount": {
"Min": 1.0,
"Max": 1.0
},
"PlayerCount": {
"Min": 3.0,
"Max": 4.0
}
},
{
"Name": "team1",
"TeamCount": {
"Min": 1.0,
"Max": 1.0
},
"PlayerCount": {
"Min": 3.0,
"Max": 4.0
}
}
]
},
"DefaultScore": 0.0,
"MinTicketAgeMs": 1000.0,
"MinBackfillTicketAgeMs": 0.0,
"TicketTimeoutMs": 10000.0
}
},
"Multiplay":{
"Profile": "",
"Access": "",
"Secret": "",
"FleetId": ""
}
}