MultiplayerStack
Accounts, profiles and matchmaking on AWS

Overview

MultiplayerStack covers the same features as the Alpha XP plugins CognitoPass, DynamoLedger and GameLiftMatch in a single plugin with one shared AWS connection, one set of credentials and one settings page — plus combined nodes that connect the three areas. It can be installed next to those plugins: every module, class and setting has its own name.

• Player (combined): Sign In And Connect signs the player in to the user pool, gets identity-pool credentials for the DynamoDB and GameLift calls and creates or loads the player profile — in one node. Restore Session And Connect, Connect Player, Sign Out Everywhere, Get Player Id, Get Player Name.
• Profile (combined): one DynamoDB item per player keyed by the player id, with rating, wins / losses / draws, numeric stats and text fields. Ensure / Load / Save Player Profile, Update Player Stats (atomic), Get Leaderboard, Record Match Result with an Elo rating update and the pure Calculate Elo.
• Matchmake (combined): Matchmake With Profile sends the player's rating and region latencies to FlexMatch; Find Match And Travel also travels to the server; Cancel Matchmaking.
• Login: Amazon Cognito user pools — sign-up, sign-in with challenges and MFA, authenticator apps, password reset, attributes, remembered sessions with automatic refresh, AWS credentials.
• Data: Amazon DynamoDB with plain JSON — items, queries, scans, batches, transactions, atomic counters, leaderboards, {IdentityId} tokens.
• Match: Amazon GameLift for the game client — FlexMatch, queue placement, session search and creation, region latencies, connect URLs.
• MultiplayerStack Subsystem events: On Signed In, On Signed Out, On Session Refreshed, On Profile Loaded, On Match Found, On Matchmaking Failed.

Requirements

Installation

1. Install MultiplayerStack from Fab into your engine, or copy the MultiplayerStack folder into your project's Plugins folder.
2. Enable MultiplayerStack in Edit > Plugins and restart the editor.
3. Open Project Settings > Plugins > MultiplayerStack and set User Pool Id, App Client Id, Identity Pool Id, Profile Table and Default Matchmaking Configuration. Region can stay empty (it is read from the user pool id).
4. C++ only: add PublicDependencyModuleNames.Add("MultiplayerStack"); to your Build.cs.

Setting up AWS

1. User pool

In Amazon Cognito create a user pool and an app client with the ALLOW_USER_PASSWORD_AUTH and ALLOW_REFRESH_TOKEN_AUTH flows (preferably without a client secret). Copy the pool id (for example us-east-1_AbCdEf123) and the client id into the Login settings.

2. Identity pool

Create an identity pool and add the user pool as an identity provider (user pool id + app client id). Enable guest access if players may play before signing in. Signed-in players are registered with the pool automatically; their identity id is the player id of every area.

3. Profile table

Table mygame-prod-players       (on-demand capacity)
  PlayerId  String  partition key   = the player id (Cognito identity id)

Global secondary index Rating-index    (one per stat you rank by: Wins-index, xp-index ...)
  partition key  Board   (String)      every profile has Board = "global"
  sort key       Rating  (Number)
  projection     INCLUDE PlayerName (or ALL)

Set Profile Table to players and Table Prefix to mygame-prod- (or the full name with an empty prefix). The key name, the leaderboard partition attribute and the index name pattern are settings.

4. Matchmaking

Upload your dedicated server, create a fleet (and an alias), a game session queue, a FlexMatch rule set and a matchmaking configuration. For Matchmake With Profile the rule set needs a Number attribute named like Rating Attribute Name (default skill), for example:

"playerAttributes": [{ "name": "skill", "type": "number", "default": 1000 }],
"rules": [{ "name": "FairSkill", "type": "distance", "measurements": ["avg(teams[*].players.attributes[skill])"],
            "referenceValue": "avg(flatten(teams[*].players.attributes[skill]))", "maxDistance": 200 }]

5. Role policy

Attach this policy to the role the identity pool gives to players (authenticated and/or guest). The first statement only allows the player's own profile item (the partition key must be the caller's identity id), the second lets everyone read the leaderboard indexes, the third allows the GameLift client actions.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OwnProfileOnly",
      "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",
      "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-players/index/*"
    },
    {
      "Sid": "Matchmaking",
      "Effect": "Allow",
      "Action": [
        "gamelift:StartMatchmaking", "gamelift:DescribeMatchmaking",
        "gamelift:StopMatchmaking", "gamelift:AcceptMatch",
        "gamelift:StartGameSessionPlacement", "gamelift:DescribeGameSessionPlacement",
        "gamelift:StopGameSessionPlacement", "gamelift:SearchGameSessions",
        "gamelift:DescribeGameSessions", "gamelift:CreateGameSession",
        "gamelift:CreatePlayerSession"
      ],
      "Resource": "*"
    }
  ]
}

Remove the actions your game does not call (FlexMatch games only need the first four GameLift actions). User-pool calls (sign-in, sign-up, MFA, attributes) need no IAM permissions: they are authenticated by the app client and the player's tokens.

Quick start

Sign in, profile, match

1. Main menu: call Restore Session And Connect. On Success = the returning player is signed in and Profile is loaded; On Failure with NoSavedSession = show the login screen.
2. Login screen: Sign In And Connect with user name and password. On Challenge (MFA code, new password): answer with Respond To Challenge, then call Connect Player. New players use Sign Up / Confirm Sign Up first.
3. Show Get Player Name and Profile > Rating; bind UI to the subsystem's On Profile Loaded so it updates by itself.
4. Play button: Find Match And Travel (Configuration Name empty = the settings default). The player's Rating goes to FlexMatch, latencies are measured, and when the match is ready the player travels to host:port?PlayerSessionId=.... On Requires Acceptance: call Accept Match with Ticket.TicketId. A Cancel button calls Cancel Matchmaking on the subsystem.
5. After the match: Record Match Result (Win / Loss / Draw, the opponent's rating) and Update Player Stats (for example kills = 12, xp = 300).
6. Leaderboard screen: Get Leaderboard (Stat Rating, Count 10) → rows with Rank, Player Name, Score and Is Local Player.
7. Settings menu: Sign Out Everywhere.

Your dedicated server must validate each player: read PlayerSessionId from the login options and accept it through GameLift's server-side AcceptPlayerSession call, rejecting the login when that fails.

Player profiles

A profile is one item in the Profile Table, keyed by the player id (the Cognito identity id). Fixed attributes: PlayerName, Rating, Wins, Losses, Draws, MatchesPlayed, CreatedAt, UpdatedAt (ISO-8601 UTC) and the leaderboard partition attribute (Board = "global"). Every other number attribute appears in Stats, every other text attribute in Attributes; the whole item is in Item JSON, so the Data nodes work on the same item too.

{ "PlayerId": "us-east-1:7a3c...", "PlayerName": "Ada", "Rating": 1016.4, "Wins": 3, "Losses": 1, "Draws": 0,
  "MatchesPlayed": 4, "Board": "global", "kills": 41, "xp": 1200, "avatar": "fox",
  "CreatedAt": "2026-10-29T18:02:11.000Z", "UpdatedAt": "2026-10-29T19:40:03.000Z" }

• New profiles get Default Rating (1000) and Default Stats. Ensure Player Profile uses a conditional write, so it is safe to call on every start.
• Update Player Stats is one atomic ADD; Record Match Result increments the counters atomically and writes the new rating only when the rating did not change since it was read (retried up to four times).
• Elo: Expected = 1 / (1 + 10^((Opponent - Player) / 400)), New = Player + K * (Score - Expected), Score 1 / 0.5 / 0, K = Elo K Factor (32). Ratings are rounded to 0.01 and never go below 0.
• Guest and signed-in players have different identity ids, so a guest's profile does not carry over to the account automatically.

Nodes: Player, Profile, Matchmake

The combined nodes. Latent nodes can be stopped with Cancel on their return value and fire exactly one final pin on the game thread.

Nodes: Config & Identity

Shared by all areas (one region, one set of credentials).

Nodes: Login (Amazon Cognito user pools)

Nodes: Data (Amazon DynamoDB)

Items are plain JSON; {IdentityId} inside any string value is replaced with the player id. Plain table names get the Table Prefix.

Nodes: Match (Amazon GameLift)

Subsystem events

Get Game Instance Subsystem > MultiplayerStack Subsystem, then bind:

Credentials

User-pool requests (the Login area) are always unsigned; the Data and Match areas and Get AWS Credentials use the mode above. All areas share one region, one worker pool and one SDK instance.

C++ API

// Build.cs: PublicDependencyModuleNames.Add("MultiplayerStack");
#include "MultiplayerStackGlueAsyncActions.h"

UMultiplayerStackSignInAndConnectAction* Connect = UMultiplayerStackSignInAndConnectAction::SignInAndConnect(this, User, Password);
Connect->OnSuccess.AddDynamic(this, &UMyLoginWidget::HandleConnected);   // (Session, Profile, Error)
Connect->OnFailure.AddDynamic(this, &UMyLoginWidget::HandleConnectFailed);
Connect->Activate();

UMultiplayerStackFindAndTravelAction* Play = UMultiplayerStackFindAndTravelAction::FindMatchAndTravel(this, nullptr, FString(), FString(),
    TMap<FString, FMultiplayerStackMatchAttribute>(), FMultiplayerStackMatchLatencyMap(), TMap<FString, FString>());
Play->OnFailed.AddDynamic(this, &UMyLobbyWidget::HandleNoMatch);
Play->Activate();

Every latent node class has a static factory with the node's inputs; bind the delegates, then call Activate(). Area headers: MultiplayerStackLoginAsyncActions.h, MultiplayerStackDataAsyncActions.h, MultiplayerStackMatchAsyncActions.h; libraries: MultiplayerStackLibrary.h, MultiplayerStackGlueLibrary.h, MultiplayerStackLoginLibrary.h, MultiplayerStackDataLibrary.h, MultiplayerStackMatchLibrary.h.

Types

Settings

Project Settings > Plugins > MultiplayerStack (saved to DefaultGame.ini, section [/Script/MultiplayerStack.MultiplayerStackSettings]). 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). Built for Unreal Engine 4.27 and 5.8.