- Last Updated
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.
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
| File | Description |
|---|---|
Include/stove_api.h | The umbrella header. Including this one header brings in the public API of every module. |
Include/<module>_api.h | Function declarations of the module (e.g., Stove_FetchOwnerships). |
Include/<module>_types.h | Interfaces of the module (names starting with IStove) and callback types. |
Include/<module>_misc.h | Enumerations and result codes of the module. |
Include/<module>_flat_api.h | Declarations that flatten the interface methods into C functions. See Two Types of Calls. |
Include/base_guard.h | C++-only RAII helpers. Optional. See RAII Helpers. |
lib/x64/BaseSDK.lib | The import library to link. |
dll/x64/BaseSDK.dll | The 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 Settings | Value |
|---|---|
| Configuration Properties > C/C++ > General > Additional Include Directories | Path to the package's Include directory |
| Configuration Properties > Linker > General > Additional Library Directories | Path to the package's lib\x64 directory |
| Configuration Properties > Linker > Input > Additional Dependencies | BaseSDK.lib |
| Post-Build Event | Copy dll\x64\BaseSDK.dll to the folder of the executable |
In the source code, include only the umbrella header.
#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.
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.
| Item | Content |
|---|---|
| Deployment Files | One BaseSDK.dll and one BaseSDK.lib. Per-module DLL and LIB files are not added. |
| Header | Including only the umbrella header stove_api.h brings in the public API of every module. |
| Function | Every public function starts with Stove_. Module names are not part of function names (e.g., Stove_FetchOwnerships). |
| Data Types | Parameters 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 Termination | A 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 Handling | The 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.
- Call
Stove_CreateParam(kind)to create a parameter object. Pass the type value of the parameter to create (k_EStove*TypeKind_*Param) askind. - Check whether the return value is
nullptr. If the type value is invalid or not a parameter type,nullptris returned instead of an error. - The return type is
IStoveTypeBase*, so cast it to the parameter interface. - Fill in the values with the setters.
- Call the function.
- 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 Value | Interface Created | Used By |
|---|---|---|
k_EStoveBaseTypeKind_RestartAppIfNecessaryParam | IStoveRestartAppIfNecessaryParam | Stove_RestartAppIfNecessary |
k_EStoveBaseTypeKind_InitializeParam | IStoveInitializeParam | Stove_Initialize |
k_EStoveBaseTypeKind_SetGameProfileParam | IStoveSetGameProfileParam | Stove_SetGameProfile |
k_EStoveGameSupportTypeKind_FetchStatParam | IStoveFetchStatParam | Stove_FetchStat |
k_EStoveGameSupportTypeKind_SetStatParam | IStoveSetStatParam | Stove_SetStat |
k_EStoveGameSupportTypeKind_FetchAchievementParam | IStoveFetchAchievementParam | Stove_FetchAchievement |
k_EStoveGameSupportTypeKind_FetchAchievementsParam | IStoveFetchAchievementsParam | Stove_FetchAchievements |
k_EStoveGameSupportTypeKind_FetchRankingParam | IStoveFetchRankingParam | Stove_FetchRanking |
k_EStoveIAPTypeKind_FetchProductsParam | IStoveFetchProductsParam | Stove_FetchProducts |
k_EStoveIAPTypeKind_OrderProductParam | IStoveOrderProductParam | Stove_StartPurchase (order information for one product) |
k_EStoveIAPTypeKind_PurchaseParam | IStovePurchaseParam | Stove_StartPurchase (payment flow) |
k_EStoveIAPTypeKind_StartPurchaseParam | IStoveStartPurchaseParam | Stove_StartPurchase |
k_EStoveIAPTypeKind_ConfirmPurchaseParam | IStoveConfirmPurchaseParam | Stove_ConfirmPurchase |
k_EStoveLogTypeKind_SendLogParam | IStoveSendLogParam | Stove_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.
| Object | Example | Release |
|---|---|---|
Parameter created with Stove_CreateParam | IStoveInitializeParam* | The game calls Destroy() when the call returns. |
| Result returned by a synchronous function | IStoveResult* returned by Stove_Initialize · Stove_GetUser, etc. | The game calls Destroy() after checking it. |
| Object received through an out parameter | IStoveUser* of Stove_GetUser, IStoveGds* of Stove_GetGds, IStoveSignin* of Stove_GetSignin | Whether the call succeeds or fails, if it is not nullptr, the game calls Destroy() after reading the values. |
| Callback argument | IStoveCallbackResult*, the second callback argument (outcome · list · info object), and objects taken from them | Owned 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 callingDestroy()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.
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.
| Helper | Role |
|---|---|
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 ->. |
StoveResultGuard | Holds 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.
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.
// 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.
| Method | Return Type | Description |
|---|---|---|
IsSuccessful() | bool | true on success. |
GetResultCode() | uint32_t | The result code. 0 on success; on failure, a value that indicates the cause. |
GetMethodCode() | uint32_t | A 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.
| Method | Return Type | Description |
|---|---|---|
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_t | External 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.
| Code | Name | Meaning |
|---|---|---|
| 0 | k_EStoveCommonResultCode_Success | Success. |
| 1 | k_EStoveCommonResultCode_Fail | General failure. |
| 5 | k_EStoveCommonResultCode_InvalidParam | Invalid parameter. Also returned when a buffer is too small. |
| 16 | k_EStoveCommonResultCode_BaseNotInitialized | Called before the SDK was initialized. |
| 18 | k_EStoveCommonResultCode_AlreadyInitialized | Stove_Initialize was called again while already initialized. |
| 29 | k_EStoveCommonResultCode_AsyncOperationInProgress | The same asynchronous task is still in progress. |
| 31 | k_EStoveCommonResultCode_NotSupportedCountry | The feature is not supported in the user's country. |
| 249 | k_EStoveCommonResultCode_NetworkTransportError | Network transport error. GetExternalError() contains the transport layer error code. |
| 304 | k_EStoveResultCode_NeedStoveLauncher | The STOVE Launcher is required but not running. |
| 307 | k_EStoveResultCode_IpcConnectFailed | Communication with the launcher failed. |
| 308 | k_EStoveResultCode_IpcAesKeyNotReceived | Communication with the launcher failed. |
| 309 | k_EStoveResultCode_IpcTimeout | Communication 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.
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.
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.
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 objectuserDatapoints to must stay alive until the callback runs. Brick Smash passesStoveSessionandAppState, which live untilmain()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.
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
statusisIdleand setsstatustoLoading. - The callback gets the state struct pointer with
GetUserData(), copies the needed values immediately, and setsstatustoDoneorError. - 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.
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.
- Call
Stove_RunCallback()every frame in the game loop. - Call it on the main (UI) thread. The header states that it must be called on the main thread.
- Keep calling it from right after the first asynchronous function (
Stove_RestartAppIfNecessary) untilStove_Uninitialize()is called. - 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.
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 asconst wchar_t*and write literals asL"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 withDestroy()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.
// 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.
| Rule | Content |
|---|---|
Unit of length | The number of wchar_t characters, not bytes. Pass a buffer size that fits the terminating null character. |
Buffer is nullptr or length is 0 | Fails with k_EStoveCommonResultCode_InvalidParam(5). |
| Buffer too small | A 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.
// 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.
| Format | Example | Environment |
|---|---|---|
| Interface call format | result->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.
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.
#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
boolbut do not include<stdbool.h>themselves. C++ is not affected; only when building as pure C, include<stdbool.h>beforestove_api.h.
Summary
| Rule | One-Line Summary |
|---|---|
| Parameter | Create it with Stove_CreateParam() and release it when the call returns. StoveMakeParam<T>() releases it automatically. |
| Release | The game calls Destroy() on objects it receives, and does not release callback arguments. |
| Result | Always decide with IsSuccessful(). |
| Callback | Two arguments. Retrieve userData with GetUserData(), and copy values inside the callback. |
| Callback execution | Call Stove_RunCallback() on the main thread every frame. |
| String | wchar_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.
| Value | Setter | Description |
|---|---|---|
| Environment | IStoveRestartAppIfNecessaryParam::SetEnvironment | Use L"SANDBOX" during development and testing, and L"LIVE" in release builds. Not case-sensitive. |
| Game ID | IStoveRestartAppIfNecessaryParam::SetGameId | The game ID issued by STOVE Studio. |
| App Key | IStoveRestartAppIfNecessaryParam::SetAppKey | The app key issued by STOVE Studio. |
| Shop Key | IStoveInitializeParam::SetShopKey | Required 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.
[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.
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
- Create the launch check parameter with
Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam)and set the environment, game ID, and app key. - Call
Stove_RestartAppIfNecessary(). It is asynchronous, so the result arrives in a callback. Release the parameter when the call returns. - Start the game loop and call
Stove_RunCallback()every frame. This call is what runs the callback from step 2. - Check the result in the callback.
- On failure, notify the user and exit the game.
- If
outcome->IsRestartRequired()istrue, the launcher restarts the game, so exit the current process immediately. - If it is
false, continue to the next step.
- Create the initialization parameter with
Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam), and set the shop key and window handle if the game uses payment. - Call
Stove_Initialize(). It is synchronous, so check success right away with the returnedIStoveResult*. - After a successful initialization, read the user information with
Stove_GetUser()and the SDK version withStove_GetVersion(). - Fetch ownership with
Stove_FetchOwnerships()and decide whether the game was purchased in the callback. - Register the shutdown and over-immersion notification callbacks. Chapter 4 explains them.
- Run the game loop.
- Call
Stove_Uninitialize()when the game ends, and do not callStove_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.
// 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; }
// ...
};
| Phase | Meaning | Transition Condition |
|---|---|---|
Idle | Not started yet, or already terminated. | Calling Begin() changes it to RestartCheckPending. |
RestartCheckPending | Waiting 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. |
OwnershipPending | Initialization is done; waiting for the ownership callback. | Ready if the base game is owned, otherwise Failed. |
Ready | Everything is ready. The game screen is drawn. | |
RestartRequired | The launcher restarts the game. Exit immediately. | |
Failed | A 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.
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.
| Setter | Format | Description |
|---|---|---|
SetEnvironment | const wchar_t* | The environment value. Set L"SANDBOX" or L"LIVE". |
SetGameId | const wchar_t* | The game ID. |
SetAppKey | const wchar_t* | The app key. |
SetWaitTimeMilliSec | uint32_t | How long to wait (in milliseconds) when checking whether the game was launched by the launcher. 0 right after creation. |
SetLaunchStoveLauncher | bool | Whether to start the launcher when it is not running. false right after creation. |
SetPlatformName | const 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.
| Method | Return Type | Description |
|---|---|---|
IsRestartRequired() | bool | If 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.
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.
| Setter | Format | Description |
|---|---|---|
SetShopKey | const wchar_t* | The shop key. If set, Stove_Initialize() also initializes the payment feature. If empty, the payment feature is not initialized. |
SetMainWndHandle | const 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
SetShopKeyandSetMainWndHandle. 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 thatinitParamcan benullptr. Ownership, achievements, stats, leaderboards, logs, and regulatory notifications all still work.
Brick Smash uses payment, so it sets both.
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:
StoveResultGuardreceives theIStoveResult*returned byStove_Initialize(), andif (!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, callStove_Initialize()again after this cleanup. - The out parameter of
Stove_GetUser()is received throughPut()ofStoveGuard<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 intonickname_. - The
lengthargument ofStove_GetVersion()is 64, the number ofwchar_tcharacters, 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
- After
Stove_Initialize()succeeds, callStove_FetchOwnerships(nullptr, callback, userData). The SDK does not use the parameter argument, so passnullptr. - The callback runs in
Stove_RunCallback()of the game loop. - In the callback, iterate over
IStoveOwnershipListwithGetCount()·GetAt(i). - For each item, check the game ID, product category, and ownership status together.
- If ownership of the base game is not confirmed, handle it according to the game's policy.
Result Object
The callback type is OnOwnershipListCallback.
typedef void(__cdecl* OnOwnershipListCallback)(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships);
IStoveOwnershipList is a list of ownership entries.
| Method | Return Type | Description |
|---|---|---|
GetCount() | uint32_t | Number of items. |
GetAt(uint32_t index) | const IStoveOwnership* | The item at index. nullptr if out of range. |
Each IStoveOwnership item has the following values.
| Method | Return Type | Description |
|---|---|---|
GetGameId() | const wchar_t* | STOVE game ID linked to this item. |
GetGameCode() | int32_t | Product category. An EStoveOwnershipGameCode value. |
GetOwnershipCode() | int32_t | Ownership status. An EStoveOwnershipCode value. |
GetPurchaseDate() | uint64_t | Purchase time, in Unix epoch milliseconds (UTC). |
The ownership status values (EStoveOwnershipCode) are as follows. Acquire is the only value treated as owned.
| Value | Name | Meaning |
|---|---|---|
| 0 | k_EStoveOwnershipCode_None | No recorded ownership status. Treat as not owned. |
| 1 | k_EStoveOwnershipCode_Acquire | Currently owned. |
| 2 | k_EStoveOwnershipCode_Lose | Ownership 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.
| Value | Name | Meaning |
|---|---|---|
| 0 | k_EStoveOwnershipGameCode_None | Not a product item, or no category assigned. |
| 3 | k_EStoveOwnershipGameCode_Basic | Base game. |
| 4 | k_EStoveOwnershipGameCode_Demo | Demo build. |
| 5 | k_EStoveOwnershipGameCode_Dlc | DLC 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.
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. TreatNoneandLose(refund, etc.) as not owned. - Check the game ID and product category together. The base game is the
Basicitem that matchesgame_idin the configuration file, and the DLC is theDlcitem that matchesdlc_game_id. - Handle a failed query (
IsSuccessful()isfalse) separately from not owning the game. Brick Smash setsFailedin both cases but shows different messages. - Copy the results into
ownsBaseGame_andownsDlc_, and do not keep theIStoveOwnership*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".
// 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
Failedand 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_Demoitem. - 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.
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.
// 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()istrue, 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.
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_istrue. Do not call it if initialization did not succeed or the flow ended withRestartRequired. - After the call, do not use SDK functions, and stop calling
Stove_RunCallback(). - Release the returned
IStoveResult*as well. In the sample,StoveResultGuardreleases 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
| Situation | Result | Recommended Handling |
|---|---|---|
| Launch check callback reports a failure | Typically 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 true | Success | The 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 check | NeedStoveLauncher(304), etc. | Always call initialization from the launch check callback. |
Stove_Initialize() fails | Failure code | Some features may remain initialized. To retry, call Stove_Uninitialize() first and then Stove_Initialize(). |
Stove_Initialize() called again without termination | AlreadyInitialized(18) | The failed features are not initialized again. Call Stove_Uninitialize() first, as above. |
| Ownership query reports a failure | Network error, etc. | Notify the user differently from the not-owned case. Query again or exit the game. |
| Base game not owned | Query succeeded | Show that a purchase is required and exit the game. |
Points to Note
Stove_RunCallback()must run in the game loop from right afterStove_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 asBaseNotInitialized(16). Brick Smash prevents this by not drawing feature screens untilready()istrue.
Use only
SANDBOXandLIVEas environment values. Make sure release builds setL"LIVE".
If
Stove_Initialize()fails, clean up withStove_Uninitialize()before retrying. Calling it again without cleanup returnsAlreadyInitialized(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 headerStoveSignatureVerifier.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.
#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.dllexists 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.
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.
| Criterion | Value | How to Choose |
|---|---|---|
| Architecture | Win32, x64 | Same as the game's target architecture |
| Runtime | MD, MT | Same as the game's runtime library setting |
| Toolset | vs2015(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.
- Create a
StoveSignatureVerifierdirectory in the solution directory, and copy theIncludeandLibdirectories under the package'sDeployinto it. - Add the header path to
Configuration Properties > C/C++ > General > Additional Include Directories.text$(SolutionDir)StoveSignatureVerifier\Deploy\Include - 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 toMT. The path must go down to the runtime folder instead of ending at...\Release.text$(SolutionDir)StoveSignatureVerifier\Deploy\Lib\$(Platform)\Release\MD - 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 andBaseSDK.libin the additional dependencies.textStoveSignatureVerifier_vs2022.lib - Check that
Configuration Properties > C/C++ > Code Generation > Runtime Librarymatches theMD·MTchosen 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.
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.libfrom the package and places it inthird_party/StoveSignatureVerifier/Lib. This is a choice of the sample to keep the path short. To keep the package structure as is, point toLib/x64/Release/MDas 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.
#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 (
NDEBUGor_NDEBUG). The CMake Release configuration definesNDEBUG, so the configuration that links the library matches the one that calls it. A mismatch can cause link errors. StartStoveVerify()comes beforesession.Begin()from Chapter 2, that is, beforeStove_RestartAppIfNecessary(). It is the first line ofmain().- 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.dllas 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 Libraryof 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.DllMainruns 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
| Function | Target | When the Callback Arrives | Callback Info |
|---|---|---|---|
Stove_ShutdownNotification | Accounts under the Game Time Selection System (shutdown) | Each time the end time approaches, and at the end time | IStoveShutdownInfo |
Stove_OverImmersionNotification | Users subject to Korean over-immersion prevention | Every hour | IStoveOverImmersionInfo |
- 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
- After
Stove_Initialize()succeeds, callStove_ShutdownNotification()andStove_OverImmersionNotification()once each to register the callbacks. - Each time a callback arrives in
Stove_RunCallback()of the game loop, show the notice on screen with the delivered information. - 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.
// 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.
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.
// 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).
};
| Field | Value | Use |
|---|---|---|
message | Text of GetMsg() from the callback, converted to UTF-8 | Drawn on the banner as is. |
secondsLeft | GetExposureTime() | Remaining display time of the banner. Decreased every frame, and the banner is hidden at 0 or below. |
blocksGame | Whether the shutdown time has been reached | If 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.
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.
| Method | Return Type | Description |
|---|---|---|
GetMsg() | const wchar_t* | Shutdown notice message. |
GetExposureTime() | int32_t | Message display time, in seconds. |
GetInadvanceMinutes() | int32_t | Time 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().
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
blocksGametotrue. All play time is used up, so the game must end after the user confirms.
Stove_ShutdownNotificationis 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.
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.
| Method | Return Type | Description |
|---|---|---|
GetMsg() | const wchar_t* | Over-immersion warning message. |
GetElapsedHours() | int32_t | Time spent playing, in hours. |
GetExposureTime() | int32_t | Message display time, in seconds. |
The following is StoveSession::OnOverImmersion().
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().
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 ...
}
dtis the elapsed time (in seconds) since the previous frame.- While
blocksGameistrue, 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()andOnOverImmersion()refillsecondsLeft, 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.
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
blocksGameistrue, 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.messageas is. The game does not change the value provided by the SDK. - The confirmation button is drawn only when
blocksGameistrue. Pressing it sets*requestQuit = true, andmain()receives this value asquitand ends the game loop. When the loop ends,session.Shutdown(), shown in Game Loop and Termination in Chapter 2, callsStove_Uninitialize().
When the shutdown time is reached, the flow is as follows.
- When play time runs out, the SDK sends a callback with
GetInadvanceMinutes()set to 0. OnShutdown()setsblocksGametotrueand copies the text.- The banner stays on screen and a confirmation button appears.
- When the user confirms, the game ends.
Summary
| Item | Content |
|---|---|
| Registration | Call once after Stove_Initialize() succeeds. |
| First argument | nullptr. |
| Callback count | After one registration, the SDK sends callbacks as many times as needed. |
| Shutdown | The 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-immersion | Korea-only. Other countries fail with NotSupportedCountry(31), which is normal. Arrives every hour. |
| Text | Use GetMsg() from the SDK as is. |
| Callback info | Valid 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