STOVE Store Developer Guide alpha

# PC SDK Unity連動ガイド

# 紹介

ーズゲームのためのSTOVEプラットフォームは、ゲームの配布·販売、コミュニティ、指標分析などを含めたゲーム発売の全過程をワンストップで処理できる統合サービスを提供しています。 PC SDK（Unity、以下PC SDKという）を使用すれば、Stoveプラットフォームが提供するサービスをゲームに簡単に統合させることができます。

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

confirm PC SDKの連動が初めてなら、PC SDK Unityチュートリアル(../Getting Started/tutorial_unity.md) をまず読んでみてください。

# 事前準備

  • STOVE登録アカウントと発売ゲーム用Appkey、Appsecret、Game IdをSTOVE Studio (opens new window)で取得しているかを確認します。
  • Unity2017以上のバージョンとVisual Studio2017以上のバージョンのインストールをお勧めします。
  • PCSDKダウンロードページから最新バージョンのUnity(C#)配布ファイル(以下、StovePCSDK_NETといいます。)をダウンロードします。

# StovePCSDK_NET配布ファイル構成

# 1) StovePCSDK フォルダ

StovePaSDK_NETをダウンロードして圧縮を解除すると、StovePASDKというフォルダに次のようなフォルダがあります。

  • Plugins
    Unity Projectプラグインフォルダです。

  • Plugins\x86
    x86用のビルドに必要なバイナリが含まれています。

  • Plugins\x86_64
    x64用のビルドに必要なバイナリが含まれています。

# StovePCSDK_NETビルド環境構成

# 1) Assetsを追加する

統合するUnityプロジェクトを開き、先ほど説明したStovePCSDKフォルダからx86フォルダとx86_64フォルダのうち1つだけを残して、もう1つは削除した後StovePCSDKフォルダをコピーしてAssetsフォルダの下位に貼り付けます。

Figure1
Figure2

# 2) x86フォルダのファイルを確認する

x86フォルダの下位にあるファイルを選択し、インスペクター(Inspector)でPlatform settingsセクションにWindows x86項目がチェックされているかを確認します。 もしチェックされていない場合は、チェックボックスを選択します。

Figure3
Figure4

# 3) x86_64 フォルダのファイルを確認する

x86_64フォルダーの下位にあるファイルを選択して、インスペクターでPlatform settingsセクションにWindows x86_x64項目が選択されているかを確認します。 選択されていない場合はお選びください。

Figure5
Figure6

# 4) Build Settings

File > Build Settings... メニューをクリックしてBuild Settingsダイアログを開き、Player Settings... ボタンをクリックしてInspectorまたはProject Settingsウィンドウを開きます。
Other Settings グループ > Configuration セクション > Api Compatibility Level の項目を下記のように設定します。
Unity 2018以前のバージョン:.NET 2.0 (.NET 2.0 Subsetではない)

Figure11

Unity 2018以降のバージョン:.NET 4.x (.NET Standard 2.0ではない)

Figure12

# 5) 空のゲームオブジェクト作成

適当なシーンにゲームオブジェクト(Game Object -> Create Empty)を生成します。 空のゲームオブジェクト名を便宜上StovePCSDKManagerに設定します。

Figure7
Figure8

# 6) スクリプトコンポーネントを追加する

StovePCSDKManagerオブジェクトにScriptコンポーネントを追加します。 便宜上スクリプトの名前をStovePCSDKManagerに設定します。
Figure9
Figure10

# 7) スクリプトを作成する

StovePCSDKManagerオブジェクトがシーン切り替えなどによって解除されないようAwakeメソッドに下記のように処理します。

private void Awake()
{
    DontDestroyOnLoad(transform.gameObject);
}
1
2
3
4

# PC SDKを連動する

# 1) RunCallback

PCSDKのAPIは、ゲームエンジンやゲームロジックの邪魔にならないよう、ほとんどが非同期で行われます。 API呼び出しの結果は、PC SDK内部のキューに積載され、ゲームがAPI呼び出しに対する結果を処理するためのRunCallbackメソッドを呼び出すことによって登録したコールバックが実行されます。 通常、RunCallbackメソッドの呼び出しはコルチンを利用して作成し、呼び出し周期は設定が可能です。

private IEnumerator RunCallback(float intervalSeconds)
{
    WaitForSeconds wfs = new WaitForSeconds(intervalSeconds);
    while (true)
    {
        StovePC.RunCallback();
        yield return wfs;
    }
}
1
2
3
4
5
6
7
8
9

コルティンはMonoBehaviour.StartCoroutineメソッドから始まり、一般的にPC SDK初期化が 成功してから始め、PC SDK 終了が成功したら中止します。
PC SDK終了成功後、RunCallbackコルティンを中止するためにメンバー変数を利用する方法があります。

private Coroutine runcallbackCoroutine;
1

ゲームプロジェクトのメンバ変数として宣言されたruncallbackCoroutineを下のコードのようにStartCoroutine関数とStopCoroutine関数を使用することでタイマーのように動作させることができます。

public void ToggleRunCallback_ValueChanged(bool isOn)
    {
        if (isOn)
        {
            float intervalSeconds = 1f;
            runcallbackCoroutine = StartCoroutine(RunCallback(intervalSeconds));

            WriteLog("RunCallback Start");
        }
        else
        {
            if (runcallbackCoroutine != null)
            {
                StopCoroutine(runcallbackCoroutine);
                runcallbackCoroutine = null;

                WriteLog("RunCallback Stop");
            }
        }
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 2) Config, Callback設定

PCSDKを初期化するには、まずStovePCConfigとStovePCCallback構造体に値を満たし、StovePC.Initializeメソッドを呼び出します。
以下のコードを参照してStove PC Config構造体の各フィールド値を満たします。

StovePCConfig config = new StovePCConfig
{
    Env = "live",
    AppKey = "YOUR_APP_KEY",
    AppSecret = "YOUR_SECRET_KEY",
    GameId = "YOUR_GAME_ID",
    LogLevel = StovePCLogLevel.Debug,
    LogPath = ""
};
1
2
3
4
5
6
7
8
9

confirm
YOUR_APP_KEY、YOUR_SECRET_KEY、YOUR_GAME_IDはSTOVE Studioで発行されたキー値のデータに変更してください。
STOVEランチャーにログインしていない状態でStovePC.Initializeメソッドを呼び出すとエラーが発生しますので、事前にSTOVEランチャーを実行してログインします。

ゲームとPC SDK間の連動はC# デリゲートを使用します。 ゲームでは、以下のStovePCCallbackクラスのコールバックに繋げるデリゲートメソッドをご定義ください。

public class StovePCCallback
{
    // StovePCSDKでエラー発生時に呼び出されるコールバック
    public StovePCErrorDelegate OnError;

    // PC SDKの初期化が完了した時に呼び出されるコールバック
    public StovePCInitializationCompleteDelegate OnInitializationComplete;

    // GetToken処理が完了した時に呼び出されるコールバック
    public StovePCTokenDelegate OnToken;

    // GetUser処理が完了した時に呼び出されるコールバック
    public StovePCUserDelegate OnUser;

    // GetOwnership処理が完了した時に呼び出されるコールバック
    public StovePCOwnershipDelegate OnOwnership;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

ここで注意する点がありますが、StovePCCallbackオブジェクトはPCSDKが終了するまで保存されなければなりません。 その理由はStovePCCallbackのオブジェクトがガベージ(Gabitage)コレクティングされた場合、PCSDK内ではコールバックを呼び出せないためです。
この点を満たすためにStovePCCallbackクラスをゲームプロジェクトクラスのメンバー変数として宣言し、ガベージ(Gabitage)コレクティングされないようにして解決できます。

private StovePCCallback callback;
1
// StovePCCallbackクラスinstance作成 
this.callback = new StovePCCallback
{
    OnError = new StovePCErrorDelegate(this.OnError),
    OnInitializationComplete = new StovePCInitializationCompleteDelegate(this.OnInitializationComplete),
    OnToken = new StovePCTokenDelegate(this.OnToken),
    OnUser = new StovePCUserDelegate(this.OnUser),
    OnOwnership = new StovePCOwnershipDelegate(this.OnOwnership)
};
1
2
3
4
5
6
7
8
9

連動しなければならないOnError、OnInitializationComplete、OnOwnershipコールバック関数以外の残りのコールバック関数は必要な時だけ連動してください。 例えば、所有権(Ownership)機能のみを使用する場合、以下のようにデリゲートメソッドに接続します。

/*
所有権(Ownership)機能のみを使用する場合は、
必須実現コールバックであるOnError、OnInitialization Completeの他、
OnOwnershipコールマンを追加で接続します。 
*/
this.callback = new StovePCCallback
{
    OnError = new StovePCErrorDelegate(this.OnError),
    OnInitializationComplete = new StovePCInitializationCompleteDelegate(this.OnInitializationComplete),
    OnOwnership = new StovePCOwnershipDelegate(this.OnOwnership)
};
1
2
3
4
5
6
7
8
9
10
11

# 3) SDKの初期化

PCS SDKを初期化するためにStove PC.Initializeメソッドを呼び出します。

StovePCResult sdkResult = StovePC.Initialize(config, this.callback);
if (StovePCResult.NoError == sdkResult)
{
    this.runCallbackCoroutine = StartCoroutine(RunCallback(0.5f));
    // 初期化エラーがなくRunCallbackの周期的に呼び出し
}
else
{
    // 初期化失敗でゲーム終了
}
1
2
3
4
5
6
7
8
9
10

Stove PC.Initializeメソッドは、configとcallbackの有効性のみを確認して、直ちにStove PC Resultenumタイプ値を返します。
成功した場合、Stove PCResult.NoErrorの値が返されます。 失敗した場合は、このエラーコードを返してゲーム終了となります。

払い戻し額がStove PC Result.No Error、つまり成功の場合、Stove PC.Run Callbackメソッドを周期的に呼び出します。
StovePC.RunCallbackメソッドを周期的に呼び出すと、つないだコールバックが正常に呼び出されます。
呼び出し周期が長いとコールバックの応答速度も遅くなるので、適度な呼び出し周期を保つことをお勧めします。 例題コードでは1秒に1度コールバック関数が呼び出されると設定していました。

confirm InitializeメソッドでPCSDKを初期化したスレッド(Thread)とStovePC.RunCallbackメソッドでコールバック関数が呼び出されるスレッドは同一である必要があります。

StovePC.Initializeメソッドはconfigとcallback有効性の確認以外の作業を非同期で処理します。
非同期作業が成功した場合、OnInitializationCompleteコールバックが呼び出され、エラーが発生した場合はOnErrorコールバックが呼び出されます。
エラーが発生した場合、お届けしたStovePCError構造体でエラーコード、メッセージなどを確認できます。

private void OnInitializationComplete()
{
    Debug.Log("PC SDK initialization success");
}

    private void OnError(StovePCError error)
    {
        #region Log
        StringBuilder sb = new StringBuilder();
        sb.AppendLine("OnError");
        sb.AppendFormat(" - error.FunctionType : {0}" + Environment.NewLine, error.FunctionType.ToString());
        sb.AppendFormat(" - error.Result : {0}" + Environment.NewLine, (int)error.Result);
        sb.AppendFormat(" - error.Message : {0}" + Environment.NewLine, error.Message);
        sb.AppendFormat(" - error.ExternalError : {0}", error.ExternalError.ToString());
        WriteLog(sb.ToString());
        #endregion

        switch (error.FunctionType)
        {
            case StovePCFunctionType.Initialize:
            case StovePCFunctionType.GetUser:
            case StovePCFunctionType.GetOwnership:
                BeginQuitAppDueToError();
                break;
        }
    }

    private void BeginQuitAppDueToError()
    {
        #region Log
        StringBuilder sb = new StringBuilder();
        sb.AppendLine("BeginQuitAppDueToError");
        sb.AppendFormat(" - nothing");
        WriteLog(sb.ToString());
        #endregion

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

OnInitializationCompleteコールバックが来る前に、PC SDKの初期化状態値を照会する必要がある場合、StovePC.GetInitializationState関数を使用することができます。

// StovePC.Initialize 呼び出し後...
while (StovePC.GetInitializationState() == StovePCInitializationState.Pending)
{
    Thread.Sleep(500);
    StovePC.RunCallback();
}

if (StovePC.GetInitializationState() == StovePCInitializationState.Complete)
{
    // 初期化完了 OnInitializationComplete コールバックが呼び出されます。
}
else
{
    // 初期化失敗 OnErrorコールバックが呼び出される
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

confirm 初期化が完了する前に GetToken, GetUser, GetOwnership メソッドを呼び出すと正常に結果が得られないことがあります。 つまり、On Initialization Completeコールバックが正常に受信された後にGet Token、Get User、Get Ownershipメソッドを呼び出すと正常に結果を受け取ることができます。

! confirm StovePCConfig構造体のログレベル設定時のPCSDKテスト時には、StovePCLogLevel.Debug値を入力し、正式なビルドにはStovePCLogLevel.Error値に設定して不必要なログが生成されることを防止してください。

# 5) SDK終了

PC SDK使用が終わった後に呼び出して使用中のリソースを整理します。 StovePC.Uninitializeメソッドが呼び出された後は、PCSDKのAPIが動作しません。 Stove PC.Uninitializeメソッド呼び出し前後に必ずStop Coroutine関数でruncallback Coroutineコルティン実行を中止してください。

StovePCResult result = StovePC.Uninitialize();
if (result == StovePCResult.NoError)
{
    // 成功処理
}
1
2
3
4
5

# 6) ユーザー情報を得る

StovePC.GetUserメソッドでSTOVEンチャー (opens new window)にログインしたユーザー情報をご確認いただけます。

StovePCResult result = StovePC.GetUser();
if (result == StovePCResult.NoError)
{
    // 成功処理
}
1
2
3
4
5

StovePC.GetUserメソッドが正常に処理されるとOnUserコールバックが呼び出されます。
コールバックで配信されるStovePCUser構造体を通じて、ユーザーのメンバーナンバー、ニックネーム、ゲームユーザーのID情報を確認できます。

private void OnUser(StovePCUser user)
{
    // ユーザー情報出力
    StringBuilder sb = new StringBuilder();
    sb.AppendLine("OnUser");    
    sb.AppendFormat(" - user.MemberNo : {0}" + Environment.NewLine, user.MemberNo.ToString());
    sb.AppendFormat(" - user.Nickname : {0}" + Environment.NewLine, user.Nickname);
    sb.AppendFormat(" - user.GameUserId : {0}", user.GameUserId);
    
    Debug.Log(sb.ToString());
}
1
2
3
4
5
6
7
8
9
10
11

# 7) トークン情報を得る

StovePC.GetTokenメソッドでストーブランチャーにログインしたユーザーのトークン情報を得てきます。

StovePCResult result = StovePC.GetToken();
if (result == StovePCResult.NoError)
{
    // 成功処理
}
1
2
3
4
5

StovePC.GetTokenメソッドが正常に処理されるとOnToken``コールバックが呼び出されます。 コールバックに伝わるStove PC Token`構造体にはトークン文字列が含まれています。

private void OnToken(StovePCToken token)
{
    // トークン情報出力
    StringBuilder sb = new StringBuilder();
    sb.AppendLine("OnToken");
    sb.AppendFormat(" - token.AccessToken : {0}", token.AccessToken);

    Debug.Log(sb.ToString());
}
1
2
3
4
5
6
7
8
9

confirm トークンとは？ STOVEランチャーにログインしたユーザーのアクセストークン（Access Token）で、ゲームサーバーはこのアクセストークンをSTOVE認証サーバーに渡してログインしたユーザーの検証を行うことができます。 アクセストークンの詳細な説明は、store.support@smilegate.comで技術サポートを受けることができます。

# 8) 所有権情報を得る

StovePC.GetOwnershipメソッドでSTOVEランチャーユーザーがそのゲームを購入して所有しているかどうかを照会します。

StovePCResult result = StovePC.GetOwnership();
if (result == StovePCResult.NoError)
{
    // 成功処理
}
1
2
3
4
5

StovePC.GetOwnershipメソッドが正常に処理されるとOnOwnershipコールバックが呼び出されます。
以下はOnOwnershipコールバックでゲームを購入するかどうかを判断する例コードです。
DLCがないゲームの場合、22~27lineの確認コードは不要です。

private void OnOwnership(StovePCOwnership[] ownerships)
{
    bool owned = false;
 
    foreach(var ownership in ownerships)
    {
        // [LOGIN_USER_MEMBER_NO] StovePCUser構造体のMemberNo
        // [OwnershipCode] 1:所有権獲得、2:所有権解除(購入をキャンセルした場合)
        if (ownership.MemberNo != LOGIN_USER_MEMBER_NO ||
            ownership.OwnershipCode != 1)
        {
            continue;
        }
 
        // [GameCode] 3: BASIC 게임, 4: DEMO
        if (ownership.GameId == "YOUR_GAME_ID" &&
            ownership.GameCode == 3)
        {
            owned = true; // 所有権確認変数trueに設定
        }
 
        // DLCを販売するゲームの場合のみ必要
        if (ownership.GameId == "YOUR_DLC_ID" &&
            ownership.GameCode == 5)
        {
            // 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
37
38

*ゲームを購入したアカウント(所有権保有)でSTOVEランチャーにログインした後、ゲームをプレイできます。 *ゲーム所有権がないアカウントでSTOVEランチャーにログインした後、exe実行時に以下の案内メッセージ(例)を出力してゲームを終了します。

  • 韓国語以外のOS : Please log in to STOVE Client with the account that has purchased the game.
  • 韓国語: 게임을 구매한 계정으로 STOVE 클라이언트에 로그인하시기 바랍니다.

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

  • また、所有権(Ownership)の呼び出し<GetOwnership Success>後に、output_log.txtまたはPlayer.logに以下のようなログを追加してください。
例:

成功: 所有権を持つユーザーです。
失敗: 所有権を持たないユーザーです。
1
2
3
4

# エラー確認

PC SDK使用中に発生するエラーは大きく二つのケースに分けてご確認いただけます。

# メソッド呼び出し後に返還されるStovePCResultenum値

PCSDKのすべてのメソッドは、呼び出し直後、呼び出しが成功したかどうかを表すStove PCResultenum値を返します。
返却されるエラーコードは、PC SDKエラーコードページで確認できます。

# OnErrorコールバックを通じて伝えられるStovePCError構造体

PCS DK APIでエラーが発生した場合は、On Errorというコールバックが呼び出され、エラーに対する詳しい情報が含まれたStove PC Errorという構造体がお届けされます。

// OnErrorコールバックが呼び出しされたときに転送されます。
public struct StovePCError
{
    // 呼び出された関数を表すenum値
    public StovePCFunctionType FunctionType;

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

    // 発生したエラーメッセージ
    public string Message;

    // 外部エラー（httpエラー、外部モジュールエラー）が発生した場合、該当するエラーコード
    public int ExternalError;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# ゲームサポートサービスを連動する

PC SDKはSTOVEプラットフォームのゲームサポートサービスをゲームに統合できるようにAPIを提供しています。 PCSDKが対応しているゲーム対応サービスには、スタット、業績、リーダーボードがあります。 それぞれのサービスは以下のように定義します。

  • スタット:ユーザーの様々なゲームPlay Dataを数値で記録してくれるサービス
  • 業績:ゲームPlayチャレンジ課題を設定し、ユーザーごとに達成情報を提供してくれるサービス
  • リーダーボード:特定のゲームPlay Dataのユーザーランキング情報を提供するサービス

PC SDKゲーム支援サービスAPIを使用するためには、Studioでのゲーム支援サービスのメタデータ登録が先行される必要があります。

メタデータの管理についての内容は簡単なコンソール使用マニュアルを参照してください。

# 1) Callback 設定

ゲーム支援サービスAPIを使用してPCSDKとコミュニケーションするためには、以下のStovePCCallbak構造体のコールバックポインターに連結するコールバック関数をご定義ください。

public class StovePCCallback
{
    public StovePCErrorDelegate OnError;
    public StovePCInitializationCompleteDelegate OnInitializationComplete;
    public StovePCTokenDelegate OnToken;
    public StovePCUserDelegate OnUser;
    public StovePCOwnershipDelegate OnOwnership;
 
    // GetStat処理が完了した時に呼び出されるコールバック
    public StovePCStatDelegate OnStat;
 
    // GetStat処理が完了した時に呼び出されるコールバック
    public StovePCSetStatDelegate OnSetStat;
 
    // GetAchievement処理が完了した時に呼び出されるコールバック
    public StovePCAchievementDelegate OnAchievement;
 
    // GetAllAchievement処理が完了した時に呼び出されるコールバック
    public StovePCAllAchievementDelegate OnAllAchievement;
 
    // GetRank API 呼び出し時に応答を受けるコールバック関数ポインタ
    public StovePCRankDelegate OnRank;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

連動する1）Config、Callbak設定のようにStove PCCallback構造体のコールバックポインタにコールバック関数を接続します。

// StovePCCallback構造体インスタンス作成
StovePCCallback callback;
this.callback = new StovePCCallback
{
    OnError = new StovePCErrorDelegate(this.OnError),
    OnInitializationComplete = new StovePCInitializationCompleteDelegate(this.OnInitializationComplete),
    OnToken = new StovePCTokenDelegate(this.OnToken),
    OnUser = new StovePCUserDelegate(this.OnUser),
    OnOwnership = new StovePCOwnershipDelegate(this.OnOwnership),
 
    // ゲームサポートサービス 
    OnStat = new StovePCStatDelegate(this.OnStat),
    OnSetStat = new StovePCSetStatDelegate(this.OnSetStat),
    OnAchievement = new StovePCAchievementDelegate(this.OnAchievement),
    OnAllAchievement = new StovePCAllAchievementDelegate(this.OnAllAchievement),
    OnRank = new StovePCRankDelegate(this.OnRank)
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

OnStat、OnSetStat、OnAchievement、OnAllAchievement、OnRankコールバック関数を必ず実現する必要はありません。

ゲームで使用するゲームサポートサービスに合わせて必要なコールバック関数を実装して接続できます。

# 2) 使用者スタットアップデートする

StovePC_SetStatメソッドでログインした使用者の当該ゲームに対する特定スタットをアップデートします。

// 入力パラメータ
// string stat Id：Studioで登録したスタット識別子
// int statValue：アップデートするスタット値
StovePCResult result = StovePC.SetStat("STAT_ID", STAT_VALUE);
if(result == StovePCResult.NoError)
{
    // 成功処理
}
1
2
3
4
5
6
7
8

StovePC_SetStat関数が正常に処理されれば、OnSetStatコールバックが呼び出されます。
コールバックに伝達されるStovePCStatValue構造体には現在スタット値とアップデートの状態を示すフラグやエラーメッセージが含まれています。

スタット価格が完全に反映されてアップデートされたなら、Updatedフィールドはtrue、ErrorMessageフィールドは、空の文字列が含まれ、スタット価格が部分的にアップデートしたら、Updatedフィールドはtrue、ErrorMessageフィールドは"integer overflow"のような文字列が含まれます。

例えば、INCREMENTタイプスタットの現在スタット価格が2,147,483,000と仮定してStovePC_SetStatAPIを通じて1,000を合算しとするなら、Int32タイプが持つことのできる値の範囲を脱することになるため、アップデートを要請した値(1,000)の一部だけが反映され、現在価格がInt32タイプの最大値の2,147,483,647にアップデートされている場合ErrorMessageフィールドに"integer overflow"のような文字列が含まれます。

下表はStovePCStatValue構造体を通じて得られる結果の一覧です。

スタット類型 Updated ErrorMessage 結果
すべての類型 True ""(空の文字列) 要請の価格が現在価格に完全にアップデートすること
INCREMENT True
INCREMENT False "integer overflow" ストレージ容量超過でアップデートされない
MIN False
MAX False
REPLACE Fasle 
private void OnSetStat(StovePCStatValue statValue)
{
    // スタットアップデート結果情報出力
    StringBuilder sb = new StringBuilder();
    sb.AppendLine("OnSetStat");
    sb.AppendFormat(" - statValue.CurrentValue : {0}" + Environment.NewLine, statValue.CurrentValue.ToString());
    sb.AppendFormat(" - statValue.Updated : {0}" + Environment.NewLine, statValue.Updated.ToString());
    sb.AppendFormat(" - statValue.ErrorMessage : {0}", statValue.ErrorMessage);
   
    Debug.Log(sb.ToString());
}
1
2
3
4
5
6
7
8
9
10
11

confirm 注意事項) コールバックパラメータStovePCStatValue構造体の有効な範囲は、コールバック関数スコープに限定されます。 PC SDKは、コールバック関数の実行が完了するとすぐに、内部で割り当てたメモリを解除します。 したがって、コールバック関数スコープの外でStovePCStatValue構造体の情報を使用するために保存が必要な場合は、必ず深いコピー(DeepCopy)を使ってコピーを生成し、コピーの使用が完了したらメモリご解除ください。

StovePC_SetStatのメソッドが実行中にエラーが発生するとOnErrorのコールバックが呼び出されます。 Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
2000 Invalid Access
3000 Wrong API Usage
4000 Stats ID Not Found
9000 Service Error

# 3) ユーザースタット情報を得る

Stove PC_Get Stat関数でログインしたユーザーの該当ゲームの特定のスタット情報を照会します。

// 入力パラメータ
// constchar*statId：Studioで登録したスタット識別子
StovePCResult result = StovePC.GetStat("STAT_ID");
if(result == StovePCResult.NoError)
{
    /* 成功処理 */
}
1
2
3
4
5
6
7

StovePC_GetStatのメソッドが正常に処理されるとOnStatのコールバックが呼び出されます。 コールバックにお届けするStovePCStat構造体には現在のスタット値が含まれています。

private void OnStat(StovePCStat stat)
{
    // スタット情報出力
    StringBuilder sb = new StringBuilder();
    sb.AppendLine("OnStat");
    sb.AppendFormat(" - stat.StatFullId.GameId : {0}" + Environment.NewLine, stat.StatFullId.GameId);
    sb.AppendFormat(" - stat.StatFullId.StatId : {0}" + Environment.NewLine, stat.StatFullId.StatId);
    sb.AppendFormat(" - stat.MemberNo : {0}" + Environment.NewLine, stat.MemberNo.ToString());
    sb.AppendFormat(" - stat.CurrentValue : {0}" + Environment.NewLine, stat.CurrentValue.ToString());
    sb.AppendFormat(" - stat.UpdatedAt : {0}", stat.UpdatedAt.ToString());
 
    Debug.Log(sb.ToString());
}
1
2
3
4
5
6
7
8
9
10
11
12
13

confirm 注意事項) コールバックパラメータStovePCStat構造体の有効な範囲はコールバックSTOVEのみとなります。 PC SDKはコールバックの実行が終わるとすぐに内部で割り当てたメモリを解除します。 したがって、コールバックSTOVEの外でStovePCStat構造体の情報を使用するために保存が必要な場合は、必ず深いコピー(Deep Copy)を使ってコピーを生成し、コピーの使用が完了したらメモリご解除ください。

StovePC_GetStatのメソッドが実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
2000 Invalid Access
3000 Wrong API Usage
4000 Stats ID Not Found
9000 Service Error

# 4)ユーザー単一業績情報を得る

Stove PC.Get Achievementメソッドでログインしたユーザーの当該ゲームの特定の単一業績情報を照会します。

// 入力パラメータ
// constchar*achievement Id：Studioで生成した業績識別子
StovePCResult result = StovePC.GetAchievement("ACHIEVEMENT_ID");
if(result == StovePCResult.NoError)
{
    /* 成功処理 */
}
1
2
3
4
5
6
7

StovePC_GetAchievementのメソッドが正常に処理されると、OnAchievementのコールバックが呼び出されます。

コールバックに配信されるStovePCAchievement構造体には、現在の業績値と業績達成状態、および業績のメタ情報が含まれています。

private void OnAchievement(StovePCAchievement achievement)
{
    // 単一業績情報出力
    StringBuilder sb = new StringBuilder();
    sb.AppendLine("OnAchievement");
    sb.AppendFormat(" - achievement.AchievementId : {0}" + Environment.NewLine, achievement.AchievementId);
    sb.AppendFormat(" - achievement.Name : {0}" + Environment.NewLine, achievement.Name);
    sb.AppendFormat(" - achievement.Description : {0}" + Environment.NewLine, achievement.Description);
    sb.AppendFormat(" - achievement.DefaultImage : {0}" + Environment.NewLine, achievement.DefaultImage);
    sb.AppendFormat(" - achievement.AchievedImage : {0}" + Environment.NewLine, achievement.AchievedImage);
    sb.AppendFormat(" - achievement.Condition.GoalValue : {0}" + Environment.NewLine, achievement.Condition.GoalValue.ToString());
    sb.AppendFormat(" - achievement.Condition.ValueOperation : {0}" + Environment.NewLine, achievement.Condition.ValueOperation);
    sb.AppendFormat(" - achievement.Condition.Type : {0}" + Environment.NewLine, achievement.Condition.Type);
    sb.AppendFormat(" - achievement.Value : {0}" + Environment.NewLine, achievement.Value.ToString());
    sb.AppendFormat(" - achievement.Status : {0}", achievement.Status);
 
    Debug.Log(sb.ToString());
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

confirm 注意事項) コールバックパラメータStovePCAchievement構造体の有効な範囲はコールバックSTOVEのみとなります。 PC SDKはコールバックの実行が終わるとすぐに内部で割り当てたメモリを解除します。 したがって、コールバックSTOVEの外でStovePCAchievement構造体の情報を使用するために保存が必要な場合は、必ずディープコピー(Deep Copy)でコピーを生成し、コピーの使用が完了したらメモリをご解除ください。

StovePC_GetAchievementのメソッドが実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
1200 Not found achievement
9000 Service Error

# 5) ユーザー全体の業績情報を得る

Stove PC.Get All Achievementメソッドでログインしたユーザーの当該ゲームのすべての業績情報を照会します。

StovePCResult result = StovePC.GetAllAchievement();
if(result == StovePCResult.NoError)
{
    /* 成功処理 */
}
1
2
3
4
5

StovePC_GetAllAchievementのメソッドが正常に処理されると、OnAllAchievementのコールバックが呼び出されます。

コールバックに配信されるStovePCAchievement構造体には、現在の業績値と業績達成状態、および業績のメタ情報が含まれています。

private void OnAchievement(StovePCAchievement[] achievements)
{
    // 全業績情報出力
    StringBuilder sb = new StringBuilder();
    sb.AppendLine("OnAllAchievement");
    sb.AppendFormat(" - achievements.Length : {0}" + Environment.NewLine, achievements.Length);
 
    for (int i = 0; i < achievements.Length; i++)
    {
        sb.AppendFormat(" - achievements[{0}].AchievementId : {1}" + Environment.NewLine, i, achievements[i].AchievementId);
        sb.AppendFormat(" - achievements[{0}].Name : {1}" + Environment.NewLine, i, achievements[i].Name);
        sb.AppendFormat(" - achievements[{0}].Description : {1}" + Environment.NewLine, i, achievements[i].Description);
        sb.AppendFormat(" - achievements[{0}].DefaultImage : {1}" + Environment.NewLine, i, achievements[i].DefaultImage);
        sb.AppendFormat(" - achievements[{0}].AchievedImage : {1}" + Environment.NewLine, i, achievements[i].AchievedImage);
        sb.AppendFormat(" - achievements[{0}].Condition.GoalValue : {1}" + Environment.NewLine, i, achievements[i].Condition.GoalValue.ToString());
        sb.AppendFormat(" - achievements[{0}].Condition.ValueOperation : {1}" + Environment.NewLine, i, achievements[i].Condition.ValueOperation);
        sb.AppendFormat(" - achievements[{0}].Condition.Type : {1}" + Environment.NewLine, i, achievements[i].Condition.Type);
        sb.AppendFormat(" - achievements[{0}].Value : {1}" + Environment.NewLine, i, achievements[i].Value.ToString());
        sb.AppendFormat(" - achievements[{0}].Status : {1}", i, achievements[i].Status);
 
        if (i < achievements.Length - 1)
            sb.AppendFormat(Environment.NewLine);
    }

    Debug.Log(sb.ToString());
}
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

confirm 注意事項) コールバックパラメータStovePCAchievement構造体配列の有効な範囲は、コールバック関数スコープに限られます。 PC SDKは、コールバック関数の実行が完了するとすぐに、内部で割り当てたメモリを解除します。 したがって、コールバック関数スコープ外でStovePCAchievement構造体配列の情報を使用するために保存が必要な場合は、必ずディープコピー(Deep Copy)を使ってコピーを生成し、コピーの使用が完了したらメモリをご解除ください。

StovePC_GetAllAchievementのメソッドが実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
9000 Service Error

# 6) リーダーボードランキング情報を得る

Stove PC_Get Rankメソッドで、該当ゲームの特定リーダーボードの順位情報を照会します。

// 入力パラメータ
// const char*leaderboardId:Studioで作成したリーダーボード識別子
// constunsigned int pageIndex : 照会するページ番号 (1 <= pageIndex)
// const unsigned int pageSize : 照会順位の個数 (1 <= pageSize <= 50)
// constbool includeMyRank:照会結果にログインしたユーザーの順位を含むかどうか
StovePCResult result = StovePC_GetRank("LEADERBOARD_ID", PAGE_INDEX, PAGE_SIZE, INCLUDE_MY_RANK);
if(result == StovePCResult.NoError)
{
    /* 成功処理 */
}
1
2
3
4
5
6
7
8
9
10

StovePC_GetRankのメソッドが正常に処理されるとOnRankのコールバックが呼び出されます。

コールバックに送られるStovePCRank構造体には、特定のユーザーの点数と順位情報が含まれます。

// コールバックパラメータ
// unsigned intrankTotalCount:照会したリーダーボードに集計された全体順位数
private void OnRank(StovePCRank[] ranks, uint rankTotalCount)
{
    // 順位情報出力
    StringBuilder sb = new StringBuilder();
    sb.AppendLine("OnRank");
    sb.AppendFormat(" - ranks.Length : {0}" + Environment.NewLine, ranks.Length);
 
    for (int i = 0; i < ranks.Length; i++)
    {
        sb.AppendFormat(" - ranks[{0}].MemberNo : {1}" + Environment.NewLine, i, ranks[i].MemberNo.ToString());
        sb.AppendFormat(" - ranks[{0}].Score : {1}" + Environment.NewLine, i, ranks[i].Score.ToString());
        sb.AppendFormat(" - ranks[{0}].Rank : {1}" + Environment.NewLine, i, ranks[i].Rank.ToString());
        sb.AppendFormat(" - ranks[{0}].Nickname : {1}" + Environment.NewLine, i, ranks[i].Nickname);
        sb.AppendFormat(" - ranks[{0}].ProfileImage : {1}" + Environment.NewLine, i, ranks[i].ProfileImage);
    }
 
    sb.AppendFormat(" - rankTotalCount : {0}", rankTotalCount);

    Debug.Log(sb.ToString());
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

confirm 注意事項) コールバックパラメータ StovePCRank 構造体配列の有効な範囲は、コールバック関数スコープに限定されます。 PC SDKは、コールバック関数の実行が完了するとすぐに、内部で割り当てたメモリを解除します。 したがって、コールバック関数スコープの外でStovePCRank構造体配列の情報を使用するために保存が必要な場合は、必ず深いコピー(DeepCopy)を使ってコピーを生成し、コピーの使用が完了したらメモリをご解除ください。

StovePC_GetRankのメソッドが実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
1251 Invalid Parameter
1252 CannotFindData
3603 ErrorLeaderBoardNotFound
3631 ErrorMembershipAPI
500 External Server Error
Last Updated: 2024/3/4 13:52:06

← PC SDK Unreal連動ガイド →