Dynamic Content Engineering Details

This topic provides programmatic details about the dynamic content update process. This includes manifest file information, Dynamic Content Cloud Gem EBus events, and Dynamic Content Cloud Gem service API. For information about the lmbr_aws CLI extensions enabled by the Dynamic Content Cloud Gem, see Using the Dynamic Content Command Line.

Manifest File

In your Lumberyard installation, the default location of the manifest file is <GameFolder>/AWS/DynamicContent/DynamicContentManifest.json.

The following is a simple example manifest for the SamplesProject DontDie sample.

"Files": [
{
"hash": "3bebdb5bdb8cff74642e5f7f3dc4e900", 
"outputRoot": "@user@", 
"bucketPrefix": "static-data", 
"keyName": "gameproperties.csv", 
"cacheRoot": "@assets@", 
"platformType": "", 
"localFolder": "staticdata/csv"
}
]

The following table describes the properties in the manifest file.

EBus Events

The Dynamic Content Cloud Gem provides an EBus API and includes calls exposed to Lua. The basic top-level update request looks like this:

CloudCanvas::DynamicContent::DynamicContentRequestBus::BroadcastResult(
      requestSuccess,
      &CloudCanvas::DynamicContent::DynamicContentRequestBus::Events::RequestManifest, 
      manifestName)

requestSuccess (bool) – Specifies whether the request was successfully sent.

manifestName (char*) – Name of the manifest file (for example, DynamicContentTest.json). The system handles .pak file and operating system naming conventions (for example, DynamicContentTest.shared.pak).

Requesting pak files without using manifest
Use the following API calls to request pak files without using a manifest:

CloudCanvas::DynamicContent::DynamicContentRequestBus::BroadcastResult(
      requestSuccess, 
      &CloudCanvas::DynamicContent::DynamicContentRequestBus::Events::UpdateFileStatusList, 
      uploadRequests, 
      autoDownload);

requestSuccess (bool) – Specifies whether the request was successfully sent.

uploadRequests (AZStd::vector<AZStd::string>) – List of bucket keys.

autoDownload (bool) – Specify true to download files automatically.

CloudCanvas::DynamicContent::DynamicContentRequestBus::BroadcastResult(
      requestSuccess, 
      &CloudCanvas::DynamicContent::DynamicContentRequestBus::Events::UpdateFileStatus, 
      fileName, 
      autoDownload);

requestSuccess (bool) – Specifies whether the request was successfully sent.

fileName (char*) – Name of the pak file to request.

autoDownload (bool) – Specify true to download files automatically.

Versioning Support

Requesting pak files using versioned manifest
Use the following API calls to request pak files using a manifest when versioning is enabled:

CloudCanvas::DynamicContent::DynamicContentRequestBus::BroadcastResult(
      requestSuccess, 
      &CloudCanvas::DynamicContent::DynamicContentRequestBus::Events::RequestVersionedManifest, 
      manifestName, 
      versionId);

requestSuccess (bool) – Specifies whether the request was successfully sent.

manifestName (char*) – Name of the manifest file (for example, DynamicContentTest.json). The system handles .pak file and operating system naming conventions (for example, DynamicContentTest.shared.pak).

versionId (char*) – Version ID of the manifest. Uses the current active (public) version if not specified.

CloudCanvas::DynamicContent::DynamicContentRequestBus::BroadcastResult(
      requestSuccess, 
      &CloudCanvas::DynamicContent::DynamicContentRequestBus::Events::RequestVersionedFileStatus, 
      fileName, 
      outputFile, 
      versionId);

requestSuccess (bool) – Specifies whether the request was successfully sent.

fileName (char*) – Name of the pak file to request.

outputFile (char*) – Name of the output pak file.

versionId (char*) – Version ID of the file. Uses the current active (public) version if not specified.

Requesting pak files without using manifest
Use the following API calls to request files without using a manifest when versioning is enabled:

CloudCanvas::DynamicContent::DynamicContentRequestBus::BroadcastResult(
      requestSuccess, 
      &CloudCanvas::DynamicContent::DynamicContentRequestBus::Events::UpdateVersionedFileStatusList, 
      requestMap, 
      autoDownload);

requestSuccess (bool) – Specifies whether the request was successfully sent.

requestMap (AZStd::unordered_map<AZStd::string, AZStd::string>) – Map of file names to file version IDs.

autoDownload (bool) – Specify true to download files automatically.

CloudCanvas::DynamicContent::DynamicContentRequestBus::BroadcastResult(
      requestSuccess, 
      &CloudCanvas::DynamicContent::DynamicContentRequestBus::Events::UpdateVersionedFileStatus, 
      fileName, 
      autoDownload, 
      versionId);

requestSuccess (bool) – Specifies whether the request was successfully sent.

fileName (char*) – Name of the pak file to request.

autoDownload (bool) – Specify true to download files automatically.

versionId (char*) – Version ID of the file. Uses the current active (public) version if not specified.

Manifest Received

The following EBus events are triggered when a manifest has been received successfully or unsuccessfully.

Success

EBUS_EVENT(CloudCanvas::DynamicContent::DynamicContentRequestBus, ManifestUpdated, bucketName, bucketPrefix)

When all .pak files are complete, a RequestCompleted event is broadcast.

Failure

EBUS_EVENT(CloudCanvas::DynamicContent::DynamicContentRequestBus, ManifestFailed, bucketName, bucketPrefix, errorStr)

Service API

The Dynamic Content Cloud Gem exposes API calls through Amazon API Gateway for both the Cloud Gem Portal and the game client.

The following tables list the calls for the portal.

The following table lists the calls for the client.

Using Amazon CloudFront

Amazon CloudFront is a fast content delivery network (CDN) service that can extend S3 to securely deliver data to customers with low latency and high transfer speeds at an additional cost. You can take advantage of it when using the DynamicContent gem. To learn more about Amazon CloudFront, read the Amazon CloudFront documentation .

Enable the CloudFront extension

To enable the Amazon CloudFront feature, add deployment tag content-distribution when you create a deployment with CloudGemDynamicContent enabled:

lmbr_aws deployment create --deployment {deployment_name} --tags content-distribution

To learn how to create a project stack and deployment stack using CloudCanvas command line, read Using the Cloud Canvas Command Line .

Using this deployment tag will add a few more AWS resources to your deployment stack including a Amazon CloudFront distribution and an S3 bucket. All of the signed URLs from the DynamicContent gem will be created using Amazon CloudFront automatically after the feature is enabled.

Create and upload CloudFront key pairs

Each AWS account that you use to create Amazon CloudFront signed URLs or signed cookies—your trusted signers—must have its own Amazon CloudFront key pair, and the key pair must be active. This is required for using Amazon CloudFront with the DynamicContent gem. Read the AWS document Creating Amazon CloudFront Key Pairs for Your Trusted Signers to learn how to create your own key pairs.

Note that IAM users can’t create Amazon CloudFront key pairs. You must log in using root credentials to create key pairs. To learn more about the root credentials, read The AWS Account Root User .

After you have created and downloaded the key pairs, upload your private key using the following CLI command:

lmbr_aws dynamic-content upload-cf-key --key-path {path_to_private_key} --deployment-name {deployment_to_use}

The expected name format for your private key is pk-<accountkey>.pem. Your key will be securely stored in an S3 bucket called AccessBucket.

Invalidate files from CloudFront edge caches

By default, Amazon CloudFront caches a response from Amazon S3 for 24 hours. If your request lands at an edge location that served the Amazon S3 response within 24 hours, Amazon CloudFront uses the cached response even if you updated the content in Amazon S3. In this case, you may get outdated content after uploading the same named files.

When updating your content you can invalidate the cache for files being update by adding the --invalidate-existing-files argument to your CLI command:

lmbr_aws dynamic-content upload-manifest-content --manifest-path {path_to_manifest} --deployment-name {deployment_to_use} --staging-status {staging_status} --invalidate-existing-files

You can also invalidate the cached response for a specific file using the following CLI command:

lmbr_aws dynamic-content invalidate-file --file-path {file_name_in_s3_bucket} --caller-reference {unique_identity}

--caller-reference requires a value that you specify to uniquely identify an invalidation request. Amazon CloudFront uses the value to prevent you from accidentally resubmitting an identical request. If you make a second invalidation request with the same value for caller reference, and if the rest of the request is the same, Amazon CloudFront doesn’t create a new invalidation request.