CreateGameSessionQueue

Creates a placement queue that processes requests for new game sessions. A queue uses FleetIQ algorithms to locate the best available placement locations for a new game session, and then prompts the game server process to start a new game session.

A game session queue is configured with a set of destinations (Amazon GameLift Servers fleets or aliases) that determine where the queue can place new game sessions. These destinations can span multiple AWS Regions, can use different instance types, and can include both Spot and On-Demand fleets. If the queue includes multi-location fleets, the queue can place game sessions in any of a fleet's remote locations.

You can configure a queue to determine how it selects the best available placement for a new game session. Queues can prioritize placement decisions based on a combination of location, hosting cost, and player latency. You can set up the queue to use the default prioritization or provide alternate instructions using PriorityConfiguration.

Request options

Use this operation to make these common types of requests.

Results

If successful, this operation returns a new GameSessionQueue object with an assigned queue ARN. Use the queue's name or ARN when submitting new game session requests with StartGameSessionPlacement or StartMatchmaking.

Learn more

Design a game session queue

Create a game session queue

Related actions

CreateGameSessionQueue | DescribeGameSessionQueues | UpdateGameSessionQueue | DeleteGameSessionQueue | All APIs by task

Request Syntax

{
   "CustomEventData": "string",
   "Destinations": [ 
      { 
         "DestinationArn": "string"
      }
   ],
   "FilterConfiguration": { 
      "AllowedLocations": [ "string" ]
   },
   "Name": "string",
   "NotificationTarget": "string",
   "PlayerLatencyPolicies": [ 
      { 
         "MaximumIndividualPlayerLatencyMilliseconds": number,
         "PolicyDurationSeconds": number
      }
   ],
   "PriorityConfiguration": { 
      "LocationOrder": [ "string" ],
      "PriorityOrder": [ "string" ]
   },
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "TimeoutInSeconds": number
}

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

{
   "GameSessionQueue": { 
      "CustomEventData": "string",
      "Destinations": [ 
         { 
            "DestinationArn": "string"
         }
      ],
      "FilterConfiguration": { 
         "AllowedLocations": [ "string" ]
      },
      "GameSessionQueueArn": "string",
      "Name": "string",
      "NotificationTarget": "string",
      "PlayerLatencyPolicies": [ 
         { 
            "MaximumIndividualPlayerLatencyMilliseconds": number,
            "PolicyDurationSeconds": number
         }
      ],
      "PriorityConfiguration": { 
         "LocationOrder": [ "string" ],
         "PriorityOrder": [ "string" ]
      },
      "TimeoutInSeconds": number
   }
}

Response Elements

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

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

Errors

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

Examples

Create and configure a game session queue

In this example, we want to create a game session queue with two single-location destinations, each residing in different Regions. We configure the queue so that requests for new game sessions expire after 10 minutes. The queue will process game session requests with player latency data, so we provide a set of latency cap polices that initially start at 100mm and then relax to 200ms after one minute. We opt to use the default sort approach for FleetIQ.

Sample Request

{
    "Name": "matchmaker-queue",
    "Destinations": [
        { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
        { "DestinationArn": "arn:aws:gamelift:sa-east-1::fleet/fleet-5c6d3c4d-5e6f-7a8b-9a0b-1e2f3a4b5a2b" }
    ],
    "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
    "PlayerLatencyPolicies": [ 
        { "MaximumIndividualPlayerLatencyMilliseconds": 200 },
        { "MaximumIndividualPlayerLatencyMilliseconds": 100, "PolicyDurationSeconds": 60 }
    ],
    "TimeoutInSeconds": 600
}                

Sample Response

{
    "GameSessionQueue": {
        "Name": "matchmaker-queue",
        "GameSessionQueueArn": "arn:aws:gamelift:us-west-2:111122223333:gamesessionqueue/matchmaker-queue",
        "TimeoutInSeconds": 600,
        "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
        "PlayerLatencyPolicies": [
            {
                "MaximumIndividualPlayerLatencyMilliseconds": 100, 
                "PolicyDurationSeconds": 60
            }, 
            {
                "MaximumIndividualPlayerLatencyMilliseconds": 200
            }
        ],
        "Destinations": [
            {"DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"},
            {"DestinationArn": "arn:aws:gamelift:us-east-1::fleet/fleet-5c6d3c4d-5e6f-7a8b-9c0d-1e2f3a4b5a2b"}
        ]
    }
}

Create a game session queue with multi-location fleets

In this example, we want to create a game session queue to place game sessions with two multi-location Spot fleets and one single-location On-Demand fleet. The multi-location fleets have remote locations in (us-west-1, us-east-2, sa-east-1).

We also want to change how FleetIQ prioritizes destinations and locations for placement. We opt to have FleetIQ prioritize by location first (with a custom location order provided), and then by destination list order. Based on our priority configuration, the queue will always try to place game sessions in the us-west-1 remote location of the first listed destination fleet. If no game servers are available there, the queue will try to place in the us-west-1 home Region of the second listed destination fleet, and so on.

Sample Request

{
    "Name": "matchmaker-queue",
    "Destinations": [
        { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
        { "DestinationArn": "arn:aws:gamelift:us-west-1::fleet/fleet-2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d" },
        { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-5c6d3c4d-5e6f-7a8b-9a0b-1e2f3a4b5a2b" }
    ],
    "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
    "PriorityConfiguration": {
        "PriorityOrder": "LOCATION,DESTINATION",
        "LocationOrder": "us-west-1,us-west-2,us-east-2, sa-east-1"
    },
    "TimeoutInSeconds": 600
}                

Sample Response

{
    "GameSessionQueue": {
        "Name": "matchmaker-queue",
        "GameSessionQueueArn": "arn:aws:gamelift:us-west-2:111122223333:gamesessionqueue/matchmaker-queue",
        "TimeoutInSeconds": 600,
        "Destinations": [
            { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
            { "DestinationArn": "arn:aws:gamelift:us-west-1::fleet/fleet-2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d" },
            { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-5c6d3c4d-5e6f-7a8b-9a0b-1e2f3a4b5a2b" }
        ],
        "PriorityConfiguration": {
            "PriorityOrder": "LOCATION,DESTINATION",
            "LocationOrder": "us-west-1,us-west-2,us-east-2, sa-east-1"
        },
        "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
    }
}

See Also

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