DynamoLedger
Amazon DynamoDB for Blueprints and C++

Overview

DynamoLedger stores your game's player data in Amazon DynamoDB straight from Unreal Engine 4.27 and 5.8, with no web layer in between. Items go in and come out as plain JSON strings, so Blueprint structs map to items with Struct To JSON and JSON To Struct. Requests run on background worker threads with automatic retries; every result arrives on the game thread.

• Put Item, Get Item, Update Item and Delete Item with condition expressions and a dedicated On Condition Failed pin.
• Query and Scan with paging, filters, secondary indexes and parallel scans.
• Batch Get and Batch Write for many items at once, with automatic retries of unprocessed entries.
• Transact Write: all-or-nothing purchases and trades, with readable cancellation reasons.
• Increment Counter for atomic currencies and stats, Get Top Scores for leaderboards.
• {IdentityId} in any JSON value is replaced with the player's Cognito identity id, so each player can be limited to their own items with dynamodb:LeadingKeys.

Requirements

Installation

1. Install DynamoLedger from Fab into your engine, or copy the DynamoLedger folder into your project's Plugins folder.
2. Enable DynamoLedger in Edit > Plugins and restart the editor.
3. Open Project Settings > Plugins > DynamoLedger and set Region, Identity Pool Id and, optionally, Table Prefix.
4. C++ only: add PublicDependencyModuleNames.Add("DynamoLedger"); to your Build.cs.

Setting up AWS

1. Tables

Create the tables in the DynamoDB console (on-demand capacity is the simplest start). The example below keeps every player's data under their identity id and adds a leaderboard index:

Table mygame-prod-players   (on-demand capacity)
  pk  String  partition key   = the player's identity id ({IdentityId})
  sk  String  sort key        = "profile", "inventory", "item#sword-01", ...

Table mygame-prod-scores    (on-demand capacity)
  pk     String  partition key = {IdentityId}
  sk     String  sort key      = the board, for example "global" or "level-3"
  board  String                = the board again (index partition key)
  score  Number                = the player's best score (index sort key)
  name   String                = display name shown on the board

Global secondary index board-score-index on mygame-prod-scores
  partition key board (String), sort key score (Number), projection ALL

2. Identity pool

In Amazon Cognito create an identity pool. Enable guest access if players may save before signing in, and add your identity providers (for example a Cognito user pool).

3. Role policy

Attach this policy to the role the pool gives to players (authenticated and/or guest). The dynamodb:LeadingKeys condition only allows items whose partition key is the caller's own identity id, which is exactly what {IdentityId} produces. The second statement lets everyone read the leaderboard index.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OwnItemsOnly",
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem", "dynamodb:BatchGetItem", "dynamodb:Query",
        "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem",
        "dynamodb:BatchWriteItem", "dynamodb:ConditionCheckItem"
      ],
      "Resource": [
        "arn:aws:dynamodb:us-east-1:123456789012:table/mygame-prod-players",
        "arn:aws:dynamodb:us-east-1:123456789012:table/mygame-prod-scores"
      ],
      "Condition": {
        "ForAllValues:StringEquals": {
          "dynamodb:LeadingKeys": ["${cognito-identity.amazonaws.com:sub}"]
        }
      }
    },
    {
      "Sid": "ReadLeaderboards",
      "Effect": "Allow",
      "Action": "dynamodb:Query",
      "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/mygame-prod-scores/index/board-score-index"
    }
  ]
}

Quick start

With Table Prefix mygame-prod-, the nodes below use the tables from Setting up AWS:

Resolve Identity
  -> Get Item     Table "players", Key JSON {"pk": "{IdentityId}", "sk": "profile"}
       On Not Found -> Put Item  Item JSON {"pk": "{IdentityId}", "sk": "profile", "gold": 100, "level": 1}
       On Success   -> JSON To Struct (Item JSON -> FPlayerProfile)

Update Item  Key JSON {"pk": "{IdentityId}", "sk": "profile"}
             Update Expression  SET gold = gold - :cost
             Values JSON        {":cost": 50}
             Condition          gold >= :cost       -> On Condition Failed = not enough gold

Increment Counter  Key JSON {"pk": "{IdentityId}", "sk": "profile"}, Attribute "wins", Delta 1

JSON and types

Every item, key and value is a JSON object string. Numbers keep their exact text (DynamoDB stores up to 38 digits); integers stay integers. Strings containing {IdentityId} are replaced with the player's identity id in items, keys, expression values and start keys.

Expression values are a JSON object of placeholders, for example {":cost": 50, ":tag": "rare"}, converted the same way. Expression names are {"#n": "name"}.

Latent nodes

All latent nodes run in the background, can be stopped with Cancel on their return value and fire exactly one final pin on the game thread. Table names get the settings' Table Prefix.

Functions

DynamoLedger has 26 Blueprint nodes: 12 latent nodes and 14 functions.

Transactions

Transact Write takes an array of operations. Each entry has one key — put, update, delete or check — with table, item or key, expression (update only), condition, values and names. Buying a sword only if the player has enough gold and does not own it yet:

[
  {"update": {"table": "players",
              "key": {"pk": "{IdentityId}", "sk": "profile"},
              "expression": "SET gold = gold - :price",
              "condition": "gold >= :price",
              "values": {":price": 250}}},
  {"put":    {"table": "players",
              "item": {"pk": "{IdentityId}", "sk": "item#sword-01", "power": 12},
              "condition": "attribute_not_exists(sk)"}}
]

If any condition fails nothing is written and On Failure fires with Error > Code TransactionCanceledException and a message such as #0 update mygame-prod-players: ConditionalCheckFailed - The conditional request failed. Pass a Client Token (for example a purchase id) to make retries safe: the same token within 10 minutes is applied once.

Leaderboards

Each player writes their own score item (allowed by the LeadingKeys policy); the board-score-index sorts all of them by score. The condition only replaces a lower score:

Put Item    Table "scores"
            Item JSON {"pk": "{IdentityId}", "sk": "global", "board": "global", "score": 1200, "name": "Ada"}
            Condition attribute_not_exists(score) OR score < :new
            Values JSON {":new": 1200}

Get Top Scores  Table "scores", Index Name "board-score-index",
                Partition Key Name "board", Partition Value "global", Count 10, Descending

Use Descending off for boards where lower is better (race times). For competitive boards, write scores from a dedicated server so clients cannot post arbitrary values.

Paging

Query and Scan return one page (up to Limit items, at most 1 MB). When Next Start Key JSON is not empty, call the node again with it as Start Key JSON to get the next page. Count is the number of items in this page after the filter.

Credentials

Signed-in players: for a Cognito user pool call Set Login Token with Provider = Make User Pool Provider Name and Token = the ID token. Other providers use their pool login keys (accounts.google.com, appleid.apple.com, graph.facebook.com).

C++ API

Every latent node is a class with a static factory function. Create it, bind its delegates and call Activate():

// Build.cs: PublicDependencyModuleNames.Add("DynamoLedger");
#include "DynamoLedgerAsyncActions.h"

UDynamoLedgerGetItemAction* Node = UDynamoLedgerGetItemAction::GetItem(this, TEXT("players"),
    TEXT("{\"pk\": \"{IdentityId}\", \"sk\": \"profile\"}"), FString(), false, FString());
Node->OnSuccess.AddDynamic(this, &AMyActor::OnProfile);     // (const FString& ItemJson, const FDynamoLedgerError& Error)
Node->OnNotFound.AddDynamic(this, &AMyActor::OnNoProfile);
Node->OnFailure.AddDynamic(this, &AMyActor::OnProfileError);
Node->Activate();                                          // runs on a worker, pins fire on the game thread

Types

Settings

Project Settings > Plugins > DynamoLedger (saved to DefaultGame.ini). Changes apply to the next request.

Troubleshooting

Credits

© 2026 Alpha XP — alphaxp.net · Support: support@alphaxp.net. Includes the AWS SDK for C++ and the AWS Common Runtime (Apache License 2.0). Made for Unreal Engine 4.27 and 5.8.