# PC SDK Cocos2d-x連動ガイド
# 紹介
インディゲームのためのSTOVEプラットフォームは、ゲームの配布と販売、コミュニティ、指標分析などを含む、ゲームリリースのすべてのプロセスをワンストップで処理できる統合サービスを提供します。 PC SDK(Native)を使用すると、Stoveプラットフォームが提供するサービスをゲームに簡単に統合できます。
このページではPC SDKをCocos2dxに連動する方法について説明します。
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
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,
""};
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);
};
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;
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;
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()を呼び出す*/
}
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秒に設定しました。
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();
}
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)
}
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連動時の注意事項
![]()
StovePCConfig
構造体のログレベル設定時テスト実施にあたってはStovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG
値に設定し、正式発売時にはStovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR
値に設定してください。
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)
{
/*成功処理*/
}
...
2
3
4
5
6
# 5)ユーザー情報を取得
Stove PC_GetUser
関数でSTOVEランチャーにログインしたユーザー情報を照会します。
StovePCResult result = StovePC_GetUser();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*成功処理*/
}
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);
}
2
3
4
5
6
# 6)トークン情報を取得
StovePC_GetToken
関数でSTOVEランチャーにログインしたユーザーのトークン情報を確認できます。
StovePCResult result = StovePC_GetToken();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*成功処理*/
}
2
3
4
5
StovePC_GetToken
関数が正常に処理されたら OnToken
コールバックが呼び出されます。
コールバックに送られる StovePCToken
構造体にはトークン文字列が含まれています。
void OnToken(const StovePCToken token)
{
/*トークン情報出力*/
printf("Token : %s", token.accessToken);
}
2
3
4
5
トークンとは? STOVEランチャーにログインしたユーザーのアクセストークン(Access Token)で、ゲームサーバーはこのアクセストークンをSTOVE認証サーバーに渡してログインしたユーザーの検証を行うことができます。 アクセストークンの詳細な説明は、STOVEインディチームにお問い合わせ (opens new window)で技術サポートを受けることができます。
# 7) 所有権情報を得る
「StovePC_GetOwnership」の関数で、ユーザーがそのゲームを購入して所有しているかどうかを確認できます。
StovePCResult result = StovePC_GetOwnership();
if (result == STOVE_PC_NO_ERROR)
{
/* 成功処理*/
/*所有権に関する情報はOnOwnershipコールバックにお送りします。*/
}
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
{
// 所有権検証失敗後、ゲームを終了してエラーメッセージ表示ロジック作成
}
}
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 클라이언트에 로그인하시기 바랍니다.
ゲーム所有権があるアカウントがなくても所有権機能をテストすることができ、詳しい方法は FAQをご確認ください。
# エラー確認
PC SDK使用中に発生するエラーの確認方法は大きく以下の2つに分かれます。
# 関数の呼び出し後に戻される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;
};
2
3
4
5
6
7
8
9
10
11
12
13
14
15