This Guidance helps developers implement near real-time multiplayer matchmaking through Amazon GameSparks and Amazon GameLift FlexMatch. It includes all the architecture and code required to configure and initiate Amazon GameLift FlexMatch matchmaking through GameSparks to group players together and to place grouped players into games hosted on pre-configured Amazon GameLift servers. Developers using Amazon GameLift FleetIQ can also use this Guidance to deploy a standalone matchmaker for their own game server integrations.

Architecture Diagram

Download the architecture diagram PDF 

Well-Architected Pillars

The AWS Well-Architected Framework helps you understand the pros and cons of the decisions you make when building systems in the cloud. The six pillars of the Framework allow you to learn architectural best practices for designing and operating reliable, secure, efficient, cost-effective, and sustainable systems. Using the AWS Well-Architected Tool, available at no charge in the AWS Management Console, you can review your workloads against these best practices by answering a set of questions for each pillar.

The architecture diagram above is an example of a Solution created with Well-Architected best practices in mind. To be fully Well-Architected, you should follow as many Well-Architected best practices as possible.

  • This Guidance is delivered as an AWS Cloud Development Kit (AWS CDK) app where you can make changes to the configurations as small, incremental iterations. We recommend capturing the following Amazon CloudWatch metrics to create feedback loops that will help you measure performance and error rate of GameSparks in this Guidance:

    • MessageReceived
    • MessageProcessingDuration
    • MessageProcessingError

    The DynamoDB capacity mode in this Guidance is set to “On-demand,” which is ideal for unpredictable workloads. For predictable workloads, you can optimize costs by changing to “Provisioned” capacity mode. You can also use the following CloudWatch metrics to monitor DynamoDB workloads: 

    • ConsumedWriteCapacityUnits
    • ConsuedReadCapacityUnits
    Read the Operational Excellence whitepaper 
  • The resources deployed by this Guidance are not exposed to the internet, and the public can only access them using the GameSparks game backend. Users can only access the administrative services through AWS Command Line Interface (CLI) or software development kits (SDKs), using Identity and Access Management (IAM) users or roles with the appropriate permissions. All stored data resides in DynamoDB and is encrypted using AWS-managed keys.

    Read the Security whitepaper 
  • Before you release a game to production based on this Guidance, submit the completed Amazon GameLift Launch Questionnaire, which you can find in the Amazon GameLift Console. Because Lambda is used within this Guidance, we recommend checking and adjusting the Lambda (reserved) concurrency for the Lambda functions deployed in your AWS account prior to your game receiving production traffic. The data stored within this Guidance is temporarily and automatically deleted through DynamoDB’s Time to Live (TTL) functionality, so resources for backup and recovery are not required.

    Read the Reliability whitepaper 
  • GameSparks and Amazon GameLift FlexMatch are purpose-built for game backends and matchmaking. For matchmaking, latency from the game client to the game backend is not a large concern. GameSparks game backends can be deployed to several AWS Regions. You should choose where to deploy your game backend based on where most of your players reside—by deploying closer to your players, you can reduce lag in gameplay.

    Read the Performance Efficiency whitepaper 
  • GameSparks, used extensively within this Guidance, includes pricing based on Client API calls, Cloud Code API calls, and player data storage, all of which are kept to a minimum. To keep cost of client API calls to a minimum, you should poll for matchmaking updates from the game client based on a rate that makes sense for your game's matchmaking speed, as infrequently as possible. 

    Read the Cost Optimization whitepaper 
  • All of the services in this Guidance, including GameSparks, Lambda, and DynamoDB, are managed services. Managed services shift responsibility for maintaining high-average utilization and sustainability optimization of the deployed hardware from the customer to AWS. Data moved between components are kept to minimum, lowering the environmental impact of this Guidance. 

    Read the Sustainability whitepaper 

Implementation Resources

The sample code is a starting point. It is industry validated, prescriptive but not definitive, and a peek under the hood to help you begin. 

AWS Architecture


This post demonstrates how...


The sample code; software libraries; command line tools; proofs of concept; templates; or other related technology (including any of the foregoing that are provided by our personnel) is provided to you as AWS Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS Content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS Content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.