Skip to main content

matchmaking_configurations

Creates, updates, deletes, gets or lists a matchmaking_configurations resource.

Overview​

Namematchmaking_configurations
TypeResource
Idaws.gamelift.matchmaking_configurations

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
acceptance_requiredbooleanA flag that indicates whether a match that was created with this configuration must be accepted by the matched players. To require acceptance, set to TRUE. When this option is enabled, matchmaking tickets use the status REQUIRES_ACCEPTANCE to indicate when a completed potential match is waiting for player acceptance.
acceptance_timeout_secondsintegerThe length of time (in seconds) to wait for players to accept a proposed match, if acceptance is required. If any player rejects the match or fails to accept before the timeout, the ticket continues to look for an acceptable match.
additional_player_countintegerThe number of player slots in a match to keep open for future players. For example, if the configuration's rule set specifies a match for a single 12-person team, and the additional player count is set to 2, only 10 players are selected for the match. This parameter is not used when FlexMatchMode is set to STANDALONE.
backfill_modestringThe method used to backfill game sessions created with this matchmaking configuration. MANUAL indicates that the game makes backfill requests or does not use the match backfill feature. AUTOMATIC indicates that GameLift creates backfill requests whenever a game session has one or more open slots. Learn more about manual and automatic backfill in Backfill existing games with FlexMatch. Automatic backfill is not available when FlexMatchMode is set to STANDALONE. (AUTOMATIC, MANUAL)
configuration_arnstringThe Amazon Resource Name (ARN) that is assigned to a Amazon GameLift Servers matchmaking configuration resource and uniquely identifies it. ARNs are unique across all Regions. Format is arn:aws:gamelift:<region>::matchmakingconfiguration/<matchmaking configuration name>. In a Amazon GameLift Servers configuration ARN, the resource ID matches the Name value. (pattern: <code>^arn:.:matchmakingconfiguration/[a-zA-Z0-9-.]$</code>)
creation_timestring (date-time)A time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
custom_event_datastringInformation to attach to all events related to the matchmaking configuration.
descriptionstringA descriptive label that is associated with matchmaking configuration.
flex_match_modestringIndicates whether this matchmaking configuration is being used with Amazon GameLift Servers hosting or as a standalone matchmaking solution. STANDALONE - FlexMatch forms matches and returns match information, including players and team assignments, in a MatchmakingSucceeded event. WITH_QUEUE - FlexMatch forms matches and uses the specified Amazon GameLift Servers queue to start a game session for the match. (STANDALONE, WITH_QUEUE)
game_propertiesarrayA set of key-value pairs that can store custom data in a game session. For example: {"Key": "difficulty", "Value": "novice"}. This information is added to the new GameSession object that is created for a successful match. This parameter is not used when FlexMatchMode is set to STANDALONE. Avoid using periods (".") in property keys if you plan to search for game sessions by properties. Property keys containing periods cannot be searched and will be filtered out from search results due to search index limitations. If you use SearchGameSessions API, there is a limit of 500 game property keys across all game sessions and all fleets per region. If the limit is exceeded, there will potentially be game session entries missing from SearchGameSessions API results.
game_session_datastringA set of custom game session properties, formatted as a single string value. This data is passed to a game server process with a request to start a new game session. For more information, see Start a game session. This information is added to the new GameSession object that is created for a successful match. This parameter is not used when FlexMatchMode is set to STANDALONE.
game_session_queue_arnsarrayThe Amazon Resource Name (ARN) that is assigned to a Amazon GameLift Servers game session queue resource and uniquely identifies it. ARNs are unique across all Regions. Format is arn:aws:gamelift:<region>::gamesessionqueue/<queue name>. Queues can be located in any Region. Queues are used to start new Amazon GameLift Servers-hosted game sessions for matches that are created with this matchmaking configuration. This property is not set when FlexMatchMode is set to STANDALONE.
namestringA unique identifier for the matchmaking configuration. This name is used to identify the configuration associated with a matchmaking request or ticket. (pattern: <code>^[a-zA-Z0-9-.]*$</code>)
notification_targetstringAn SNS topic ARN that is set up to receive matchmaking notifications. (pattern: <code>^[a-zA-Z0-9:_/-]*(.fifo)?$</code>)
request_timeout_secondsintegerThe maximum duration, in seconds, that a matchmaking ticket can remain in process before timing out. Requests that fail due to timing out can be resubmitted as needed.
rule_set_arnstringThe Amazon Resource Name (ARN) associated with the GameLift matchmaking rule set resource that this configuration uses. (pattern: <code>^arn:.:matchmakingruleset/[a-zA-Z0-9-.]$</code>)
rule_set_namestringA unique identifier for the matchmaking rule set to use with this configuration. A matchmaking configuration can only use rule sets that are defined in the same Region. (pattern: <code>^[a-zA-Z0-9-.]*$</code>)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_matchmaking_configurationsselectregionThis API works with the following fleet types: EC2, Anywhere, Container Retrieves the details of FlexMatch matchmaking configurations. This operation offers the following options: (1) retrieve all matchmaking configurations, (2) retrieve configurations for a specified list, or (3) retrieve all configurations that use a specified rule set name. When requesting multiple items, use the pagination parameters to retrieve results as a set of sequential pages. If successful, a configuration is returned for each requested name. When specifying a list of names, only configurations that currently exist are returned. Learn more Setting up FlexMatch matchmakers
create_matchmaking_configurationinsertregion, RequestTimeoutSeconds, AcceptanceRequired, RuleSetNameThis API works with the following fleet types: EC2, Anywhere, Container Defines a new matchmaking configuration for use with FlexMatch. Whether your are using FlexMatch with Amazon GameLift Servers 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 Servers 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 Servers 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 Servers 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
update_matchmaking_configurationupdateregionThis API works with the following fleet types: EC2, Anywhere, Container Updates settings for a FlexMatch matchmaking configuration. These changes affect all matches and game sessions that are created after the update. To update settings, specify the configuration name to be updated and provide the new settings. Learn more Design a FlexMatch matchmaker
delete_matchmaking_configurationdeleteregionThis API works with the following fleet types: EC2, Anywhere, Container Permanently removes a FlexMatch matchmaking configuration. To delete, specify the configuration name. A matchmaking configuration cannot be deleted if it is being used in any active matchmaking tickets.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

This API works with the following fleet types: EC2, Anywhere, Container Retrieves the details of FlexMatch matchmaking configurations. This operation offers the following options: (1) retrieve all matchmaking configurations, (2) retrieve configurations for a specified list, or (3) retrieve all configurations that use a specified rule set name. When requesting multiple items, use the pagination parameters to retrieve results as a set of sequential pages. If successful, a configuration is returned for each requested name. When specifying a list of names, only configurations that currently exist are returned. Learn more Setting up FlexMatch matchmakers

SELECT
acceptance_required,
acceptance_timeout_seconds,
additional_player_count,
backfill_mode,
configuration_arn,
creation_time,
custom_event_data,
description,
flex_match_mode,
game_properties,
game_session_data,
game_session_queue_arns,
name,
notification_target,
request_timeout_seconds,
rule_set_arn,
rule_set_name
FROM aws.gamelift.matchmaking_configurations
WHERE region = '{{ region }}' -- required
;

INSERT examples​

This API works with the following fleet types: EC2, Anywhere, Container Defines a new matchmaking configuration for use with FlexMatch. Whether your are using FlexMatch with Amazon GameLift Servers 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 Servers 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 Servers 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 Servers 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

INSERT INTO aws.gamelift.matchmaking_configurations (
Name,
Description,
GameSessionQueueArns,
RequestTimeoutSeconds,
AcceptanceTimeoutSeconds,
AcceptanceRequired,
RuleSetName,
NotificationTarget,
AdditionalPlayerCount,
CustomEventData,
GameProperties,
GameSessionData,
BackfillMode,
FlexMatchMode,
Tags,
region
)
SELECT 
'{{ Name }}',
'{{ Description }}',
'{{ GameSessionQueueArns }}',
{{ RequestTimeoutSeconds }} /* required */,
{{ AcceptanceTimeoutSeconds }},
{{ AcceptanceRequired }} /* required */,
'{{ RuleSetName }}' /* required */,
'{{ NotificationTarget }}',
{{ AdditionalPlayerCount }},
'{{ CustomEventData }}',
'{{ GameProperties }}',
'{{ GameSessionData }}',
'{{ BackfillMode }}',
'{{ FlexMatchMode }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
configuration
;

UPDATE examples​

This API works with the following fleet types: EC2, Anywhere, Container Updates settings for a FlexMatch matchmaking configuration. These changes affect all matches and game sessions that are created after the update. To update settings, specify the configuration name to be updated and provide the new settings. Learn more Design a FlexMatch matchmaker

UPDATE aws.gamelift.matchmaking_configurations
SET 
Name = '{{ Name }}',
Description = '{{ Description }}',
GameSessionQueueArns = '{{ GameSessionQueueArns }}',
RequestTimeoutSeconds = {{ RequestTimeoutSeconds }},
AcceptanceTimeoutSeconds = {{ AcceptanceTimeoutSeconds }},
AcceptanceRequired = {{ AcceptanceRequired }},
RuleSetName = '{{ RuleSetName }}',
NotificationTarget = '{{ NotificationTarget }}',
AdditionalPlayerCount = {{ AdditionalPlayerCount }},
CustomEventData = '{{ CustomEventData }}',
GameProperties = '{{ GameProperties }}',
GameSessionData = '{{ GameSessionData }}',
BackfillMode = '{{ BackfillMode }}',
FlexMatchMode = '{{ FlexMatchMode }}'
WHERE 
region = '{{ region }}' --required
RETURNING
configuration;

DELETE examples​

This API works with the following fleet types: EC2, Anywhere, Container Permanently removes a FlexMatch matchmaking configuration. To delete, specify the configuration name. A matchmaking configuration cannot be deleted if it is being used in any active matchmaking tickets.

DELETE FROM aws.gamelift.matchmaking_configurations
WHERE region = '{{ region }}' --required
;
Last updated on