User Guide (Version 1.13)

Getting Started with the Cloud Gem Framework

Lumberyard cloud gems make it easy to create cloud-connected functionality for your games. You can use the cloud gems included with Lumberyard, or use Lumberyard's Cloud Gem Framework to create your own cloud gems.

Cloud Gems

Cloud gems are Lumberyard gems that use Cloud Canvas Resource Manager (CCRM) to define AWS resources that support their operation. CCRM provides the infrastructure needed to create, configure, and access AWS resources. A cloud gem defines resources and implements the required operations to create a complete game subsystem.

Cloud gems use general purpose AWS features that operate in your AWS account. They are not game-specific services operated by Amazon. Cloud gems follow a serverless microservice architecture that makes use of AWS Lambda functions for computation, and Amazon DynamoDB, Amazon RDS, and Amazon S3 for data storage. However, a cloud gem can use any AWS service.

For example, a cloud gem could provide a leaderboard system that uses a DynamoDB table to store high scores. The gem could use an AWS Lambda function to validate submitted scores and allow fraudulent high scores to be deleted.

In this scenario, CCRM performs the following tasks:

  • Creates the DynamoDB table and Lambda function defined by the gem.

  • Enables the game client to invoke the API to submit a score.

  • Protects the integrity of the leaderboard by removing fraudulent scores automatically.

  • Permits the creation of a user interface that enables an authorized employee to remove fraudulent scores manually.

Cloud Gem Framework

The Cloud Gem Framework is a collection of tools and API operations that support the creation and operation of cloud gems.

The following diagram shows a high-level view of the Cloud Gem Framework architecture.

        Cloud Gem Framework architecture

The Cloud Gem Framework contains the following major components:

Creating a Cloud Gem

Lumberyard includes some cloud gems, such as leaderboards and dynamic content distribution, that provide full-featured services. You can use these gems in your games with a minimum of effort. Because the full source code for these cloud gems is included with Lumberyard, you can customize them or use them as examples for developing your own cloud gems.

You can easily create your own cloud gem by using the lmbr_aws cloud-gem create command.


  1. Ensure that the Cloud Gem Framework gem is enabled for your project. Do one of the following:

    • Use the Enabling Gems to enable the Cloud Gem Framework gem.


    • From the \dev\Tools\LmbrSetup\Win directory, type the following command. Replace <projectname> with the name of your project.

      lmbr gems enable <projectname> CloudGemFramework
  2. Ensure that your project's Cloud Gem Framework resources correspond to the latest version of the Cloud Gem Framework gem. From a command prompt window on the \dev directory, type the following command :

    lmbr_aws project update-framework-version
  3. If your cloud gem will use the Cloud Gem Framework Service API, do one of the following:

    • In Running Lumberyard Setup Assistant, choose Compile the game code


    • From a command prompt window on the \dev\Tools\LmbrSetup\Win directory, type the following command:

      lmbr capabilities enable compilegame

To create a cloud gem

  • From the \dev directory, type the lmbr_aws cloud-gem create command. Use the following syntax:

    lmbr_aws cloud-gem create --gem {gem-name} --initial-content {content-option} --enable

    The syntax options are as follows.

    • --gem {gem-name} – Specifies the name of the cloud gem.

    • --initial-content {content-option} – Specifies the starter content for the cloud gem. For a list of content options, see cloud-gem create.

    • --enable – Enables the cloud gem in your project.


    The following command example creates a cloud gem called MyCloudGem that is enabled in the current project and has Amazon API Gateway and AWS Lambda function resources.

    lmbr_aws cloud-gem create --gem MyCloudGem --initial-content api-lambda --enable

    Results of the Command

    Depending on the parameter that you choose for the --initial-content option, the cloud-gem create command can do much of the initial cloud gem code work for you. For example, choosing the api-lambda parameter creates the following resources locally:

    • A \dev\Gems\{gem-name}\vN\ gem.json file that declares a dependency on the Cloud Gem Framework.

    • A \dev\Gems\{gem-name}\vN\AWS directory that includes the following items:

      • A cgp-resource-code directory that contains skeleton resource code for your Cloud Gem Portal.

      • A lambda-code directory that contains skeleton ServiceLambda API code. ServiceLambda is an AWS Lambda function that implements your cloud gem's functionality.

      • A swagger.json file that describes the API for the cloud gem. For more information about the swagger.json file, see Cloud Gem Framework Service API.

      • A resource-template.json file that defines the initial resources for the cloud gem. In the api-lambda example, the resource-template.json file specifies the following:

        • ServiceApi, ServiceLambda, and ServiceLambdaConfiguration resources.

        • An output for the service API URL.

        • An AccessControl resource configured as described in Controlling Access to Resources.

    • A \dev\Gems\{gem-name}\vN\Code\ directory with skeleton code that was automatically generated from the swagger.json file. The Code directory contains generated Using the Waf Build System files and the following subdirectories:

      • \AWS\ServiceAPI\ – Contains {gem-name}ClientComponent.h and {gem-name}ClientComponent.cpp files. Use the skeleton code in these files to implement a Lumberyard component that you can use to invoke the cloud gem's service API operations from C++ or Lua.

      • \Include\{gem-name}\ – Contains a {gem-name}Bus.h EBus file.

      • \Source\ – Contains skeleton component, gem module and system component files.

      • \Tests\ – Contains a skeleton {gem-name}Test.cpp file

Developing your Cloud Gem

After you use the lmbr_aws cloud-gem create command, you can further develop your cloud gem by doing the following:

  • Add resource definitions that the cloud gem requires to the resource-template.json file. In Cloud Canvas Resource Manager, click Upload all resources to create and deploy the AWS resources that are defined in your resource-template.json file.

  • Implement the cloud gem's functionality by adding code to the lambda-code directory.

  • Add paths and operations to the swagger.json file that expose the functionality of your cloud gem. For more information, see Cloud Gem Framework Service API.

  • Use Lumberyard components, EBus, and other features to implement game client functionality for the gem. Place the code in the cloud gem's \dev\Gems\<gem-name>\vN\Code directory. You can use the generated service API client to access the functionality in the cloud gem's ServiceLambda Lambda function.