GS2-Lottery SDK for Game Engine API リファレンス

モデル

EzLotteryModel

抽選モデル

抽選モデルはLotteryで排出方式や排出レートを定義するエンティティです。排出方式は2種類用意されており、通常抽選は毎回一定の確率で抽選をする方式 Box抽選は箱の中にあらかじめ定義された数量の景品が入っており、抽選するたびに箱から景品を取り出していく抽選方式です。

抽選処理を行うにあたって、排出確率テーブルを利用しますが、 GS2-Script を使用すれば複数回抽選を実行した際に排出確率テーブルを一部だけ異なるテーブルに差し替えることができます。この仕組みを利用することで、10連ガチャで1回だけ異なる抽選確率テーブルを適用することが可能となります。

	型	必須	値の制限	説明
name	string	✓	~ 128文字	抽選モデルの種類名
metadata	string		~ 128文字	メタデータ
mode	enum [’normal’, ‘box’]	✓	~ 128文字	抽選モード
prizeTableName	string	{method} == “prize_table”	~ 128文字	排出確率テーブルの名前

EzProbability

	型	必須	デフォルト	値の制限	説明
prize	EzDrawnPrize	✓			景品の種類
rate	float	✓		~ 1.0	排出確率(0.0〜1.0)

EzAcquireAction

	型	必須	デフォルト	値の制限	説明
action	enum []	✓		~ 128文字	スタンプシートを使用して実行するアクションの種類
request	string	✓		~ 1048576文字	リクエストのJSON

EzDrawnPrize

	型	必須	デフォルト	値の制限	説明
prizeId	string	✓		~ 36文字	景品ID
acquireActions	List<EzAcquireAction>				入手アクションのリスト

EzBoxItem

	型	必須	値の制限	説明
prizeId	string	✓	~ 128文字	景品ID
acquireActions	List<EzAcquireAction>			入手アクションのリスト
remaining	int	✓	~ 2147483646	残り数量
initial	int	✓	~ 2147483646	初期数量

EzBoxItems

	型	必須	値の制限	説明
boxId	string	✓	~ 1024文字	ボックスGRN
prizeTableName	string	✓	~ 128文字	排出確率テーブル名
items	List<EzBoxItem>			ボックスから取り出したアイテムのリスト

EzConfig

	型	必須	デフォルト	値の制限	説明
key	string	✓		~ 64文字	名前
value	string			~ 51200文字	値

メソッド

describeBoxes

ボックスの排出済みアイテム情報一覧を取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
accessToken	string	✓		~ 128文字	ユーザーID
pageToken	string			~ 1024文字	データの取得を開始する位置を指定するトークン
limit	int	✓	30	1 ~ 1000	データの取得件数

Result

	型	説明
items	List<EzBoxItems>	ボックスのリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.BoxesAsync(
    ).ToListAsync();

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Boxes(
    );
    List<EzBoxItems> items = new List<EzBoxItems>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Boxes(
    );
    for (auto Item : *It)
    {

    }

getBox

ボックスの排出済みアイテム情報を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
prizeTableName	string	✓	~ 128文字	排出確率テーブル名
accessToken	string	✓	~ 128文字	ユーザーID

Result

	型	説明
item	EzBoxItems	ボックスから取り出したアイテムのリスト

実装例

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->BoxItems(
        "prizeTable-0001" // prizeTableName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

値の変更イベントハンドリング

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->BoxItems(
        "prizeTable-0001" // prizeTableName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Lottery::Model::FBoxItems> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

resetBox

ボックスのリセット

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
prizeTableName	string	✓	~ 128文字	排出確率テーブル名
accessToken	string	✓	~ 128文字	ユーザーID

Result

	型	説明

実装例

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    var result = await domain.ResetBoxAsync(
    );

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    var future = domain.ResetBox(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->BoxItems(
        "prizeTable-0001" // prizeTableName
    );
    const auto Future = Domain->ResetBox(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

listProbabilities

排出確率を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
lotteryName	string	✓	~ 128文字	抽選モデルの種類名
accessToken	string	✓	~ 128文字	ユーザーID

Result

	型	説明
items	List<EzProbability>	景品の当選確率リスト

実装例

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.ProbabilitiesAsync(
    ).ToListAsync();

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Probabilities(
    );
    List<EzProbability> items = new List<EzProbability>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Probabilities( // lotteryName
    );
    for (auto Item : *It)
    {

    }

値の変更イベントハンドリング

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeProbabilities(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeProbabilities(callbackId);

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Probabilities(
    );
    List<EzProbability> items = new List<EzProbability>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeProbabilities(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeProbabilities(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

getLotteryModel

抽選名を指定して抽選モデルを取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
lotteryName	string	✓		~ 128文字	抽選モデルの種類名

Result

	型	説明
item	EzLotteryModel	抽選モデル

実装例

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->LotteryModel(
        "lotteryModel-0001" // lotteryName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

値の変更イベントハンドリング

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->LotteryModel(
        "lotteryModel-0001" // lotteryName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Lottery::Model::FLotteryModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

listLotteryModels

抽選モデルの一覧を取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名

Result

	型	説明
items	List<EzLotteryModel>	抽選モデルのリスト

実装例

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.LotteryModelsAsync(
    ).ToListAsync();

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.LotteryModels(
    );
    List<EzLotteryModel> items = new List<EzLotteryModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->LotteryModels(
    );
    for (auto Item : *It)
    {

    }

値の変更イベントハンドリング

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeLotteryModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeLotteryModels(callbackId);

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.LotteryModels(
    );
    List<EzLotteryModel> items = new List<EzLotteryModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeLotteryModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeLotteryModels(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。