STOVE Store Developer Guide alpha

# PC SDK Cocos2d-x Integration Guide

# Introduction

The STOVE platform for indie games provides integrated services. All processes of game release, including game distribution and sales, community, and indicator analysis, can be handled in one-stop. Using PC SDK allows you to easily integrate the services provided by the STOVE Platform with the game.

This describes how to integrate PC SDK to Cocos2dx.

confirm If this is the first time you are trying to integrate PC SDK, please read the PC SDK Cocos2d-x Follow Through first.

# Preparations

  • Check that you have issued the stove subscription account and the App key, App secret, and Game Id for the released game from STOVE Studio (opens new window).
  • Check if a version of Visual Studio 2015 Update 3 or higher is installed.
  • Download the newest Native(C/C++) distributed files(stated as StovePCSDK from here on) from the PC SDK Download page.

# StovePCSDK Distributed File Configuration

# 1) include Folder

The files below can be found in the include folder when you download and unzip StovePCSDK.

  • StovePCDefine.h
    API call result (StovePCResult), error result structure (StovePCError), callback function, API structure parameter, etc. used for communication between game project and PC SDK are declared.

  • StovePCSDK.h
    Declare API function prototypes used for communication between the game and the PC SDK.

# 2) bin Folder

Binaries required for each platforms(Win32/x64) and configurations(Debug/Release) are included in the bin folder.

  • concrt140.dll
  • msvcp100.dll
  • msvcp140.dll
  • msvcr100.dll
  • sgup_api(64).dll
  • StovePCSDK.dll
  • vcruntime140.dll

confirm Except for StovePCSDK.lib, you need to include the DLL files listed above when distributing the game client to end-users.

# 3) sample folder

The sample folder includes the StovePCSDKTestMfc.exe GUI application to check the operation of StovePCSDK as a Release build for each platform (Win32/x64). First, enter the App key and App secret in the StovePCConfig.MFC.ini file, and then run StovePCSDKTestMfc.exe. In addition, by directly executing StovePCSDKTestMfc, you can directly input AppKey, SecretKey, etc. in the Setting UI.

# Configuring StovePCSDK Build Settings

Refer to the Configuring Project Settings in the PC SDK Cocos2d-x Follow Through for configuring build settings.

# Integrate

# 1) Config, Callback Settings

To initialize PC SDK, start with filling in the values for the StovePCConfig and StovePCCallback structures, and calling the StovePC_Init function.
Refer to the code below to fill in each field values within the StovePCConfig structure.

StovePCConfig config{"live",
                    "YOUR_APP_KEY",
                    "YOUR_SECRET_KEY",
                    "YOUR_GAME_ID",
                    StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG,
                    ""};
1
2
3
4
5
6

Refer to the StovePCDefine.h file for details regarding the StovePCConfig structure.

Communication between the game and the PC SDK uses callback functions connected to the StovePCCallback structure. In the game code, you need to define the function pointer to connect to the callback pointer of the StovePCCallback structure below in advance. The pointer of the specified function should be connected.

struct StovePCCallback
{

    /// Callback for StovePCSDK errors
    void(*OnError)(const StovePCError error);
    
    /// Callback for completing PC SDK initialization 
    void(*OnInitComplete)(); 
    
    /// Callback for completing GetToken process 
    void(*OnToken)(const StovePCToken token); 
    
    /// Callback for completing GetUser process 
    void(*OnUser)(const StovePCUser user); 
    
    /// Callback for completing GetOwnership process 
    void(*OnOwnership)(int size, StovePCOwnership* ownership);
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

NULL initialization is required before using the StovePCCallback structure’s instance.

/* Create StovePCCallback structure instance*/
StovePCCallback callback;
/* Initialize all function pointers to NULL*/
memset(&callback, 0, sizeof(StovePCCallback));
/* Connect configured function pointers*/
callback.OnError = OnMyErrorCallback;
callback.OnInitComplete = OnMyInitCompleteCallback;
callback.OnToken = OnMyTokenCallback;
callback.OnUser = OnMyUserInfoCallback;
callback.OnOwnership = OnMyOwnershipCallback;
1
2
3
4
5
6
7
8
9
10

The OnError, OnInitComplete and OnOwnership callback functions must work together. You can integrate the rest of the callback functions only when necessary. For example, suppose you only use the Ownership function. In that case, you can implement it as shown below.

/*When only the ownership feature is being used, 
only the OnOwnership callback is essential 
On top of the essential callbacks, OnError and OnInitcomplte.*/
callback.OnError = OnMyErrorCallback;
callback.OnInitComplete = OnMyInitCompleteCallback;
callback.OnOwnership = OnMyOwnershipCallback;
1
2
3
4
5
6

# 2) SDK Initialization

When you complete StovePCConfig and StovePCCallback structure initialization and callback function connection, call the StovePC_Init function to initialize PC SDK.

StovePCResult result = StovePC_Init(config, callback);
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*StovePCSDK init success.    
    Call StovePC_RunCallback at regular intervals using timers, etc.*/

}
1
2
3
4
5
6
7

After the StovePC_Init function checks only the config and callback validity, it immediately returns the type value of the StovePCResult enum.
In case of success, it returns a value of STOVE_PC_NO_ERROR. In case of failure, it returns the corresponding error code, and you need to quit the game.
Check the StovePCResult enum in the StovePCDefine.h file for a complete list of error codes.

If the returned value is STOVE_PC_NO_ERROR, therefore, a 'success', regularly call the StovePC_RunCallback function.
StovePC_RunCallback function must be regularly called to normally call the connected callback.
The callback response speed slows down if the call cycle is long, so it is better to maintain an appropriate call cycle. The example code in this guide sets the call period to 0.5 seconds.

confirm Callbacks connected to PC SDK are called only from the thread calling the StovePC_RunCallback function.

Cocos2dx can use a schedule function (opens new window) to process necessary work on a regular cycle.
The sample below is a code that calls the StovePC_RunCallback every second.

StovePCResult result = StovePC_Init(config, callback); 
if (result == StovePCResult::STOVE_PC_NO_ERROR) 
{ 
    /*If the PC SDK initialization was successful, run the scheduler so that the updateTimer function is called every second*/ 
    schedule(schedule_selector(StartScene::updateTimer), 1.0f);
}
... 
void StartScene::updateTimer(float time) 
{ 
    StovePC_RunCallback();
}
1
2
3
4
5
6
7
8
9
10
11
12

The StovePC_Init function processes unsynchronized procedures excluding the config and callback validity check.
The OnInitComplete callback is called if the unsynchronized procedures are successful, and the OnError callback is called if an error occurs.
In case of an error, the error code and message can be checked through the delivered StovePCError structure.

void OnInitComplete()
{
    printf("pc sdk init success");
}

void OnError(const StovePCError error)
{
	switch (Error.functionType)
	{
	case STOVE_PC_INIT:
	case STOVE_PC_GET_USER:
	case STOVE_PC_GET_OWNERSHIP:
		QuitApplicationDueToError();
		break;
	}
}

void QuitApplicationDueToError()
{
        // After showing the user a message about app outage rather than stopping it immediately
        // Depending on user action (e.g. clicking the exit button), you may want to terminate the app.
        // If so, implement your own logic.
        // Recommended messages for required pre-task errors are as follows.
        // Korean: The required pre-task failed to operate and the game has been terminated.
        // Other Languages: The required pre-task fails and exits the game.
	OnStoveLog("QuitApplicationDueToError");
	OnStoveLog("QuitApplicationDueToError");
	exit(0)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 3) Cautions when synchronizing the SDK

confirm When setting the log level of the StovePCConfig structure, set it as StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG value when testing, and set it as StovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR value at the time of official release.

confirm If the GetToken, GetUser, GetOwnership methods are called before initialization is complete, it may not return normal results. In other words, you must call the GetToken, GetUser, GetOwnership methods after the callback of OnInitComplete has been received to receive normal results.

# 4) SDK Termination

After using PC SDK, call the StovePC_UnInit function to clean up resources in use.

StovePCResult result = StovePC_UnInit();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*Processed as a success*/
}
...
1
2
3
4
5
6

# 5) Acquiring User Information

Use the StovePC_GetUser function to retrieve the logged-in user information in STOVE Launcher.

StovePCResult result = StovePC_GetUser();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*Processed as a success*/
}
1
2
3
4
5

If the StovePC_GetUser function is normally processed, the OnUser callback is called.
The user’s member no, nickname, Game User ID information can be viewed through the StovePCUser structure delivered by the callback.
We describe the StovePCUser structure in the StovePCDefine.h file.

void OnUser(const StovePCUser user)
{
    /*Display User Information*/
    printf("User Info(memberNo = %I64d, nickname = %S, gameUserId = %s)",
                      user.memberNo, user.nickname, user.gameUserId);
}
1
2
3
4
5
6

# 6) Acquiring Token Information

With the StovePC_GetToken function, you can check the token information of the user who has logged into the STOVE launcher.

StovePCResult result = StovePC_GetToken();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*Processed as a success*/
}
1
2
3
4
5

If the StovePC_GetToken function is normally processed, the OnToken callback is called.
The StovePCToken structure delivered by the callback includes the token string.

void OnToken(const StovePCToken token)
{
    /*Display Token Information*/
    printf("Token : %s", token.accessToken);
}
1
2
3
4
5

confirm What is a token? It is the access token of the logged-in user in STOVE Launcher, and the game server passes this access token to the stove authentication server to validate the logged-in user.
For a detailed explanation of Access Token, please get in touch with Contact Stove Indie Team (opens new window) for technical support.

# 7) Acquiring Ownership Information

The StovePC_GetOwnership function lets you check whether the user has purchased and owns the game.


StovePCResult result = StovePC_GetOwnership();
if (result == STOVE_PC_NO_ERROR)
{
    /*Processed as a success*/ 
    /*Ownership information is delivered as the OnOwnership callback.*/
}
1
2
3
4
5
6
7

If the StovePC_GetOwnership function is normally processed, the OnOwnership callback is called.
For details on the StovePCOwnership structure, which is a parameter of the OnOwnership callback, refer to the StovePCDefine.h file.

The sample below is a code that checks if the game has been purchased through the OnOwnership callback. If the game is without DLC, the confirmation code for lines 20 to 23 is unnecessary.

void OnOwnership(int size, StovePCOwnership* ownership)
{
    bool owned = false;
 
    StovePCOwnership* data = ownership;
    for (int i = 0; i < size; i++, data++)
    {
        if ((data->memberNo != LOGIN_USER_MEMBER_NO /*StovePCUser structure's memberNo*/)
            || (data->ownershipCode != 1 /*1:Ownership acquired, 2:Ownership disabled(in case the purchase has been canceled)*/))
        {
            continue;
        }

        if (0 == wcscmp(L"YOUR_GAME_ID", data->gameId) && data->gameCode == 3 /* 3: Package game*/)
        {
            owned = true; // Set ownership verification variable to true
        }

        /*Necessary only if it is a package game that has DLCs*/
        if (0 == wcscmp(L"YOUR_DLC_ID", data->gameId) && data->gameCode == 5 /* 5: DLC*/)
        {
            /*Process for users who have purchased YOUR_DLC_ID(DLC)*/
        }
    }

     if(owned)
    {
        // Write game entry logic after ownership verification is usually completed
    }
    else
    {
        // After ownership verification fails, end the game and write an error message display logic
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
  • After running the game exe, users who own the game can play.
  • Users who don't own the game cannot play, and please show the following message.
    • "Please log in to STOVE Client with the account that has purchased the game."

# How to Use Additional Service

Cloud Storage(In Development)

# Checking Errors

Errors occurring during PC SDK use can be divided into two big categories.

# StovePCResult enum value returned after calling the function

All PC SDK’s functions will return a StovePCResult enum value immediately after calling, to mark whether the call was successful.
The entire value can be checked in the PC SDK Error Code page.

# StovePCError Structure Delivered Through OnError callbacks

If an error occurs in an unsynchronized function among the PC SDK functions, the OnError callback is called, and a StovePCError structure including the description of the error is delivered.

/*Delivered when the OnError callback is called.*/
struct StovePCError
{
    /*Enum value showing the called function*/
    StovePCFunctionType functionType;


    /*Enum value showing the error type*/ 
    StovePCResult result; 
    
    /*Error message*/ 
    char* message; 
    
    /*Error codes for external errors(http error, external module error)*/ 
    int externalError;

};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Last Updated: 8/22/2023, 1:49:10 AM