# Game session placement customizations
Game session placement customizations give you the opportunity to fine-tune your placement system to give your player base the best possible gameplay experience. You can optimize placement for player compatibility and preferences, as well as for operational considerations such as cost efficiency, geographic distribution, and resilience against service disruptions.
# Customize a game session queue
This topic describes how to customize your game session queues to make the best possible decisions about game session placement. For more information about game session queues and how they work, see [Configure game session placement](queues-intro.md).
These Amazon GameLift Servers features require queues:
+ [Matchmaking with FlexMatch](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-tasks.html)
+ [Build a queue for Spot Instances](spot-tasks.md)
**Topics**
+ [Define a queue's scope](queues-design-scope.md)
+ [Build a multi-location queue](queues-design-multiregion.md)
+ [Evaluate queue metrics](queues-design-metrics.md)
# Define a queue's scope
Your game's player population might have groups of players who shouldn't play together. For example, if you publish your game in two languages each language should have its own game servers.
To set up game session placement for your player population, create a separate queue for each player segment. Scope each queue to place players into the correct game servers. Some common ways to scope queues include:
+ **By geographic locations.** When deploying your game servers in multiple geographic areas, you might build queues for players in each location to reduce player latency.
+ **By build or script variations.** If you have more than one variation of your game server, you might be supporting player groups that can't play in the same game sessions. For example, game server builds or scripts might support different languages or device types.
+ **By event types.** You might create a special queue to manage games for participants in tournaments or other special events.
## Design multiple queues
Depending on your game and players, you might want to create more than one game session queue. When your game client service requests a new game session, it specifies which game session queue to use. To help you determine whether to use multiple queues, consider:
+ Variations of your game server. You can create a separate queue for each variation of your game server. All fleets in a queue must deploy compatible game servers. This is because players who use the queue to join games must be able to play on any of the queue's game servers.
+ Different player groups. You can customize how Amazon GameLift Servers places game sessions based on player group. For example, you might need queues customized for certain game modes that require a special instance type or runtime configuration. Or, you might want a special queue to manage placements for a tournament or other event.
+ Game session queue metrics. You can set up queues based on how you want to collect game session placement metrics. For more information, see [Amazon GameLift Servers metrics for queues](monitoring-cloudwatch.md#gamelift-metrics-queue).
# Build a multi-location queue
We recommend a multi-location design for all queues. This design can improve placement speed and hosting resiliency. A multi-location design is required to use player latency data to put players into game sessions with minimal latency. If you're building multi-location queues that use Spot Instance fleets, follow the instructions in [Reduce game hosting costs with Spot fleets](fleets-spot.md).
One way to create a multi-location queue is to add a [multi-location fleet](gamelift-regions.md#gamelift-regions-hosting) to a queue. That way, the queue can place game sessions in any of the fleet's locations. You can also add other fleets with different configurations or home locations for redundancy. If you're using a multi-location Spot Instance fleet, follow best practices and include an On-Demand Instance fleet with the same locations.
The following example outlines the process of designing a basic multi-location queue. In this example, we use two fleets: one Spot Instance fleet and one On-Demand Instance fleet. Each fleet has the following AWS Regions for placement locations: `us-east-1`, `us-east-2`, `ca-central-1`, and `us-west-2`.
**To create a basic multi-location queue with multi-location fleets**
1. Choose a location to create the queue in. You can minimize request latency by placing the queue in a location near where you deployed the client service. In this example, we create the queue in `us-east-1`.
1. Create a new queue and add your multi-location fleets as queue destinations. The destination order determines how Amazon GameLift Servers places game sessions. In this example, we list the Spot Instance fleet first and the On-Demand Instance fleet second.
1. Define the queue's game session placement priority order. This order determines where the queue searches first for an available game server. In this example, we use the default priority order.
1. Define the location order. If you don't define the location order, Amazon GameLift Servers uses the locations in alphabetical order.
![\[A console screenshot that illustrates the example queue's locations and destination order.\]](http://docs.aws.amazon.com/gameliftservers/latest/developerguide/images/queue-multi-location-1.png)
![\[A console screenshot that illustrates the example queue's placement priority and Location order.\]](http://docs.aws.amazon.com/gameliftservers/latest/developerguide/images/queue-multi-location-2.png)
# Evaluate queue metrics
Use metrics to evaluate how well your queues are performing. You can view metrics related to queues in the [Amazon GameLift Servers console](https://console.aws.amazon.com/gamelift) or in Amazon CloudWatch. For a list and descriptions of queue metrics, see [Amazon GameLift Servers metrics for queues](monitoring-cloudwatch.md#gamelift-metrics-queue).
Queue metrics can provide insight about the following:
+ **Overall queue performance** – Queue metrics indicate how successfully a queue responds to placement requests. These metrics can also help you identify when and why placements fail. For queues with manually scaled fleets, the `AverageWaitTime` and `QueueDepth` metrics can indicate when you should adjust capacity for a queue.
+ **FleetIQ algorithm performance** – For placement requests using the FleetIQ algorithm, metrics show how often the algorithm finds ideal game session placement. The placement may prioritize using resources with the lowest player latency or resources with the lowest cost. There are also error metrics that identify common reasons why Amazon GameLift Servers can't find an ideal placement. For more information about metrics, see [Monitor Amazon GameLift Servers with Amazon CloudWatch](monitoring-cloudwatch.md).
+ **Location specific placements** – For multi-location queues, metrics show successful placements by location. For queues that use the FleetIQ algorithm, this data provides useful insight into where player activity occurs.
When evaluating metrics for FleetIQ algorithm performance, consider the following tips:
+ To track the queue's rate of finding an ideal placement, use the `PlacementsSucceeded` metric in combination with the FleetIQ metrics for lowest latency and lowest price.
+ To boost a queue's rate of finding an ideal placement, review the following error metrics:
+ If the `FirstChoiceOutOfCapacity` is high, adjust capacity scaling for the queue's fleets.
+ If the `FirstChoiceNotViable` error metric is high, look at your Spot Instance fleets. Spot Instance fleets are considered not viable when the interruption rate for a particular instance type is too high. To resolve this issue, change the queue to use Spot Instance fleets with different instance types. We recommend that you include Spot Instance fleets with different instance types in each location.
# Prioritize game session placement
Amazon GameLift Servers uses an algorithm to determine how to prioritize a queue's destinations and determine where to place a new game session. The algorithm is based on an ordered set of criteria. You can use the default priority order, or you can customize the order. You can edit a queue's priority order at any time.
**Default priority order**
1. **Latency** – If the game session placement request includes location-specific latency data for players, Amazon GameLift Servers calculates the average player latency in each location and attempts to place a game session in a fleet location with the lowest average.
1. **Cost** – If a request doesn't include latency data, or if multiple fleets have equal latency, then Amazon GameLift Servers evaluates the hosting cost of each fleet. A fleet's hosting cost varies based on fleet type (Spot or On-Demand), instance type, and location.
1. **Destination** – If multiple fleets have equal latency and costs, then Amazon GameLift Servers prioritizes fleets based on the destination order as listed in the queue configuration.
1. **Location** – For queues with multi-location fleets, if all other criteria are equal, then Amazon GameLift Servers prioritizes the fleet's locations based on alphabetical order.
## Customize how a queue prioritizes game session placements
You can choose to customize how a queue prioritizes the placement criteria. The queue applies the custom prioritization to all game session placement requests that it receives.
**Note**
If you create a custom priority configuration and don't include all four criteria, Amazon GameLift Servers automatically appends any missing criteria in the default order.
**To customize a queue’s priority configuration**
Use the [Amazon GameLift Servers console](https://console.aws.amazon.com/gamelift/) or the AWS Command Line Interface (AWS CLI) to create a custom priority configuration.
------
#### [ Console ]
In the [Amazon GameLift Servers console](https://console.aws.amazon.com/gamelift/), you can customize a queue's priorities when creating a new queue or updating an existing queue. Select an AWS Region to work in.
Open the console’s left navigation bar and choose **Queues**. On the Queues page, select an existing queue and choose **Edit**.
1. Go to the section **Game session placement priority**. Drag and drop each priority criteria to create the order you want.
1. Go to the section **Location order**. Add any locations that you want to prioritize. This list is useful when the queue has fleets with multiple locations. At a minimum, you must specify one location. The locations you specify here are prioritized first, followed by all other locations in the queue's destinations.
1. Choose **Save changes**.
------
#### [ AWS CLI ]
Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/gamelift/update-game-session-queue.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/gamelift/update-game-session-queue.html) command with the `--priority-configuration` option to customize a queue's priority order. Amazon GameLift Servers updates a queue in your current default AWS Region, or you can add a `--region` tag to specify a different AWS Region.
The following example request adds or updates the priority configuration for a specified queue
```
aws gamelift update-game-session-queue \
--name "example-queue-with-priority"
--priority-configuration PriorityOrder="COST','LOCATION","DESTINATION",LocationOrder="us-east-1","us-east-2","ca-central-1","us-west-2" \
```
------
## Prioritize placements by player latency
If you want to give your players the best possible player experience and ensure minimal latency, take the following steps when setting up your game session placement system:
+ Set your queue to prioritize latency when choosing where to place game sessions. Latency is at the top of the priority list by default. You can also customize your queue's priority configuration and choose where to put latency in priority order.
+ Set up player latency policies for your queue. Latency policies let you set hard limits on the amount of latency to allow in a game session placement. If Amazon GameLift Servers can't place a game session without exceeding the limits, the placement request will time out and fail. You can set up a single latency policy, or you can create a series of policies that gradually relax the latency limit over time. With a series of policies, you can specify very low initial latency limits, and still accommodate players with higher latencies after a short delay. For details on creating latency policies, see [Create a player latency policy](queues-design-latency.md).
+ When making game session placement requests (see [StartGameSessionPlacement](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_StartGameSessionPlacement.html)), include latency data for each player. Player latency data includes a value for every possible location where a game session might be placed. For example, for a queue that places game sessions in AWS Regions us-east-2 and ca-central-1, latency data might look like this:
```
"PlayerLatencies": [
{ "LatencyInMilliseconds": 100, "PlayerId": "player1", "RegionIdentifier": "us-east-2" },
{ "LatencyInMilliseconds": 100, "PlayerId": "player1", "RegionIdentifier": "ca-central-1" },
{ "LatencyInMilliseconds": 150, "PlayerId": "player2", "RegionIdentifier": "us-east-2" },
{ "LatencyInMilliseconds": 150, "PlayerId": "player2", "RegionIdentifier": "ca-central-1" }
]
```
To obtain accurate latency measurements, use Amazon GameLift Servers's UDP ping beacons. These endpoints enable you to measure actual UDP network latency between player devices and each of the potential hosting locations, resulting in more accurate placement decisions than using ICMP pings. For more information on using UDP ping beacons to measure latency, refer to [UDP ping beacons](reference-udp-ping-beacons.md).
## Prioritize placements by location
You can configure a queue to make game session placements based on a prioritized list of geographic locations. Location is one of the criteria that determines how a queue chooses where to place a new game session. By default, location is prioritized fourth, after latency, cost, and destination.
For game session placement, destination and location have somewhat different meanings:
+ *Destination* refers to a specific fleet and includes all the fleet's hosting resources, wherever they're deployed. When prioritizing by destination, Amazon GameLift Servers might make a placement with any location in the fleet. Multi-location managed fleets and Anywhere fleets can have hosting resources that are deployed to one or more locations.
+ *Location* refers to a specific geographic position where a fleet's hosting resources are deployed. A fleet can have multiple locations, which might include AWS Regions, Local Zones, or custom locations (for an Anywhere fleet). A single-location managed fleet has one location and it is always an AWS Region. A multi-location managed fleet has a home Region and can have remote locations. An Anywhere fleet has one or more custom locations.
When prioritizing placements by location, Amazon GameLift Servers looks for any queue destinations that include the priority location and searches them for an available hosting resource. If there are multiple destinations with the priority location, Amazon GameLift Servers moves on to the next priority criteria (cost, latency, destination).
There are several ways that you can influence how a queue's locations are prioritized
+ Configure how the queue handles all game session placement requests:
+ **Add a priority configuration to the queue.** A queue's priority configuration includes an ordered list of locations. You can specify one or more locations to prioritize. This list doesn't exclude any locations, it simply tells Amazon GameLift Servers where to look first for an available hosting resource. A common use for an ordered location list is when you want to funnel most traffic to one or more specific geographic locations and use additional locations as backup capacity. Add a priority configuration by calling [UpdateGameSessionQueue](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_UpdateGameSessionQueue.html).
+ **Add a filter configuration to the queue.** A filter configuration is an allow list for the queue. It tells Amazon GameLift Servers to ignore any locations that aren't on the list when looking for an available hosting resource. There are two common uses for a filter configuration. First, for fleets with multiple locations, you might use a filter to exclude some of the fleet's locations. Second, you might want to temporarily disallow placements on a certain location; for example, a location might be experiencing transitory issues. Because you can update a queue's filter configuration at any time, you can easily add and remove locations as needed. Add a filter configuration by calling [UpdateGameSessionQueue](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_UpdateGameSessionQueue.html).
+ Use special instructions for individual placement requests:
+ **Include a priority override list in a game session placement request.** You can provide an alternate priority list of locations with any [StartGameSessionPlacement](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_StartGameSessionPlacement.html) request. This list effectively replaces the queue's configured prioritization for locations for that one request only. It doesn't impact any other requests. This override feature has a few requirements:
+ Use an override list only with a queue that has a priority configuration in place with `LOCATION` as the first priority.
+ Don't include player latency data in the same placement request. Including latency data sets up conflicts when prioritizing locations that Amazon GameLift Servers can't resolve.
+ Decide how you want Amazon GameLift Servers to proceed if it can't find an available resource on the priority override list. Choose between falling back to the queue's other locations, or limit placements to the override list. By default, Amazon GameLift Servers falls back to attempt placement on the queue's other locations.
+ Update the queue's filter configuration as needed, such as adding locations on the override list. The override list doesn't invalidate the filter list.
# Create a player latency policy
If your placement requests include player latency data, Amazon GameLift Servers finds game sessions in locations with the lowest average latency for all players. Placing game sessions based on average player latency prevents Amazon GameLift Servers from placing most players in games with high latency. However, Amazon GameLift Servers still places players with extreme latency. To accommodate these players, create player latency policies.
A player latency policy prevents Amazon GameLift Servers from placing a requested game session anywhere that players in the request would experience latency over the maximum value. Player latency policies can also prevent Amazon GameLift Servers from matching game session requests with higher latency players.
**Tip**
To manage latency specific rules, such as requiring similar latency across all players in a group, you can use [Amazon GameLift Servers FlexMatch](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-intro.html) to create latency-based matchmaking rules.
For example, consider this queue with a 5-minute timeout and the following player latency policies:
1. Spend 120 seconds searching for a location where all player latencies are less than 50 milliseconds.
1. Spend 120 seconds searching for a location where all player latencies are less than 100 milliseconds.
1. Spend the remaining queue time until timeout searching for a location where all player latencies are less than 200 milliseconds.
![\[A console screen shot that illustrates the example latency policies that gradually relax.\]](http://docs.aws.amazon.com/gameliftservers/latest/developerguide/images/queue-latency-policy.png)
# Build a queue for Spot Instances
You can achieve of potentially significant savings in hosting costs by using Spot fleets. For more details about Spot fleets and how to use them, see [On-Demand Instances versus Spot Instances](gamelift-compute.md#gamelift-compute-spot).
If your game hosting solution includes Spot fleets, you must use a game session placement queue. Amazon GameLift Servers uses queues to search across multiple game hosting resources and select the best one available to host a new game session. With Spot fleets, queues are particularly important for minimizing hosting costs and avoiding possible Spot interruptions. This topic helps you set up a resilient queue that can continue to host games for players even in the event of interruptions, slowdowns and outages. You can customize how the queue prioritizes available hosting resources based on several factors including hosting cost.
Are you using FlexMatch for matchmaking? You can use a queue with Spot fleets to make game session placements for your matches.
## Implementation tasks for Spot fleets
When creating or updating your game hosting solution to use Spot fleets, complete the following tasks. For more detailed guidance on how to build a queue that optimizes Spot availability and resiliency, see [Reduce game hosting costs with Spot fleets](fleets-spot.md).
1. **Choose and create a set of fleet destinations for your game session queue.**
Start by deciding where you want your queue to place game sessions. A queue can search across multiple fleets to find the best possible placement. Each fleet has one instance type but can have multiple geographic locations. Queues with fleets that offer variety in both location and instance type are more likely to make successful placements. See these best practices for designing an effective and resilient Spot-optimized queue.
1. **Create your Spot-optimized game session queue.**
Create a queue and configure it for your Spot fleets. See [Create a game session queue](queues-creating.md) for help creating and configuring the new queue. You can use the Amazon GameLift Servers console or the AWS CLI to create or edit a queue.
+ Add the fleet destinations from Step 1.
+ Prioritize the destination order as appropriate. By default, Amazon GameLift Servers prioritizes by cost before destination, so destination order is used only when the lowest costs between destinations are equal.
+ If you want to prioritize game hosting cost before player latency, provide a custom placement priority. See [Prioritize game session placement](queues-design-priority.md).
1. **Update other components in your solution to use the new queue.**
When your solution uses a Spot-optimized queue to start new game sessions, the queue automatically avoids placing game sessions with fleets that have a high likelihood of interruption. It instead searches all viable fleets for resources that match your defined priorities, including player latency, hosting cost, and destination order.
+ If you're not using FlexMatch – Update your backend service to specify the new Spot-optimized queue in game session requests. The backend service makes API requests to Amazon GameLift Servers on behalf of your game client (using `StartGameSessionPlacement()`), and each request must specify a queue name. For help implementing game session placements in your game client, see [Create game sessions](gamelift-sdk-client-api.md#gamelift-sdk-client-api-create).
+ If you are using FlexMatch – Update your matchmaking configuration to send game session requests to the new Spot-optimized queue. When the matchmaking system forms a player match, it sends a game session placement request to the designated queue to start a new game session for the match. Only matchmaking configurations with FlexMatch mode set to "Managed" can designate a placement queue. You can update a matchmaking configuration using the AWS CLI or the Amazon GameLift Servers console (see [Edit a matchmaking configuration](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-create-configuration-edit.html)).
1. **Review the performance of your Spot fleets and queues.**
View Amazon GameLift Servers metrics in the Amazon GameLift Servers console or with Amazon CloudWatch to review performance. For more information about Amazon GameLift Servers metrics, see [Monitor Amazon GameLift Servers with Amazon CloudWatch](monitoring-cloudwatch.md). Key metrics include:
+ Interruption rate – Use the `InstanceInterruptions` and `GameSessionInterruptions` metrics to track the number and frequency of Spot-related interruptions for instances and game sessions. Game sessions on reclaimed instances have a status of `TERMINATED` and a status reason of `INTERRUPTED`.
+ Queue effectiveness – Track placement success rates, average wait time, and queue depth to confirm that Spot fleets don't impact your queue performance.
+ Fleet usage – Monitor data on instances, game sessions and player sessions. Usage for your On-Demand fleets can be an indicator that queues are avoiding placements into your Spot fleets to avoid disruption.
## Best practices for queues with Spot fleets
Use the following best practices when creating fleets and queues for Spot instances.
+ **Expand your queue's geographic coverage.** Even if your players are clustered in a single AWS Region, add adjacent locations to your Spot fleet. This approach improves the queue's ability to maintain capacity during regional slowdowns, outages, and Spot interruptions. Multi-location fleets work with both Spot and On-Demand instances.
+ **Diversify your queue's instance type coverage.** Amazon GameLift Servers evaluates Spot viability based on instance type, so having Spot fleets with a variety of instance types reduces the chance that multiple Spot fleets are nonviable at the same time. Include at least two Spot fleets with different instances types each location.
**Note**
Pricing is based on the instances you use, not the number of fleets. Running five fleets with 10 instances each is the same as running one fleet with 50 instances of similar cost. Pricing varies by instance type, size, and location.
Tips for grouping Spot instance types:
+ Use instance types in the same family, such as `m6g.medium`, `m6g.large`, and `m6g.xlarge`. Larger instance types cost more, but can also host more game sessions at a time.
+ Select widely available instances types. Typically, older generation families (such as C5, M5, and R5) and common sizes (such as .large, .xlarge, and .2xlarge) have better availability.
+ Check the 30-90 day pricing history in the Amazon GameLift Servers console. Look for instance types with consistent availability patterns.
+ Use the Amazon GameLift Servers console, fleet creation tool, to explore location coverage for instance types.
+ **Add On-Demand fleets for backup capacity.** Game hosting can switch to On-Demand fleets whenever Spot fleets are unavailable. Put at least one On-Demand fleet in each location to maintain low player latency. Add auto-scaling to your backup On-Demand fleets, so you can keep them scaled down until they're needed.
+ **Assign aliases to all fleet destinations.** Create aliases for each of your queue's destinations. Aliases make it easier and more efficient whenever you need to replace fleets.
+ **Apply a queue prioritization strategy.** You can customize how a queue prioritizes where to place game sessions (see [Prioritize game session placement](queues-design-priority.md) for more details). For Spot-optimized queues, prioritizing by cost ensures that low-cost Spot fleets are used whenever possible.
You can also prioritize certain fleets by specifying a destination order. For example, some users designate a set of primary fleets for regular use and also a set of secondary fleets as backup. In this scenario, set the queue's destination order to list the primary fleets first. Then configure the queue's priority order with destination followed by cost.