Skip to content
Store Dev
Cập nhật lần cuối

Basic Integration

1. Preparing for Integration

This chapter explains the common rules to know before using the new C API. It covers, in order, the package contents, project settings, rules for creating and releasing parameter objects, result checks, asynchronous callbacks, string rules, and call formats. Every example from Chapter 2 onward assumes these rules, so read this chapter first.

All code in this guide is taken from the actual source of the sample game Brick Smash. Each explanation names the file the code comes from.

Package Contents

Download StovePCSDK_Full_C_3.5.3.0_x64.zip from the PCSDK Download page and extract it to get the following structure. Brick Smash keeps this structure as is under third_party/StovePCSDK.

text
StovePCSDK
├ Include
│ ├ stove_api.h
│ ├ base_api.h
│ ├ base_types.h
│ ├ base_misc.h
│ ├ base_flat_api.h
│ ├ base_guard.h
│ ├ game_support_api.h / game_support_types.h / game_support_misc.h / game_support_flat_api.h
│ ├ iap_api.h / iap_types.h / iap_misc.h / iap_flat_api.h
│ ├ log_api.h / log_types.h / log_misc.h / log_flat_api.h
│ ├ ownership_api.h / ownership_types.h / ownership_misc.h / ownership_flat_api.h
│ ├ pcbang_*.h
│ └ view_*.h
├ lib
│ └ x64
│   └ BaseSDK.lib
└ dll
  └ x64
    └ BaseSDK.dll
FileDescription
Include/stove_api.hThe umbrella header. Including this one header brings in the public API of every module.
Include/<module>_api.hFunction declarations of the module (e.g., Stove_FetchOwnerships).
Include/<module>_types.hInterfaces of the module (names starting with IStove) and callback types.
Include/<module>_misc.hEnumerations and result codes of the module.
Include/<module>_flat_api.hDeclarations that flatten the interface methods into C functions. See Two Types of Calls.
Include/base_guard.hC++-only RAII helpers. Optional. See RAII Helpers.
lib/x64/BaseSDK.libThe import library to link.
dll/x64/BaseSDK.dllThe SDK binary, placed next to the game executable.

The headers contain seven modules: Base, GameSupport, IAP, Log, Ownership, PCBang, and View. This guide covers Base, Ownership, GameSupport, and IAP, which StoreIndie games use. StoreIndie games do not call the PCBang and View functions even though they appear in the headers.

Project Settings

The supported environment is Windows 64-bit (x64) with C++17 or later. Visual Studio 2022 is recommended. If you need 32-bit (x86) integration, contact technical support.

Configure the following in the Visual Studio project.

Location of SettingsValue
Configuration Properties > C/C++ > General > Additional Include DirectoriesPath to the package's Include directory
Configuration Properties > Linker > General > Additional Library DirectoriesPath to the package's lib\x64 directory
Configuration Properties > Linker > Input > Additional DependenciesBaseSDK.lib
Post-Build EventCopy dll\x64\BaseSDK.dll to the folder of the executable

In the source code, include only the umbrella header.

cpp
#include "stove_api.h"

Brick Smash ships both a Visual Studio solution (BrickSmash.sln) and a CMake project (CMakeLists.txt). The solution bundles the SDL3 and Dear ImGui binaries under third_party, so it opens and builds in Visual Studio 2022 without CMake or vcpkg. Both projects use the same settings, and the include directories, additional dependencies, and post-build event in BrickSmash.vcxproj map one-to-one to the table above. The following is an excerpt from CMakeLists.txt with the same settings.

cmake
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(STOVE_SDK_DIR ${CMAKE_SOURCE_DIR}/third_party/StovePCSDK)

target_include_directories(BrickSmash PRIVATE
    ${CMAKE_SOURCE_DIR}/src
    ${STOVE_SDK_DIR}/Include
)

target_link_libraries(BrickSmash PRIVATE
    SDL3::SDL3
    imgui::imgui
    ${STOVE_SDK_DIR}/lib/x64/BaseSDK.lib
)

add_custom_command(TARGET BrickSmash POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        ${STOVE_SDK_DIR}/dll/x64/BaseSDK.dll $<TARGET_FILE_DIR:BrickSmash>
)

Brick Smash saves its source files in UTF-8, so /utf-8 is also specified in target_compile_options. If the project writes Korean string literals as L"...", keep the source file encoding and the compiler option consistent.

The SDK requires the STOVE Launcher, so the launcher must also be installed on the development PC. If the game is started without the launcher, the launcher restarts the game at the launch check step described in Chapter 2.

Features of the New API

The new API consists of functions starting with Stove_ and interfaces starting with IStove. It is designed to work in ANSI C, so it can also be used for bindings in other languages.

Since 3.5.0, the PC SDK is consolidated into a single binary. Keep the following points in mind when integrating.

ItemContent
Deployment FilesOne BaseSDK.dll and one BaseSDK.lib. Per-module DLL and LIB files are not added.
HeaderIncluding only the umbrella header stove_api.h brings in the public API of every module.
FunctionEvery public function starts with Stove_. Module names are not part of function names (e.g., Stove_FetchOwnerships).
Data TypesParameters and results are interfaces starting with IStove (e.g., IStoveUser, IStoveOwnershipList). Values are read and written with methods starting with Get, Set, and Is.
Initialization and TerminationA single Stove_Initialize() call enables ownership, achievements, payment, and log features, and a single Stove_Uninitialize() call terminates them. There are no per-module initialization functions.
Callback HandlingThe callback for every asynchronous function runs on the thread that called Stove_RunCallback().

Creating and Releasing Parameter Objects

Because the new API must also work in ANSI C, the SDK itself manages the memory of objects that cross the DLL boundary. Instead of creating a parameter with new, the game asks the SDK to create one with Stove_CreateParam() and returns it with Destroy() when done.

Functions that take values receive them as interface objects. Use a parameter in the following order.

  1. Call Stove_CreateParam(kind) to create a parameter object. Pass the type value of the parameter to create (k_EStove*TypeKind_*Param) as kind.
  2. Check whether the return value is nullptr. If the type value is invalid or not a parameter type, nullptr is returned instead of an error.
  3. The return type is IStoveTypeBase*, so cast it to the parameter interface.
  4. Fill in the values with the setters.
  5. Call the function.
  6. Call Destroy() as soon as the call returns. Even for an asynchronous function, there is no need to wait for the callback.

The parameter type values used in this guide are as follows.

Type ValueInterface CreatedUsed By
k_EStoveBaseTypeKind_RestartAppIfNecessaryParamIStoveRestartAppIfNecessaryParamStove_RestartAppIfNecessary
k_EStoveBaseTypeKind_InitializeParamIStoveInitializeParamStove_Initialize
k_EStoveBaseTypeKind_SetGameProfileParamIStoveSetGameProfileParamStove_SetGameProfile
k_EStoveGameSupportTypeKind_FetchStatParamIStoveFetchStatParamStove_FetchStat
k_EStoveGameSupportTypeKind_SetStatParamIStoveSetStatParamStove_SetStat
k_EStoveGameSupportTypeKind_FetchAchievementParamIStoveFetchAchievementParamStove_FetchAchievement
k_EStoveGameSupportTypeKind_FetchAchievementsParamIStoveFetchAchievementsParamStove_FetchAchievements
k_EStoveGameSupportTypeKind_FetchRankingParamIStoveFetchRankingParamStove_FetchRanking
k_EStoveIAPTypeKind_FetchProductsParamIStoveFetchProductsParamStove_FetchProducts
k_EStoveIAPTypeKind_OrderProductParamIStoveOrderProductParamStove_StartPurchase (order information for one product)
k_EStoveIAPTypeKind_PurchaseParamIStovePurchaseParamStove_StartPurchase (payment flow)
k_EStoveIAPTypeKind_StartPurchaseParamIStoveStartPurchaseParamStove_StartPurchase
k_EStoveIAPTypeKind_ConfirmPurchaseParamIStoveConfirmPurchaseParamStove_ConfirmPurchase
k_EStoveLogTypeKind_SendLogParamIStoveSendLogParamStove_SendLog

For functions whose parameter is declared as const IStoveTypeBase* param (Stove_FetchOwnerships · Stove_ShutdownNotification · Stove_OverImmersionNotification, etc.), pass nullptr because the SDK does not use the argument.

Release Rules

Every object passed between the SDK and the game inherits IStoveTypeBase. Who releases each object is fixed, and the rule fits in one sentence.

The game calls Destroy() on objects it receives and owns, and does not release objects it only borrows as callback arguments.

ObjectExampleRelease
Parameter created with Stove_CreateParamIStoveInitializeParam*The game calls Destroy() when the call returns.
Result returned by a synchronous functionIStoveResult* returned by Stove_Initialize · Stove_GetUser, etc.The game calls Destroy() after checking it.
Object received through an out parameterIStoveUser* of Stove_GetUser, IStoveGds* of Stove_GetGds, IStoveSignin* of Stove_GetSigninWhether the call succeeds or fails, if it is not nullptr, the game calls Destroy() after reading the values.
Callback argumentIStoveCallbackResult*, the second callback argument (outcome · list · info object), and objects taken from themOwned by the SDK. Do not call Destroy().

When unsure whether to release an object, check ShouldDestroy(). If it is true, the game calls Destroy() exactly once; if it is false, the object is managed by the SDK and must not be released. Always checking ShouldDestroy() and calling Destroy() only when it is true prevents both a missed release and a double release.

A missed release leaks memory. Calling Destroy() on an SDK-owned object or calling Destroy() twice on the same object can crash the program.

Without the helpers, a manual release looks like this. The example below is not the approach Brick Smash uses; it is a raw form that shows the release rules.

cpp
IStoveRestartAppIfNecessaryParam* param = static_cast<IStoveRestartAppIfNecessaryParam*>(
    Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam)); // Generate
if (param != nullptr)
{
    param->SetGameId(L"YOUR_GAME_ID");                                            // Setter
    Stove_RestartAppIfNecessary(param, OnRestartAppIfNecessaryFinished, nullptr); // Call
}
if (param != nullptr && param->ShouldDestroy()) param->Destroy();                 // End

RAII Helpers

Writing release code like the above every time makes it easy to miss a release on an early return path. For this reason, the package includes base_guard.h. This header has the following characteristics.

  • Optional. Every API can be used without it.
  • C++ only. Including it in a pure C project causes a compile error.
  • Header-only. No additional library to link.
  • It is separate from the umbrella header stove_api.h, so add #include "base_guard.h" to use it.
HelperRole
StoveMakeParam<T>()Creates a parameter object. T is the interface to create, such as IStoveInitializeParam. No type value or cast is needed. If the SDK cannot create the object, an empty StoveGuard is returned.
StoveGuard<T>Holds an object and, when it goes out of scope, checks ShouldDestroy() and calls Destroy(). To receive an out parameter, pass the address with Put(). Check whether it is empty with IsValid(), get the raw pointer with Get(), and call methods directly with ->.
StoveResultGuardHolds the IStoveResult* returned by a synchronous function and releases it when it goes out of scope. if (result) means the call succeeded; a missing result object is also treated as a failure. Read the result code with GetResultCode().

Even if StoveGuard wraps an SDK-owned object by mistake, it does nothing when ShouldDestroy() is false, so a double release cannot occur.

Brick Smash uses these helpers. The following is the part of Begin() in src/stove/StoveSession.cpp that creates a parameter and makes the call.

cpp
auto param = StoveMakeParam<IStoveRestartAppIfNecessaryParam>();
if (!param.IsValid())
{
    Fail("Stove_CreateParam(RestartAppIfNecessaryParam) failed");
    return;
}
param->SetEnvironment(cfg.environment.c_str()); // L"SANDBOX" or L"LIVE"
param->SetGameId(cfg.game_id.c_str());
param->SetAppKey(cfg.app_key.c_str());
param->SetWaitTimeMilliSec(60000);  // Time spent waiting for the launcher to respond
param->SetLaunchStoveLauncher(true); // If the launcher is off, start it.

// The result is returned as a callback in the game loop's `Stove_RunCallback()` function.
Stove_RestartAppIfNecessary(param.Get(), OnRestartAppIfNecessaryFinished, this);
// param is destroyed when StoveGuard goes out of range.

Out parameters and synchronous results are handled the same way. The following is the part of Initialize() in the same file that reads user information.

cpp
// Logged-in user information. The `out` object is released by StoveGuard regardless of whether the operation was successful.
StoveGuard<IStoveUser> user;
StoveResultGuard userResult(Stove_GetUser(user.Put()));
if (userResult && user.IsValid())
    nickname_ = WideToUtf8(user->GetNickName());

With the helpers, Destroy() calls disappear from the source. All later examples in this guide use this approach.

Checking Results

Every function reports its result as IStoveResult. Synchronous functions return it, and asynchronous functions deliver it through callbackResult->GetResult() in the callback. Always decide success or failure with a single IsSuccessful() branch, and do not use try-catch.

MethodReturn TypeDescription
IsSuccessful()booltrue on success.
GetResultCode()uint32_tThe result code. 0 on success; on failure, a value that indicates the cause.
GetMethodCode()uint32_tA value that identifies the function that produced the result. Modules are divided in units of 1000 (e.g., the 4000 range is Ownership). Logging it together makes the cause easier to find.

IStoveCallbackResult of an asynchronous callback gives more detail about a failure.

MethodReturn TypeDescription
GetResult()IStoveResult*The result object. It becomes invalid when the callback ends. Do not call Destroy() on it.
GetErrorMessage()const wchar_t*A message that describes why the error occurred.
GetExternalError()int32_tExternal error value (HTTP error code or server API result code).
GetUserData()void*The userData passed when the asynchronous function was called.

Result codes are defined in two enumerations in base_misc.h. 0 to 299 are common codes shared by all modules (EStoveCommonResultCode), and 300 and above are feature-specific codes (EStoveResultCode). The codes most often seen during integration are as follows.

CodeNameMeaning
0k_EStoveCommonResultCode_SuccessSuccess.
1k_EStoveCommonResultCode_FailGeneral failure.
5k_EStoveCommonResultCode_InvalidParamInvalid parameter. Also returned when a buffer is too small.
16k_EStoveCommonResultCode_BaseNotInitializedCalled before the SDK was initialized.
18k_EStoveCommonResultCode_AlreadyInitializedStove_Initialize was called again while already initialized.
29k_EStoveCommonResultCode_AsyncOperationInProgressThe same asynchronous task is still in progress.
31k_EStoveCommonResultCode_NotSupportedCountryThe feature is not supported in the user's country.
249k_EStoveCommonResultCode_NetworkTransportErrorNetwork transport error. GetExternalError() contains the transport layer error code.
304k_EStoveResultCode_NeedStoveLauncherThe STOVE Launcher is required but not running.
307k_EStoveResultCode_IpcConnectFailedCommunication with the launcher failed.
308k_EStoveResultCode_IpcAesKeyNotReceivedCommunication with the launcher failed.
309k_EStoveResultCode_IpcTimeoutCommunication with the launcher failed.

Brick Smash has one function that turns the cause of a failed callback into readable text, and every callback shares it. The following is DescribeFailure() in src/StoveState.h. It joins the result code and the error message into one line.

cpp
inline std::string DescribeFailure(const IStoveCallbackResult* r)
{
    std::string s = "code=" + std::to_string(r->GetResult()->GetResultCode());
    std::string msg = WideToUtf8(r->GetErrorMessage());
    if (!msg.empty())
        s += " " + msg;
    return s;
}

Asynchronous Functions and Callbacks

A function whose return type is void in the header and that takes a callback is an asynchronous function. Its result is delivered through the callback, not the return value. Asynchronous functions share the following form.

cpp
void Stove_FetchOwnerships(const IStoveTypeBase* param, OnOwnershipListCallback onFinished, void* userData);

The callback is a __cdecl function pointer with two arguments. The first is IStoveCallbackResult*, and the second is a feature-specific result object. The userData passed at call time is not a separate callback argument; retrieve it with callbackResult->GetUserData().

Only plain functions or non-capturing lambdas can be passed as callbacks. Because the callback is a function pointer, capturing lambdas ([&], [this]) cannot be passed. If a game object is needed, pass it as userData and retrieve it with GetUserData() in the callback, as Brick Smash does. The following is the callback wiring in src/stove/StoveSession.cpp. Begin() passes this as userData, and the callback retrieves it and forwards the call to a member function of the session object.

cpp
namespace
{
    StoveSession* Self(const IStoveCallbackResult* r)
    {
        return static_cast<StoveSession*>(r->GetUserData());
    }

    void __cdecl OnFetchOwnershipsFinished(const IStoveCallbackResult* r, const IStoveOwnershipList* list)
    {
        Self(r)->OnOwnerships(r, list);
    }
}

Do not pass the address of a local variable as userData. The callback runs in a later frame after the function returns, when the local variable no longer exists. The object userData points to must stay alive until the callback runs. Brick Smash passes StoveSession and AppState, which live until main() ends.

Callback Arguments Are Valid Only Inside the Callback

Callback arguments (IStoveCallbackResult*, the second argument, and objects and strings taken from them) are valid only while the callback runs. The objects disappear when the callback ends, so copy any value needed outside the callback while inside it. Move strings into game-side storage such as std::string or std::wstring.

Brick Smash applies this rule consistently with the state structs in src/StoveState.h. Each struct has one AsyncStatus, which the screen and the callback use to signal each other.

cpp
enum class AsyncStatus
{
    Idle,
    Loading,
    Done,
    Error,
};

// View Stats (Stove_FetchStat)
struct StatState
{
    AsyncStatus status = AsyncStatus::Idle;
    std::string error;
    int currentValue = 0;
};
  • The screen (the requesting side) starts the SDK call only once while status is Idle and sets status to Loading.
  • The callback gets the state struct pointer with GetUserData(), copies the needed values immediately, and sets status to Done or Error.
  • Pointers to IStove* objects received by the callback are not stored.

The following is OnFetchStatFinished() in src/stove/StoveGameSupport.cpp. On failure, it stores the cause with DescribeFailure(); on success, it copies the value.

cpp
void __cdecl OnFetchStatFinished(const IStoveCallbackResult* r, const IStoveStat* stat)
{
    auto* st = Self<StatState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    st->currentValue = stat->GetCurrentValue();
    st->status = AsyncStatus::Done;
}

Stove_RunCallback Call Rules

Callbacks run on the thread that calls Stove_RunCallback(), during that call.

  1. Call Stove_RunCallback() every frame in the game loop.
  2. Call it on the main (UI) thread. The header states that it must be called on the main thread.
  3. Keep calling it from right after the first asynchronous function (Stove_RestartAppIfNecessary) until Stove_Uninitialize() is called.
  4. Do not create a separate loop such as while (true) { Stove_RunCallback(); } that runs only this function. Add it as one step of the game loop.

Brick Smash calls Stove_RunCallback() within StoveSession::Pump(), and the game loop in main() calls Pump() every frame. See Game Loop and Termination in Chapter 2 for the full code.

If callback processing in a single frame may take too long, use Stove_RunCallbackWithTimeout(timeoutMillisec) instead. It processes callbacks only up to the given time (in milliseconds) and continues the rest on the next call. Use only one of the two functions.

cpp
Stove_RunCallbackWithTimeout(10); // Callback processing takes up to 10 ms.

Strings and Buffers

  • Every string exchanged with the SDK is wchar_t-based (UTF-16). Pass input as const wchar_t* and write literals as L"string".
  • A const wchar_t* returned by the SDK is valid only while the object holding the string is alive. Do not read it again after the object is destroyed with Destroy() or the callback has ended.

The UI library of Brick Smash (Dear ImGui) uses UTF-8 char*, so WideToUtf8() and Utf8ToWide(), which convert between the two, are placed in src/StringUtil.h. Configuration values are kept as std::wstring in src/AppConfig.h so they can be passed to the SDK directly.

cpp
// The SDK treats all strings as wchar_t* (UTF-16), while ImGui treats them as char* (UTF-8).
// A utility that converts between the two expressions.
std::string WideToUtf8(const wchar_t* src);
std::wstring Utf8ToWide(const std::string& src);

Functions that return a string in a buffer take the form wchar_t* out, uint32_t length. In this guide, Stove_GetVersion and Stove_GetCloudSavingPath are such functions.

RuleContent
Unit of lengthThe number of wchar_t characters, not bytes. Pass a buffer size that fits the terminating null character.
Buffer is nullptr or length is 0Fails with k_EStoveCommonResultCode_InvalidParam(5).
Buffer too smallA truncated string is not returned. The buffer is cleared to an empty string, and the call fails with k_EStoveCommonResultCode_InvalidParam(5).

The following is the part of Initialize() in src/stove/StoveSession.cpp that reads the SDK version.

cpp
// SDK version. Please include this information when contacting technical support.
wchar_t version[64] = { 0 };
StoveResultGuard versionResult(Stove_GetVersion(version, 64));
if (versionResult)
    sdkVersion_ = WideToUtf8(version);

Two Types of Calls

The headers provide the same features in two formats.

FormatExampleEnvironment
Interface call formatresult->IsSuccessful(), param->SetGameId(L"..."), result->Destroy()Projects built with a C++ compiler
Flat function format (*_flat_api.h)Stove_IStoveResult_IsSuccessful(result), Stove_IStoveRestartAppIfNecessaryParam_SetGameId(param, L"...")Pure C compilers, or language bindings that cannot call virtual functions

All examples in this guide use the interface call format. If the project can be built as C++, this format gives shorter code with fewer casts.

The flat API is a concept taken from the Steamworks SDK. It is used where virtual calls on an interface (obj->Method()) are not possible, that is, when building with a pure C compiler or when calling DLL functions directly from languages and engines that do not support C++ syntax. Each interface method is flattened into a C function of the same name, so pass the target object as the first argument. Flat function names follow this rule.

text
Stove_<interface name>_<method name>(self, remaining arguments...)
  • result->IsSuccessful() → Stove_IStoveResult_IsSuccessful(result)
  • callbackResult->GetResult() → Stove_IStoveCallbackResult_GetResult(callbackResult)
  • user->GetNickName() → Stove_IStoveUser_GetNickName(user)
  • param->SetGameId(L"...") → Stove_IStoveRestartAppIfNecessaryParam_SetGameId(param, L"...")

Release is the only exception. Destroy has a flat function only on IStoveTypeBase, the common parent of all objects, so cast the object as in Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)obj). ShouldDestroy likewise uses Stove_IStoveTypeBase_ShouldDestroy.

The same code in the flat function format looks like this. Pure C cannot use base_guard.h, so the release is also done manually.

c
#include <stdbool.h> /* In pure C, include it before `stove_api.h`. */
#include "stove_api.h"

IStoveRestartAppIfNecessaryParam* param = (IStoveRestartAppIfNecessaryParam*)
    Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam);
Stove_IStoveRestartAppIfNecessaryParam_SetGameId(param, L"YOUR_GAME_ID");
Stove_RestartAppIfNecessary(param, OnRestartAppIfNecessaryFinished, NULL);
if (param != NULL && Stove_IStoveTypeBase_ShouldDestroy((IStoveTypeBase*)param)) Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

The headers use bool but do not include <stdbool.h> themselves. C++ is not affected; only when building as pure C, include <stdbool.h> before stove_api.h.

Summary

RuleOne-Line Summary
ParameterCreate it with Stove_CreateParam() and release it when the call returns. StoveMakeParam<T>() releases it automatically.
ReleaseThe game calls Destroy() on objects it receives, and does not release callback arguments.
ResultAlways decide with IsSuccessful().
CallbackTwo arguments. Retrieve userData with GetUserData(), and copy values inside the callback.
Callback executionCall Stove_RunCallback() on the main thread every frame.
Stringwchar_t-based, and buffer lengths are counted in wchar_t characters.

2. Initialization · Termination · Ownership

This step checks that the game was launched through the STOVE Launcher, initializes the SDK, checks whether the user purchased the game, and terminates the SDK when the game ends. Every other feature depends on it, so integrate it first. For a game that is sold, include the ownership check in the first integration.

The code in this chapter comes from src/stove/StoveSession.h, src/stove/StoveSession.cpp, and src/main.cpp of Brick Smash. A single StoveSession class handles the SDK lifecycle, and the game loop only calls its Pump(). Follow what each function does to understand the whole flow.

Preparations

Check the following values in STOVE Studio in advance. The game ID and app key are shown under Product Key at the top right of the Build Management menu in STOVE Studio.

ValueSetterDescription
EnvironmentIStoveRestartAppIfNecessaryParam::SetEnvironmentUse L"SANDBOX" during development and testing, and L"LIVE" in release builds. Not case-sensitive.
Game IDIStoveRestartAppIfNecessaryParam::SetGameIdThe game ID issued by STOVE Studio.
App KeyIStoveRestartAppIfNecessaryParam::SetAppKeyThe app key issued by STOVE Studio.
Shop KeyIStoveInitializeParam::SetShopKeyRequired only for games that use payment (Chapter 6). Issued when the in-game shop is registered in STOVE Studio.

Brick Smash keeps these values in config/stove_config.ini next to the executable instead of the source. The repository contains only the template config/stove_config.example.ini, so copy it to stove_config.ini and fill in the issued values.

ini
[stove]
; Environment: SANDBOX for development/testing, LIVE for release builds
environment = SANDBOX
; Value issued in STOVE Studio
game_id = YOUR_GAME_ID
app_key = YOUR_APP_KEY
; In-game shop key. If left empty, the payment feature is not initialized.
shop_key = YOUR_SHOP_KEY

[ownership]
; Game ID of the DLC on sale. If owned, the game uses a wider paddle. Leave empty if there is no DLC.
dlc_game_id = YOUR_DLC_GAME_ID

Values read from the configuration file are stored in the AppConfig struct in src/AppConfig.h. The SDK requires wchar_t*, so strings are kept as std::wstring.

cpp
struct AppConfig
{
    // [stove]
    std::wstring environment = L"SANDBOX"; // SANDBOX / LIVE
    std::wstring game_id;
    std::wstring app_key;
    std::wstring shop_key;                 // If left blank, the payment function will not be initialized.

    // [ownership]
    std::wstring dlc_game_id;              // The game ID of the DLC currently for sale. Leave blank if none.
    // ...
};

Use only the defined environment values. An undefined value runs in the sandbox environment without an error, so make sure release builds set L"LIVE".

Call Order

  1. Create the launch check parameter with Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam) and set the environment, game ID, and app key.
  2. Call Stove_RestartAppIfNecessary(). It is asynchronous, so the result arrives in a callback. Release the parameter when the call returns.
  3. Start the game loop and call Stove_RunCallback() every frame. This call is what runs the callback from step 2.
  4. Check the result in the callback.
    • On failure, notify the user and exit the game.
    • If outcome->IsRestartRequired() is true, the launcher restarts the game, so exit the current process immediately.
    • If it is false, continue to the next step.
  5. Create the initialization parameter with Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam), and set the shop key and window handle if the game uses payment.
  6. Call Stove_Initialize(). It is synchronous, so check success right away with the returned IStoveResult*.
  7. After a successful initialization, read the user information with Stove_GetUser() and the SDK version with Stove_GetVersion().
  8. Fetch ownership with Stove_FetchOwnerships() and decide whether the game was purchased in the callback.
  9. Register the shutdown and over-immersion notification callbacks. Chapter 4 explains them.
  10. Run the game loop.
  11. Call Stove_Uninitialize() when the game ends, and do not call Stove_RunCallback() afterward.

Set the environment, game ID, and app key only once, in step 1. Stove_Initialize() reuses the values set for the launch check, so do not set them again in the initialization parameter. For this reason, the launch check and initialization must run as one continuous flow.

StoveSession State Flow

Brick Smash tracks this sequence with the Phase value of the StoveSession class. The following is an excerpt from src/stove/StoveSession.h.

cpp
// Manages the entire SDK lifecycle.
//
//   1) Begin(cfg, hwnd)   : Start Stove_RestartAppIfNecessary (asynchronous)
//   2) Pump() every frame: Update Stove_RunCallback and remaining exposure time
//      Callback → Stove_Initialize → GetUser/GetVersion → FetchOwnerships → Register Regulatory Notifications
//   3) Shutdown() upon termination: Stove_Uninitialize
class StoveSession
{
public:
    enum class Phase
    {
        Idle,
        RestartCheckPending, // Waiting for the RestartAppIfNecessary callback
        OwnershipPending,    // Initialization complete; waiting for ownership lookup callback
        Ready,               // Everything is ready
        RestartRequired,     // The launcher restarts the game. Close immediately.
        Failed,
    };

    void Begin(const AppConfig& cfg, void* hwnd);
    void Pump(float dt);
    void Shutdown();

    bool ready() const { return phase_ == Phase::Ready; }
    bool shouldQuit() const { return phase_ == Phase::RestartRequired; }
    // ...
};
PhaseMeaningTransition Condition
IdleNot started yet, or already terminated.Calling Begin() changes it to RestartCheckPending.
RestartCheckPendingWaiting for the callback of Stove_RestartAppIfNecessary().If IsRestartRequired() is false in the callback and initialization succeeds, it becomes OwnershipPending; if true, RestartRequired; on failure, Failed.
OwnershipPendingInitialization is done; waiting for the ownership callback.Ready if the base game is owned, otherwise Failed.
ReadyEverything is ready. The game screen is drawn.
RestartRequiredThe launcher restarts the game. Exit immediately.
FailedA step failed. error() holds the cause.

The game screen is drawn only when ready() is true. Until then, "Initializing STOVE SDK..." is shown, and in Failed, the cause of the failure is shown.

Launch Check

StoveSession::Begin() is called after the window is created. It creates the launch check parameter and calls Stove_RestartAppIfNecessary(). The function is asynchronous, so the result is unknown right after it returns. The result arrives as a callback from Stove_RunCallback() in the game loop.

cpp
void StoveSession::Begin(const AppConfig& cfg, void* hwnd)
{
    cfg_ = &cfg;
    hwnd_ = hwnd;
    phase_ = Phase::RestartCheckPending;

    auto param = StoveMakeParam<IStoveRestartAppIfNecessaryParam>();
    if (!param.IsValid())
    {
        Fail("Stove_CreateParam(RestartAppIfNecessaryParam) failed");
        return;
    }
    param->SetEnvironment(cfg.environment.c_str()); // L"SANDBOX" or L"LIVE"
    param->SetGameId(cfg.game_id.c_str());
    param->SetAppKey(cfg.app_key.c_str());
    param->SetWaitTimeMilliSec(60000);  // Time spent waiting for the launcher to respond
    param->SetLaunchStoveLauncher(true); // If the launcher is off, start it.

    // The results are returned as a callback in the game loop's `Stove_RunCallback()` function.
    Stove_RestartAppIfNecessary(param.Get(), OnRestartAppIfNecessaryFinished, this);
    // param is destroyed when StoveGuard goes out of range.
}

The setters of IStoveRestartAppIfNecessaryParam are as follows.

SetterFormatDescription
SetEnvironmentconst wchar_t*The environment value. Set L"SANDBOX" or L"LIVE".
SetGameIdconst wchar_t*The game ID.
SetAppKeyconst wchar_t*The app key.
SetWaitTimeMilliSecuint32_tHow long to wait (in milliseconds) when checking whether the game was launched by the launcher. 0 right after creation.
SetLaunchStoveLauncherboolWhether to start the launcher when it is not running. false right after creation.
SetPlatformNameconst wchar_t*Name of the integrated platform (e.g., L"Stove", L"Steam"). Do not set it for games sold only on STOVE.

The callback type is OnRestartAppIfNecessaryCallback, and its second argument IStoveRestartAppIfNecessaryOutcome has one method.

MethodReturn TypeDescription
IsRestartRequired()boolIf true, the game must be restarted through the launcher, so the current process must exit. If false, continue.

When the callback arrives, OnRestartChecked() evaluates the result and then calls initialization and the ownership query.

cpp
void StoveSession::OnRestartChecked(const IStoveCallbackResult* r, const IStoveRestartAppIfNecessaryOutcome* outcome)
{
    if (!r->GetResult()->IsSuccessful())
    {
        Fail("Launcher launch check failed: " + DescribeFailure(r));
        return;
    }
    if (outcome->IsRestartRequired())
    {
        // The launcher restarts the game. Since it hasn't been initialized yet, it does not call `Uninitialize`.
        phase_ = Phase::RestartRequired;
        return;
    }
    if (!Initialize())
        return;

    // 2) Ownership Check (Base Game + DLC). Since the SDK does not use the parameter slot, it is nullptr.
    phase_ = Phase::OwnershipPending;
    Stove_FetchOwnerships(nullptr, OnFetchOwnershipsFinished, this);
}

Note the three branches. On failure, the phase becomes Failed; if a restart is needed, RestartRequired; otherwise, the flow continues to initialization. RestartRequired happens before initialization, so Stove_Uninitialize() is not called.

Initialization

StoveSession::Initialize() calls Stove_Initialize(), reads the user information and SDK version, and registers the regulatory notification callbacks.

IStoveInitializeParam has two setters.

SetterFormatDescription
SetShopKeyconst wchar_t*The shop key. If set, Stove_Initialize() also initializes the payment feature. If empty, the payment feature is not initialized.
SetMainWndHandleconst void*The handle (HWND) of the game's main window. The handle is valid only after the window is created. The SDK positions the payment window relative to this window.
  • Games that use payment set both SetShopKey and SetMainWndHandle. Without the shop key, the payment feature is not initialized and the functions in Chapter 6 do not work.
  • Games that do not use payment can call Stove_Initialize(nullptr) without a parameter. The header states that initParam can be nullptr. Ownership, achievements, stats, leaderboards, logs, and regulatory notifications all still work.

Brick Smash uses payment, so it sets both.

cpp
bool StoveSession::Initialize()
{
    auto param = StoveMakeParam<IStoveInitializeParam>();
    if (!param.IsValid())
    {
        Fail("Stove_CreateParam(InitializeParam) failed");
        return false;
    }
    // Since we're using payment, include both the shop key and the main window handle. If there is no payment, Stove_Initialize(nullptr) is sufficient.
    param->SetShopKey(cfg_->shop_key.c_str());
    param->SetMainWndHandle(hwnd_);

    StoveResultGuard result(Stove_Initialize(param.Get()));
    if (!result)
    {
        // Since only some modules may have been initialized, clean up the system and handle the failure.
        StoveResultGuard uninit(Stove_Uninitialize());
        Fail("Stove_Initialize failed: code=" + std::to_string(result.GetResultCode()));
        return false;
    }
    initialized_ = true;

    // Logged-in user information. The `out` object is released by StoveGuard regardless of whether the operation was successful.
    StoveGuard<IStoveUser> user;
    StoveResultGuard userResult(Stove_GetUser(user.Put()));
    if (userResult && user.IsValid())
        nickname_ = WideToUtf8(user->GetNickName());

    // SDK version. Please include this information when contacting technical support.
    wchar_t version[64] = { 0 };
    StoveResultGuard versionResult(Stove_GetVersion(version, 64));
    if (versionResult)
        sdkVersion_ = WideToUtf8(version);

    // 3) Register a regulatory notification callback. Once registered, the SDK will send a callback whenever necessary.
    Stove_ShutdownNotification(nullptr, OnShutdownNotificationFinished, this);
    Stove_OverImmersionNotification(nullptr, OnOverImmersionNotificationFinished, this);
    // ... See Chapter 7 of the Advanced Integration document for registering the Vietnam notifications ...
    return true;
}

Points to note in this code:

  • StoveResultGuard receives the IStoveResult* returned by Stove_Initialize(), and if (!result) decides success. The helper releases the result object when it goes out of scope.
  • If initialization fails, call Stove_Uninitialize() first and then handle the failure. A failed initialization can leave some features initialized, so cleanup is needed. To retry, call Stove_Initialize() again after this cleanup.
  • The out parameter of Stove_GetUser() is received through Put() of StoveGuard<IStoveUser>. The helper releases the object whether the call succeeds or fails. The nickname comes from a synchronous function rather than a callback, but the string is still copied into nickname_.
  • The length argument of Stove_GetVersion() is 64, the number of wchar_t characters, not bytes.
  • The regulatory notification functions are asynchronous with no return value, so call them only once. Chapter 4 explains the notifications.

Ownership Check

This feature checks whether the signed-in user actually owns the base game, demo, or DLC of the running game. StoreIndie games are sold by default, so include it in the first integration. For a game that sells DLC, also check ownership before unlocking DLC content so that users who did not purchase it cannot see it.

Nothing needs to be configured in STOVE Studio. The base game, demo, and DLC items to check are already registered while the game is registered in the store and prepared for sale.

Call Order

  1. After Stove_Initialize() succeeds, call Stove_FetchOwnerships(nullptr, callback, userData). The SDK does not use the parameter argument, so pass nullptr.
  2. The callback runs in Stove_RunCallback() of the game loop.
  3. In the callback, iterate over IStoveOwnershipList with GetCount() · GetAt(i).
  4. For each item, check the game ID, product category, and ownership status together.
  5. If ownership of the base game is not confirmed, handle it according to the game's policy.

Result Object

The callback type is OnOwnershipListCallback.

cpp
typedef void(__cdecl* OnOwnershipListCallback)(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships);

IStoveOwnershipList is a list of ownership entries.

MethodReturn TypeDescription
GetCount()uint32_tNumber of items.
GetAt(uint32_t index)const IStoveOwnership*The item at index. nullptr if out of range.

Each IStoveOwnership item has the following values.

MethodReturn TypeDescription
GetGameId()const wchar_t*STOVE game ID linked to this item.
GetGameCode()int32_tProduct category. An EStoveOwnershipGameCode value.
GetOwnershipCode()int32_tOwnership status. An EStoveOwnershipCode value.
GetPurchaseDate()uint64_tPurchase time, in Unix epoch milliseconds (UTC).

The ownership status values (EStoveOwnershipCode) are as follows. Acquire is the only value treated as owned.

ValueNameMeaning
0k_EStoveOwnershipCode_NoneNo recorded ownership status. Treat as not owned.
1k_EStoveOwnershipCode_AcquireCurrently owned.
2k_EStoveOwnershipCode_LoseOwnership was lost (e.g., refund). Treat as not owned.

The product categories (EStoveOwnershipGameCode) are as follows. Values 1 and 2 are retired and never returned.

ValueNameMeaning
0k_EStoveOwnershipGameCode_NoneNot a product item, or no category assigned.
3k_EStoveOwnershipGameCode_BasicBase game.
4k_EStoveOwnershipGameCode_DemoDemo build.
5k_EStoveOwnershipGameCode_DlcDLC of the base game.

Deciding Ownership in the Callback

The following is StoveSession::OnOwnerships(). It iterates over the list, looks only at owned items, checks the game ID and product category together, and copies whether the base game and DLC are owned into member variables.

cpp
void StoveSession::OnOwnerships(const IStoveCallbackResult* r, const IStoveOwnershipList* list)
{
    if (!r->GetResult()->IsSuccessful())
    {
        Fail("Ownership query failed: " + DescribeFailure(r));
        return;
    }

    ownsBaseGame_ = false;
    ownsDlc_ = false;
    for (uint32_t i = 0; i < list->GetCount(); ++i)
    {
        const IStoveOwnership* o = list->GetAt(i);
        if (o == nullptr || o->GetOwnershipCode() != k_EStoveOwnershipCode_Acquire)
            continue; // None · "Lose" refers to a state of not possessing something

        const wchar_t* gameId = o->GetGameId();
        if (o->GetGameCode() == k_EStoveOwnershipGameCode_Basic && wcscmp(gameId, cfg_->game_id.c_str()) == 0)
            ownsBaseGame_ = true;
        else if (o->GetGameCode() == k_EStoveOwnershipGameCode_Dlc && wcscmp(gameId, cfg_->dlc_game_id.c_str()) == 0)
            ownsDlc_ = true;
    }

    if (!ownsBaseGame_)
    {
        Fail("Please run with the account that purchased the game.");
        return;
    }
    phase_ = Phase::Ready;
}

This code follows these rules.

  • Look only at items whose ownership status is Acquire. Treat None and Lose (refund, etc.) as not owned.
  • Check the game ID and product category together. The base game is the Basic item that matches game_id in the configuration file, and the DLC is the Dlc item that matches dlc_game_id.
  • Handle a failed query (IsSuccessful() is false) separately from not owning the game. Brick Smash sets Failed in both cases but shows different messages.
  • Copy the results into ownsBaseGame_ and ownsDlc_, and do not keep the IStoveOwnership* pointer. The list and items become invalid when the callback ends.

Finding and Using DLC

DLC is returned as an ownership item separate from the base game, so checking DLC requires its game ID. Brick Smash reads dlc_game_id from the configuration file into cfg.dlc_game_id and looks for the item in the list that is k_EStoveOwnershipGameCode_Dlc with the same game ID. If that item is Acquire, ownsDlc_ becomes true.

How owning the DLC changes the game is up to the game. Brick Smash gives DLC owners a wider paddle. The following is an excerpt from src/ui/GameScreen.cpp. At the start of a round, the paddle width is chosen from ownsDlc(), and the menu screen (src/ui/MenuScreen.cpp) shows "DLC: wide paddle enabled".

cpp
// If you own the DLC, use the wide paddles (180).
game.Start(field.x, field.y, field.w, field.h,
           ctx.session->ownsDlc() ? 180.0f : 110.0f);

For a game without DLC, leave dlc_game_id empty. No game ID equals an empty string, so ownsDlc_ stays false.

Handling When Not Owned

  • Base game not owned: The usual approach is to show that a purchase is required and then exit the game. Brick Smash stays in Failed and shows "Please launch the game with the account that purchased it." The message and exit behavior follow the game's policy.
  • Demo build: For a build distributed as a demo, check the k_EStoveOwnershipGameCode_Demo item.
  • DLC not owned: The game continues and only the DLC content is locked. Brick Smash gives the default paddle. Whether to show a purchase prompt follows the game's policy.
  • Query failed: Handle it separately from not owning the game. It may be a network issue, so notify the user and then query again or exit the game.

The list contains the items of the running game (base game · DLC · demo).

Game Loop and Termination

The game loop calls StoveSession::Pump() every frame. Pump() calls Stove_RunCallback() to run the queued callbacks. OnRestartChecked() and OnOwnerships() shown above also run inside this call.

cpp
void StoveSession::Pump(float dt)
{
    // All asynchronous callbacks are executed within this call, on this thread.
    Stove_RunCallback();

    if (notice_.secondsLeft > 0.0f && !notice_.blocksGame)
        notice_.secondsLeft -= dt;
    if (overimmersion_.visible && (overimmersion_.secondsLeft -= dt) <= 0.0f)
        overimmersion_.visible = false;
}

The notice_ and overimmersion_ handling at the bottom of Pump() counts down the remaining display time of the regulatory notification banners. Chapter 4 explains it.

The following is an excerpt from src/main.cpp. After creating the window, it calls session.Begin(), processes callbacks with Pump() inside the loop, draws the game screen only when ready, and calls Shutdown() when the loop ends.

cpp
// Create the window and then call it. After that, the callback is received in `Stove_RunCallback` within `Pump()` every frame.
StoveSession session;
session.Begin(cfg, hwnd);

// ...

while (!quit)
{
    SDL_Event e;
    while (SDL_PollEvent(&e))
    {
        ImGui_ImplSDL3_ProcessEvent(&e);
        if (e.type == SDL_EVENT_QUIT)
            quit = true;
    }

    session.Pump(io.DeltaTime); // Calling Stove_RunCallback internally
    if (session.shouldQuit())   // When the launcher restarts the game
        break;

    // ... Drawing on the Screen ...
    if (!session.ready())
    {
        if (session.phase() == StoveSession::Phase::Failed)
        {
            ImGui::TextColored(ImVec4(1, 0.4f, 0.4f, 1), "SDK initialization failed");
            ImGui::TextWrapped("%s", session.error().c_str());
            ImGui::TextDisabled("Check that you launched via STOVE Launcher and that config/stove_config.ini is correct.");
        }
        else
        {
            ImGui::TextUnformatted("Initializing STOVE SDK...");
        }
    }
    else
    {
        // ... Menu, Game, Achievements, Leaderboards, Stats, Store, Inventory screens ...
    }
}

session.Shutdown();
  • The game loop runs even before initialization completes, because Pump() processes callbacks only while the loop runs. While initialization is in progress, only the "Initializing" message is shown.
  • If session.shouldQuit() is true, the launcher is restarting the game. End the loop immediately.
  • When the game ends, for example when the window is closed, the loop exits and session.Shutdown() is called.

Termination calls Stove_Uninitialize(), which StoveSession::Shutdown() handles.

cpp
void StoveSession::Shutdown()
{
    if (initialized_)
    {
        // It may take up to 3 seconds to finish reporting usage time. After that, Stove_RunCallback() is no longer called.
        StoveResultGuard result(Stove_Uninitialize());
        initialized_ = false;
    }
    phase_ = Phase::Idle;
}

Stove_Uninitialize() is a synchronous function. The new API has no per-module termination functions, so this one call terminates every feature.

  • Call it only once, when the game ends. Do not repeat initialization and termination while the game runs.
  • Call it only when initialized_ is true. Do not call it if initialization did not succeed or the flow ended with RestartRequired.
  • After the call, do not use SDK functions, and stop calling Stove_RunCallback().
  • Release the returned IStoveResult* as well. In the sample, StoveResultGuard releases it.
  • Since 3.5.3, Stove_Uninitialize() can take up to 3 seconds because it reports play time to the server. Call it when the game is closing, and since the screen may look frozen during that time, handle it as the game requires, for example by showing an exit screen first.

Handling Failures

SituationResultRecommended Handling
Launch check callback reports a failureTypically IpcConnectFailed(307) · IpcAesKeyNotReceived(308) · IpcTimeout(309)The game was started without the launcher, or communication with the launcher failed. SDK features do not work afterward, so notify the user and exit the game. Check the cause with GetResultCode() and GetErrorMessage(). Brick Smash shows the cause on screen with DescribeFailure().
IsRestartRequired() is trueSuccessThe launcher restarts the game. Exit the current process immediately. Initialization has not happened yet, so do not call Stove_Uninitialize().
Stove_Initialize() called without the launch checkNeedStoveLauncher(304), etc.Always call initialization from the launch check callback.
Stove_Initialize() failsFailure codeSome features may remain initialized. To retry, call Stove_Uninitialize() first and then Stove_Initialize().
Stove_Initialize() called again without terminationAlreadyInitialized(18)The failed features are not initialized again. Call Stove_Uninitialize() first, as above.
Ownership query reports a failureNetwork error, etc.Notify the user differently from the not-owned case. Query again or exit the game.
Base game not ownedQuery succeededShow that a purchase is required and exit the game.

Points to Note

Stove_RunCallback() must run in the game loop from right after Stove_RestartAppIfNecessary() is called. If the game blocks waiting for the callback before starting the loop, the callback never runs and initialization never starts.

Do not call other feature functions before Stove_Initialize() succeeds. Calling them before initialization fails with errors such as BaseNotInitialized(16). Brick Smash prevents this by not drawing feature screens until ready() is true.

Use only SANDBOX and LIVE as environment values. Make sure release builds set L"LIVE".

If Stove_Initialize() fails, clean up with Stove_Uninitialize() before retrying. Calling it again without cleanup returns AlreadyInitialized(18).

The list and items received in the callback become invalid when the callback ends. Copy the results into member variables and do not keep the IStoveOwnership* pointer.

3. Signature Verifier

STOVE Signature Verifier is a static library that counters tampering attacks that swap the PC SDK DLL. Every game that is sold must apply it. This chapter explains what the library checks, which files to pick and add to the project, and where to call it in code, along with the actual Brick Smash settings.

What Is Signature Verifier

  • A library distributed separately from the PC SDK. It supports both PC SDK 2.x and 3.x, so games integrated with the new C API apply it as is.
  • The only function to call is StartStoveVerify(), declared in the header StoveSignatureVerifier.h.
  • The function checks whether the DLLs used by the PC SDK are properly code-signed (digitally signed). Code signing is a digital signature that proves a DLL was distributed unmodified by a trusted publisher. If an unsigned DLL is found, the game is terminated immediately for security.

The following is the declaration in StoveSignatureVerifier.h included in the package.

cpp
#ifdef __cplusplus
extern "C" {
#endif

// StoveSignatureVerifier Library Functions
void StartStoveVerify();

#ifdef __cplusplus
}
#endif

What It Checks

The check is limited to the PC SDK DLLs distributed by STOVE. The library searches the folder of the game executable and its subfolders, finds the PC SDK DLLs included in the game, and checks them. For games integrated with the new C API, BaseSDK.dll is checked.

  • Game executables, DLLs built by the game, and engine or framework runtime DLLs are not checked. Applying this library therefore does not require code-signing the game's own binaries.
  • The check repeats periodically while the game runs, so a DLL replaced at run time is also detected.

If the PC SDK DLL cannot be found, it is treated the same as tampering and the game is terminated. Make sure BaseSDK.dll exists as an actual file in the executable folder or one of its subfolders in the packaged game.

Package Contents

Download the latest package from the PCSDK Download page or from the following link.

StoveSignatureVerifier_v1.0.5_x86_x64.zip

It contains libraries for every Visual Studio 2015 to 2026 toolset and runtime library. One package includes both 32-bit (Win32) and 64-bit (x64) libraries. The extracted package has the following structure.

text
Deploy
├ Include
│ └ StoveSignatureVerifier.h
└ Lib
  ├ Win32
  │ └ Release
  │   ├ MD
  │   │ ├ StoveSignatureVerifier_vs2015.lib
  │   │ ├ StoveSignatureVerifier_vs2017.lib
  │   │ ├ StoveSignatureVerifier_vs2019.lib
  │   │ ├ StoveSignatureVerifier_vs2022.lib
  │   │ └ StoveSignatureVerifier_vs2026.lib
  │   └ MT
  │     └ (same file layout as MD)
  └ x64
    └ Release
      ├ MD
      │ └ (same file layout as Win32)
      └ MT
        └ (same file layout as Win32)
  • Deploy/Include/StoveSignatureVerifier.h: The header file to include in the source code.
  • Lib/{architecture}/Release/{runtime}/StoveSignatureVerifier_{toolset}.lib: The static library file.

Choose the library by three criteria.

CriterionValueHow to Choose
ArchitectureWin32, x64Same as the game's target architecture
RuntimeMD, MTSame as the game's runtime library setting
Toolsetvs2015(v140), vs2017(v141), vs2019(v142), vs2022(v143), vs2026(v145)Same as the platform toolset of the game project

If no file matches the toolset, pick a library of a lower version than the game project's platform toolset. The linker can link only libraries built with the same or an older version, so picking a higher version can cause link errors (LNK2019, LNK1120).

This guide on the new C API covers only x64, so pick from Lib/x64/Release/. Brick Smash is an x64 sample built with Visual Studio 2022, so it uses the vs2022 library.

Project Settings

In a Visual Studio project, configure the settings in the following order.

  1. Create a StoveSignatureVerifier directory in the solution directory, and copy the Include and Lib directories under the package's Deploy into it.
  2. Add the header path to Configuration Properties > C/C++ > General > Additional Include Directories.
    text
    $(SolutionDir)StoveSignatureVerifier\Deploy\Include
    
  3. Add the library path to Configuration Properties > Linker > General > Additional Library Directories. The example below is for a project whose runtime library is MD. For MT, change the end of the path to MT. The path must go down to the runtime folder instead of ending at ...\Release.
    text
    $(SolutionDir)StoveSignatureVerifier\Deploy\Lib\$(Platform)\Release\MD
    
  4. Add the file name that matches the platform toolset to Configuration Properties > Linker > Input > Additional Dependencies. The example below is for Visual Studio 2022 (v143). Keep both this file and BaseSDK.lib in the additional dependencies.
    text
    StoveSignatureVerifier_vs2022.lib
    
  5. Check that Configuration Properties > C/C++ > Code Generation > Runtime Library matches the MD · MT chosen in step 3. If they differ, the link step fails with LNK2038.

To keep it out of development builds, apply these settings only to the Release configuration. Select Release in the configuration drop-down before entering them.

Brick Smash Settings

Brick Smash applies the same configuration to the Release configuration of its Visual Studio solution and to its CMake project. The following is an excerpt from CMakeLists.txt. The signature verification library is linked only in the Release configuration. It is not included in Debug builds for development.

cmake
set(STOVE_VERIFIER_DIR ${CMAKE_SOURCE_DIR}/third_party/StoveSignatureVerifier)

target_include_directories(BrickSmash PRIVATE
    ${CMAKE_SOURCE_DIR}/src
    ${STOVE_SDK_DIR}/Include
    ${STOVE_VERIFIER_DIR}/Include
)

target_link_libraries(BrickSmash PRIVATE
    SDL3::SDL3
    imgui::imgui
    ${STOVE_SDK_DIR}/lib/x64/BaseSDK.lib
    # The signature verification library is linked only in the Release configuration.
    $<$<CONFIG:Release>:${STOVE_VERIFIER_DIR}/Lib/StoveSignatureVerifier_vs2022.lib>
)
  • The header path is added to the include directories for every configuration. Including the header has no effect unless the library is linked.
  • $<$<CONFIG:Release>:...> is a CMake generator expression. It adds the inner file to the link list only when the build configuration is Release.
  • Brick Smash takes only StoveSignatureVerifier_vs2022.lib from the package and places it in third_party/StoveSignatureVerifier/Lib. This is a choice of the sample to keep the path short. To keep the package structure as is, point to Lib/x64/Release/MD as shown in the table above.

Call Location

Call StartStoveVerify() right at game startup, before any PC SDK function. Also wrap it in a preprocessor condition so that it is called only in release builds. The following is the beginning of main() in src/main.cpp.

cpp
#if defined(NDEBUG) || defined(_NDEBUG)
#include "StoveSignatureVerifier.h"
#endif

int main(int, char**)
{
#if defined(NDEBUG) || defined(_NDEBUG)
    // Signature verification is called only in release builds, before any other function in the PC SDK.
    StartStoveVerify();
#endif

    AppConfig cfg;
    cfg.Load("config/stove_config.ini");

    // ... Creating a window ...
    // Create the window and then call it. After that, the callback is received in `Stove_RunCallback` within `Pump()` every frame.
    StoveSession session;
    session.Begin(cfg, hwnd);
  • Wrap the header include and the function call in the same condition (NDEBUG or _NDEBUG). The CMake Release configuration defines NDEBUG, so the configuration that links the library matches the one that calls it. A mismatch can cause link errors.
  • StartStoveVerify() comes before session.Begin() from Chapter 2, that is, before Stove_RestartAppIfNecessary(). It is the first line of main().
  • Calling it from the entry point of the game executable is the safest.

Points to Note

Never use it in builds under development. Apply it only to release builds for official distribution.

If the PC SDK DLL cannot be found, it is treated the same as tampering and the game is terminated. Make sure the packaged release build folder contains BaseSDK.dll as an actual file.

A runtime library mismatch causes an LNK2038 error at the link step. The package contains libraries for both MT (static CRT) and MD (dynamic CRT), so pick the one that matches Configuration Properties > C/C++ > Code Generation > Runtime Library of the game project.

If no file has the same toolset name, pick a library of a lower version than the project's platform toolset. A higher version can cause link errors.

Frequently Asked Questions

Do the game executable and DLLs built by the game also need code signing

No. Only the PC SDK DLLs distributed by STOVE are checked; the game executable, DLLs built by the game, and engine or framework runtime DLLs are not. See What It Checks above for details.

Can StartStoveVerify() be called from a DLL instead of the game executable

Yes. The check is based on the folder of the running process's executable, not the location of the calling module, so the targets are found the same way wherever the DLL that links the library is located.

Keep the following two points in mind.

  • Do not call it from DllMain. StartStoveVerify() creates a verification thread and searches the file system. DllMain runs while the loader lock is held, so calling it there can deadlock. Call it from an initialization function that runs after the DLL is loaded.
  • When possible, call it from the entry point of the game executable. If the verification code lives in a separate module, it can be bypassed by not loading that module. If the executable can be built directly, calling it from the entry point is safer.

Which to choose, MT or MD

Choose the one that matches the Configuration Properties > C/C++ > Code Generation > Runtime Library setting of the game project. A different choice causes an LNK2038 error at the link step.

4. Shutdown · Game Time Limits

These features show notices that the laws of the service country require. This chapter integrates the shutdown (Game Time Selection System) notification and the Korean over-immersion notification. The Vietnam age rating and over-immersion notifications are covered in Chapter 7.

The code in this chapter comes from src/stove/StoveSession.cpp, src/stove/StoveSession.h, and src/ui/RegulationOverlay.cpp of Brick Smash.

Differences Between the Two Functions

FunctionTargetWhen the Callback ArrivesCallback Info
Stove_ShutdownNotificationAccounts under the Game Time Selection System (shutdown)Each time the end time approaches, and at the end timeIStoveShutdownInfo
Stove_OverImmersionNotificationUsers subject to Korean over-immersion preventionEvery hourIStoveOverImmersionInfo
  • Services in Korea must integrate over-immersion prevention. The Game Time Selection System must be integrated if the game is played by minors under 19.
  • Both are functions that register a callback to receive notifications. After one call, the SDK sends the callback to target users as many times as needed. Non-target users receive no callback or a failure result.
  • The SDK does not use the first argument, so pass nullptr. No parameter object is needed.

Call Order

  1. After Stove_Initialize() succeeds, call Stove_ShutdownNotification() and Stove_OverImmersionNotification() once each to register the callbacks.
  2. Each time a callback arrives in Stove_RunCallback() of the game loop, show the notice on screen with the delivered information.
  3. Callback information is valid only inside the callback, so copy the values needed for display into game variables.

Brick Smash registers these two functions in StoveSession::Initialize() from Chapter 2, right after initialization succeeds and after the user information and version are read. These are the two lines.

cpp
// 3) Register a regulatory notification callback. Once registered, the SDK will send a callback whenever necessary.
Stove_ShutdownNotification(nullptr, OnShutdownNotificationFinished, this);
Stove_OverImmersionNotification(nullptr, OnOverImmersionNotificationFinished, this);

this is passed as userData, and the callback retrieves StoveSession with GetUserData() and forwards the call to a member function. The following is the callback wiring in src/stove/StoveSession.cpp.

cpp
void __cdecl OnShutdownNotificationFinished(const IStoveCallbackResult* r, const IStoveShutdownInfo* info)
{
    Self(r)->OnShutdown(r, info);
}
void __cdecl OnOverImmersionNotificationFinished(const IStoveCallbackResult* r, const IStoveOverImmersionInfo* info)
{
    Self(r)->OnOverImmersion(r, info);
}

Storing Values to Display on the Screen

The callback runs inside Stove_RunCallback(), but the screen is drawn separately, so the received information is copied into a struct the screen can read. Brick Smash places NoticeState in src/stove/StoveSession.h. The shutdown and Korean over-immersion notifications share one banner, so they share one struct.

cpp
// Values for displaying regulatory notifications (shutdown · excessive use in Korea) on the screen.
struct NoticeState
{
    std::string message;      // Text provided by the SDK. The game does not modify it.
    float secondsLeft = 0.0f; // Remaining exposure time (seconds). If the value is 0 or less, hide it.
    bool blocksGame = false;  // If true, the user must confirm and then exit the game (shutdown time has been reached).
};
FieldValueUse
messageText of GetMsg() from the callback, converted to UTF-8Drawn on the banner as is.
secondsLeftGetExposureTime()Remaining display time of the banner. Decreased every frame, and the banner is hidden at 0 or below.
blocksGameWhether the shutdown time has been reachedIf true, the banner shows a confirmation button, and confirming it ends the game.

Shutdown Notification (Stove_ShutdownNotification)

Sends a notice to accounts under the Game Time Selection System as the end time approaches.

cpp
void Stove_ShutdownNotification(const IStoveTypeBase* param, OnShutdownNotificationCallback onFinished, void* userData);
typedef void(__cdecl* OnShutdownNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveShutdownInfo* shutdown);

The second callback argument IStoveShutdownInfo has the following methods.

MethodReturn TypeDescription
GetMsg()const wchar_t*Shutdown notice message.
GetExposureTime()int32_tMessage display time, in seconds.
GetInadvanceMinutes()int32_tTime left until shutdown, in minutes.
  • If GetInadvanceMinutes() is greater than 0, show a notice that play will be restricted in that many minutes.
  • If GetInadvanceMinutes() is 0, all available play time is used up. Show the notice, and end the game as soon as the user confirms it.
  • Use the text from GetMsg() as is. The game does not write its own text.

The following is StoveSession::OnShutdown().

cpp
void StoveSession::OnShutdown(const IStoveCallbackResult* r, const IStoveShutdownInfo* info)
{
    if (!r->GetResult()->IsSuccessful())
        return; // If the account is not subject to a shutdown, a failure message may appear. This is normal behavior.

    notice_.message = WideToUtf8(info->GetMsg());
    notice_.secondsLeft = static_cast<float>(info->GetExposureTime());
    // If the remaining time is 0, it means all available time has been used up. Once the user confirms this, the game ends.
    notice_.blocksGame = (info->GetInadvanceMinutes() <= 0);
}
  • On a failure result, it returns without doing anything. Accounts not subject to shutdown can receive a failure result, which is normal.
  • On success, it copies the text and display time into notice_. The text is used exactly as the SDK provides it.
  • If the remaining time is 0 or less, it sets blocksGame to true. All play time is used up, so the game must end after the user confirms.

Stove_ShutdownNotification is not Korea-only. It works the same for accounts under the Game Time Selection System even when they connect from abroad. Integrating the function alone does not deliver callbacks; the game must first be registered as a Game Time Selection System game. Contact technical support for registration.

Korean Over-Immersion Notification (Stove_OverImmersionNotification)

Sends an hourly warning message to users subject to Korean over-immersion prevention.

cpp
void Stove_OverImmersionNotification(const IStoveTypeBase* param, OnOverImmersionNotificationCallback onFinished, void* userData);
typedef void(__cdecl* OnOverImmersionNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveOverImmersionInfo* overImmersion);

The header labels it a Korea-only API. If the country determined from the connection IP (the GetNation value of Stove_GetGds) is not Korea, the call fails with NotSupportedCountry(31). This failure is a normal result, so do not present it as an error.

The second callback argument IStoveOverImmersionInfo has the following methods.

MethodReturn TypeDescription
GetMsg()const wchar_t*Over-immersion warning message.
GetElapsedHours()int32_tTime spent playing, in hours.
GetExposureTime()int32_tMessage display time, in seconds.

The following is StoveSession::OnOverImmersion().

cpp
void StoveSession::OnOverImmersion(const IStoveCallbackResult* r, const IStoveOverImmersionInfo* info)
{
    // For use in Korea only. Users in other countries will receive a "NotSupportedCountry (31)" error, which is normal.
    if (!r->GetResult()->IsSuccessful())
        return;

    notice_.message = WideToUtf8(info->GetMsg());
    notice_.secondsLeft = static_cast<float>(info->GetExposureTime());
    notice_.blocksGame = false;
}

The only difference from shutdown is that blocksGame is always false. The over-immersion warning only informs the user and does not end the game.

Show the over-immersion warning where the user can clearly see it on the game screen. Do not show it small in a corner or let other UI cover it. Use the GetMsg() text as is.

Counting Down the Display Time

The banner is shown for the GetExposureTime() seconds given by the callback. The callback does not report elapsed time, so the game decreases the remaining time every frame. Brick Smash does this in StoveSession::Pump().

cpp
void StoveSession::Pump(float dt)
{
    // All asynchronous callbacks are executed within this call, on this thread.
    Stove_RunCallback();

    if (notice_.secondsLeft > 0.0f && !notice_.blocksGame)
        notice_.secondsLeft -= dt;
    // ... See Chapter 7 of the Advanced Integration document for the remaining-time handling of the Vietnam over-immersion overlay ...
}
  • dt is the elapsed time (in seconds) since the previous frame.
  • While blocksGame is true, the time is not decreased. The notice that the shutdown time has been reached must stay until the user presses the confirmation button.
  • When a new callback arrives, OnShutdown() and OnOverImmersion() refill secondsLeft, and the banner appears again.

Drawing the Banner and Ending the Game

Drawing is done by DrawRegulationOverlays() in src/ui/RegulationOverlay.cpp, which main() calls every frame. The shutdown and over-immersion banner part is as follows.

cpp
void DrawRegulationOverlays(StoveSession& session, bool* requestQuit)
{
    // Shutdown and Excessive Use Alert Banners. Use the text exactly as provided by the SDK.
    const NoticeState& n = session.notice();
    if (n.secondsLeft > 0.0f || n.blocksGame)
    {
        ImGuiViewport* vp = ImGui::GetMainViewport();
        ImGui::SetNextWindowPos(ImVec2(vp->Size.x * 0.5f, 20.0f), ImGuiCond_Always, ImVec2(0.5f, 0.0f));
        ImGui::SetNextWindowSize(ImVec2(vp->Size.x * 0.8f, 0.0f));
        ImGui::PushStyleColor(ImGuiCol_WindowBg, ImVec4(0.7f, 0.1f, 0.1f, 0.95f));
        ImGui::Begin("##notice", nullptr,
                     ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoMove |
                     ImGuiWindowFlags_NoSavedSettings | ImGuiWindowFlags_AlwaysAutoResize);
        ImGui::TextWrapped("%s", n.message.c_str());
        if (n.blocksGame && ImGui::Button("OK"))
            *requestQuit = true;
        ImGui::End();
        ImGui::PopStyleColor();
    }
    // ... See Chapter 7 of the Advanced Integration document for drawing the Vietnam overlays ...
}
  • If display time remains or blocksGame is true, the banner is drawn at the top center of the screen. The red background makes it stand out, and it spans 80% of the screen width.
  • The text prints n.message as is. The game does not change the value provided by the SDK.
  • The confirmation button is drawn only when blocksGame is true. Pressing it sets *requestQuit = true, and main() receives this value as quit and ends the game loop. When the loop ends, session.Shutdown(), shown in Game Loop and Termination in Chapter 2, calls Stove_Uninitialize().

When the shutdown time is reached, the flow is as follows.

  1. When play time runs out, the SDK sends a callback with GetInadvanceMinutes() set to 0.
  2. OnShutdown() sets blocksGame to true and copies the text.
  3. The banner stays on screen and a confirmation button appears.
  4. When the user confirms, the game ends.

Summary

ItemContent
RegistrationCall once after Stove_Initialize() succeeds.
First argumentnullptr.
Callback countAfter one registration, the SDK sends callbacks as many times as needed.
ShutdownThe game must first be registered as a Game Time Selection System game. Not Korea-only. If GetInadvanceMinutes() is 0, show the notice and end the game.
Korean over-immersionKorea-only. Other countries fail with NotSupportedCountry(31), which is normal. Arrives every hour.
TextUse GetMsg() from the SDK as is.
Callback infoValid only inside the callback, so copy the values.

Games serving users in Vietnam must also integrate the age rating and over-immersion notifications. Chapter 7 explains them.

This completes the basic integration. To add the features your game needs, continue with Chapter 5 in Advanced Integration.

If you get stuck during integration, contact technical support.

Email : store.support@smilegate.com