Version: en

Contracts - Config File

warning

This documentation is now deprecated. If you are using Matchmaker Self Serve though UDash, please use the documentation here.

Main Contract#

{
    "Matchmaking":{...},
    "Multiplay":{...}
}

Field	Description	Type
`matchmaking`	Configuration for continuously running matchmaking.	object
`multiplay`	Multiplayer 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":{...}
}

Field	Description	Type
`name`	Configuration for continuously running matchmaking.	string
`TargetFunction.Name`	Currently 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
`Pools`	Contains the different attributes used to isolate ticket population.	Dictionary<string, PoolFilter[]]>
`Config`	Configurable 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
      }
    ]
  }
}

Field	Description	Type
`standard`	An array of attributes to be used to isolate the ticket population.	`List<Attribute>`
`Attribute`	The name of the attribute.	string
`Max`	The maximum value possible for this attribute.	double
`Min`	The 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
  }
}

Field	Description	Type
`attribute`	The name of the indexable attribute on the ticket to query on. Filters are currently `intersecting` only.	string
`min`	The min range (inclusive) for the double field.	double
`max`	The 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
`segmentation`	A method for automatically generating non-intersecting filters from a basic filter. See the documentation on segmentation and scale.	object
`distributionType`	A 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
`segmentBehaviorType`	The method to subdivide the curve described in the `distributionType`. Current options are `TargetPercentage`, `BucketSize`, and `BucketCount`. See the documentation on segmentation and scale.	string
`Value`	The 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
`Stddev`	The 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
}

Field	Description	Type	Default Value
`Name`	A friendly name for this configuration.	`string`	---
`DefaultQoSRegion`	Default Multiplay region ID.	`string`	---
`MatchDefinition`	Configurable properties for the different teams in the game.	`object`	---
`DefaultScore`	An arbitrary score for games generated by this configuration. This field is useful when creating multiple configurations. (Optional)	`double`	0.0
`TicketTimeoutMs`	The number of milliseconds before a ticket will be timed out. (Optional).	`double`	60 seconds
`BackfillEnabled`	Whether to enable backfill support (requires DGS support, see Backfill Sample). (Optional).	`boolean`	`false`

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 }, ... ]
}

Field	Description	Type
`Teams`	A list of teams in a game.	`List<object>`
`MatchRules`	A list of rules that apply in the Match level. Refer to the Rules Page for more information	`List<object>`
`Teams[x].Name`	The team name.	`string`
`Teams[x].TeamCount`	The number of teams of this type in a game. Imagine a game that has 2 hunter teams and 1 monsters team.	`object`
`Teams[x].PlayerCount`	The number of players allowed in this team.	`object`
`Teams[x].TeamRules`	A list of rules that apply in the Team level for this specific team. Refer to the Rules Page for more information	`List<object>`

Standard Config#

{
    "Name": "",
    "QoSConfig":{...},
    "TeamRules":{...},
    "DefaultScore": 0.0,
    "MinTicketAgeMs": 1000.0,
    "MinBackfillTicketAgeMs": 0.0,
    "TicketTimeoutMs": 10000.0,
    "BackfillEnabled": false,
    "IgnoreIncompatibleTickets": false
}

Field	Description	Type	Default Value
`Name`	A friendly name for this configuration.	`string`	---
`QoSConfig`	Configurable properties for QoS.	`object`	---
`TeamRules`	Configurable properties for the different teams in the game.	`object`	---
`DefaultScore`	An arbitrary score for games generated by this configuration. This field is useful when creating nested configurations. (Optional)	`double`	0.0
`MinTicketAgeMs`	The minimum number of milliseconds before a ticket can be considered for a match. (Optional).	`double`	0.0
`MinBackfillTicketAgeMs`	The minimum number of milliseconds before a backfill ticket can be considered for a match. (Optional).	`double`	0.0
`TicketTimeoutMs`	The number of milliseconds before a ticket will be timed out. (Optional).	`double`	∞
`BackfillEnabled`	Whether to enable backfill support (requires DGS support, see Backfill Tutorial). (Optional).	`boolean`	`false`
`IgnoreIncompatibleTickets`	Whether 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).	`boolean`	`false`

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
}

Field	Description	Type
`DefaultQoSRegion`	The Default QoS Region to use when the `GroupByStrategy` is set to 1 (Group By Default Region). (Required when `GroupByStrategy` = 1).	`string`
`MaxPacketLoss`	The maximum packet loss allowed for a ticket to be considered. (Required when `GroupByStrategy` = 0).	`object`
`MaxLatency`	The maximum latency allowed for a ticket to be considered. (Required when `GroupByStrategy` = 0).	`object`
`TopResultsToConsider`	The maximum number of results to consider when `GroupByStrategy` is set to 0 (Group By Best Region). (Required when `GroupByStrategy` = 0).	`double`
`GroupByStrategy`	The 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
      }
  ]
}

Field	Description	Type
`Teams`	A list of teams in a game.	`List<object>`
`Teams[x].Name`	The team name.	`string`
`Teams[x].TeamCount`	The number of teams of this type in a game. Imagine a game that has 2 hunter teams and 1 monsters team.	`object`
`Teams[x].PlayerCount`	The number of players allowed in this team.	`object`
`Teams[x].AllowPartialMatchesAfterMs`	The 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"
}

Field	Description	Type
`Profile`	The Multiplay profile. This is typically associated with a build image revision, hardware specifications, server-side game configs, and resource definitions.	string
`Access`	The Multiplay access key. An AWS Access Key that is generated following Multiplay guidance.	string
`Secret`	The Multiplay secret key. An AWS Secret Key that is generated following Multiplay guidance.	string
`FleetId`	The ID of the Multiplay fleet to allocate into.	string

ValidationErrorResponse#

[
  {
    "ResultCode": "badFilterRange",
    "Message": "Pool default' Filter mode has an invalid value range (Max < Min)",
  },
  {...}
]

Field	Description	Type
`ResultCode`	A result code.	string
`Message`	A 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": ""
    }
}