# PC SDK Cocos2d-x Follow Through

An example to follow to learn how to apply STOVE PC SDK 2.0 to a Cocos2d-x based game.

Before proceeding with the following example, install STOVE Launcher (opens new window) and refer to Preparing SDK development environment to obtain the App key, App secret, Game Id.

# Downloading a Follow Through HelloStove Project

Download the Follow Through HelloStove Project from the link below.

Download HelloStove Project

We created the HelloStove project in Visual Studio 2015 Update 3, and we tested it to work correctly in Visual Studio 2019. Since the downloaded HelloStove project is the source code for sequentially explaining the STOVE PC SDK integrating method, we didn't integrate it with the SDK. From the following description, we will explain the SDK integration method sequentially.

# Configuring the project environment

Download the newest Native(C/C++) distributed files(stated as StovePCSDK from here on) from the Download page.
After unzipping the file, copy the contents to the HelloStove_Cocos2dx folder.

Run Visual Studio and open HelloStove_Cocos2dx.sln in the HelloStove_Cocos2dx\proj.win32 directory.

# 1)`Additional Included Directories` Settings

The following example is explained based on the win32/Release environment. Since win32/Debug is not supported, you may face problems if you follow the examples.

Add the path of StovePCSDK_{Version Number}/include to the project property page’s Additional Included Directories.

$(SolutionDir)..\StovePCSDK_2.1.0\include

# 2) `Additional Library Directories` Settings

Add the folder path of the StovePCSDK_{Version Number}/bin to the project property page’s Additional Library Directories.

$(SolutionDir)..\StovePCSDK_2.1.0\bin\$(Platform)\$(Configuration)

# 3) `Additional Dependencies` Settings

Add StovePCSDK.lib to the project property page’s Additional Dependencies.

StovePCSDK.lib

# 4) Including `StovePCSDK.h` to the Source File

Open the HelloStove.cpp file and add #include "StovePCSDK.h" as shown below.

#include "HelloStove.h"
#include "SimpleAudioEngine.h"

/*Add the 'Follow Through' code here.*/
#include "StovePCSDK.h"

1
2
3
4
5

# 5) Building

Run the Solution Build from the Build menu. If there are no problems in the settings, the build will be smooth without any compiling errors.
If a compilation error occurs, check the error message and check the path setting or Configuring the project environment again.

# SDK Initialization

To initialize PC SDK, fill in the values for StovePCConfig and StovePCCallback structures, and call the StovePC_Init function.
Enter the code below into the HelloStove::onClickedInit function.

void HelloStove::onClickedInit(Ref* pSender)
{
    /*Add the 'Follow Through' code here.*/

    //config
    StovePCConfig config;
    memset(&config, 0, sizeof(StovePCConfig));

    config.env = "LIVE";
    config.appKey = "YOUR_APP_KEY";
    config.secretKey = "YOUR_SECRET_KEY";
    config.gameId = L"YOUR_GAME_ID";
    config.logLevel = StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG;
    config.logPath = L"";

    //callback
    StovePCCallback callback;
    memset(&callback, 0, sizeof(StovePCCallback));

    callback.OnError = OnError;
    callback.OnInitComplete = OnInitComplete;
    callback.OnToken = OnToken;
    callback.OnUser = OnUser;

    StovePCResult result = StovePC_Init(config, callback);
    if (result != StovePCResult::STOVE_PC_NO_ERROR)
    {
        std::string error = StringUtils::format("[ERROR] StovePC_Init, Result: %d", result);
        logOutput(LogType::LogError, error);
    }
    else
    {
        std::string success = "[OK] StovePC_Init";
        logOutput(LogType::LogSuccess, success);

        //You have successfully called the StovePC_Init function.  
        //Now, regularly call the StovePC_RunCallback function.
        schedule(schedule_selector(HelloStove::updateTimer), 1.0f);
    }
}

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
35
36
37
38
39
40

Please change YOUR_APP_KEY, YOUR_SECRET_KEY, and YOUR_GAME_ID in the code above to the ID and Key values registered in advance in STOVE Studio. Also, if you call the StovePC_Init function without logging in to the stove launcher with the STOVE account applied for joining into STOVE Studio, error code 150 (sgup initialization failure) occurs.

If you call the StovePC_Init function successfully, it returnsSTOVE_PC_NO_ERROR. If it returns STOVE_PC_NO_ERROR successfully, the StovePC_RunCallback function should be called periodically through a timer. For this processing, set the callback HelloStove::updateTimer function that runs every 1 second with the schedule function, a timer of Cocos2d-x, and makes the StovePC_RunCallback function run periodically within the updateTimer part.

void HelloStove::updateTimer(float time)
{
    /*Add the 'Follow Through' code here.*/
    StovePC_RunCallback();
}

1
2
3
4
5

When the StovePC_Init function is executed normally, the callback OnInitComplete function that was hung in callback.OnInitComplete = OnInitComplete is executed. Uncomment this function and enter the code below.

void OnInitComplete()
{
    /*Add the 'Follow Through' code here.*/
    std::stringstream ss;
    ss << "<Init Complete>" << std::endl;

    GetHelloStove()->logOutput(LogType::LogNormal, ss.str(), 1);
}

1
2
3
4
5
6
7
8
9

Comment out the OnError function, which you call back when the StovePC_Init function or any other function’s call has failed, and input the code below.

void OnError(const StovePCError error)
{
    /*Add the 'Follow Through' code here.*/
    std::stringstream ss;
    ss << "<Error>" << std::endl
        << error.functionType << std::endl
        << error.result << std::endl
        << error.message << std::endl
        << error.externalError << std::endl;

    GetHelloStove()->logOutput(LogType::LogError, ss.str(), 5);
}

1
2
3
4
5
6
7
8
9
10
11
12

# SDK Termination

After you finish all use of the StovePCSDK function, enter the code below into the HelloStove::onClickedUnInitialize function to clean up the resources used in StovePCSDK and stop the timer set earlier.

void HelloStove::onClickedUnInitialize(Ref* pSender)
{
    /*Add the 'Follow Through' code here.*/
    StovePCResult result = StovePC_UnInit();
    if (result != StovePCResult::STOVE_PC_NO_ERROR)
    {
        std::string error = StringUtils::format("[ERROR] StovePC_UnInit, Result: %d", result);
        logOutput(LogType::LogError, error);
    }
    else
    {
        unschedule(schedule_selector(HelloStove::updateTimer));
        std::string success = "[OK] StovePC_UnInit";
        logOutput(LogType::LogSuccess, success);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Acquiring User Information

StovePCSDK's StovePC_GetUser function lets you get the information of the user who launched the game through the STOVE launcher. Enter the code below into the HelloStove::onClickedGetUser function to check how to use the StovePC_GetUser function.

void HelloStove::onClickedGetUser(Ref* pSender)
{
    /*Add the 'Follow Through' code here.*/
    StovePCResult result = StovePC_GetUser();
    if (result != StovePCResult::STOVE_PC_NO_ERROR)
    {
        std::string error = StringUtils::format("[ERROR] StovePC_GetUser, Result: %d", result);
        logOutput(LogType::LogError, error);
    }
    else
    {
        std::string success = "[OK] StovePC_GetUser";
        logOutput(LogType::LogSuccess, success);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

When you execute the StovePC_GetUser function correctly, it calls the callback OnUser function. You can obtain User information with the StovePCUser parameter. Check it with the code below.

void OnUser(const StovePCUser user)
{
    /*Add the 'Follow Through' code here.*/
    std::stringstream ss;
    ss << "<UserInfo>" << "\n"        
        << " memberNo: " << user.memberNo << "\n"
        << " nickname: " << g_converter.to_bytes(user.nickname) << "\n"       
        << " gameUserId: " << user.gameUserId << "\n";


    GetHelloStove()->logOutput(LogType::LogNormal, ss.str(), 5);
}

1
2
3
4
5
6
7
8
9
10
11
12

# Acquiring Token Information

This is used for acquiring the token information of logged in users. Input the code below into the HelloStoveDlg::OnClickedGetToken function.

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.

void HelloStove::onClickedGetToken(Ref* pSender)
{
    /*Add the 'Follow Through' code here.*/
    StovePCResult result = StovePC_GetToken();
    if (result != StovePCResult::STOVE_PC_NO_ERROR)
    {
        std::string error = StringUtils::format("[ERROR] StovePC_GetToken, Result: %d", result);
        logOutput(LogType::LogError, error);
    }
    else
    {
        std::string success = "[OK] StovePC_GetToken";
        logOutput(LogType::LogSuccess, success);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Suppose you usually call the StovePC_GetToken function. In that case, you can check the token value in the callback OnToken function with the code below.

void OnToken(const StovePCToken token)
{
    /*Add the 'Follow Through' code here.*/
    std::stringstream ss;
    ss << "<Token>" << "\n"
        << token.accessToken;

    GetHelloStove()->logOutput(LogType::LogNormal, ss.str(), 2);
}

1
2
3
4
5
6
7
8
9

# Build and Execute

To run HelloStove_Cocos2dx.exe after the build is completed, you need to copy the dynamic library (DLL) files in the StovePCSDK_{version number}\bin\Win32\Release folder to the HelloStove_Cocos2dx\proj.win32\Release.win32 folder.

When the file copy is complete, run the STOVE launcher and log in with the ID you signed up for in STOVE Studio. Now, press F5 in Visual Studio to build and run the HelloStove project. Press the buttons in order on the HelloStove screen to see if they usually work.

Congratulations!
You have completed integrating StovePCSDK with Cocos2d-x.