CreateMatchmakingConfiguration

Defines a new matchmaking configuration for use with FlexMatch. Whether your are using FlexMatch with Amazon GameLift hosting or as a standalone matchmaking service, the matchmaking configuration sets out rules for matching players and forming teams. If you're also using Amazon GameLift hosting, it defines how to start game sessions for each match. Your matchmaking system can use multiple configurations to handle different game scenarios. All matchmaking requests identify the matchmaking configuration to use and provide player attributes consistent with that configuration.

To create a matchmaking configuration, you must provide the following: configuration name and FlexMatch mode (with or without Amazon GameLift hosting); a rule set that specifies how to evaluate players and find acceptable matches; whether player acceptance is required; and the maximum time allowed for a matchmaking attempt. When using FlexMatch with Amazon GameLift hosting, you also need to identify the game session queue to use when starting a game session for the match.

In addition, you must set up an Amazon Simple Notification Service topic to receive matchmaking notifications. Provide the topic ARN in the matchmaking configuration.

Learn more

Design a FlexMatch matchmaker

Set up FlexMatch event notification

Request Syntax

{
   "AcceptanceRequired": boolean,
   "AcceptanceTimeoutSeconds": number,
   "AdditionalPlayerCount": number,
   "BackfillMode": "string",
   "CustomEventData": "string",
   "Description": "string",
   "FlexMatchMode": "string",
   "GameProperties": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "GameSessionData": "string",
   "GameSessionQueueArns": [ "string" ],
   "Name": "string",
   "NotificationTarget": "string",
   "RequestTimeoutSeconds": number,
   "RuleSetName": "string",
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ]
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Response Syntax

{
   "Configuration": { 
      "AcceptanceRequired": boolean,
      "AcceptanceTimeoutSeconds": number,
      "AdditionalPlayerCount": number,
      "BackfillMode": "string",
      "ConfigurationArn": "string",
      "CreationTime": number,
      "CustomEventData": "string",
      "Description": "string",
      "FlexMatchMode": "string",
      "GameProperties": [ 
         { 
            "Key": "string",
            "Value": "string"
         }
      ],
      "GameSessionData": "string",
      "GameSessionQueueArns": [ "string" ],
      "Name": "string",
      "NotificationTarget": "string",
      "RequestTimeoutSeconds": number,
      "RuleSetArn": "string",
      "RuleSetName": "string"
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Errors

For information about the errors that are common to all actions, see Common Errors.

Examples

Create a matchmaking configuration for use with GameLift managed hosting

The following example creates a matchmaking configuration for a game that is being hosted on Amazon GameLift servers, identifying a game session queue and providing a set of game properties to be passed on to new game sessions. Player acceptance is required, with a 60-second timeout, and auto-backfill is enabled.

Sample Request

{
    "Name": "MM-1v1",
    "Description": "Head-to-head sprint format",
    "RequestTimeoutSeconds": 120,
    "RuleSetName": "mm_one_v_one",
    "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Matchmaking_SNS_Topic",
    "FlexMatchMode": "WITH_QUEUE",
    "GameSessionQueueArns": "arn:aws:gamelift:us-west-2:111122223333:gamesessionqueue/My_Game_Session_Queue_One",
    "AcceptanceRequired": true,
    "AcceptanceTimeoutSeconds": 60,
    "BackfillMode": "AUTOMATIC",
    "AdditionalPlayerCount": 8,
    "GameProperties": [
      {
          "Key": "level",
          "Value": "10"
      },
      {
          "Key": "difficulty",
          "Value": "hard"
      }
    ]
}

Sample Response

{
   "Configuration": { 
      "AcceptanceRequired": true,
      "AcceptanceTimeoutSeconds": 60,
      "AdditionalPlayerCount": 8,
      "BackfillMode": "AUTOMATIC",
      "ConfigurationArn": "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MM-1v1",
      "CreationTime": 1496365885.44,
      "Description": "Head-to-head sprint format",
      "FlexMatchMode": "WITH_QUEUE",
      "GameProperties": [
        {
            "Key": "level",
            "Value": "10"
        },
        {
            "Key": "difficulty",
            "Value": "hard"
        }
      ],
      "GameSessionQueueArns": "arn:aws:gamelift:us-west-2:111122223333:gamesessionqueue/My_Game_Session_Queue_One",
      "Name": "MM-1v1",
      "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Matchmaking_SNS_Topic",
      "RequestTimeoutSeconds": 120,
      "RuleSetArn": "arn:aws:gamelift:us-west-2:111122223333:matchmakingruleset/mm_one_v_one",
      "RuleSetName": "mm_one_v_one"
   }
}
}

Create a matchmaking configuration for a standalone FlexMatch system

The following example creates a matchmaking configuration for a game that is hosted on resources other than Amazon GameLift game servers. This includes games that are hosted on Amazon EC2 with Amazon GameLift FleetIQ. This configuration omits the game session queue, game properties, and additional player count. Player acceptance is required, with a 60-second timeout.

Sample Request

{
    "Name": "MM-1v1",
    "Description": "Head-to-head sprint format",
    "RequestTimeoutSeconds": 120,
    "RuleSetName": "mm_one_v_one",
    "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Matchmaking_SNS_Topic",
    "FlexMatchMode": "STANDALONE",
    "AcceptanceRequired": true,
    "AcceptanceTimeoutSeconds": 60,
    "BackfillMode": "MANUAL"
}

Sample Response

{
   "Configuration": { 
      "AcceptanceRequired": true,
      "AcceptanceTimeoutSeconds": 60,
      "AdditionalPlayerCount": 0,
      "BackfillMode": "MANUAL",
      "ConfigurationArn": "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MM-1v1",
      "CreationTime": 1496365885.44,
      "Description": "Head-to-head sprint format",
      "FlexMatchMode": "STANDALONE",
      "GameSessionQueueArns": "",
      "Name": "MM-1v1",
      "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Matchmaking_SNS_Topic",
      "RequestTimeoutSeconds": 120,
      "RuleSetArn": "arn:aws:gamelift:us-west-2:111122223333:matchmakingruleset/mm_one_v_one",
      "RuleSetName": "mm_one_v_one"
   }
}
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: