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文字	排出確率テーブルの名前

mode に指定する列挙型の定義

定義	説明
normal	通常抽選
box	BOX抽選

EzProbability

排出確率

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

EzAcquireAction

入手アクション

	型	必須	デフォルト	値の制限	説明
action	enum { "Gs2AdReward:AcquirePointByUserId", "Gs2Dictionary:AddEntriesByUserId", "Gs2Enchant:ReDrawBalanceParameterStatusByUserId", "Gs2Enchant:SetBalanceParameterStatusByUserId", "Gs2Enchant:ReDrawRarityParameterStatusByUserId", "Gs2Enchant:AddRarityParameterStatusByUserId", "Gs2Enchant:SetRarityParameterStatusByUserId", "Gs2Enhance:DirectEnhanceByUserId", "Gs2Enhance:UnleashByUserId", "Gs2Enhance:CreateProgressByUserId", "Gs2Exchange:ExchangeByUserId", "Gs2Exchange:IncrementalExchangeByUserId", "Gs2Exchange:CreateAwaitByUserId", "Gs2Exchange:AcquireForceByUserId", "Gs2Exchange:SkipByUserId", "Gs2Experience:AddExperienceByUserId", "Gs2Experience:SetExperienceByUserId", "Gs2Experience:AddRankCapByUserId", "Gs2Experience:SetRankCapByUserId", "Gs2Experience:MultiplyAcquireActionsByUserId", "Gs2Formation:AddMoldCapacityByUserId", "Gs2Formation:SetMoldCapacityByUserId", "Gs2Formation:AcquireActionsToFormProperties", "Gs2Formation:SetFormByUserId", "Gs2Formation:AcquireActionsToPropertyFormProperties", "Gs2Friend:UpdateProfileByUserId", "Gs2Grade:AddGradeByUserId", "Gs2Grade:ApplyRankCapByUserId", "Gs2Grade:MultiplyAcquireActionsByUserId", "Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName", "Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName", "Gs2Idle:IncreaseMaximumIdleMinutesByUserId", "Gs2Idle:SetMaximumIdleMinutesByUserId", "Gs2Idle:ReceiveByUserId", "Gs2Inbox:SendMessageByUserId", "Gs2Inventory:AddCapacityByUserId", "Gs2Inventory:SetCapacityByUserId", "Gs2Inventory:AcquireItemSetByUserId", "Gs2Inventory:AcquireItemSetWithGradeByUserId", "Gs2Inventory:AddReferenceOfByUserId", "Gs2Inventory:DeleteReferenceOfByUserId", "Gs2Inventory:AcquireSimpleItemsByUserId", "Gs2Inventory:SetSimpleItemsByUserId", "Gs2Inventory:AcquireBigItemByUserId", "Gs2Inventory:SetBigItemByUserId", "Gs2JobQueue:PushByUserId", "Gs2Limit:CountDownByUserId", "Gs2Limit:DeleteCounterByUserId", "Gs2LoginReward:DeleteReceiveStatusByUserId", "Gs2LoginReward:UnmarkReceivedByUserId", "Gs2Lottery:DrawByUserId", "Gs2Lottery:ResetBoxByUserId", "Gs2Mission:RevertReceiveByUserId", "Gs2Mission:IncreaseCounterByUserId", "Gs2Mission:SetCounterByUserId", "Gs2Money:DepositByUserId", "Gs2Money:RevertRecordReceipt", "Gs2Money2:DepositByUserId", "Gs2Quest:CreateProgressByUserId", "Gs2Schedule:TriggerByUserId", "Gs2Script:InvokeScript", "Gs2SerialKey:RevertUseByUserId", "Gs2SerialKey:IssueOnce", "Gs2Showcase:DecrementPurchaseCountByUserId", "Gs2Showcase:ForceReDrawByUserId", "Gs2SkillTree:MarkReleaseByUserId", "Gs2Stamina:RecoverStaminaByUserId", "Gs2Stamina:RaiseMaxValueByUserId", "Gs2Stamina:SetMaxValueByUserId", "Gs2Stamina:SetRecoverIntervalByUserId", "Gs2Stamina:SetRecoverValueByUserId", "Gs2StateMachine:StartStateMachineByUserId", }	✓		~ 128文字	入手アクションで実行するアクションの種類
request	string	✓		~ 1048576文字	リクエストのJSON

EzDrawnPrize

景品の種類

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

EzBoxItem

ボックスから取り出したアイテム

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

EzBoxItems

ボックスから取り出したアイテムのリスト

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

EzConfig

コンフィグ設定

トランザクションの変数に適用する設定値

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

EzVerifyActionResult

検証アクションの実行結果

	型	必須	値の制限	説明
action	enum { }	✓	~ 128文字	検証アクションで実行するアクションの種類
verifyRequest	string	✓	~ 1048576文字	リクエストのJSON
statusCode	int		~ 999	ステータスコード
verifyResult	string		~ 1048576文字	結果内容

action に指定する列挙型の定義

定義	説明

EzConsumeActionResult

消費アクションの実行結果

	型	必須	値の制限	説明
action	enum { }	✓	~ 128文字	消費アクションで実行するアクションの種類
consumeRequest	string	✓	~ 1048576文字	リクエストのJSON
statusCode	int		~ 999	ステータスコード
consumeResult	string		~ 1048576文字	結果内容

action に指定する列挙型の定義

定義	説明

EzAcquireActionResult

入手アクションの実行結果

	型	必須	値の制限	説明
action	enum { }	✓	~ 128文字	入手アクションで実行するアクションの種類
acquireRequest	string	✓	~ 1048576文字	リクエストのJSON
statusCode	int		~ 999	ステータスコード
acquireResult	string		~ 1048576文字	結果内容

action に指定する列挙型の定義

定義	説明

EzTransactionResult

トランザクション実行結果

サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果

	型	必須	値の制限	説明
transactionId	string	✓	36 ~ 36文字	トランザクションID
verifyResults	List<EzVerifyActionResult>		~ 10 items	検証アクションの実行結果リスト
consumeResults	List<EzConsumeActionResult>		~ 10 items	消費アクションの実行結果リスト
acquireResults	List<EzAcquireActionResult>		~ 100 items	入手アクションの実行結果リスト

メソッド

describeBoxes

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

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名
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(
        GameSession
    );
    const auto It = Domain->Boxes(
    );
    TArray<Gs2::UE5::Lottery::Model::FEzBoxItemsPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

getBox

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

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名
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.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->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.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->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	✓	~ 128文字	ネームスペース名
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 result = await domain.ResetBoxAsync(
    );
    var item = await result.ModelAsync();

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

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

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

listProbabilities

排出確率を取得

Request

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

Result

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

実装例

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

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Lottery(
        lotteryName: "lottery-0001"
    );
    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(
        GameSession
    )->Lottery(
        "lottery-0001" // lotteryName
    );
    const auto It = Domain->Probabilities(
    );
    TArray<Gs2::UE5::Lottery::Model::FEzProbabilityPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

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

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

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

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Lottery(
        lotteryName: "lottery-0001"
    );
    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(
        GameSession
    )->Lottery(
        "lottery-0001" // lotteryName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeProbabilities(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

Warning

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

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

getLotteryModel

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

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名
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.ModelFuture();
    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.ModelFuture();
    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	✓		~ 128文字	ネームスペース名

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(
    );
    TArray<Gs2::UE5::Lottery::Model::FEzLotteryModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

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

    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がもつローカルキャッシュの値が変更された時に呼び出されます。

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