Menu
Amazon GameLift
Developer Guide (Version )

Create a Queue

You create a queue to place new game sessions by searching for available hosting resources across multiple fleets and regions. To request new game sessions using a queue, call StartGameSessionPlacement and specify the queue name. For tips on designing queues for your game, see Create Game Sessions with Queues.

To create a queue, you can use either the Amazon GameLift console or the AWS Command Line Interface (CLI).

Set destinations

A destination is either a fleet or an alias. Destinations determine where Amazon GameLift searches for available hosting resources when trying a place a new game session. A queue usually has several destinations that are deployed in different regions. When choosing destinations for the queue, consider the following:

  • A destination can be any fleet or alias in any region. If you assign aliases to your fleets (as recommended), it is a good idea to use alias names here.

  • All destinations in the queue must be running game builds that are compatible with the game clients that use the queue.

  • New game session requests processed by the queue might be placed on any destination in the queue.

  • The list order of destinations in a queue matters. When Amazon GameLift searches for a fleet with available resources to host the new game session, by default it follows the list order. This means that game sessions will always be hosted on the first fleet, if resources are available, and only fall back to secondary fleets as needed. Individual game session placement requests can override a queue's default order and instead find the best available fleet based on player latency data.

  • If you're requesting new game sessions from a game service (such as for matchmaking), create your queue in a region that is geographically near where the service is deployed. This arrangement minimizes latency when submitting game session placement requests.

Set player latency policies (optional)

If you're using the queue to place sessions based on player latency data, it's a good idea to set up player latency policies . Amazon GameLift uses player latency data (when provided) to place game sessions in destinations with the best average latency for all players. In contrast, a player latency policy prevents placement in destinations where an individual player is reporting unacceptably high latency.

You can set more than one latency policy. Multiple policies are enforced consecutively, starting with the policy that has the lowest maximum latency value. For example, you might define the following policies for a queue with a 10-minute timeout. This set of policies raises the latency maximum gradually to strike a balance between ensuring a low latency gameplay experience and limiting the amount of time that players must wait for a game.

  1. Spend 120 seconds searching for a destination where all player latencies are less than 50 milliseconds, then...

  2. Spend 120 seconds searching for a destination where all player latencies are less than 100 milliseconds, then...

  3. Spend the remaining queue timeout searching for a destination where all player latencies are less than 150 milliseconds.

In this example, the first policy is in force for the first two minutes, the second policy is in force for the third and fourth minute, and the third policy is in force for six minutes until the placement request times out.

While player latency policies do protect players from high-latency game sessions, they also increase the risk that game sessions will time out when any players report high latency. To ensure that your latency policies do not prevent game session placements, you can set the "remaining queue timeout" policy to a very high maximum value.

Create a Queue (Console)

You can create a queue from the AWS Management Console.

To create a queue

  1. Open the Amazon GameLift console at https://console.aws.amazon.com/gamelift/, and choose the region you want to create your queue in.

  2. From the Amazon GameLift menu, choose Create a queue.

  3. On the Create queue page, complete the Queue Details section:

    • Queue Name – Create a meaningful queue name so you can identify it in a list and in metrics. Requests for new a game session (using StartGameSessionPlacement) must specify a queue by this name. Spaces and special characters are not allowed.

    • Queue Timeout – Specify how long you want Amazon GameLift to try to place a new game session before stopping. Amazon GameLift continues to search for available resources on any fleet until the request times out.

  4. Under Player latency policies, define zero or more policies for the queue. Player latency policies are only evaluated when game session placement requests include player latency data.

    1. To add a first policy, choose Add player latency policy. Enter a maximum player latency value for this policy (default is 150 milliseconds). As indicated in the policy language, this first policy will be enforced at the end of a placement period, after all other policies. If you set just this one policy, it will be enforced for the entire queue placement effort.

    2. To add another player latency policy, choose Add player latency policy again. For additional policies, set the maximum player latency value and a length of time (in seconds) to enforce it. Maximum latency values for these policies must be lower than the first policy.

      As you add policies, the console automatically reorders the polices based on the maximum player latency value, lowest value listed first. This is the order in which the policies are enforced during a game session placement effort.

  5. Under Destinations, add one or more destinations to the queue. Fleets and aliases must already exist before you can add them as destinations.

    1. Choose Add destination.

    2. Use the columns to specify the region and type (fleet or alias) for your destination. From the resulting list of fleet or alias names, select the one you want to add.

    3. To save the destination, choose the green checkmark icon. You must save each destination before adding another one, changing the default order, or saving the queue.

    4. If you have multiple destinations, set the default order by using the arrow icons in the Priority (default) column. This order is used by Amazon GameLift when searching destinations for available resources to place a new game session. (The default order is overridden if a game session placement request includes player latency data.)

  6. Once you've finished configuring your new queue, choose Create queue. Your new queue is saved and the Queues page shows the new queue and any other queues that exist. You can choose a queue from this page to view detailed information, including queue metrics. You can edit a queue configuration at any time.

Create a Queue (AWS CLI)

You can use the AWS Command Line Interface (AWS CLI) to create a queue. If you haven't yet installed the AWS CLI, see the topic Install the AWS CLI.

To create a queue

  • Open a command line window and use the create-game-session-queue command to define a new queue. For more information, see the AWS CLI Command Reference.

The following example creates a queue for placing new game sessions on any of several fleets before timing out at five minutes. Fleets are listed as destinations and identified by either a fleet ARN or alias ARN. All fleets and aliases must already exist. Amazon GameLift tries to place new game sessions on fleets in the order they are listed here unless the order is overridden by individual game session placement requests.

Note

You can get fleet and alias ARN values by calling either describe-fleet-attributes or describe-alias with the fleet or alias ID. For more information on ARN (Amazon Resource Name) formats, see ARNs and AWS Service Namespaces.

$ aws gamelift create-game-session-queue --name "Sample test queue" --timeout-in-seconds 300 --destinations DestinationArn=arn:aws:gamelift:us-east-1::alias/alias-a1234567-b8c9-0d1e-2fa3-b45c6d7e8910 DestinationArn=arn:aws:gamelift:us-west-2::alias/alias-b0234567-c8d9-0e1f-2ab3-c45d6e7f8901 DestinationArn=arn:aws:gamelift:us-west-2::fleet/fleet-f1234567-b8c9-0d1e-2fa3-b45c6d7e8912

Copiable version:

aws gamelift create-game-session-queue --name "Sample test queue" --timeout-in-seconds 300 --destinations DestinationArn=arn:aws:gamelift:us-east-1::alias/alias-a1234567-b8c9-0d1e-2fa3-b45c6d7e8910 DestinationArn=arn:aws:gamelift:us-west-2::alias/alias-b0234567-c8d9-0e1f-2ab3-c45d6e7f8901 DestinationArn=arn:aws:gamelift:us-west-2::fleet/fleet-f1234567-b8c9-0d1e-2fa3-b45c6d7e8912

If the create-game-session-queue request is successful, Amazon GameLift returns a GameSessionQueue object with the new queue configuration. You can now submit requests to the queue using StartGameSessionPlacement.

To create a queue with player latency policies

  • Open a command line window and use the create-game-session-queue command to define a new queue. For more information, see the AWS CLI Command Reference.

The following example creates a queue with a 10-minute timeout, three destinations, and a set of player latency policies. In this example, the first player latency policy is in force for the first two minutes, the second policy is in force for the third and fourth minute, and the third policy is in force for six minutes until the placement request times out.

$ aws gamelift create-game-session-queue --name "matchmaker-queue" --timeout-in-seconds 600 --destinations DestinationArn=arn:aws:gamelift:us-east-1::alias/alias-a1234567-b8c9-0d1e-2fa3-b45c6d7e8910 DestinationArn=arn:aws:gamelift:us-west-2::alias/alias-b0234567-c8d9-0e1f-2ab3-c45d6e7f8901 DestinationArn=arn:aws:gamelift:us-west-2::fleet/fleet-f1234567-b8c9-0d1e-2fa3-b45c6d7e8912 --player-latency-policies "MaximumIndividualPlayerLatencyMilliseconds=50,PolicyDurationSeconds=120" "MaximumIndividualPlayerLatencyMilliseconds=100,PolicyDurationSeconds=120" "MaximumIndividualPlayerLatencyMilliseconds=150"

Copiable version:

aws gamelift create-game-session-queue --name "matchmaker-queue" --timeout-in-seconds 600 --destinations DestinationArn=arn:aws:gamelift:us-east-1::alias/alias-a1234567-b8c9-0d1e-2fa3-b45c6d7e8910 DestinationArn=arn:aws:gamelift:us-west-2::alias/alias-b0234567-c8d9-0e1f-2ab3-c45d6e7f8901 DestinationArn=arn:aws:gamelift:us-west-2::fleet/fleet-f1234567-b8c9-0d1e-2fa3-b45c6d7e8912 --player-latency-policies "MaximumIndividualPlayerLatencyMilliseconds=50,PolicyDurationSeconds=120" "MaximumIndividualPlayerLatencyMilliseconds=100,PolicyDurationSeconds=120" "MaximumIndividualPlayerLatencyMilliseconds=150"

If the create-game-session-queue request is successful, Amazon GameLift returns a GameSessionQueue object with the new queue configuration.