StepFlow
AWS Step Functions for Blueprints and C++

Overview

AWS Step Functions runs multi-step workflows — reward pipelines, match result processing, moderation, crafting queues, account deletion, AI chains — as state machines on AWS. StepFlow connects Unreal Engine 4.27 and 5.8 to it. Every request runs on a background worker thread with automatic retries; every result arrives back on the game thread.

• Start Execution, Run Execution (start + wait) and Wait For Execution with progress pins and a timeout.
• Start Sync Execution: Express workflows in one call, with output, error / cause and billed duration / memory.
• Describe, stop, list (status / redrive filters, paging) and redrive executions; full execution history with typed events, state timeline and error extraction.
• State machines: list, describe, create, update, delete, validate definitions on the service, versions and aliases.
• Activities and callbacks: the StepFlow Activity Worker component long-polls tasks in the background and answers them with Send Task Success / Failure, with automatic heartbeats; task tokens from waitForTaskToken integrations work too.
• Distributed Map runs: list, describe and update.
• ARN builders and parsers, execution name and trace header helpers, JSON helpers.

Requirements

Installation

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

Setting up AWS

1. Create your state machine in the Step Functions console (Standard for long, durable workflows; Express for short, high-volume ones you want to run synchronously). Note its ARN.
2. For an activity worker, create an activity (console or Create Activity) and use it in a Task state: "Resource": "arn:aws:states:us-east-1:123456789012:activity:CraftItem". Add "HeartbeatSeconds" if tasks may take long.
3. In Amazon Cognito create an identity pool (guest access if players may act before signing in, plus your identity providers).
4. Give the pool's player role only what the game needs. Least-privilege player policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RunGameWorkflows",
      "Effect": "Allow",
      "Action": ["states:StartExecution", "states:StartSyncExecution"],
      "Resource": "arn:aws:states:us-east-1:123456789012:stateMachine:mygame-*"
    },
    {
      "Sid": "FollowGameExecutions",
      "Effect": "Allow",
      "Action": ["states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution"],
      "Resource": "arn:aws:states:us-east-1:123456789012:execution:mygame-*:*"
    },
    {
      "Sid": "ActivityWorker",
      "Effect": "Allow",
      "Action": ["states:GetActivityTask"],
      "Resource": "arn:aws:states:us-east-1:123456789012:activity:mygame-*"
    },
    {
      "Sid": "AnswerTasks",
      "Effect": "Allow",
      "Action": ["states:SendTaskSuccess", "states:SendTaskFailure", "states:SendTaskHeartbeat"],
      "Resource": "*"
    }
  ]
}

Answers to callback (waitForTaskToken) tasks are not tied to an ARN, so the task-token actions usually need "Resource": "*"; if the game only answers activity tasks you can limit them to the activity ARNs. Only grant them to roles that really answer tasks (often a server role, not the guest role). For Express executions use the express: resource type in the execution ARN (...:express:mygame-*:*:*).

Admin nodes (Create / Update / Delete State Machine, Publish State Machine Version, Create / Delete Activity, Update Map Run, Redrive Execution, List State Machines / Activities, Validate State Machine Definition) need states:CreateStateMachine, states:UpdateStateMachine, states:DeleteStateMachine, states:PublishStateMachineVersion, states:CreateActivity, states:DeleteActivity, states:UpdateMapRun, states:RedriveExecution, states:List*, states:Describe*, states:ValidateStateMachineDefinition and iam:PassRole on the workflow role. Use them in tools, editor utilities and dedicated servers — not in player roles.

Quick start

Run a workflow and use its result

1. Build the input: Make JSON Object with playerId = Get Identity Id, questId = Q42.
2. Call Run Execution with State Machine mygame-QuestRewards (or empty for the default) and that input.
3. On Polled fires after every check (show a spinner, read Execution > Status).
4. On Succeeded: Get JSON Field on Execution > Output with Path rewards[0].itemId, or JSON To Struct into your reward struct.
5. On Failed: Error > Code is the workflow error (for example States.TaskFailed) or an API error; Error > Message the cause.

Express workflow, one call

Start Sync Execution runs an Express state machine and returns its output in the same node (up to 5 minutes). Check Result > Status: Succeeded, Failed or Timed Out. Billed Duration Ms and Billed Memory MB show what AWS charges.

Inspect what happened

Get Execution History returns every event; feed it to Get State Timeline for per-state durations, Get Last Error And Cause to find the state that failed, or Get State Output to read one state's result.

Activity worker

An activity is a Task state whose work is done by an outside worker — here, your game or dedicated server (spawn an NPC event, run a simulation, grant items that only the server may grant, ask a human moderator in a tool).

1. Add the StepFlow Activity Worker component to an actor (Game Mode on a server, or any actor). Set Activity (ARN or name), optionally Auto Start, Max Pending Tasks and Auto Heartbeat Interval.
2. Call Start Worker. The component long-polls GetActivityTask on a background thread (each poll waits up to 60 seconds on AWS; the game thread is never blocked).
3. On Task Received gives the task token and JSON input. Do the work, then call Complete Current Task with a JSON output, or Fail Current Task with an error name (match it in the state's Catch / Retry) and a cause.
4. While Max Pending Tasks tasks are unanswered the worker pauses polling (Waiting) and resumes after an answer.
5. With Auto Heartbeat Interval > 0 the component sends heartbeats for every pending task; a task that timed out on AWS fires On Task Lost and is removed.

Callback tasks: for .waitForTaskToken integrations (Lambda, SQS, EventBridge, ...) pass $$.Task.Token to the game in the message, then answer with Send Task Success / Send Task Failure / Send Task Heartbeat (or the component's Complete Task / Fail Task by token).

Node reference (79 nodes)

Latent nodes (Latent) run in the background, can be stopped with Cancel on their return value and fire exactly one final pin on the game thread (Wait For Execution / Run Execution also fire On Polled on the way). Every Error output is an FStepFlowError (Code, Message, Http Status, Retryable). State Machine inputs take an ARN, a version or alias ARN, or a plain name (with Account Id set); empty = Default State Machine Arn.

Executions

History helpers

State machines

Activities and task tokens

Activity worker component

Events: On Task Received (Task), On Task Answered (Task Token, Delivered, Error), On Task Lost (Task Token, Error), On Worker Error (Error), On Worker Stopped.

Map runs

ARNs

Config and identity

JSON

Credentials

C++ API

// Build.cs: PublicDependencyModuleNames.Add("StepFlow");
#include "StepFlowLibrary.h"

UStepFlowLibrary::StartSyncExecutionNative(TEXT("mygame-ScoreCheck"), TEXT("{\"score\":1200}"),
    FStepFlowNativeSyncDelegate::CreateLambda([](const FStepFlowSyncResult& Result, const FStepFlowError& Error)
    {
        // runs on the game thread; Result.Status, Result.Output, Error.Code
    }));

StartExecutionNative works the same for Standard workflows. The latent node classes (UStepFlowWaitAction and the others) can be created from C++ through their static factory functions; bind the delegates, then call Activate(). The worker is a normal component: UStepFlowActivityWorkerComponent.

Types

Settings

Project Settings > Plugins > StepFlow (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). Built for Unreal Engine 4.27 and 5.8.