StartGameSessionPlacement

Places a request for a new game session in a queue. 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:

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.

Request Syntax

{
   "DesiredPlayerSessions": [ 
      { 
         "PlayerData": "string",
         "PlayerId": "string"
      }
   ],
   "GameProperties": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "GameSessionData": "string",
   "GameSessionName": "string",
   "GameSessionQueueName": "string",
   "MaximumPlayerSessionCount": number,
   "PlacementId": "string",
   "PlayerLatencies": [ 
      { 
         "LatencyInMilliseconds": number,
         "PlayerId": "string",
         "RegionIdentifier": "string"
      }
   ]
}

Request Parameters

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

The request accepts the following data in JSON format.

Response Syntax

{
   "GameSessionPlacement": { 
      "DnsName": "string",
      "EndTime": number,
      "GameProperties": [ 
         { 
            "Key": "string",
            "Value": "string"
         }
      ],
      "GameSessionArn": "string",
      "GameSessionData": "string",
      "GameSessionId": "string",
      "GameSessionName": "string",
      "GameSessionQueueName": "string",
      "GameSessionRegion": "string",
      "IpAddress": "string",
      "MatchmakerData": "string",
      "MaximumPlayerSessionCount": number,
      "PlacedPlayerSessions": [ 
         { 
            "PlayerId": "string",
            "PlayerSessionId": "string"
         }
      ],
      "PlacementId": "string",
      "PlayerLatencies": [ 
         { 
            "LatencyInMilliseconds": number,
            "PlayerId": "string",
            "RegionIdentifier": "string"
         }
      ],
      "Port": number,
      "StartTime": number,
      "Status": "string"
   }
}

Response Elements

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

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

Errors

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

Examples

Request a new game session placement with player latency data

This example starts a new game session placement. The request calls for player sessions for two players, and provides each player's latency data for two Regions.

Amazon GameLift uses the latency data provided to determine what order to use when looking for a fleet to host the new game session. It does this by calculating the average player latency for each Region and ordering the queue's destinations starting with the lowest average latency. If the queue "matchmaker-queue" has a latency policy, however, things may change. For example, let's say matchmaker-queue has a policy that caps latency at 130 milliseconds for 60 seconds, followed by no cap. In this scenario, using the sample request below, the following sequence plays out:

Sample Request

POST / HTTP/1.1
Host: gamelift.us-west-2.amazonaws.com;
Accept-Encoding: identity
Content-Length: 824
User-Agent: aws-cli/1.11.36 Python/2.7.9 Windows/7 botocore/1.4.93
Content-Type: application/x-amz-json-1.0
Authorization: AWS4-HMAC-SHA256  Credential=AKIAIOSFODNN7EXAMPLE/20170406/us-west-2/gamelift/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
X-Amz-Date: 20170406T004805Z
X-Amz-Target: GameLift.StartGameSessionPlacement 
	
{
   "DesiredPlayerSessions": [ 
      { "PlayerData": "level:10", "PlayerId": "player1" },
      { "PlayerData": "level:11", "PlayerId": "player2" },
   ],
   "GameProperties": [ 
      { "Key": "map", "Value": "winter" }
   ],
   "GameSessionName": "matchmaker-1234567890",
   "GameSessionQueueName": "matchmaker-queue",
   "MaximumPlayerSessionCount": 4,
   "PlacementId": "Place-12345",
   "PlayerLatencies": [ 
      { "LatencyInMilliseconds": 100, "PlayerId": "player1", "RegionIdentifier": "us-east-1" },
      { "LatencyInMilliseconds":  50, "PlayerId": "player1", "RegionIdentifier": "us-west-2" },
      { "LatencyInMilliseconds": 120, "PlayerId": "player2", "RegionIdentifier": "us-east-1" },
      { "LatencyInMilliseconds": 150, "PlayerId": "player2", "RegionIdentifier": "us-west-2" },
   ]
}
                

See Also

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