Other engines

Two routes, depending on what your engine can link.

C++, for Source and custom engines

The core is C++17 and the standard library, compiled with -fno-exceptions -fno-rtti so a regression fails in the SDK's own build rather than in yours. It performs no I/O of its own: you hand it an HttpClient, a Scheduler and a SteamBridge, and every call completes through a callback on the thread that drives the client.

Adapters you can opt into:

Requirements

• Steamworks SDK 1.57 or later, for ISteamUser::GetAuthTicketForWebApi. The Source SDK 2013 tree ships an older steam_api: update both the headers and the steam_api(64) library the game loads.
• Construct SteamworksBridge after SteamAPI_Init(), and once — its callback listeners register in its constructor, and a bridge created at the moment of purchase can miss a player's answer that arrived before the order id did.
• Something must call SteamAPI_RunCallbacks() every frame. Source already does. If your engine pumps it on another thread, pass SteamworksBridge a dispatcher that posts to the game thread.

Install

Add encore/src/*.cpp to your build — or add_subdirectory(encore) and link plany::encore — and put encore/include on the include path. The SDK is in plany-cloud/apis under sdk/cpp/encore.

Quick start

1#include "plany/encore/encore.hpp"
2#include "plany/encore/adapters/steam_http_client.hpp"
3#include "plany/encore/adapters/steamworks_bridge.hpp"
4 
5static std::unique_ptr<plany::encore::SteamHttpClient> g_encoreHttp;
6static std::unique_ptr<plany::encore::SteamworksBridge> g_encoreSteam;
7static std::unique_ptr<plany::encore::Client> g_encore;
8 
9// After Steam is up — not at static initialisation.
10void Encore_Init() {
11  g_encoreHttp = std::make_unique<plany::encore::SteamHttpClient>();
12  g_encoreSteam = std::make_unique<plany::encore::SteamworksBridge>();
13 
14  plany::encore::ClientOptions options;
15  options.scheduler = &g_frameScheduler;              // enables retries — see below
16  options.newRequestId = [] { return MakeUuid(); };   // a real random UUID
17  g_encore = std::make_unique<plany::encore::Client>("ek-01j9...", options, *g_encoreHttp);
18}
19 
20void Encore_Shutdown() {  // the Client first
21  g_encore.reset();
22  g_encoreSteam.reset();
23  g_encoreHttp.reset();
24}

A store:

1void Store_Open() {
2  g_encore->ListOffers([](plany::encore::Result<plany::encore::OfferList> offers) {
3    if (!offers) return;  // offers.error().reason is typed
4    for (const auto& offer : offers.value().offers) {
5      if (!offer.price) continue;
6      Store_AddRow(offer.offerId, offer.displayName,
7                   offer.price->ToDecimalString(), offer.price->currencyCode,
8                   /*enabled=*/offers.value().purchasable);
9    }
10  });
11}

A "keep the servers running" button:

1void Store_Buy(const std::string& offerId) {
2  std::string language = plany::encore::IsoLanguageFromSteam(
3      steamapicontext->SteamApps()->GetCurrentGameLanguage());
4 
5  g_encore->Purchase(offerId, *g_encoreSteam, language,
6      [](plany::encore::Result<plany::encore::PurchaseResult> result) {
7        if (!result) {
8          // No order was opened. Nothing was charged; safe to let the player try again.
9          return;
10        }
11        switch (result.value().state) {
12          case plany::encore::PurchaseState::Credited:   Store_ShowThanks(); break;
13          case plany::encore::PurchaseState::Authorized: Store_ShowProcessing(); break;  // paid; still settling
14          case plany::encore::PurchaseState::Cancelled:  break;                          // declined
15          default:                                       Store_ShowNotCharged(); break;
16        }
17        if (result.value().funding) Store_ShowRunway(*result.value().funding);
18      });
19}

Purchase gets the ticket, opens the order, waits for the overlay and settles it. done receives an Error only when no order was opened. Once an order exists the result is always a value — telling a player "purchase failed" about an order they may have approved is the worst thing a store can say — and a decline is Cancelled. When Encore could not be told the answer, confirmed is false and unconfirmedBecause says why; an approval still lands, because Encore settles approved orders on its own.

Showing the runway:

1void Store_ShowRunway(const plany::encore::PublicFunding& f) {
2  if (!f.funded)            ShowText("The servers are asleep until somebody keeps them running.");
3  else if (!f.runwayDays)   ShowText("The servers are funded.");            // nothing to project from
4  else if (*f.runwayDays == 0) ShowText("Less than a day of servers left."); // zero is real
5  else                      ShowText(std::to_string(*f.runwayDays) + " days of servers left.");
6}

runwayDays is a std::optional: absent is "no estimate", zero is "less than a day". See What players see.

Retries need a timer

Without a Scheduler the client never retries. With one, it retries reads, CompletePurchase, and BeginPurchase when it carries a request id, with jittered backoff, and asks CompletePurchase again up to settlementPolls times while an order settles.

1struct FrameScheduler : plany::encore::Scheduler {
2  void After(std::chrono::milliseconds delay, std::function<void()> task) override {
3    timers.push_back({Now() + delay, std::move(task)});  // run from your frame loop
4  }
5  // ...
6};

Request ids come from ClientOptions::newRequestId, because the core has no random source it can trust on every platform. Use a real random UUID. An id that repeats across attempts is answered with somebody's earlier order — and with no generator at all, BeginPurchase is sent without an id and never retried.

Errors

A failed Result carries an Error with a gRPC status, a typed reason, the raw reasonName, the httpStatus (0 when no response arrived) and retryable.

All named refusals but PlayerNotAuthenticated are FailedPrecondition (HTTP 400), none improves by retrying, and every refusal of a purchase happens before the player is charged. See Refusals.

Threading and lifetime

The Client is not thread-safe. The HttpClient, the Scheduler and any SteamBridge must outlive it; the Client itself may be destroyed with calls in flight, and their callbacks are then dropped rather than run — so a callback capturing an object that is already gone is never invoked.

Testing before launch

Point the client at a sandbox link's Encore key and buy from a signed-in Steam client: the same overlay and the same calls, with nothing charged and nothing credited.

Any other language

Encore's game-facing API is four POSTs with JSON bodies and no credential. A port to another language is a JSON client, a Steam ticket, and a handler for MicroTxnAuthorizationResponse_t. The contract is on HTTPS API.