PC SDK provides API to integrate the Stove platform’s game support service into the game. The game support service supported by the PC SDK includes stats, achievements, and leaderboards. Each service is defined as follows:
•
Stats: A service that records the user’s various game play data in numerical terms
•
Achievements: A service that sets gameplay challenges and provides user-specific achievement information
•
Leaderboard: A service that provides user ranking information of specific game play data
In order to use the PC SDK game support service API, metadata registration for game support services must be conducted first through the studio.
1. Callback Settings
To communicate with the PC SDK using the game support service API, the game should define a callback function to connect to the callback pointer of the StovePCCallback structure below.
struct StovePCCallback
{
void(*OnError)(const StovePCError error);
void(*OnInitComplete)();
void(*OnToken)(const StovePCToken token);
void(*OnUser)(const StovePCUser user);
void(*OnOwnership)(int size, StovePCOwnership* ownership);
// Callback that is called when GetStat has been completed
void(*OnStat)(const StovePCStat stat);
// Callback that is called when SetStat has been completed
void(*OnSetStat)(const StovePCStatValue statValue);
// Callback that is called when GetAchievement has been completed
void(*OnAchievement)(StovePCAchievement achievement);
// Callback that is called when GetAllAchievement has been completed
void(*OnAllAchievement)(int size, StovePCAchievement* achievement);
// Callback function pointer received when calling GetRank API
void(*OnRank)(int size, StovePCRank* rank, unsigned int rankTotalCount);
};
C++
복사
Connect the callback function to the callback of the StovePCCallback structure as in Integration 1) Config, Callback Settings.
// Create StovePCCallback structure instance
StovePCCallback callback;
// Initialize every function pointer with NULL
memset(&callback, 0, sizeof(StovePCCallback));
// Connect the implemented function pointer
callback.OnError = OnMyErrorCallback; /*Globally defined callback function*/
callback.OnInitComplete = OnMyInitCompleteCallback; /*Globally defined callback function*/
callback.OnToken = OnMyTokenCallback; /*Globally defined callback function*/
callback.OnUser = OnMyUserInfoCallback; /*Globally defined callback function*/
callback.OnOwnership = OnMyOwnershipCallback; /*Globally defined callback function*/
// Game support service
callback.OnStat = OnMyStat; /*Globally defined callback function*/
callback.OnSetStat = OnMySetStat; /*Globally defined callback function*/
callback.OnAchievement = OnMyAchievement; /*Globally defined callback function*/
callback.OnAllAchievement = OnMyAllAchievement; /*Globally defined callback function*/
callback.OnRank = OnMyRank; /*Globally defined callback function*/
C++
복사
You do not need to implement the callbacks other than OnStat, OnSetStat, OnAchievement, OnAllAchievement, and OnRank.
You only need to implement and connect callback functions necessary for the game support service used in the game.
2. Update User Stats
Update specific stats in the game for a logged in user with the StovePC_SetStat function.
// Input parameters
// const char* statId : Stat identifier registered in the studio
// const int statValue : Stat value to be updated
StovePCResult result = StovePC_SetStat("STAT_ID", STAT_VALUE);
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
C++
복사
The OnSetStat callback is called when the StovePC_SetStat function is processed properly.
The StovePCStatValue structure delivered to the callback contains a flag indicating the current stat value, update status and error messages.
If the stat value is fully reflected and updated, the Updated field will contain ‘true’ and the ErrorMessage field will contain an empty string. If the stat value is partially updated, the Updated field will contain ‘true’ and the ErrorMessage field will contain a string such as “integer overflow”.
For example, assuming that the current stat value of the INCREMENT type is 2,147,483,000 and you try to add 1,000 through the StovePC_SetStat API, it will become out of range of the values that the Int32 type can have, and when it is updated to 2,147,483,647 which is the maximum value of the Int32 type, reflecting only part of the value (1,000), the ErrorMessage field will contain a string such as “integer overflow”.
The table below lists the results that can be obtained through the StovePCStatValue structure.
Stat Type | Updated | ErrorMessage | Result |
All Types | True | “”(Empty string) | Requested value is fully updated to current value |
INCREMENT | True | "integer overflow" | Storage space exceeded, partial update |
INCREMENT | False | "integer overflow" | Storage space exceeded, no update |
MIN | False | “”(Empty string) | Requested value larger than current value |
MAX | False | “”(Empty string) | Requested value smaller than current value |
REPLACE | Fasle | “”(Empty string) | Requested value same as current value |
void OnSetStat(const StovePCStatValue statValue)
{
// Display stat update result information
printf("OnSetStat");
printf(" - statValue.currentValue : %d", statValue.currentValue);
printf(" - statValue.updated : %s", statValue.updated ? "true" : "false");
printf(" - statValue.errorMessage : %s", statValue.errorMessage);
}
C++
복사
Caution) The valid range of the callback parameter StovePCStatValue structure is limited to the scope of the callback function. The PC SDK releases internally allocated memory as soon as execution of the callback function is completed. Therefore, if storage is required to use information of the StovePCStatValue structure outside of the scope of the callback function, a copy must be created through Deep Copy, and the memory must be released when use of the copy is completed.
If an error occurs while the StovePC_SetStat function is running, the ‘OnError’ callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
2000 | Invalid Access |
3000 | Wrong API Usage |
4000 | Stats ID Not Found |
9000 | Service Error |
3. Get User Stat Information
Use the StovePC_GetStat function to retrieve specific game stat information for a logged in user.
// Input parameters
// const char* statId : Stat identifier registered in the studio
StovePCResult result = StovePC_GetStat("STAT_ID");
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
C++
복사
The OnStat callback is called when the StovePC_GetStat function is processed properly.
The StovePCStat structure delivered to the callback contains the current stat value.
void OnStat(const StovePCStat stat)
{
// Display stat info
printf("OnStat");
wprintf(L" - stat.statFullId.gameId : %s", stat.statFullId.gameId);
printf(" - stat.statFullId.statId : %s", stat.statFullId.statId);
printf(" - stat.memberNo : %llu", stat.memberNo);
printf(" - stat.currentValue : %d", stat.currentValue);
printf(" - stat.updatedAt : %llu", stat.updatedAt);
}
C++
복사
Caution) The valid range of the callback parameter StovePCStat structure is limited to the scope of the callback. The PC SDK releases internally allocated memory as soon as execution of the callback is completed. Therefore, if storage is required to use information of the StovePCStat structure outside of the scope of the callback, a copy must be created through Deep Copy, and the memory must be released when use of the copy is completed.
If an error occurs while the StovePC_GetStat function is running, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
2000 | Invalid Access |
3000 | Wrong API Usage |
4000 | Stats ID Not Found |
9000 | Service Error |
4. Get User Single Achievement Information
Use the StovePC_GetAchievement function to retrieve specific game single achievement information for a logged in user.
// Input parameters
// const char* achievementId : Achievement identifier created in the studio
StovePCResult result = StovePC_GetAchievement("ACHIEVEMENT_ID");
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
C++
복사
The OnAchievement callback is called when the StovePC_GetAchievement function is processed properly.
The StovePCAchievement structure delivered to the callback contains the current achievement value, achievement status, and achievement metadata.
void OnAchievement(const StovePCAchievement achievement)
{
// Display single achievement information
printf("OnAchievement");
printf(" - achievement.achievementId : %s", achievement.achievementId);
wprintf(L" - achievement.name : %s", achievement.name);
wprintf(L" - achievement.description : %s", achievement.description);
wprintf(L" - achievement.defaultImage : %s", achievement.defaultImage);
wprintf(L" - achievement.achievedImage : %s", achievement.achievedImage);
printf(" - achievement.condition.goalValue : %d", achievement.condition.goalValue);
printf(" - achievement.condition.valueOperation : %s", achievement.condition.valueOperation);
printf(" - achievement.condition.type : %s", achievement.condition.type);
printf(" - achievement.value : %d", achievement.value);
printf(" - achievement.status : %s", achievement.status);
}
C++
복사
Caution) The valid range of the callback parameter StovePCAchievement structure is limited to the scope of the callback. The PC SDK releases internally allocated memory as soon as execution of the callback is completed. Therefore, if storage is required to use information of the StovePCAchievement structure outside of the scope of the callback, a copy must be created through Deep Copy, and the memory must be released when use of the copy is completed.
If an error occurs while the StovePC_GetAchievement function is running, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
1200 | Not found achievement |
9000 | Service Error |
5. Get All User Achievement Information
Use the StovePC_GetAllAchievement function to retrieve specific game single achievement information for a logged in user.
StovePCResult result = StovePC_GetAllAchievement();
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
C++
복사
The OnAllAchievement callback is called when the StovePC_GetAllAchievement function is processed properly.
The StovePCAchievement structure delivered to the callback contains the current achievement value, achievement status, and achievement metadata.
void OnAllAchievement(int size, StovePCAchievement* achievements)
{
// Display all achievement information
printf("OnAllAchievement");
printf(" - achievements size : %d", size);
for (int i = 0; i < size; i++, achievements++)
{
printf(" - achievements[%d].achievementId : %s", i, achievements->achievementId);
wprintf(L" - achievements[%d].name : %s", i, achievements->name);
wprintf(L" - achievements[%d].description : %s", i, achievements->description);
wprintf(L" - achievements[%d].defaultImage : %s", i, achievements->defaultImage);
wprintf(L" - achievements[%d].achievedImage : %s", i, achievements->achievedImage);
printf(" - achievements[%d].condition.goalValue : %d", i, achievements->condition.goalValue);
printf(" - achievements[%d].condition.valueOperation : %s", i, achievements->condition.valueOperation);
printf(" - achievements[%d].condition.type : %s", i, achievements->condition.type);
printf(" - achievements[%d].value : %d", i, achievements->value);
printf(" - achievements[%d].status : %s", i, achievements->status);
}
}
C++
복사
Caution) The valid range of the callback parameter StovePCAchievement structure array is limited to the scope of the callback function. The PC SDK releases internally allocated memory as soon as execution of the callback function is completed. Therefore, if storage is required to use information of the StovePCAchievement structure array outside of the scope of the callback function, a copy must be created through Deep Copy, and the memory must be released when use of the copy is completed.
If an error occurs while the StovePC_GetAllAchievement function is running, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
9000 | Service Error |
6. Get Leaderboard Ranking Information
Use the StovePC_GetRank function to retrieve the ranking information of a specific game leaderboard.
// Input parameters
// const char* leaderboardId : Leaderboard identifier created in the studio
// const unsigned int pageIndex : Page number to search (1 <= pageIndex)
// const unsigned int pageSize : Number of ranks to search (1 <= pageSize <= 50)
// const bool includeMyRank : Include rank of logged-in users in search results
StovePCResult result = StovePC_GetRank("LEADERBOARD_ID", PAGE_INDEX, PAGE_SIZE, INCLUDE_MY_RANK);
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
C++
복사
The OnRank callback is called when the StovePC_GetRank function is processed properly.
The StovePCRank structure delivered to the callback contains score and rank information for a specific user.
// Callback Paramter
// unsigned int rankTotalCount : Total number of rankings aggregated in the searched leaderboard
void OnRank(int size, StovePCRank* ranks, unsigned int rankTotalCount)
{
// Display Ranking Information
printf("OnRank");
printf(" - ranks.Length : %d", size);
for (int i = 0; i < size; i++, ranks++)
{
printf(" - ranks[%d].memberNo : %llu", i, ranks->memberNo);
printf(" - ranks[%d].score : %d", i, ranks->score);
printf(" - ranks[%d].rank : %u", i, ranks->rank);
wprintf(L" - ranks[%d].nickname : %s", i, ranks->nickname);
wprintf(L" - ranks[%d].profileImage : %s", i, ranks->profileImage);
}
printf(" - rankTotalCount : %u", rankTotalCount);
}
C++
복사
Caution) The valid range of the callback parameter StovePCRank structure array is limited to the scope of the callback function. The PC SDK releases internally allocated memory as soon as execution of the callback function is completed. Therefore, if storage is required to use information of the StovePCRank structure array outside of the scope of the callback function, a copy must be created through Deep Copy, and the memory must be released when use of the copy is completed.
If an error occurs while the StovePC_GetRank function is running, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
1251 | Invalid Parameter |
1252 | CannotFindData |
3603 | ErrorLeaderBoardNotFound |
3631 | ErrorMembershipAPI |
500 | External Server Error |