SocketGate
API Gateway WebSockets for Blueprints and C++

Overview

SocketGate connects Unreal Engine 4.27 and 5.8 games to Amazon API Gateway WebSocket APIs (wss://<api-id>.execute-api.<region>.amazonaws.com/<stage>). It is useful for chat, lobbies, live events, notifications, turn-based play and anything else your backend pushes to players. The socket uses the engine's own WebSocket client; AWS signing and the management API use the bundled AWS SDK for C++. Every event arrives on the game thread.

• Socket Connection object: On Connected, On Message, On Closed, On Error, On Reconnecting; Send Text, Send Json Action, Close.
• $connect authorization: None, IAM (a presigned SigV4 URL from Cognito identity pool credentials) or Token (header or query parameter for a Lambda authorizer), plus extra headers and query parameters.
• Auto-reconnect with exponential back-off and jitter. Every attempt signs a fresh URL, because presigned URLs expire.
• Keep-alive: API Gateway closes connections after 10 minutes without traffic, so SocketGate sends a message whenever the client has been quiet.
• Send And Wait For Reply: request/response over the socket, matched by a generated requestId.
• Post To Connection, Get Connection, Delete Connection for dedicated servers and tools.

Requirements

Installation

1. Install SocketGate from Fab into your engine, or copy the SocketGate folder into your project's Plugins folder.
2. Enable SocketGate in Edit > Plugins and restart the editor.
3. Open Project Settings > Plugins > SocketGate and set Default WebSocket Url and Auth Mode. For IAM mode also set Region and Identity Pool Id.
4. C++ only: add PublicDependencyModuleNames.Add("SocketGate"); to your Build.cs.

Setting up AWS

1. The WebSocket API

1. In the API Gateway console create a WebSocket API with the route selection expression $request.body.action.
2. Add the routes $connect, $disconnect, $default and your own routes (for example sendmessage), usually with Lambda integrations.
3. Add a ping route with a Mock integration for the keep-alive message {"action":"ping"}, or let $default handle it.
4. Deploy to a stage (for example production). The stage page shows the WebSocket URL; copy it into Default WebSocket Url.

2. Protect $connect with IAM (recommended for game clients)

In the console open Routes > $connect > Route request and set Authorization to AWS_IAM, then deploy the API again. With the AWS CLI:

aws apigatewayv2 get-routes --api-id abc123
aws apigatewayv2 update-route --api-id abc123 --route-id r1s2t3 --authorization-type AWS_IAM
aws apigatewayv2 create-deployment --api-id abc123 --stage-name production

On WebSocket APIs, authorization only applies to $connect. Once a client is connected it can use every route.

3. The Cognito identity pool role

Create an Amazon Cognito identity pool. Enable guest access if players may connect before signing in, and add your identity providers. Then allow the pool's IAM role (authenticated and/or guest) to open connections to your API and nothing else:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "execute-api:Invoke",
    "Resource": "arn:aws:execute-api:us-east-1:123456789012:abc123/production/$connect"
  }]
}

Replace the region, account id (123456789012), API id (abc123) and stage with your own. Use abc123/*/$connect to allow every stage.

4. The server role (connection management)

Code that pushes messages to clients (your Lambda functions, or a dedicated server using Post To Connection) needs execute-api:ManageConnections:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "execute-api:ManageConnections",
    "Resource": "arn:aws:execute-api:us-east-1:123456789012:abc123/production/*/@connections/*"
  }]
}

The * after the stage covers POST (Post To Connection), GET (Get Connection) and DELETE (Delete Connection). Never give this permission to the players' identity pool role.

Quick start

1. Call Create Socket Connection (leave Url empty to use the settings) and promote the result to a variable.
2. From the variable, bind On Connected, On Message, On Closed and On Error, then call Connect.
3. In On Connected call Send Json Action with Route sendmessage and Payload Json {"text": "hi"}. This sends {"action":"sendmessage","text":"hi"}.
4. In On Message read the text, for example with Get JSON Field (Path text) or JSON To Struct.
5. Call Close when the player leaves.

Connection object

USocketGateConnection is a Blueprint type. Its options are copied from the project settings when it is created; change them on the object before calling Connect.

Options (read / write on the object)

Url, Auth Mode, Auth Token, Token Location, Token Header Name, Token Query Name, Headers, Query Parameters, Protocols, Signing Region, Presign Expiry Seconds, Connect Timeout Seconds, Auto Reconnect, Max Reconnect Attempts, Reconnect Base Delay Seconds, Reconnect Max Delay Seconds, Keep Alive Interval Seconds, Keep Alive Message, Route Field, Request Id Field. The Settings section explains each one.

Authorization

Signing runs on a background worker, because credentials may need a network round trip. The socket itself is created and used on the game thread. URLs are presigned for Presign Expiry Seconds (default 300). Once a connection is open it no longer needs the URL; API Gateway keeps connections open for up to 2 hours.

Reconnect & keep-alive

• Auto Reconnect (default on) reacts to failed attempts and to connections the server or network dropped. It does not reconnect after you call Close, or after a normal close (1000) from the server, for example Delete Connection.
• The delay starts at Reconnect Base Delay Seconds (1 s) and doubles with every attempt up to Reconnect Max Delay Seconds (30 s), with plus or minus 20% jitter so clients do not reconnect all at once. A successful connection resets the count.
• After Max Reconnect Attempts failed attempts in a row (default 10, 0 = never give up) On Error fires with ReconnectFailed and the state becomes Not Connected.
• Every IAM attempt signs a new URL, so expired signatures and refreshed Cognito credentials are handled for you. API Gateway ends every connection after 2 hours; the reconnect brings it back.
• Keep-alive: when the client has sent nothing for Keep Alive Interval Seconds (default 300, 0 = off), it sends Keep Alive Message (default {"action":"ping"}). API Gateway closes connections that are idle for 10 minutes.
• The handshake times out after Socket Connect Timeout Seconds (default 15) and counts as a failed attempt.

Request / reply

Send And Wait For Reply (Connection, Route, Payload Json, Timeout Seconds, Request Id Field Name) sends {"action": Route, "requestId": "<32 hex digits>", ...}. It fires On Reply (Reply = the whole message) when a message with the same top-level requestId string arrives. Otherwise it fires On Timeout after the timeout (0 = Default Reply Timeout Seconds), or On Failure if the connection is not open or closes while waiting. You can stop waiting with Cancel.

Your backend only has to echo the id. In a Lambda integration (Node.js):

import { ApiGatewayManagementApiClient, PostToConnectionCommand } from "@aws-sdk/client-apigatewaymanagementapi";

export const handler = async (event) => {
  const { domainName, stage, connectionId } = event.requestContext;
  const body = JSON.parse(event.body);
  const api = new ApiGatewayManagementApiClient({ endpoint: `https://${domainName}/${stage}` });
  await api.send(new PostToConnectionCommand({
    ConnectionId: connectionId,
    Data: JSON.stringify({ requestId: body.requestId, score: 1200 })
  }));
  return { statusCode: 200 };
};

Another way: give the route a route response. API Gateway then sends the integration's response body straight back to the client.

Server side: connection management

Dedicated servers and tools with IAM credentials (Static Keys or the Default Credential Chain, with the server role above) can push to clients and manage them through the API Gateway management API. The connection id is $context.connectionId / event.requestContext.connectionId in your route integrations.

Endpoint is https://<api-id>.execute-api.<region>.amazonaws.com/<stage>. When it is empty, SocketGate uses Default Management Endpoint, and if that is empty too it uses Default WebSocket Url with wss:// changed to https://. The signing region comes from the host name.

Functions

Credentials

Credentials are only needed for IAM mode and for the management nodes. None and Token modes do not use AWS credentials at all.

C++ API

// Build.cs: PublicDependencyModuleNames.Add("SocketGate");
#include "SocketGateConnection.h"
#include "SocketGateLibrary.h"

// UPROPERTY() USocketGateConnection* Connection;
Connection = USocketGateLibrary::CreateSocketConnection(this, FString());
Connection->AuthMode = ESocketGateAuthMode::Iam;
Connection->OnConnected.AddDynamic(this, &AMyActor::HandleConnected);   // UFUNCTION() void HandleConnected();
Connection->OnMessage.AddDynamic(this, &AMyActor::HandleMessage);       // UFUNCTION() void HandleMessage(const FString& Message);
Connection->Connect();

void AMyActor::HandleConnected()
{
    Connection->SendJsonAction(TEXT("sendmessage"), TEXT("{\"text\":\"hi\"}"));
}

The latent node classes (USocketGateReplyAction, USocketGateManageAction, USocketGateIdentityAction) can also be created from C++ through their static factory functions; bind the delegates, then call Activate().

Types

Settings

Project Settings > Plugins > SocketGate (saved to DefaultGame.ini). WebSocket, reconnect, keep-alive and reply options are copied into each connection when it is created.

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 and verified warning-free for Unreal Engine 4.27 and 5.8.