Unreal Engine

Unreal uses Encore's C++ SDK: C++17 and the standard library, no exceptions, no RTTI, no threads — the way Unreal builds — plus a complete sample UGameInstanceSubsystem that wraps it for C++ and Blueprint.

Requirements

• Steamworks SDK 1.57 or later, for ISteamUser::GetAuthTicketForWebApi.
• The OnlineSubsystemSteam plugin enabled and configured as usual. It is what initialises Steam and pumps its callbacks.
• A Steam client signed in, and the game launched through Steam or with a steam_appid.txt in development.

Install

1. Copy the SDK and the sample

   From sdk/cpp/encore in plany-cloud/apis: copy include/ and src/ into your game module — say Source/YourGame/ThirdParty/PlanyEncore/ — and the two files in samples/unreal/ into Source/YourGame/. Replace YOURGAME_API with your module's API macro.

2. Add the modules

   In YourGame.Build.cs:

   C#

   1PublicDependencyModuleNames.AddRange(new[] { "Core", "CoreUObject", "Engine", "HTTP" });
   2AddEngineThirdPartyPrivateStaticDependencies(Target, "Steamworks");
   3PrivateIncludePaths.Add(Path.Combine(ModuleDirectory, "ThirdParty/PlanyEncore/include"));
   4PrivateIncludePaths.Add(Path.Combine(ModuleDirectory, "ThirdParty/PlanyEncore/src"));

3. Configure the Encore key

   In Config/DefaultGame.ini:

   INI

   [/Script/YourGame.PlanyEncoreSubsystem]
   EncoreKey=ek-01j9…

   The key is not a secret — it ships in every copy of the game — but it is the game's, so it belongs in config. See The Encore key.

How the subsystem is put together

UPlanyEncoreSubsystem is a game instance subsystem: one Encore client for the life of the running game, surviving level travel — which is exactly when a store widget is most likely to be torn down with a purchase still in flight. It is not created on a dedicated server.

When it initialises it builds:

• an HttpClient over FHttpModule,
• a Scheduler over FTSTicker, which is what enables retries,
• a request-id generator over FGuid::NewGuid(), which is what makes opening a purchase safely retryable, and
• a SteamworksBridge — once, at start-up, because Steam can deliver the player's answer before the HTTP response naming the order has arrived, and a bridge created at the moment of purchase would miss it. Steam's callbacks are posted to the game thread.

If Steam is not running, it logs a warning and purchases report that Steam is unavailable; funding and offers still load.

A "keep the servers running" button

1void UStoreWidget::NativeConstruct()
2{
3    Super::NativeConstruct();
4 
5    UPlanyEncoreSubsystem* Encore = GetGameInstance()->GetSubsystem<UPlanyEncoreSubsystem>();
6    Encore->OnOffersLoaded.AddDynamic(this, &UStoreWidget::HandleOffers);
7    Encore->OnFundingLoaded.AddDynamic(this, &UStoreWidget::HandleFunding);
8    Encore->OnPurchaseFinished.AddDynamic(this, &UStoreWidget::HandlePurchase);
9 
10    Encore->RefreshOffers();
11    Encore->RefreshFunding();
12}
13 
14void UStoreWidget::HandleOffers(bool bSuccess, const TArray<FPlanyEncoreOffer>& Offers, const FString& Error)
15{
16    if (!bSuccess || Offers.Num() == 0)
17    {
18        StatusText->SetText(FText::FromString(TEXT("The store is unavailable right now.")));
19        return;
20    }
21    Offer = Offers[0];
22    BuyLabel->SetText(FText::FromString(FString::Printf(
23        TEXT("Keep the servers running — %s %s"), *Offer.Price, *Offer.CurrencyCode)));
24 
25    // Offers are listed before the game is verified. When they are not purchasable
26    // yet, Error carries the reason — ENCORE_NOT_VERIFIED, ENCORE_NOT_READY — and
27    // the button stays disabled.
28    BuyButton->SetIsEnabled(Error.IsEmpty());
29}
30 
31void UStoreWidget::OnBuyClicked()
32{
33    GetGameInstance()->GetSubsystem<UPlanyEncoreSubsystem>()->Purchase(Offer.OfferId);
34}
35 
36void UStoreWidget::HandlePurchase(bool bSuccess, EPlanyEncorePurchaseState State, bool bConfirmed, const FString& Error)
37{
38    if (!bSuccess)
39    {
40        // No order was opened, so nothing was charged. Safe to try again.
41        StatusText->SetText(FText::FromString(TEXT("The store is unavailable right now. You have not been charged.")));
42        return;
43    }
44    switch (State)
45    {
46    case EPlanyEncorePurchaseState::Credited:
47        StatusText->SetText(FText::FromString(TEXT("Thank you — you are keeping the servers running.")));
48        break;
49    case EPlanyEncorePurchaseState::Authorized:
50        // The player has paid; Encore finishes crediting it on its own.
51        StatusText->SetText(FText::FromString(TEXT("Thank you! Your support will show up shortly.")));
52        break;
53    case EPlanyEncorePurchaseState::Cancelled:
54        break; // the player declined — not an error
55    default:
56        StatusText->SetText(FText::FromString(TEXT("Steam did not complete the purchase. You have not been charged.")));
57        break;
58    }
59}

The same three events and three functions are Blueprint-assignable and Blueprint-callable, under the Encore category.

OnPurchaseFinished is the one to read carefully:

Purchase is one at a time: a second call while one is in flight is ignored, because two overlays for two orders is how a player is charged twice. IsPurchaseInFlight() tells a widget to disable its button.

The player's Steam language is passed to the overlay automatically.

Showing the runway

1void UStoreWidget::HandleFunding(bool bSuccess, const FPlanyEncoreFunding& Funding, const FString& Error)
2{
3    FString Text;
4    if (!bSuccess)
5        Text = TEXT("");                                                  // unknown is not "unfunded"
6    else if (!Funding.bFunded)
7        Text = TEXT("The servers are asleep until somebody keeps them running.");
8    else if (Funding.RunwayDays < 0)
9        Text = TEXT("The servers are funded.");                          // nothing to project from
10    else if (Funding.RunwayDays == 0)
11        Text = TEXT("Less than a day of servers left.");                 // zero is real, and urgent
12    else
13        Text = FString::Printf(TEXT("%lld days of servers left."), Funding.RunwayDays);
14    RunwayText->SetText(FText::FromString(Text));
15}

What a funding response contains depends on what the studio chose to publish — see What players see.

Handling errors

The C++ Error carries a gRPC status, a typed reason, the raw reasonName, the httpStatus (0 when no response arrived), and retryable. The sample turns it into the Error string on each event; a game that needs to branch on the reason should read reason in the sample's callbacks.

All named refusals but PlayerNotAuthenticated are HTTP 400, none improves by retrying, and none is retried. Every refusal of a purchase happens before the player is charged. The full list is in Refusals.

Retries. With the sample's scheduler, reads and CompletePurchase are retried on transient failures with jittered backoff, and opening a purchase is retried only under its request id — without one, a retry could open a second Steam order. While an order settles, CompletePurchase is asked again up to settlementPolls times (four by default).

Testing before launch

Test the whole store against a sandbox link: the same overlay and the same calls, with nothing charged and nothing credited. Put the sandbox Encore's key in a test build's DefaultGame.ini, launch it through a signed-in Steam client, and buy — the purchase walks through every state a real one does and ends in Credited, with nothing added to the project's balance.