STOVE Store Developer Guide alpha

# PC SDK Cocos2d-x連動ガイド

# 紹介

インディゲームのためのSTOVEプラットフォームは、ゲームの配布と販売、コミュニティ、指標分析などを含む、ゲームリリースのすべてのプロセスをワンストップで処理できる統合サービスを提供します。 PC SDK（Native）を使用すると、Stoveプラットフォームが提供するサービスをゲームに簡単に統合できます。

このページではPC SDKをCocos2dxに連動する方法について説明します。

confirm PC SDK連動が初めてなら、PC SDK Cocos2d-xチュートリアルを先に読んでください。

# 事前準備

  • STOVE加入アカウントとリリースするゲーム用のApp key、App secret、Game IdをSTOVE Studio (opens new window)で発行されたことを確認します。
  • ビジュアル・スタジオ2015アップデート3以上のコンパイラが設置されているか確認します。
  • PC SDK ダウンロード ページから、最新バージョンの Native(C/C++) 配布ファイル (以下 StovePCSDK と表記) をダウンロードします。

# StovePCSDK配布ファイルの構成

# 1) includeフォルダー

Stove PC SDKをダウンロードして解凍したらincludeフォルダーの中に下記のフォルダーが含まれています。

  • StovePCDefine.h
    ゲームとPC SDKのコミュニケーションのため使われるAPI呼び出し結果（StovePCResult）、エラー結果構造体（StovePCError）、コールバック関数、API構造体パラメータなどが宣言されています。

  • StovePCSDK.h
    ゲームとPC SDKのコミュニケーションのため使われるAPI関数プロトタイプが宣言されています。

# 2) binフォルダー

binフォルダーの下にはプラットフォーム(Win32/x64)及び構成(Debug/Release)別に必要なバイナリーが含まれています。

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

confirm StovePCSDK.libを除く上記のリストのDllファイルは、ゲームクライアントをエンドユーザーに配布するときに必ず含める必要があります。

# 3) sampleフォルダー

sample フォルダーの下には、 StovePCSDKの動作確認ができる StovePCSDKTestMfc.exe GUIアプリケーションが各プラットフォーム(Win32/x64)ごとにReleaseビルドで入っています。
まず、 StovePCConfig.MFC.ini ファイルにApp key、App secretなどを入力した後 StovePCSDKTestMfc.exeを実行します。また、StovePCSDKTestMfcを直接実行してSetting UIにAppKey、SecretKeyなどを直接入力することもできます。

# StovePCSDKビルド環境構築

ビルド環境の構成についてはPC SDK Cocos2d-xチュートリアルの プロジェクトの環境構築 項目をご覧ください。

# 連動開始

# 1) Config、Callback設定

PC SDK初期化のためには、まずStovePCConfigと StovePCCallback 構造体に値を入れた後、StovePC_Init 関数を呼び出します。 下記のコードを参考に StovePCConfig 構造体の各フィールド値を入れます。

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

StovePCConfig 構造体についての説明は StovePCDefine.h ファイルをご覧ください。

ゲームとPC SDKの間のコミュニケーションは、StovePCCallback構造体に関連付けられたコールバック関数を使用します。 ゲームコードでは、以下の StovePCCallback 構造体のコールバックポインタに接続する関数ポインタを事前に定義し、定義された関数のポインタご連結ください。

struct StovePCCallback
{
    /// StovePCSDKでエラーが発生すると呼び出されるコールバック
    void(*OnError)(const StovePCError error);

    /// PC SDK初期化が完了した際に呼び出されるコールバック
    void(*OnInitComplete)();

    /// GetToken処理が完了した際に呼び出されるコールバック
    void(*OnToken)(const StovePCToken token);

    /// GetUser処理が完了した際に呼び出されるコールバック
    void(*OnUser)(const StovePCUser user);

    /// GetOwnership処理が完了した際に呼び出されるコールバック
    void(*OnOwnership)(int size, StovePCOwnership* ownership);
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

StovePCCallback 構造体のinstanceは使用する前に必ずNULL初期化が必要です。

/*StovePCCallback構造体instance生成*/
StovePCCallback callback;
/*全ての関数ポインタをNULLに初期化*/
memset(&callback, 0, sizeof(StovePCCallback));
/*作成した関数ポインタに繋げる*/
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

必須連動の OnError, OnInitComplete, OnOwnership コールバック関数以外の残りのコールバック関数は必要なときにのみ連動を行うことができます。 たとえば、オーナーシップ機能のみを使用する場合は、次のように接続できます。

/*所有権(Ownership)機能のみ使用する場合、
必須のコールバックであるOnError、OnInitcomplte以外に
OnOwnershipコールバックのみ作成して繋げます。*/
callback.OnError = OnMyErrorCallback;
callback.OnInitComplete = OnMyInitCompleteCallback;
callback.OnOwnership = OnMyOwnershipCallback;
1
2
3
4
5
6

# 2) SDK初期化

StovePCConfigとStovePCCallback構造体の初期化とコールバック関数の接続が完了したら、PC SDKを初期化するためにStovePC_Init関数を呼び出します。

StovePCResult result = StovePC_Init(config, callback);
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*StovePCSDK init成功
    タイマーなどを利用し、定期的にStovePC_RunCallback()を呼び出す*/

}
1
2
3
4
5
6
7

StovePC_Init 関数はconfigとcallbackの有効性可否のみ確認し、すぐ StovePCResult enumタイプの値を戻します。
成功した場合、STOVE_PC_NO_ERRORの値が返されます。 失敗した場合は、対応するエラーコードを返し、ゲームの終了を処理する必要があります。 完全なエラーコードのリストは、StovePCDefine.hファイルのStovePCResult enumごチェックください。

戻り値が STOVE_PC_NO_ERROR、即ち「成功」である場合、 StovePC_RunCallback 関数を定期的に呼び出します。
繋がっているコールバックが正常に呼び出されるためには、StovePC_RunCallback 関数を定期的に呼び出す必要があります。
呼び出しの間隔が長いとコールバックが返す速度も遅くなるため、適切な呼び出しの間隔を保つ方がいいです。このガイドのサンプルコードは、呼び出し周期を0.5秒に設定しました。

confirm PC SDKに繋がってるコールバックは StovePC_RunCallback 関数を呼び出したスレッドでのみ呼び出されます。

Cocos 2dx では、chedule 関数 (opens new window)を使って、一定の周期ごとに必要な作業を処理することができます。
以下は1秒ごとに「StovePC_RunCallback」関数を呼び出す例コードです。

...
StovePCResult result = StovePC_Init(config, callback);
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /* PCSDKの初期化が成功したら、1秒ごとにupdateTimer 関数を呼び出すようにスケジューラーを実行*/
    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
13

StovePC_Init 関数はconfigとcallbackの有効性確認を除くその他の作業を非同期状態で処理します。
非同期作業が問題なく終わった場合、 OnInitComplete コールバックが呼び出され、エラーが発生した場合には OnError コールバックが呼び出されます。
エラーが発生した場合、送られた StovePCError 構造体からエラーコードとメッセージなどを確認できます。

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()
{
// たぶんすぐにアプリを停止するのではなく、ユーザーにアプリの停止に関するメッセージを表示した後
// ユーザーアクション(e.g. 終了ボタンをクリック)によってアプリを中断したいかもしれません。
// その場合は、ここでQuitApplicationをクリアして独自のロジックを実装します。
// 推奨する必須の事前処理エラーに関するメッセージは次のとおりです。
// 韓国語 : 필수 사전 작업이 실패하여 게임을 종료합니다.
//その他の言語：The required pre-task fails and exits the game
	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

# 3) SDK連動時の注意事項

confirm StovePCConfig構造体のログレベル設定時テスト実施にあたってはStovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG値に設定し、正式発売時にはStovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR値に設定してください。

confirm PC SDKの初期化が完了する前に GetToken、 GetUser、 GetOwnership関数を呼び出すと、正常に結果が得られないことがあります。 つまり、 OnInitComplete コールバックが正常に受信された後に GetToken、 GetUser、 GetOwnership 関数を呼び出さなければ正常に結果を受け取ることができます。

# 4) SDK終了

PC SDKの使用が終わった後、StovePC_UnInit関数を呼び出し、使用中のリソースを整理します。

StovePCResult result = StovePC_UnInit();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*成功処理*/
}
...
1
2
3
4
5
6

# 5)ユーザー情報を取得

Stove PC_GetUser関数でSTOVEランチャーにログインしたユーザー情報を照会します。

StovePCResult result = StovePC_GetUser();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*成功処理*/
}
1
2
3
4
5

StovePC_GetUser 関数が正常に処理されたら OnUser コールバックが呼び出されます。
コールバックで配信される「StovePCUser」構造体を通じて、ユーザーのメンバーナンバー、ニックネーム、ゲームユーザーのID情報などを確認できます。 StovePCUser 構造体についての説明は StovePCDefine.h ファイルをご覧ください。

void OnUser(const StovePCUser user)
{
    /*사용자 정보 출력*/
    printf("User Info(memberNo = %I64d, nickname = %S, gameUserId = %s)",
                      user.memberNo, user.nickname, user.gameUserId);
}
1
2
3
4
5
6

# 6)トークン情報を取得

StovePC_GetToken関数でSTOVEランチャーにログインしたユーザーのトークン情報を確認できます。

StovePCResult result = StovePC_GetToken();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*成功処理*/
}
1
2
3
4
5

StovePC_GetToken 関数が正常に処理されたら OnToken コールバックが呼び出されます。
コールバックに送られる StovePCToken 構造体にはトークン文字列が含まれています。

void OnToken(const StovePCToken token)
{
    /*トークン情報出力*/
    printf("Token : %s", token.accessToken);
}
1
2
3
4
5

confirm トークンとは？ STOVEランチャーにログインしたユーザーのアクセストークン（Access Token）で、ゲームサーバーはこのアクセストークンをSTOVE認証サーバーに渡してログインしたユーザーの検証を行うことができます。 アクセストークンの詳細な説明は、STOVEインディチームにお問い合わせ (opens new window)で技術サポートを受けることができます。

# 7) 所有権情報を得る

「StovePC_GetOwnership」の関数で、ユーザーがそのゲームを購入して所有しているかどうかを確認できます。


StovePCResult result = StovePC_GetOwnership();
if (result == STOVE_PC_NO_ERROR)
{
    /* 成功処理*/
    /*所有権に関する情報はOnOwnershipコールバックにお送りします。*/ 
}
1
2
3
4
5
6
7

「StovePC_GetOwnership」の関数が正常に処理されると、OnOwnershipのコールバックが呼び出されます。
OnOwnershipコールバックのパラメータである「StovePCOwnership」構造体に対する詳細情報はStovePCDEfine.hファイルをご参照ください。

以下はOnOwnershipコールバックでゲームを購入するかどうかを判断する例コードです。
DLCがないパッケージゲームの場合、20~23 lineの確認コードは不要です。

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構造体のmemberNo*/)
            |||(data->ownershipCode!=1/*1:所有権獲得、2:所有権解除(購入をキャンセルした場合)*/))
        {
            continue;
        }
 
        if (0 == wcscmp(L"YOUR_GAME_ID", data->gameId) && data->gameCode == 3 /* 3: インディーゲーム*/)
        {
            owned = true; // 所有権確認変数trueに設定
        }
 
        /* DLCを販売するパッケージゲームの場合のみ必要 */
        if (0 == wcscmp(L"YOUR_DLC_ID", data->gameId) && data->gameCode == 5 /* 5: DLC*/)
        {
            // YOUR_DLC_ID(DLC)の所有権があるのでDLCプレイ許可
        }
    }
 
    if(owned)
    {
        // 所有権検証が正常に完了した後、ゲーム進入ロジック作成
    }
    else
    {
        // 所有権検証失敗後、ゲームを終了してエラーメッセージ表示ロジック作成
    }
     
     
}
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
  • ゲームを購入したアカウント(所有権保有)でSTOVEランチャーにログインした後、ゲームをプレイできます。
  • ゲーム所有権がないアカウントでSTOVEランチャーにログインした後、exe実行時に以下の案内メッセージ(例)を出力してゲームを終了します。
    • 韓国語以外のOS : Please log in to STOVE Client with the account that has purchased the game.
    • 韓国語: 게임을 구매한 계정으로 STOVE 클라이언트에 로그인하시기 바랍니다.

confirm ゲーム所有権があるアカウントがなくても所有権機能をテストすることができ、詳しい方法は FAQをご確認ください。

# エラー確認

PC SDK使用中に発生するエラーの確認方法は大きく以下の２つに分かれます。

# 関数の呼び出し後に戻されるStovePCResult enum値

PC SDKの全ての関数は、呼び出し直後に呼び出しの成功可否を表すStovePCResult enum 値を戻します。
全体値は、PC SDKエラーコードページから確認できます。

# OnErrorコールバックで送られるStovePCError構造体

PC SDK関数の中、非同期で動作する関数からエラーが発生した場合にはOnErrorコールバックが呼び出されて、エラーについての説明が含まれた StovePCError 構造体が送られます。

/*OnErrorコールバックが呼び出される際に送られます。*/
struct StovePCError
{
    /*呼び出された関数を表すenum値*/
    StovePCFunctionType functionType;

    /*発生したエラータイプを表すenum値*/
    StovePCResult result;

    /*発生したエラーメッセージ*/
    char* message;

    /*外部エラー(httpエラー、外部モジュールエラー)が発生した場合、該当するエラーコード*/
    int externalError; 
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Last Updated: 2023/12/24 7:50:45