2017/08/16 - Amazon GameLift - 11 new 8 updated api methods
Changes The Matchmaking Grouping Service is a new feature that groups player match requests for a given game together into game sessions based on developer configured rules.
Uses FlexMatch to create a game match for a group of players based on custom matchmaking rules, and starts a new game for the matched players. Each matchmaking request specifies the type of match to build (team configuration, rules for an acceptable match, etc.). The request also specifies the players to find a match for and where to host the new game session for optimal performance. A matchmaking request might start with a single player or a group of players who want to play together. FlexMatch finds additional players as needed to fill the match. Match type, rules, and the queue used to place a new game session are defined in a MatchmakingConfiguration . For complete information on setting up and using FlexMatch, see the topic Adding FlexMatch to Your Game.
To start matchmaking, provide a unique ticket ID, specify a matchmaking configuration, and include the players to be matched. You must also include a set of player attributes relevant for the matchmaking configuration. If successful, a matchmaking ticket is returned with status set to QUEUED . Track the status of the ticket to respond as needed and acquire game session connection information for sucessfully completed matches.
Tracking ticket status -- A couple of options are available for tracking the status of matchmaking requests:
Polling -- Call DescribeMatchmaking . This operation returns the full ticket object, including current status and (for completed tickets) game session connection info. We recommend polling no more than once every 10 seconds.
Notifications -- Get event notifications for changes in ticket status using Amazon Simple Notification Service (SNS). Notifications are easy to set up (see CreateMatchmakingConfiguration ) and typically deliver match status changes faster and more efficiently than polling. We recommend that you use polling to back up to notifications (since delivery is not guaranteed) and call DescribeMatchmaking only when notifications are not received within 30 seconds.
Processing a matchmaking request -- FlexMatch handles a matchmaking request as follows:
Your client code submits a StartMatchmaking request for one or more players and tracks the status of the request ticket.
FlexMatch uses this ticket and others in process to build an acceptable match. When a potential match is identified, all tickets in the proposed match are advanced to the next status.
If the match requires player acceptance (set in the matchmaking configuration), the tickets move into status REQUIRES_ACCEPTANCE . This status triggers your client code to solicit acceptance from all players in every ticket involved in the match, and then call AcceptMatch for each player. If any player rejects or fails to accept the match before a specified timeout, the proposed match is dropped (see AcceptMatch for more details).
Once a match is proposed and accepted, the matchmaking tickets move into status PLACING . FlexMatch locates resources for a new game session using the game session queue (set in the matchmaking configuration) and creates the game session based on the match data.
When the match is successfully placed, the matchmaking tickets move into COMPLETED status. Connection information (including game session endpoint and player session) is added to the matchmaking tickets. Matched players can use the connection information to join the game.
Matchmaking-related operations include:
StartMatchmaking
DescribeMatchmaking
StopMatchmaking
AcceptMatch
See also: AWS API Documentation
Request Syntax
client.start_matchmaking(
TicketId='string',
ConfigurationName='string',
Players=[
{
'PlayerId': 'string',
'PlayerAttributes': {
'string': {
'S': 'string',
'N': 123.0,
'SL': [
'string',
],
'SDM': {
'string': 123.0
}
}
},
'Team': 'string',
'LatencyInMs': {
'string': 123
}
},
]
)
string
Unique identifier for a matchmaking ticket. Use this identifier to track the matchmaking ticket status and retrieve match results.
string
[REQUIRED]
Name of the matchmaking configuration to use for this request. Matchmaking configurations must exist in the same region as this request.
list
[REQUIRED]
Information on each player to be matched. This information must include a player ID, and may contain player attributes and latency data to be used in the matchmaking process. After a successful match, Player objects contain the name of the team the player is assigned to.
(dict) --
Object used in matchmaking to represent a player. When starting a matchmaking request, a player has a player ID and may have latency data. Team information is added after a match has been successfully completed.
PlayerId (string) --
Unique identifier for a player
PlayerAttributes (dict) --
Collection of name:value pairs containing player information for use in matchmaking. Player attribute names need to match playerAttributes names in the rule set being used. Example: "PlayerAttributes": {"skill": {"N": "23"}, "gameMode": {"S": "deathmatch"}} .
(string) --
(dict) --
Values for use in Player attribute type:value pairs. This object lets you specify an attribute value using any of the valid data types: string, number, string array or data map. Each AttributeValue object can use only one of the available properties.
S (string) --
For single string values. Maximum string length is 100 characters.
N (float) --
For number values, expressed as double.
SL (list) --
For a list of up to 10 strings. Maximum length for each string is 100 characters. Duplicate values are not recognized; all occurances of the the repeated value after the first of a repeated value are ignored.
(string) --
SDM (dict) --
For a map of up to 10 type:value pairs. Maximum length for each string value is 100 characters.
(string) --
(float) --
Team (string) --
Name of the team that the player is assigned to in a match. Team names are defined in a matchmaking rule set.
LatencyInMs (dict) --
Set of values, expressed in milliseconds, indicating the amount of latency that a player experiences when connected to AWS regions. If this property is present, FlexMatch considers placing the match only in regions that are included in the object map. If not present (that is, null), FlexMatch ignores latency issues and may place the match in any region in the queue.
Note
If this property contains an empty map, FlexMatch assumes that no regions are available to the player. In this scenario, the ticket is not matchable and always times out unless canceled.
(string) --
(integer) --
dict
Response Syntax
{
'MatchmakingTicket': {
'TicketId': 'string',
'ConfigurationName': 'string',
'Status': 'CANCELED'|'COMPLETE'|'FAILED'|'PLACING'|'QUEUED'|'REQUIRES_ACCEPTANCE'|'SEARCHING'|'TIMED_OUT',
'StatusReason': 'string',
'StatusMessage': 'string',
'StartTime': datetime(2015, 1, 1),
'Players': [
{
'PlayerId': 'string',
'PlayerAttributes': {
'string': {
'S': 'string',
'N': 123.0,
'SL': [
'string',
],
'SDM': {
'string': 123.0
}
}
},
'Team': 'string',
'LatencyInMs': {
'string': 123
}
},
],
'GameSessionConnectionInfo': {
'GameSessionArn': 'string',
'IpAddress': 'string',
'Port': 123,
'MatchedPlayerSessions': [
{
'PlayerId': 'string',
'PlayerSessionId': 'string'
},
]
}
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
MatchmakingTicket (dict) --
Ticket representing the matchmaking request. This object include the information included in the request, ticket status, and match results as generated during the matchmaking process.
TicketId (string) --
Unique identifier for a matchmaking ticket.
ConfigurationName (string) --
Name of the MatchmakingConfiguration that is used with this ticket. Matchmaking configurations determine how players are grouped into a match and how a new game session is created for the match.
Status (string) --
Current status of the matchmaking request.
QUEUED – The matchmaking request has been received and is currently waiting to be processed.
SEARCHING – The matchmaking request is currently being processed.
REQUIRES_ACCEPTANCE – A match has been proposed and the players must accept the match (see AcceptMatch ). This status is used only with requests that use a matchmaking configuration with a player acceptance requirement.
PLACING – The FlexMatch engine has matched players and is in the process of placing a new game session for the match.
COMPLETED – Players have been matched and a game session is ready to host the players. A ticket in this state contains the necessary connection information for players.
FAILED – The matchmaking request was not completed. Tickets with players who fail to accept a proposed match are placed in FAILED status; new matchmaking requests can be submitted for these players.
CANCELLED – The matchmaking request was canceled with a call to StopMatchmaking.
TIMED_OUT – The matchmaking request was not completed within the duration specified in the matchmaking configuration. Matchmaking requests that time out can be resubmitted.
StatusReason (string) --
Code to explain the current status. For example, a status reason may indicate when a ticket has returned to SEARCHING status after a proposed match fails to receive player acceptances.
StatusMessage (string) --
Additional information about the current status.
StartTime (datetime) --
Time stamp indicating when this matchmaking request was received. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
Players (list) --
A set of Player objects, each representing a player to find matches for. Players are identified by a unique player ID and may include latency data for use during matchmaking. If the ticket is in status COMPLETED , the Player objects include the team the players were assigned to in the resulting match.
(dict) --
Object used in matchmaking to represent a player. When starting a matchmaking request, a player has a player ID and may have latency data. Team information is added after a match has been successfully completed.
PlayerId (string) --
Unique identifier for a player
PlayerAttributes (dict) --
Collection of name:value pairs containing player information for use in matchmaking. Player attribute names need to match playerAttributes names in the rule set being used. Example: "PlayerAttributes": {"skill": {"N": "23"}, "gameMode": {"S": "deathmatch"}} .
(string) --
(dict) --
Values for use in Player attribute type:value pairs. This object lets you specify an attribute value using any of the valid data types: string, number, string array or data map. Each AttributeValue object can use only one of the available properties.
S (string) --
For single string values. Maximum string length is 100 characters.
N (float) --
For number values, expressed as double.
SL (list) --
For a list of up to 10 strings. Maximum length for each string is 100 characters. Duplicate values are not recognized; all occurances of the the repeated value after the first of a repeated value are ignored.
(string) --
SDM (dict) --
For a map of up to 10 type:value pairs. Maximum length for each string value is 100 characters.
(string) --
(float) --
Team (string) --
Name of the team that the player is assigned to in a match. Team names are defined in a matchmaking rule set.
LatencyInMs (dict) --
Set of values, expressed in milliseconds, indicating the amount of latency that a player experiences when connected to AWS regions. If this property is present, FlexMatch considers placing the match only in regions that are included in the object map. If not present (that is, null), FlexMatch ignores latency issues and may place the match in any region in the queue.
Note
If this property contains an empty map, FlexMatch assumes that no regions are available to the player. In this scenario, the ticket is not matchable and always times out unless canceled.
(string) --
(integer) --
GameSessionConnectionInfo (dict) --
Identifier and connection information of the game session created for the match. This information is added to the ticket only after the matchmaking request has been successfully completed.
GameSessionArn (string) --
Amazon Resource Name ( ARN ) that is assigned to a game session and uniquely identifies it.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
MatchedPlayerSessions (list) --
Collection of player session IDs, one for each player ID that was included in the original matchmaking request.
(dict) --
New player session created as a result of a successful FlexMatch match. A successful match automatically creates new player sessions for every player ID in the original matchmaking request.
When players connect to the match's game session, they must include both player ID and player session ID in order to claim their assigned player slot.
PlayerId (string) --
Unique identifier for a player
PlayerSessionId (string) --
Unique identifier for a player session
Defines a new matchmaking configuration for use with FlexMatch. A matchmaking configuration sets out guidelines for matching players and getting the matches into games. You can set up multiple matchmaking configurations to handle the scenarios needed for your game. Each matchmaking request ( StartMatchmaking ) specifies a configuration for the match and provides player attributes to support the configuration being used.
To create a matchmaking configuration, at a minimum you must specify the following: configuration name; a rule set that governs how to evaluate players and find acceptable matches; a game session queue to use when placing a new game session for the match; and the maximum time allowed for a matchmaking attempt.
Player acceptance -- In each configuration, you have the option to require that all players accept participation in a proposed match. To enable this feature, set AcceptanceRequired to true and specify a time limit for player acceptance. Players have the option to accept or reject a proposed match, and a match does not move ahead to game session placement unless all matched players accept.
Matchmaking status notification -- There are two ways to track the progress of matchmaking tickets: (1) polling ticket status with DescribeMatchmaking; or (2) receiving notifications with Amazon Simple Notification Service (SNS). To use notifications, you first need to set up an SNS topic to receive the notifications, and provide the topic ARN in the matchmaking configuration (see Setting up Notifications for Matchmaking ). Since notifications promise only "best effort" delivery, we recommend calling DescribeMatchmaking if no notifications are received within 30 seconds.
Operations related to match configurations and rule sets include:
CreateMatchmakingConfiguration
DescribeMatchmakingConfigurations
UpdateMatchmakingConfiguration
DeleteMatchmakingConfiguration
CreateMatchmakingRuleSet
DescribeMatchmakingRuleSets
ValidateMatchmakingRuleSet
See also: AWS API Documentation
Request Syntax
client.create_matchmaking_configuration(
Name='string',
Description='string',
GameSessionQueueArns=[
'string',
],
RequestTimeoutSeconds=123,
AcceptanceTimeoutSeconds=123,
AcceptanceRequired=True|False,
RuleSetName='string',
NotificationTarget='string',
AdditionalPlayerCount=123,
CustomEventData='string',
GameProperties=[
{
'Key': 'string',
'Value': 'string'
},
],
GameSessionData='string'
)
string
[REQUIRED]
Unique identifier for a matchmaking configuration. This name is used to identify the configuration associated with a matchmaking request or ticket.
string
Meaningful description of the matchmaking configuration.
list
[REQUIRED]
Amazon Resource Name ( ARN ) that is assigned to a game session queue and uniquely identifies it. Format is arn:aws:gamelift:<region>::fleet/fleet-a1234567-b8c9-0d1e-2fa3-b45c6d7e8912 . These queues are used when placing game sessions for matches that are created with this matchmaking configuration. Queues can be located in any region.
(string) --
integer
[REQUIRED]
Maximum duration, in seconds, that a matchmaking ticket can remain in process before timing out. Requests that time out can be resubmitted as needed.
integer
Length of time (in seconds) to wait for players to accept a proposed match. If any player rejects the match or fails to accept before the timeout, the ticket continues to look for an acceptable match.
boolean
[REQUIRED]
Flag that determines whether or not a match that was created with this configuration must be accepted by the matched players. To require acceptance, set to TRUE.
string
[REQUIRED]
Unique identifier for a matchmaking rule set to use with this configuration. A matchmaking configuration can only use rule sets that are defined in the same region.
string
SNS topic ARN that is set up to receive matchmaking notifications.
integer
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.
string
Information to attached to all events related to the matchmaking configuration.
list
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) -- [REQUIRED]
Game property identifier.
Value (string) -- [REQUIRED]
Game property value.
string
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
dict
Response Syntax
{
'Configuration': {
'Name': 'string',
'Description': 'string',
'GameSessionQueueArns': [
'string',
],
'RequestTimeoutSeconds': 123,
'AcceptanceTimeoutSeconds': 123,
'AcceptanceRequired': True|False,
'RuleSetName': 'string',
'NotificationTarget': 'string',
'AdditionalPlayerCount': 123,
'CustomEventData': 'string',
'CreationTime': datetime(2015, 1, 1),
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'GameSessionData': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
Configuration (dict) --
Object that describes the newly created matchmaking configuration.
Name (string) --
Unique identifier for a matchmaking configuration. This name is used to identify the configuration associated with a matchmaking request or ticket.
Description (string) --
Descriptive label that is associated with matchmaking configuration.
GameSessionQueueArns (list) --
Amazon Resource Name ( ARN ) that is assigned to a game session queue and uniquely identifies it. Format is arn:aws:gamelift:<region>::fleet/fleet-a1234567-b8c9-0d1e-2fa3-b45c6d7e8912 . These queues are used when placing game sessions for matches that are created with this matchmaking configuration. Queues can be located in any region.
(string) --
RequestTimeoutSeconds (integer) --
Maximum duration, in seconds, that a matchmaking ticket can remain in process before timing out. Requests that time out can be resubmitted as needed.
AcceptanceTimeoutSeconds (integer) --
Length of time (in seconds) to wait for players to accept a proposed match. If any player rejects the match or fails to accept before the timeout, the ticket continues to look for an acceptable match.
AcceptanceRequired (boolean) --
Flag that determines whether or not a match that was created with this configuration must be accepted by the matched players. To require acceptance, set to TRUE.
RuleSetName (string) --
Unique identifier for a matchmaking rule set to use with this configuration. A matchmaking configuration can only use rule sets that are defined in the same region.
NotificationTarget (string) --
SNS topic ARN that is set up to receive matchmaking notifications.
AdditionalPlayerCount (integer) --
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.
CustomEventData (string) --
Information to attached to all events related to the matchmaking configuration.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
Updates settings for a FlexMatch matchmaking configuration. To update settings, specify the configuration name to be updated and provide the new settings.
Operations related to match configurations and rule sets include:
CreateMatchmakingConfiguration
DescribeMatchmakingConfigurations
UpdateMatchmakingConfiguration
DeleteMatchmakingConfiguration
CreateMatchmakingRuleSet
DescribeMatchmakingRuleSets
ValidateMatchmakingRuleSet
See also: AWS API Documentation
Request Syntax
client.update_matchmaking_configuration(
Name='string',
Description='string',
GameSessionQueueArns=[
'string',
],
RequestTimeoutSeconds=123,
AcceptanceTimeoutSeconds=123,
AcceptanceRequired=True|False,
RuleSetName='string',
NotificationTarget='string',
AdditionalPlayerCount=123,
CustomEventData='string',
GameProperties=[
{
'Key': 'string',
'Value': 'string'
},
],
GameSessionData='string'
)
string
[REQUIRED]
Unique identifier for a matchmaking configuration to update.
string
Descriptive label that is associated with matchmaking configuration.
list
Amazon Resource Name ( ARN ) that is assigned to a game session queue and uniquely identifies it. Format is arn:aws:gamelift:<region>::fleet/fleet-a1234567-b8c9-0d1e-2fa3-b45c6d7e8912 . These queues are used when placing game sessions for matches that are created with this matchmaking configuration. Queues can be located in any region.
(string) --
integer
Maximum duration, in seconds, that a matchmaking ticket can remain in process before timing out. Requests that time out can be resubmitted as needed.
integer
Length of time (in seconds) to wait for players to accept a proposed match. If any player rejects the match or fails to accept before the timeout, the ticket continues to look for an acceptable match.
boolean
Flag that determines whether or not a match that was created with this configuration must be accepted by the matched players. To require acceptance, set to TRUE.
string
Unique identifier for a matchmaking rule set to use with this configuration. A matchmaking configuration can only use rule sets that are defined in the same region.
string
SNS topic ARN that is set up to receive matchmaking notifications. See Setting up Notifications for Matchmaking for more information.
integer
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.
string
Information to attached to all events related to the matchmaking configuration.
list
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) -- [REQUIRED]
Game property identifier.
Value (string) -- [REQUIRED]
Game property value.
string
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
dict
Response Syntax
{
'Configuration': {
'Name': 'string',
'Description': 'string',
'GameSessionQueueArns': [
'string',
],
'RequestTimeoutSeconds': 123,
'AcceptanceTimeoutSeconds': 123,
'AcceptanceRequired': True|False,
'RuleSetName': 'string',
'NotificationTarget': 'string',
'AdditionalPlayerCount': 123,
'CustomEventData': 'string',
'CreationTime': datetime(2015, 1, 1),
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'GameSessionData': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
Configuration (dict) --
Object that describes the updated matchmaking configuration.
Name (string) --
Unique identifier for a matchmaking configuration. This name is used to identify the configuration associated with a matchmaking request or ticket.
Description (string) --
Descriptive label that is associated with matchmaking configuration.
GameSessionQueueArns (list) --
Amazon Resource Name ( ARN ) that is assigned to a game session queue and uniquely identifies it. Format is arn:aws:gamelift:<region>::fleet/fleet-a1234567-b8c9-0d1e-2fa3-b45c6d7e8912 . These queues are used when placing game sessions for matches that are created with this matchmaking configuration. Queues can be located in any region.
(string) --
RequestTimeoutSeconds (integer) --
Maximum duration, in seconds, that a matchmaking ticket can remain in process before timing out. Requests that time out can be resubmitted as needed.
AcceptanceTimeoutSeconds (integer) --
Length of time (in seconds) to wait for players to accept a proposed match. If any player rejects the match or fails to accept before the timeout, the ticket continues to look for an acceptable match.
AcceptanceRequired (boolean) --
Flag that determines whether or not a match that was created with this configuration must be accepted by the matched players. To require acceptance, set to TRUE.
RuleSetName (string) --
Unique identifier for a matchmaking rule set to use with this configuration. A matchmaking configuration can only use rule sets that are defined in the same region.
NotificationTarget (string) --
SNS topic ARN that is set up to receive matchmaking notifications.
AdditionalPlayerCount (integer) --
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.
CustomEventData (string) --
Information to attached to all events related to the matchmaking configuration.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
Creates a new rule set for FlexMatch matchmaking. A rule set describes the type of match to create, such as the number and size of teams, and sets the parameters for acceptable player matches, such as minimum skill level or character type. Rule sets are used in matchmaking configurations, which define how matchmaking requests are handled. Each MatchmakingConfiguration uses one rule set; you can set up multiple rule sets to handle the scenarios that suit your game (such as for different game modes), and create a separate matchmaking configuration for each rule set. See additional information on rule set content in the MatchmakingRuleSet structure. For help creating rule sets, including useful examples, see the topic Adding FlexMatch to Your Game.
Once created, matchmaking rule sets cannot be changed or deleted, so we recommend checking the rule set syntax using ValidateMatchmakingRuleSet before creating the rule set.
To create a matchmaking rule set, provide the set of rules and a unique name. Rule sets must be defined in the same region as the matchmaking configuration they will be used with. Rule sets cannot be edited or deleted. If you need to change a rule set, create a new one with the necessary edits and then update matchmaking configurations to use the new rule set.
Operations related to match configurations and rule sets include:
CreateMatchmakingConfiguration
DescribeMatchmakingConfigurations
UpdateMatchmakingConfiguration
DeleteMatchmakingConfiguration
CreateMatchmakingRuleSet
DescribeMatchmakingRuleSets
ValidateMatchmakingRuleSet
See also: AWS API Documentation
Request Syntax
client.create_matchmaking_rule_set(
Name='string',
RuleSetBody='string'
)
string
[REQUIRED]
Unique identifier for a matchmaking rule set. This name is used to identify the rule set associated with a matchmaking configuration.
string
[REQUIRED]
Collection of matchmaking rules, formatted as a JSON string. (Note that comments are not allowed in JSON, but most elements support a description field.)
dict
Response Syntax
{
'RuleSet': {
'RuleSetName': 'string',
'RuleSetBody': 'string',
'CreationTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
RuleSet (dict) --
Object that describes the newly created matchmaking rule set.
RuleSetName (string) --
Unique identifier for a matchmaking rule set
RuleSetBody (string) --
Collection of matchmaking rules, formatted as a JSON string. (Note that comments14 are not allowed in JSON, but most elements support a description field.)
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
Retrieves the details for FlexMatch matchmaking rule sets. You can request all existing rule sets for the region, or provide a list of one or more rule set names. When requesting multiple items, use the pagination parameters to retrieve results as a set of sequential pages. If successful, a rule set is returned for each requested name.
Operations related to match configurations and rule sets include:
CreateMatchmakingConfiguration
DescribeMatchmakingConfigurations
UpdateMatchmakingConfiguration
DeleteMatchmakingConfiguration
CreateMatchmakingRuleSet
DescribeMatchmakingRuleSets
ValidateMatchmakingRuleSet
See also: AWS API Documentation
Request Syntax
client.describe_matchmaking_rule_sets(
Names=[
'string',
],
Limit=123,
NextToken='string'
)
list
Unique identifier for a matchmaking rule set. This name is used to identify the rule set associated with a matchmaking configuration.
(string) --
integer
Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages.
string
Token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To start at the beginning of the result set, do not specify a value.
dict
Response Syntax
{
'RuleSets': [
{
'RuleSetName': 'string',
'RuleSetBody': 'string',
'CreationTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
RuleSets (list) --
Collection of requested matchmaking rule set objects.
(dict) --
Set of rule statements, used with FlexMatch, that determine how to build a certain kind of player match. Each rule set describes a type of group to be created and defines the parameters for acceptable player matches. Rule sets are used in MatchmakingConfiguration objects.
A rule set may define the following elements for a match. For detailed information and examples showing how to construct a rule set, see Create Matchmaking Rules for Your Game.
Teams -- Required. A rule set must define one or multiple teams for the match and set minimum and maximum team sizes. For example, a rule set might describe a 4x4 match that requires all eight slots to be filled.
Player attributes -- Optional. These attributes specify a set of player characteristics to evaluate when looking for a match. Matchmaking requests that use a rule set with player attributes must provide the corresponding attribute values. For example, an attribute might specify a player's skill or level.
Rules -- Optional. Rules define how to evaluate potential players for a match based on player attributes. A rule might specify minimum requirements for individual players--such as each player must meet a certain skill level, or may describe an entire group--such as all teams must be evenly matched or have at least one player in a certain role.
Expansions -- Optional. Expansions allow you to relax the rules after a period of time if no acceptable matches are found. This feature lets you balance getting players into games in a reasonable amount of time instead of making them wait indefinitely for the best possible match. For example, you might use an expansion to increase the maximum skill variance between players after 30 seconds.
RuleSetName (string) --
Unique identifier for a matchmaking rule set
RuleSetBody (string) --
Collection of matchmaking rules, formatted as a JSON string. (Note that comments14 are not allowed in JSON, but most elements support a description field.)
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
NextToken (string) --
Token that indicates where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
Retrieves a set of one or more matchmaking tickets. Use this operation to retrieve ticket information, including status and--once a successful match is made--acquire connection information for the resulting new game session.
You can use this operation to track the progress of matchmaking requests (through polling) as an alternative to using event notifications. See more details on tracking matchmaking requests through polling or notifications in StartMatchmaking.
You can request data for a one or a list of ticket IDs. If the request is successful, a ticket object is returned for each requested ID. When specifying a list of ticket IDs, objects are returned only for tickets that currently exist.
Matchmaking-related operations include:
StartMatchmaking
DescribeMatchmaking
StopMatchmaking
AcceptMatch
See also: AWS API Documentation
Request Syntax
client.describe_matchmaking(
TicketIds=[
'string',
]
)
list
[REQUIRED]
Unique identifier for a matchmaking ticket. To request all existing tickets, leave this parameter empty.
(string) --
dict
Response Syntax
{
'TicketList': [
{
'TicketId': 'string',
'ConfigurationName': 'string',
'Status': 'CANCELED'|'COMPLETE'|'FAILED'|'PLACING'|'QUEUED'|'REQUIRES_ACCEPTANCE'|'SEARCHING'|'TIMED_OUT',
'StatusReason': 'string',
'StatusMessage': 'string',
'StartTime': datetime(2015, 1, 1),
'Players': [
{
'PlayerId': 'string',
'PlayerAttributes': {
'string': {
'S': 'string',
'N': 123.0,
'SL': [
'string',
],
'SDM': {
'string': 123.0
}
}
},
'Team': 'string',
'LatencyInMs': {
'string': 123
}
},
],
'GameSessionConnectionInfo': {
'GameSessionArn': 'string',
'IpAddress': 'string',
'Port': 123,
'MatchedPlayerSessions': [
{
'PlayerId': 'string',
'PlayerSessionId': 'string'
},
]
}
},
]
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
TicketList (list) --
Collection of existing matchmaking ticket objects matching the request.
(dict) --
Ticket generated to track the progress of a matchmaking request. Each ticket is uniquely identified by a ticket ID, supplied by the requester, when creating a matchmaking request with StartMatchmaking. Tickets can be retrieved by calling DescribeMatchmaking with the ticket ID.
TicketId (string) --
Unique identifier for a matchmaking ticket.
ConfigurationName (string) --
Name of the MatchmakingConfiguration that is used with this ticket. Matchmaking configurations determine how players are grouped into a match and how a new game session is created for the match.
Status (string) --
Current status of the matchmaking request.
QUEUED – The matchmaking request has been received and is currently waiting to be processed.
SEARCHING – The matchmaking request is currently being processed.
REQUIRES_ACCEPTANCE – A match has been proposed and the players must accept the match (see AcceptMatch ). This status is used only with requests that use a matchmaking configuration with a player acceptance requirement.
PLACING – The FlexMatch engine has matched players and is in the process of placing a new game session for the match.
COMPLETED – Players have been matched and a game session is ready to host the players. A ticket in this state contains the necessary connection information for players.
FAILED – The matchmaking request was not completed. Tickets with players who fail to accept a proposed match are placed in FAILED status; new matchmaking requests can be submitted for these players.
CANCELLED – The matchmaking request was canceled with a call to StopMatchmaking.
TIMED_OUT – The matchmaking request was not completed within the duration specified in the matchmaking configuration. Matchmaking requests that time out can be resubmitted.
StatusReason (string) --
Code to explain the current status. For example, a status reason may indicate when a ticket has returned to SEARCHING status after a proposed match fails to receive player acceptances.
StatusMessage (string) --
Additional information about the current status.
StartTime (datetime) --
Time stamp indicating when this matchmaking request was received. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
Players (list) --
A set of Player objects, each representing a player to find matches for. Players are identified by a unique player ID and may include latency data for use during matchmaking. If the ticket is in status COMPLETED , the Player objects include the team the players were assigned to in the resulting match.
(dict) --
Object used in matchmaking to represent a player. When starting a matchmaking request, a player has a player ID and may have latency data. Team information is added after a match has been successfully completed.
PlayerId (string) --
Unique identifier for a player
PlayerAttributes (dict) --
Collection of name:value pairs containing player information for use in matchmaking. Player attribute names need to match playerAttributes names in the rule set being used. Example: "PlayerAttributes": {"skill": {"N": "23"}, "gameMode": {"S": "deathmatch"}} .
(string) --
(dict) --
Values for use in Player attribute type:value pairs. This object lets you specify an attribute value using any of the valid data types: string, number, string array or data map. Each AttributeValue object can use only one of the available properties.
S (string) --
For single string values. Maximum string length is 100 characters.
N (float) --
For number values, expressed as double.
SL (list) --
For a list of up to 10 strings. Maximum length for each string is 100 characters. Duplicate values are not recognized; all occurances of the the repeated value after the first of a repeated value are ignored.
(string) --
SDM (dict) --
For a map of up to 10 type:value pairs. Maximum length for each string value is 100 characters.
(string) --
(float) --
Team (string) --
Name of the team that the player is assigned to in a match. Team names are defined in a matchmaking rule set.
LatencyInMs (dict) --
Set of values, expressed in milliseconds, indicating the amount of latency that a player experiences when connected to AWS regions. If this property is present, FlexMatch considers placing the match only in regions that are included in the object map. If not present (that is, null), FlexMatch ignores latency issues and may place the match in any region in the queue.
Note
If this property contains an empty map, FlexMatch assumes that no regions are available to the player. In this scenario, the ticket is not matchable and always times out unless canceled.
(string) --
(integer) --
GameSessionConnectionInfo (dict) --
Identifier and connection information of the game session created for the match. This information is added to the ticket only after the matchmaking request has been successfully completed.
GameSessionArn (string) --
Amazon Resource Name ( ARN ) that is assigned to a game session and uniquely identifies it.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
MatchedPlayerSessions (list) --
Collection of player session IDs, one for each player ID that was included in the original matchmaking request.
(dict) --
New player session created as a result of a successful FlexMatch match. A successful match automatically creates new player sessions for every player ID in the original matchmaking request.
When players connect to the match's game session, they must include both player ID and player session ID in order to claim their assigned player slot.
PlayerId (string) --
Unique identifier for a player
PlayerSessionId (string) --
Unique identifier for a player session
Cancels a matchmaking ticket that is currently being processed. To stop the matchmaking operation, specify the ticket ID. If successful, work on the ticket is stopped, and the ticket status is changed to CANCELLED .
Matchmaking-related operations include:
StartMatchmaking
DescribeMatchmaking
StopMatchmaking
AcceptMatch
See also: AWS API Documentation
Request Syntax
client.stop_matchmaking(
TicketId='string'
)
string
[REQUIRED]
Unique identifier for a matchmaking ticket.
dict
Response Syntax
{}
Response Structure
(dict) --
Registers a player's acceptance or rejection of a proposed FlexMatch match. A matchmaking configuration may require player acceptance; if so, then matches built with that configuration cannot be completed unless all players accept the proposed match within a specified time limit.
When FlexMatch builds a match, all the matchmaking tickets involved in the proposed match are placed into status REQUIRES_ACCEPTANCE . This is a trigger for your game to get acceptance from all players in the ticket. Acceptances are only valid for tickets when they are in this status; all other acceptances result in an error.
To register acceptance, specify the ticket ID, a response, and one or more players. Once all players have registered acceptance, the matchmaking tickets advance to status PLACING , where a new game session is created for the match.
If any player rejects the match, or if acceptances are not received before a specified timeout, the proposed match is dropped. The matchmaking tickets are then handled in one of two ways: For tickets where all players accepted the match, the ticket status is returned to SEARCHING to find a new match. For tickets where one or more players failed to accept the match, the ticket status is set to FAILED , and processing is terminated. A new matchmaking request for these players can be submitted as needed.
Matchmaking-related operations include:
StartMatchmaking
DescribeMatchmaking
StopMatchmaking
AcceptMatch
See also: AWS API Documentation
Request Syntax
client.accept_match(
TicketId='string',
PlayerIds=[
'string',
],
AcceptanceType='ACCEPT'|'REJECT'
)
string
[REQUIRED]
Unique identifier for a matchmaking ticket. The ticket must be in status REQUIRES_ACCEPTANCE ; otherwise this request will fail.
list
[REQUIRED]
Unique identifier for a player delivering the response. This parameter can include one or multiple player IDs.
(string) --
string
[REQUIRED]
Player response to the proposed match.
dict
Response Syntax
{}
Response Structure
(dict) --
Retrieves the details of FlexMatch matchmaking configurations. with this operation, you have the following options: (1) retrieve all existing configurations, (2) provide the names of one or more configurations to retrieve, 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.
Operations related to match configurations and rule sets include:
CreateMatchmakingConfiguration
DescribeMatchmakingConfigurations
UpdateMatchmakingConfiguration
DeleteMatchmakingConfiguration
CreateMatchmakingRuleSet
DescribeMatchmakingRuleSets
ValidateMatchmakingRuleSet
See also: AWS API Documentation
Request Syntax
client.describe_matchmaking_configurations(
Names=[
'string',
],
RuleSetName='string',
Limit=123,
NextToken='string'
)
list
Unique identifier for a matchmaking configuration(s) to retrieve. To request all existing configurations, leave this parameter empty.
(string) --
string
Unique identifier for a matchmaking rule set. Use this parameter to retrieve all matchmaking configurations that use this rule set.
integer
Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages. This parameter is limited to 10.
string
Token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To start at the beginning of the result set, do not specify a value.
dict
Response Syntax
{
'Configurations': [
{
'Name': 'string',
'Description': 'string',
'GameSessionQueueArns': [
'string',
],
'RequestTimeoutSeconds': 123,
'AcceptanceTimeoutSeconds': 123,
'AcceptanceRequired': True|False,
'RuleSetName': 'string',
'NotificationTarget': 'string',
'AdditionalPlayerCount': 123,
'CustomEventData': 'string',
'CreationTime': datetime(2015, 1, 1),
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'GameSessionData': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
Configurations (list) --
Collection of requested matchmaking configuration objects.
(dict) --
Guidelines for use with FlexMatch to match players into games. All matchmaking requests must specify a matchmaking configuration.
Name (string) --
Unique identifier for a matchmaking configuration. This name is used to identify the configuration associated with a matchmaking request or ticket.
Description (string) --
Descriptive label that is associated with matchmaking configuration.
GameSessionQueueArns (list) --
Amazon Resource Name ( ARN ) that is assigned to a game session queue and uniquely identifies it. Format is arn:aws:gamelift:<region>::fleet/fleet-a1234567-b8c9-0d1e-2fa3-b45c6d7e8912 . These queues are used when placing game sessions for matches that are created with this matchmaking configuration. Queues can be located in any region.
(string) --
RequestTimeoutSeconds (integer) --
Maximum duration, in seconds, that a matchmaking ticket can remain in process before timing out. Requests that time out can be resubmitted as needed.
AcceptanceTimeoutSeconds (integer) --
Length of time (in seconds) to wait for players to accept a proposed match. If any player rejects the match or fails to accept before the timeout, the ticket continues to look for an acceptable match.
AcceptanceRequired (boolean) --
Flag that determines whether or not a match that was created with this configuration must be accepted by the matched players. To require acceptance, set to TRUE.
RuleSetName (string) --
Unique identifier for a matchmaking rule set to use with this configuration. A matchmaking configuration can only use rule sets that are defined in the same region.
NotificationTarget (string) --
SNS topic ARN that is set up to receive matchmaking notifications.
AdditionalPlayerCount (integer) --
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.
CustomEventData (string) --
Information to attached to all events related to the matchmaking configuration.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ). This information is added to the new GameSession object that is created for a successful match.
NextToken (string) --
Token that indicates where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
Validates the syntax of a matchmaking rule or rule set. This operation checks that the rule set uses syntactically correct JSON and that it conforms to allowed property expressions. To validate syntax, provide a rule set string.
Operations related to match configurations and rule sets include:
CreateMatchmakingConfiguration
DescribeMatchmakingConfigurations
UpdateMatchmakingConfiguration
DeleteMatchmakingConfiguration
CreateMatchmakingRuleSet
DescribeMatchmakingRuleSets
ValidateMatchmakingRuleSet
See also: AWS API Documentation
Request Syntax
client.validate_matchmaking_rule_set(
RuleSetBody='string'
)
string
[REQUIRED]
Collection of matchmaking rules to validate, formatted as a JSON string.
dict
Response Syntax
{
'Valid': True|False
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
Valid (boolean) --
Response indicating whether or not the rule set is valid.
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.
Operations related to match configurations and rule sets include:
CreateMatchmakingConfiguration
DescribeMatchmakingConfigurations
UpdateMatchmakingConfiguration
DeleteMatchmakingConfiguration
CreateMatchmakingRuleSet
DescribeMatchmakingRuleSets
ValidateMatchmakingRuleSet
See also: AWS API Documentation
Request Syntax
client.delete_matchmaking_configuration(
Name='string'
)
string
[REQUIRED]
Unique identifier for a matchmaking configuration
dict
Response Syntax
{}
Response Structure
(dict) --
{'GameSessionData': 'string'}
Response {'GameSession': {'GameSessionData': 'string'}}
Creates a multiplayer game session for players. This action creates a game session record and assigns an available server process in the specified fleet to host the game session. A fleet must have an ACTIVE status before a game session can be created in it.
To create a game session, specify either fleet ID or alias ID and indicate a maximum number of players to allow in the game session. You can also provide a name and game-specific properties for this game session. If successful, a GameSession object is returned containing the game session properties and other settings you specified.
Idempotency tokens. You can add a token that uniquely identifies game session requests. This is useful for ensuring that game session requests are idempotent. Multiple requests with the same idempotency token are processed only once; subsequent requests return the original result. All response values are the same with the exception of game session status, which may change.
Resource creation limits. If you are creating a game session on a fleet with a resource creation limit policy in force, then you must specify a creator ID. Without this ID, Amazon GameLift has no way to evaluate the policy for this new game session request.
Player acceptance policy. By default, newly created game sessions are open to new players. You can restrict new player access by using UpdateGameSession to change the game session's player session creation policy.
Game session logs. Logs are retained for all active game sessions for 14 days. To access the logs, call GetGameSessionLogUrl to download the log files.
Available in Amazon GameLift Local.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.create_game_session(
FleetId='string',
AliasId='string',
MaximumPlayerSessionCount=123,
Name='string',
GameProperties=[
{
'Key': 'string',
'Value': 'string'
},
],
CreatorId='string',
GameSessionId='string',
IdempotencyToken='string',
GameSessionData='string'
)
string
Unique identifier for a fleet to create a game session in. Each request must reference either a fleet ID or alias ID, but not both.
string
Unique identifier for an alias associated with the fleet to create a game session in. Each request must reference either a fleet ID or alias ID, but not both.
integer
[REQUIRED]
Maximum number of players that can be connected simultaneously to the game session.
string
Descriptive label that is associated with a game session. Session names do not need to be unique.
list
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) -- [REQUIRED]
Game property identifier.
Value (string) -- [REQUIRED]
Game property value.
string
Unique identifier for a player or entity creating the game session. This ID is used to enforce a resource protection policy (if one exists) that limits the number of concurrent active game sessions one player can have.
string
This parameter is no longer preferred. Please use IdempotencyToken instead.Custom string that uniquely identifies a request for a new game session. Maximum token length is 48 characters. If provided, this string is included in the new game session's ID. (A game session ID has the following format: arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token> .)
string
Custom string that uniquely identifies a request for a new game session. Maximum token length is 48 characters. If provided, this string is included in the new game session's ID. (A game session ID has the following format: arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token> .) Idempotency tokens remain in use for 30 days after a game session has ended; game session objects are retained for this time period and then deleted.
string
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
dict
Response Syntax
{
'GameSession': {
'GameSessionId': 'string',
'Name': 'string',
'FleetId': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'CurrentPlayerSessionCount': 123,
'MaximumPlayerSessionCount': 123,
'Status': 'ACTIVE'|'ACTIVATING'|'TERMINATED'|'TERMINATING'|'ERROR',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'IpAddress': 'string',
'Port': 123,
'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL',
'CreatorId': 'string',
'GameSessionData': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSession (dict) --
Object that describes the newly created game session record.
GameSessionId (string) --
Unique identifier for the game session. A game session ID has the following format: arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token> .
Name (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
FleetId (string) --
Unique identifier for a fleet the game session is running on.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
TerminationTime (datetime) --
Time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
CurrentPlayerSessionCount (integer) --
Number of players currently in the game session.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
Status (string) --
Current status of the game session. A game session must have an ACTIVE status to have player sessions.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
PlayerSessionCreationPolicy (string) --
Indicates whether or not the game session is accepting new players.
CreatorId (string) --
Unique identifier for a player. This ID is used to enforce a resource protection policy (if one exists), that limits the number of game sessions a player can create.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
{'GameSessionDetails': {'GameSession': {'GameSessionData': 'string'}}}
Retrieves properties, including the protection policy in force, for one or more game sessions. This action can be used in several ways: (1) provide a GameSessionId or GameSessionArn to request details for a specific game session; (2) provide either a FleetId or an AliasId to request properties for all game sessions running on a fleet.
To get game session record(s), specify just one of the following: game session ID, fleet ID, or alias ID. You can filter this request by game session status. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, a GameSessionDetail object is returned for each session matching the request.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.describe_game_session_details(
FleetId='string',
GameSessionId='string',
AliasId='string',
StatusFilter='string',
Limit=123,
NextToken='string'
)
string
Unique identifier for a fleet to retrieve all game sessions active on the fleet.
string
Unique identifier for the game session to retrieve.
string
Unique identifier for an alias associated with the fleet to retrieve all game sessions for.
string
Game session status to filter results on. Possible game session statuses include ACTIVE , TERMINATED , ACTIVATING and TERMINATING (the last two are transitory).
integer
Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages.
string
Token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To start at the beginning of the result set, do not specify a value.
dict
Response Syntax
{
'GameSessionDetails': [
{
'GameSession': {
'GameSessionId': 'string',
'Name': 'string',
'FleetId': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'CurrentPlayerSessionCount': 123,
'MaximumPlayerSessionCount': 123,
'Status': 'ACTIVE'|'ACTIVATING'|'TERMINATED'|'TERMINATING'|'ERROR',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'IpAddress': 'string',
'Port': 123,
'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL',
'CreatorId': 'string',
'GameSessionData': 'string'
},
'ProtectionPolicy': 'NoProtection'|'FullProtection'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSessionDetails (list) --
Collection of objects containing game session properties and the protection policy currently in force for each session matching the request.
(dict) --
A game session's properties plus the protection policy currently in force.
GameSession (dict) --
Object that describes a game session.
GameSessionId (string) --
Unique identifier for the game session. A game session ID has the following format: arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token> .
Name (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
FleetId (string) --
Unique identifier for a fleet the game session is running on.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
TerminationTime (datetime) --
Time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
CurrentPlayerSessionCount (integer) --
Number of players currently in the game session.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
Status (string) --
Current status of the game session. A game session must have an ACTIVE status to have player sessions.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
PlayerSessionCreationPolicy (string) --
Indicates whether or not the game session is accepting new players.
CreatorId (string) --
Unique identifier for a player. This ID is used to enforce a resource protection policy (if one exists), that limits the number of game sessions a player can create.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
ProtectionPolicy (string) --
Current status of protection for the game session.
NoProtection – The game session can be terminated during a scale-down event.
FullProtection – If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
NextToken (string) --
Token that indicates where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
{'GameSessionPlacement': {'GameSessionData': 'string'}}
Retrieves properties and current status of a game session placement request. To get game session placement details, specify the placement ID. If successful, a GameSessionPlacement object is returned.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.describe_game_session_placement(
PlacementId='string'
)
string
[REQUIRED]
Unique identifier for a game session placement to retrieve.
dict
Response Syntax
{
'GameSessionPlacement': {
'PlacementId': 'string',
'GameSessionQueueName': 'string',
'Status': 'PENDING'|'FULFILLED'|'CANCELLED'|'TIMED_OUT',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'MaximumPlayerSessionCount': 123,
'GameSessionName': 'string',
'GameSessionId': 'string',
'GameSessionArn': 'string',
'GameSessionRegion': 'string',
'PlayerLatencies': [
{
'PlayerId': 'string',
'RegionIdentifier': 'string',
'LatencyInMilliseconds': ...
},
],
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'IpAddress': 'string',
'Port': 123,
'PlacedPlayerSessions': [
{
'PlayerId': 'string',
'PlayerSessionId': 'string'
},
],
'GameSessionData': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSessionPlacement (dict) --
Object that describes the requested game session placement.
PlacementId (string) --
Unique identifier for a game session placement.
GameSessionQueueName (string) --
Descriptive label that is associated with game session queue. Queue names must be unique within each region.
Status (string) --
Current status of the game session placement request.
PENDING – The placement request is currently in the queue waiting to be processed.
FULFILLED – A new game session and player sessions (if requested) have been successfully created. Values for GameSessionArn and GameSessionRegion are available.
CANCELLED – The placement request was canceled with a call to StopGameSessionPlacement.
TIMED_OUT – A new game session was not successfully created before the time limit expired. You can resubmit the placement request as needed.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
GameSessionName (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
GameSessionId (string) --
Unique identifier for the game session. This value is set once the new game session is placed (placement status is FULFILLED ).
GameSessionArn (string) --
Identifier for the game session created by this placement request. This value is set once the new game session is placed (placement status is FULFILLED ). This identifier is unique across all regions. You can use this value as a GameSessionId value as needed.
GameSessionRegion (string) --
Name of the region where the game session created by this placement request is running. This value is set once the new game session is placed (placement status is FULFILLED ).
PlayerLatencies (list) --
Set of values, expressed in milliseconds, indicating the amount of latency that a player experiences when connected to AWS regions.
(dict) --
Regional latency information for a player, used when requesting a new game session with StartGameSessionPlacement. This value indicates the amount of time lag that exists when the player is connected to a fleet in the specified region. The relative difference between a player's latency values for multiple regions are used to determine which fleets are best suited to place a new game session for the player.
PlayerId (string) --
Unique identifier for a player associated with the latency data.
RegionIdentifier (string) --
Name of the region that is associated with the latency value.
LatencyInMilliseconds (float) --
Amount of time that represents the time lag experienced by the player when connected to the specified region.
StartTime (datetime) --
Time stamp indicating when this request was placed in the queue. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
EndTime (datetime) --
Time stamp indicating when this request was completed, canceled, or timed out.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number. This value is set once the new game session is placed (placement status is FULFILLED ).
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number. This value is set once the new game session is placed (placement status is FULFILLED ).
PlacedPlayerSessions (list) --
Collection of information on player sessions created in response to the game session placement request. These player sessions are created only once a new game session is successfully placed (placement status is FULFILLED ). This information includes the player ID (as provided in the placement request) and the corresponding player session ID. Retrieve full player sessions by calling DescribePlayerSessions with the player session ID.
(dict) --
Information about a player session that was created as part of a StartGameSessionPlacement request. This object contains only the player ID and player session ID. To retrieve full details on a player session, call DescribePlayerSessions with the player session ID.
Player-session-related operations include:
CreatePlayerSession
CreatePlayerSessions
DescribePlayerSessions
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
PlayerId (string) --
Unique identifier for a player that is associated with this player session.
PlayerSessionId (string) --
Unique identifier for a player session.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
{'GameSessions': {'GameSessionData': 'string'}}
Retrieves a set of one or more game sessions. Request a specific game session or request all game sessions on a fleet. Alternatively, use SearchGameSessions to request a set of active game sessions that are filtered by certain criteria. To retrieve protection policy settings for game sessions, use DescribeGameSessionDetails.
To get game sessions, specify one of the following: game session ID, fleet ID, or alias ID. You can filter this request by game session status. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, a GameSession object is returned for each game session matching the request.
Available in Amazon GameLift Local.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.describe_game_sessions(
FleetId='string',
GameSessionId='string',
AliasId='string',
StatusFilter='string',
Limit=123,
NextToken='string'
)
string
Unique identifier for a fleet to retrieve all game sessions for.
string
Unique identifier for the game session to retrieve. You can use either a GameSessionId or GameSessionArn value.
string
Unique identifier for an alias associated with the fleet to retrieve all game sessions for.
string
Game session status to filter results on. Possible game session statuses include ACTIVE , TERMINATED , ACTIVATING , and TERMINATING (the last two are transitory).
integer
Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages.
string
Token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To start at the beginning of the result set, do not specify a value.
dict
Response Syntax
{
'GameSessions': [
{
'GameSessionId': 'string',
'Name': 'string',
'FleetId': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'CurrentPlayerSessionCount': 123,
'MaximumPlayerSessionCount': 123,
'Status': 'ACTIVE'|'ACTIVATING'|'TERMINATED'|'TERMINATING'|'ERROR',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'IpAddress': 'string',
'Port': 123,
'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL',
'CreatorId': 'string',
'GameSessionData': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSessions (list) --
Collection of objects containing game session properties for each session matching the request.
(dict) --
Properties describing a game session.
A game session in ACTIVE status can host players. When a game session ends, its status is set to TERMINATED .
Once the session ends, the game session object is retained for 30 days. This means you can reuse idempotency token values after this time. Game session logs are retained for 14 days.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
GameSessionId (string) --
Unique identifier for the game session. A game session ID has the following format: arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token> .
Name (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
FleetId (string) --
Unique identifier for a fleet the game session is running on.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
TerminationTime (datetime) --
Time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
CurrentPlayerSessionCount (integer) --
Number of players currently in the game session.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
Status (string) --
Current status of the game session. A game session must have an ACTIVE status to have player sessions.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
PlayerSessionCreationPolicy (string) --
Indicates whether or not the game session is accepting new players.
CreatorId (string) --
Unique identifier for a player. This ID is used to enforce a resource protection policy (if one exists), that limits the number of game sessions a player can create.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
NextToken (string) --
Token that indicates where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
{'GameSessions': {'GameSessionData': 'string'}}
Retrieves a set of game sessions that match a set of search criteria and sorts them in a specified order. A game session search is limited to a single fleet. Search results include only game sessions that are in ACTIVE status. If you need to retrieve game sessions with a status other than active, use DescribeGameSessions. If you need to retrieve the protection policy for each game session, use DescribeGameSessionDetails.
You can search or sort by the following game session attributes:
gameSessionId -- Unique identifier for the game session. You can use either a GameSessionId or GameSessionArn value.
gameSessionName -- Name assigned to a game session. This value is set when requesting a new game session with CreateGameSession or updating with UpdateGameSession. Game session names do not need to be unique to a game session.
creationTimeMillis -- Value indicating when a game session was created. It is expressed in Unix time as milliseconds.
playerSessionCount -- Number of players currently connected to a game session. This value changes rapidly as players join the session or drop out.
maximumSessions -- Maximum number of player sessions allowed for a game session. This value is set when requesting a new game session with CreateGameSession or updating with UpdateGameSession.
hasAvailablePlayerSessions -- Boolean value indicating whether a game session has reached its maximum number of players. When searching with this attribute, the search value must be true or false . It is highly recommended that all search requests include this filter attribute to optimize search performance and return only sessions that players can join.
To search or sort, specify either a fleet ID or an alias ID, and provide a search filter expression, a sort expression, or both. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, a collection of GameSession objects matching the request is returned.
Note
Returned values for playerSessionCount and hasAvailablePlayerSessions change quickly as players join sessions and others drop out. Results should be considered a snapshot in time. Be sure to refresh search results often, and handle sessions that fill up before a player can join.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.search_game_sessions(
FleetId='string',
AliasId='string',
FilterExpression='string',
SortExpression='string',
Limit=123,
NextToken='string'
)
string
Unique identifier for a fleet to search for active game sessions. Each request must reference either a fleet ID or alias ID, but not both.
string
Unique identifier for an alias associated with the fleet to search for active game sessions. Each request must reference either a fleet ID or alias ID, but not both.
string
String containing the search criteria for the session search. If no filter expression is included, the request returns results for all game sessions in the fleet that are in ACTIVE status.
A filter expression can contain one or multiple conditions. Each condition consists of the following:
Operand -- Name of a game session attribute. Valid values are gameSessionName , gameSessionId , creationTimeMillis , playerSessionCount , maximumSessions , hasAvailablePlayerSessions .
Comparator -- Valid comparators are: = , <> , < , > , <= , >= .
Value -- Value to be searched for. Values can be numbers, boolean values (true/false) or strings. String values are case sensitive, enclosed in single quotes. Special characters must be escaped. Boolean and string values can only be used with the comparators = and <> . For example, the following filter expression searches on gameSessionName : " FilterExpression": "gameSessionName = 'Matt\\'s Awesome Game 1'" .
To chain multiple conditions in a single expression, use the logical keywords AND , OR , and NOT and parentheses as needed. For example: x AND y AND NOT z , NOT (x OR y) .
Session search evaluates conditions from left to right using the following precedence rules:
= , <> , < , > , <= , >=
Parentheses
NOT
AND
OR
For example, this filter expression retrieves game sessions hosting at least ten players that have an open player slot: "maximumSessions>=10 AND hasAvailablePlayerSessions=true" .
string
Instructions on how to sort the search results. If no sort expression is included, the request returns results in random order. A sort expression consists of the following elements:
Operand -- Name of a game session attribute. Valid values are gameSessionName , gameSessionId , creationTimeMillis , playerSessionCount , maximumSessions , hasAvailablePlayerSessions .
Order -- Valid sort orders are ASC (ascending) and DESC (descending).
For example, this sort expression returns the oldest active sessions first: "SortExpression": "creationTimeMillis ASC" . Results with a null value for the sort operand are returned at the end of the list.
integer
Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages. The maximum number of results returned is 20, even if this value is not set or is set higher than 20.
string
Token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To start at the beginning of the result set, do not specify a value.
dict
Response Syntax
{
'GameSessions': [
{
'GameSessionId': 'string',
'Name': 'string',
'FleetId': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'CurrentPlayerSessionCount': 123,
'MaximumPlayerSessionCount': 123,
'Status': 'ACTIVE'|'ACTIVATING'|'TERMINATED'|'TERMINATING'|'ERROR',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'IpAddress': 'string',
'Port': 123,
'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL',
'CreatorId': 'string',
'GameSessionData': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSessions (list) --
Collection of objects containing game session properties for each session matching the request.
(dict) --
Properties describing a game session.
A game session in ACTIVE status can host players. When a game session ends, its status is set to TERMINATED .
Once the session ends, the game session object is retained for 30 days. This means you can reuse idempotency token values after this time. Game session logs are retained for 14 days.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
GameSessionId (string) --
Unique identifier for the game session. A game session ID has the following format: arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token> .
Name (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
FleetId (string) --
Unique identifier for a fleet the game session is running on.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
TerminationTime (datetime) --
Time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
CurrentPlayerSessionCount (integer) --
Number of players currently in the game session.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
Status (string) --
Current status of the game session. A game session must have an ACTIVE status to have player sessions.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
PlayerSessionCreationPolicy (string) --
Indicates whether or not the game session is accepting new players.
CreatorId (string) --
Unique identifier for a player. This ID is used to enforce a resource protection policy (if one exists), that limits the number of game sessions a player can create.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
NextToken (string) --
Token that indicates where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
{'GameSessionData': 'string'}
Response {'GameSessionPlacement': {'GameSessionData': 'string'}}
Places a request for a new game session in a queue (see CreateGameSessionQueue ). When processing a placement request, Amazon GameLift searches for available resources on the queue's destinations, scanning each until it finds resources or the placement request times out.
A game session placement request can also request player sessions. When a new game session is successfully created, Amazon GameLift creates a player session for each player included in the request.
When placing a game session, by default Amazon GameLift tries each fleet in the order they are listed in the queue configuration. Ideally, a queue's destinations are listed in preference order.
Alternatively, when requesting a game session with players, you can also provide latency data for each player in relevant regions. Latency data indicates the performance lag a player experiences when connected to a fleet in the region. Amazon GameLift uses latency data to reorder the list of destinations to place the game session in a region with minimal lag. If latency data is provided for multiple players, Amazon GameLift calculates each region's average lag for all players and reorders to get the best game play across all players.
To place a new game session request, specify the following:
The queue name and a set of game session properties and settings
A unique ID (such as a UUID) for the placement. You use this ID to track the status of the placement request
(Optional) A set of IDs and player data for each player you want to join to the new game session
Latency data for all players (if you want to optimize game play for the players)
If successful, a new game session placement is created.
To track the status of a placement request, call DescribeGameSessionPlacement and check the request's status. If the status is FULFILLED , a new game session has been created and a game session ARN and region are referenced. If the placement request times out, you can resubmit the request or retry it with a different queue.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.start_game_session_placement(
PlacementId='string',
GameSessionQueueName='string',
GameProperties=[
{
'Key': 'string',
'Value': 'string'
},
],
MaximumPlayerSessionCount=123,
GameSessionName='string',
PlayerLatencies=[
{
'PlayerId': 'string',
'RegionIdentifier': 'string',
'LatencyInMilliseconds': ...
},
],
DesiredPlayerSessions=[
{
'PlayerId': 'string',
'PlayerData': 'string'
},
],
GameSessionData='string'
)
string
[REQUIRED]
Unique identifier to assign to the new game session placement. This value is developer-defined. The value must be unique across all regions and cannot be reused unless you are resubmitting a canceled or timed-out placement request.
string
[REQUIRED]
Name of the queue to use to place the new game session.
list
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) -- [REQUIRED]
Game property identifier.
Value (string) -- [REQUIRED]
Game property value.
integer
[REQUIRED]
Maximum number of players that can be connected simultaneously to the game session.
string
Descriptive label that is associated with a game session. Session names do not need to be unique.
list
Set of values, expressed in milliseconds, indicating the amount of latency that a player experiences when connected to AWS regions. This information is used to try to place the new game session where it can offer the best possible gameplay experience for the players.
(dict) --
Regional latency information for a player, used when requesting a new game session with StartGameSessionPlacement. This value indicates the amount of time lag that exists when the player is connected to a fleet in the specified region. The relative difference between a player's latency values for multiple regions are used to determine which fleets are best suited to place a new game session for the player.
PlayerId (string) --
Unique identifier for a player associated with the latency data.
RegionIdentifier (string) --
Name of the region that is associated with the latency value.
LatencyInMilliseconds (float) --
Amount of time that represents the time lag experienced by the player when connected to the specified region.
list
Set of information on each player to create a player session for.
(dict) --
Player information for use when creating player sessions using a game session placement request with StartGameSessionPlacement.
PlayerId (string) --
Unique identifier for a player to associate with the player session.
PlayerData (string) --
Developer-defined information related to a player. Amazon GameLift does not use this data, so it can be formatted as needed for use in the game.
string
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
dict
Response Syntax
{
'GameSessionPlacement': {
'PlacementId': 'string',
'GameSessionQueueName': 'string',
'Status': 'PENDING'|'FULFILLED'|'CANCELLED'|'TIMED_OUT',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'MaximumPlayerSessionCount': 123,
'GameSessionName': 'string',
'GameSessionId': 'string',
'GameSessionArn': 'string',
'GameSessionRegion': 'string',
'PlayerLatencies': [
{
'PlayerId': 'string',
'RegionIdentifier': 'string',
'LatencyInMilliseconds': ...
},
],
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'IpAddress': 'string',
'Port': 123,
'PlacedPlayerSessions': [
{
'PlayerId': 'string',
'PlayerSessionId': 'string'
},
],
'GameSessionData': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSessionPlacement (dict) --
Object that describes the newly created game session placement. This object includes all the information provided in the request, as well as start/end time stamps and placement status.
PlacementId (string) --
Unique identifier for a game session placement.
GameSessionQueueName (string) --
Descriptive label that is associated with game session queue. Queue names must be unique within each region.
Status (string) --
Current status of the game session placement request.
PENDING – The placement request is currently in the queue waiting to be processed.
FULFILLED – A new game session and player sessions (if requested) have been successfully created. Values for GameSessionArn and GameSessionRegion are available.
CANCELLED – The placement request was canceled with a call to StopGameSessionPlacement.
TIMED_OUT – A new game session was not successfully created before the time limit expired. You can resubmit the placement request as needed.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
GameSessionName (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
GameSessionId (string) --
Unique identifier for the game session. This value is set once the new game session is placed (placement status is FULFILLED ).
GameSessionArn (string) --
Identifier for the game session created by this placement request. This value is set once the new game session is placed (placement status is FULFILLED ). This identifier is unique across all regions. You can use this value as a GameSessionId value as needed.
GameSessionRegion (string) --
Name of the region where the game session created by this placement request is running. This value is set once the new game session is placed (placement status is FULFILLED ).
PlayerLatencies (list) --
Set of values, expressed in milliseconds, indicating the amount of latency that a player experiences when connected to AWS regions.
(dict) --
Regional latency information for a player, used when requesting a new game session with StartGameSessionPlacement. This value indicates the amount of time lag that exists when the player is connected to a fleet in the specified region. The relative difference between a player's latency values for multiple regions are used to determine which fleets are best suited to place a new game session for the player.
PlayerId (string) --
Unique identifier for a player associated with the latency data.
RegionIdentifier (string) --
Name of the region that is associated with the latency value.
LatencyInMilliseconds (float) --
Amount of time that represents the time lag experienced by the player when connected to the specified region.
StartTime (datetime) --
Time stamp indicating when this request was placed in the queue. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
EndTime (datetime) --
Time stamp indicating when this request was completed, canceled, or timed out.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number. This value is set once the new game session is placed (placement status is FULFILLED ).
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number. This value is set once the new game session is placed (placement status is FULFILLED ).
PlacedPlayerSessions (list) --
Collection of information on player sessions created in response to the game session placement request. These player sessions are created only once a new game session is successfully placed (placement status is FULFILLED ). This information includes the player ID (as provided in the placement request) and the corresponding player session ID. Retrieve full player sessions by calling DescribePlayerSessions with the player session ID.
(dict) --
Information about a player session that was created as part of a StartGameSessionPlacement request. This object contains only the player ID and player session ID. To retrieve full details on a player session, call DescribePlayerSessions with the player session ID.
Player-session-related operations include:
CreatePlayerSession
CreatePlayerSessions
DescribePlayerSessions
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
PlayerId (string) --
Unique identifier for a player that is associated with this player session.
PlayerSessionId (string) --
Unique identifier for a player session.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
{'GameSessionPlacement': {'GameSessionData': 'string'}}
Cancels a game session placement that is in PENDING status. To stop a placement, provide the placement ID values. If successful, the placement is moved to CANCELLED status.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.stop_game_session_placement(
PlacementId='string'
)
string
[REQUIRED]
Unique identifier for a game session placement to cancel.
dict
Response Syntax
{
'GameSessionPlacement': {
'PlacementId': 'string',
'GameSessionQueueName': 'string',
'Status': 'PENDING'|'FULFILLED'|'CANCELLED'|'TIMED_OUT',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'MaximumPlayerSessionCount': 123,
'GameSessionName': 'string',
'GameSessionId': 'string',
'GameSessionArn': 'string',
'GameSessionRegion': 'string',
'PlayerLatencies': [
{
'PlayerId': 'string',
'RegionIdentifier': 'string',
'LatencyInMilliseconds': ...
},
],
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'IpAddress': 'string',
'Port': 123,
'PlacedPlayerSessions': [
{
'PlayerId': 'string',
'PlayerSessionId': 'string'
},
],
'GameSessionData': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSessionPlacement (dict) --
Object that describes the canceled game session placement, with CANCELLED status and an end time stamp.
PlacementId (string) --
Unique identifier for a game session placement.
GameSessionQueueName (string) --
Descriptive label that is associated with game session queue. Queue names must be unique within each region.
Status (string) --
Current status of the game session placement request.
PENDING – The placement request is currently in the queue waiting to be processed.
FULFILLED – A new game session and player sessions (if requested) have been successfully created. Values for GameSessionArn and GameSessionRegion are available.
CANCELLED – The placement request was canceled with a call to StopGameSessionPlacement.
TIMED_OUT – A new game session was not successfully created before the time limit expired. You can resubmit the placement request as needed.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
GameSessionName (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
GameSessionId (string) --
Unique identifier for the game session. This value is set once the new game session is placed (placement status is FULFILLED ).
GameSessionArn (string) --
Identifier for the game session created by this placement request. This value is set once the new game session is placed (placement status is FULFILLED ). This identifier is unique across all regions. You can use this value as a GameSessionId value as needed.
GameSessionRegion (string) --
Name of the region where the game session created by this placement request is running. This value is set once the new game session is placed (placement status is FULFILLED ).
PlayerLatencies (list) --
Set of values, expressed in milliseconds, indicating the amount of latency that a player experiences when connected to AWS regions.
(dict) --
Regional latency information for a player, used when requesting a new game session with StartGameSessionPlacement. This value indicates the amount of time lag that exists when the player is connected to a fleet in the specified region. The relative difference between a player's latency values for multiple regions are used to determine which fleets are best suited to place a new game session for the player.
PlayerId (string) --
Unique identifier for a player associated with the latency data.
RegionIdentifier (string) --
Name of the region that is associated with the latency value.
LatencyInMilliseconds (float) --
Amount of time that represents the time lag experienced by the player when connected to the specified region.
StartTime (datetime) --
Time stamp indicating when this request was placed in the queue. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
EndTime (datetime) --
Time stamp indicating when this request was completed, canceled, or timed out.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number. This value is set once the new game session is placed (placement status is FULFILLED ).
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number. This value is set once the new game session is placed (placement status is FULFILLED ).
PlacedPlayerSessions (list) --
Collection of information on player sessions created in response to the game session placement request. These player sessions are created only once a new game session is successfully placed (placement status is FULFILLED ). This information includes the player ID (as provided in the placement request) and the corresponding player session ID. Retrieve full player sessions by calling DescribePlayerSessions with the player session ID.
(dict) --
Information about a player session that was created as part of a StartGameSessionPlacement request. This object contains only the player ID and player session ID. To retrieve full details on a player session, call DescribePlayerSessions with the player session ID.
Player-session-related operations include:
CreatePlayerSession
CreatePlayerSessions
DescribePlayerSessions
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
PlayerId (string) --
Unique identifier for a player that is associated with this player session.
PlayerSessionId (string) --
Unique identifier for a player session.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
{'GameSession': {'GameSessionData': 'string'}}
Updates game session properties. This includes the session name, maximum player count, protection policy, which controls whether or not an active game session can be terminated during a scale-down event, and the player session creation policy, which controls whether or not new players can join the session. To update a game session, specify the game session ID and the values you want to change. If successful, an updated GameSession object is returned.
Game-session-related operations include:
CreateGameSession
DescribeGameSessions
DescribeGameSessionDetails
SearchGameSessions
UpdateGameSession
GetGameSessionLogUrl
Game session placements
StartGameSessionPlacement
DescribeGameSessionPlacement
StopGameSessionPlacement
See also: AWS API Documentation
Request Syntax
client.update_game_session(
GameSessionId='string',
MaximumPlayerSessionCount=123,
Name='string',
PlayerSessionCreationPolicy='ACCEPT_ALL'|'DENY_ALL',
ProtectionPolicy='NoProtection'|'FullProtection'
)
string
[REQUIRED]
Unique identifier for the game session to update.
integer
Maximum number of players that can be connected simultaneously to the game session.
string
Descriptive label that is associated with a game session. Session names do not need to be unique.
string
Policy determining whether or not the game session accepts new players.
string
Game session protection policy to apply to this game session only.
NoProtection – The game session can be terminated during a scale-down event.
FullProtection – If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
dict
Response Syntax
{
'GameSession': {
'GameSessionId': 'string',
'Name': 'string',
'FleetId': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'CurrentPlayerSessionCount': 123,
'MaximumPlayerSessionCount': 123,
'Status': 'ACTIVE'|'ACTIVATING'|'TERMINATED'|'TERMINATING'|'ERROR',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'IpAddress': 'string',
'Port': 123,
'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL',
'CreatorId': 'string',
'GameSessionData': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSession (dict) --
Object that contains the updated game session metadata.
GameSessionId (string) --
Unique identifier for the game session. A game session ID has the following format: arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token> .
Name (string) --
Descriptive label that is associated with a game session. Session names do not need to be unique.
FleetId (string) --
Unique identifier for a fleet the game session is running on.
CreationTime (datetime) --
Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
TerminationTime (datetime) --
Time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
CurrentPlayerSessionCount (integer) --
Number of players currently in the game session.
MaximumPlayerSessionCount (integer) --
Maximum number of players that can be connected simultaneously to the game session.
Status (string) --
Current status of the game session. A game session must have an ACTIVE status to have player sessions.
GameProperties (list) --
Set of developer-defined properties for a game session, formatted as a set of type:value pairs. These properties are included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).
(dict) --
Set of key-value pairs that contain information about a game session. When included in a game session request, these properties communicate details to be used when setting up the new game session, such as to specify a game mode, level, or map. Game properties are passed to the game server process when initiating a new game session; the server process uses the properties as appropriate. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Game property identifier.
Value (string) --
Game property value.
IpAddress (string) --
IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
Port (integer) --
Port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.
PlayerSessionCreationPolicy (string) --
Indicates whether or not the game session is accepting new players.
CreatorId (string) --
Unique identifier for a player. This ID is used to enforce a resource protection policy (if one exists), that limits the number of game sessions a player can create.
GameSessionData (string) --
Set of developer-defined game session properties, formatted as a single string value. This data is included in the GameSession object, which is passed to the game server with a request to start a new game session (see Start a Game Session ).