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

ゲームエンジン向け GS2-Lottery SDK の モデルの仕様 と API のリファレンス

モデル

EzProbability

排出確率

特定の景品の算出された排出確率を表します。確率は排出確率テーブル内の全景品の重みの合計に対するこの景品の重みから計算されます。ボックスガチャの場合、景品がボックスから排出されるにつれて確率は動的に変化します。

有効化条件必須デフォルト値の制限説明
prizeEzDrawnPrize
景品
この確率が対応する景品で、IDと入手アクションを含みます。
ratefloat
0 ~ 1.0排出確率 (0.0〜1.0)
この景品が排出される確率で、0.0から1.0の値で表されます。この景品の重みをテーブル内の全景品の重みの合計で割って算出されます。

EzDrawnPrize

排出された景品

抽選で排出された景品を表します。景品IDとユーザーに景品を付与するために実行された入手アクションを含みます。

有効化条件必須デフォルト値の制限説明
prizeIdstring
~ 36文字景品ID
排出された景品のIDで、排出確率テーブル内の景品エントリに対応します。
acquireActionsList<EzAcquireAction>0 ~ 100 items入手アクションのリスト
この景品をユーザーに付与するために実行された入手アクションのリストです。

EzBoxItems

ボックスアイテム

特定のユーザーと排出確率テーブルに対するボックスガチャの状態を記録します。ボックス内のすべての景品とその残数・初期数量のリストを含み、どの景品が排出済みでどの景品が残っているかをユーザーが確認できます。

有効化条件必須デフォルト値の制限説明
boxIdstring
~ 1024文字ボックス GRN
※ サーバーが自動で設定
prizeTableNamestring
~ 128文字排出確率テーブル名
このボックスに関連付けられた排出確率テーブルの名前です。このレコードがどのボックスガチャに属するかを識別します。
itemsList<EzBoxItem>[]0 ~ 1000 itemsアイテムリスト
ボックス内のすべての景品とその残数・初期数量のリストです。各アイテムはその景品が最初にボックスに何個あったか、何個残っているかを示し、ボックスガチャの抽選進行状況の追跡を可能にします。

EzLotteryModel

抽選モデル

抽選モデルは排出方式や排出テーブルの参照方法を定義するエンティティです。

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

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

有効化条件必須デフォルト値の制限説明
namestring
~ 128文字抽選モデル名
抽選モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
metadatastring~ 2048文字メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。
mode文字列列挙型
enum {
  “normal”,
  “box”
}
抽選モード
景品の抽選方式を選択します。“normal” は毎回一定の確率で抽選を行います(景品は繰り返し排出されます)。“box” は仮想的な箱にあらかじめ定義された数量の景品を入れ、抽選するたびに箱から景品を取り出します(すべての景品が最終的に排出されることが保証されます)。
定義説明
“normal”通常抽選
“box”BOX抽選
prizeTableNamestring{method} == “prize_table”
✓※
~ 128文字排出確率テーブルの名前
この抽選モデルで使用する排出確率テーブルの名前です。抽選方法が “prize_table” の場合に必須です。

※ method が “prize_table” であれば 必須

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",
"Gs2Schedule:ExtendTriggerByUserId",
"Gs2Script:InvokeScript",
"Gs2SerialKey:RevertUseByUserId",
"Gs2SerialKey:IssueOnce",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
}
入手アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzBoxItem

ボックスアイテム

ボックスガチャ内の単一の景品タイプを表し、ボックス内の初期数量、残数量、および排出時に実行される入手アクションを示します。

有効化条件必須デフォルト値の制限説明
prizeIdstring
~ 128文字景品ID
このボックスアイテムが対応する排出確率テーブル内の景品IDです。
acquireActionsList<EzAcquireAction>[]0 ~ 100 items入手アクションのリスト
この景品がボックスから排出された時に実行する入手アクションのリストです。
remainingint
0 ~ 2147483646残り数量
ボックス内に残っているこの景品の数です。この景品が排出されるたびに1つ減少します。
initialint
0 ~ 2147483646初期数量
最初にボックスに入れられたこの景品の数です。残数と合わせてどれだけ排出されたかを計算するために使用されます。

EzConfig

コンフィグ設定

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

有効化条件必須デフォルト値の制限説明
keystring
~ 64文字名前
valuestring~ 51200文字

EzVerifyActionResult

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

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
"Gs2Dictionary:VerifyEntryByUserId",
"Gs2Distributor:IfExpressionByUserId",
"Gs2Distributor:AndExpressionByUserId",
"Gs2Distributor:OrExpressionByUserId",
"Gs2Enchant:VerifyRarityParameterStatusByUserId",
"Gs2Experience:VerifyRankByUserId",
"Gs2Experience:VerifyRankCapByUserId",
"Gs2Grade:VerifyGradeByUserId",
"Gs2Grade:VerifyGradeUpMaterialByUserId",
"Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
"Gs2Guild:VerifyIncludeMemberByUserId",
"Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId",
"Gs2Inventory:VerifyItemSetByUserId",
"Gs2Inventory:VerifyReferenceOfByUserId",
"Gs2Inventory:VerifySimpleItemByUserId",
"Gs2Inventory:VerifyBigItemByUserId",
"Gs2Limit:VerifyCounterByUserId",
"Gs2Matchmaking:VerifyIncludeParticipantByUserId",
"Gs2Mission:VerifyCompleteByUserId",
"Gs2Mission:VerifyCounterValueByUserId",
"Gs2Ranking2:VerifyGlobalRankingScoreByUserId",
"Gs2Ranking2:VerifyClusterRankingScoreByUserId",
"Gs2Ranking2:VerifySubscribeRankingScoreByUserId",
"Gs2Schedule:VerifyTriggerByUserId",
"Gs2Schedule:VerifyEventByUserId",
"Gs2SerialKey:VerifyCodeByUserId",
"Gs2Stamina:VerifyStaminaValueByUserId",
"Gs2Stamina:VerifyStaminaMaxValueByUserId",
"Gs2Stamina:VerifyStaminaRecoverIntervalMinutesByUserId",
"Gs2Stamina:VerifyStaminaRecoverValueByUserId",
"Gs2Stamina:VerifyStaminaOverflowValueByUserId",
}
検証アクションで実行するアクションの種類
verifyRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
verifyResultstring~ 1048576文字結果内容

EzConsumeActionResult

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

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
"Gs2AdReward:ConsumePointByUserId",
"Gs2Dictionary:DeleteEntriesByUserId",
"Gs2Enhance:DeleteProgressByUserId",
"Gs2Exchange:DeleteAwaitByUserId",
"Gs2Experience:SubExperienceByUserId",
"Gs2Experience:SubRankCapByUserId",
"Gs2Formation:SubMoldCapacityByUserId",
"Gs2Grade:SubGradeByUserId",
"Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
"Gs2Inbox:OpenMessageByUserId",
"Gs2Inbox:DeleteMessageByUserId",
"Gs2Inventory:ConsumeItemSetByUserId",
"Gs2Inventory:ConsumeSimpleItemsByUserId",
"Gs2Inventory:ConsumeBigItemByUserId",
"Gs2JobQueue:DeleteJobByUserId",
"Gs2Limit:CountUpByUserId",
"Gs2LoginReward:MarkReceivedByUserId",
"Gs2Mission:ReceiveByUserId",
"Gs2Mission:BatchReceiveByUserId",
"Gs2Mission:DecreaseCounterByUserId",
"Gs2Mission:ResetCounterByUserId",
"Gs2Money:WithdrawByUserId",
"Gs2Money:RecordReceipt",
"Gs2Money2:WithdrawByUserId",
"Gs2Money2:VerifyReceiptByUserId",
"Gs2Quest:DeleteProgressByUserId",
"Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId",
"Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId",
"Gs2Schedule:DeleteTriggerByUserId",
"Gs2SerialKey:UseByUserId",
"Gs2Showcase:IncrementPurchaseCountByUserId",
"Gs2SkillTree:MarkRestrainByUserId",
"Gs2Stamina:DecreaseMaxValueByUserId",
"Gs2Stamina:ConsumeStaminaByUserId",
}
消費アクションで実行するアクションの種類
consumeRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
consumeResultstring~ 1048576文字結果内容

EzAcquireActionResult

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

有効化条件必須デフォルト値の制限説明
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",
"Gs2Schedule:ExtendTriggerByUserId",
"Gs2Script:InvokeScript",
"Gs2SerialKey:RevertUseByUserId",
"Gs2SerialKey:IssueOnce",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
}
入手アクションで実行するアクションの種類
acquireRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
acquireResultstring~ 1048576文字結果内容

EzTransactionResult

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

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

有効化条件必須デフォルト値の制限説明
transactionIdstring
36 ~ 36文字トランザクションID
verifyResultsList<EzVerifyActionResult>0 ~ 10 items検証アクションの実行結果リスト
consumeResultsList<EzConsumeActionResult>[]0 ~ 10 items消費アクションの実行結果リスト
acquireResultsList<EzAcquireActionResult>[]0 ~ 100 items入手アクションの実行結果リスト

メソッド

describeBoxes

プレイヤーが引いたすべてのボックスガチャの状態を取得する

ネームスペース内のすべてのボックスモードのガチャについて、ボックスの状態を取得します。
各エントリには、景品ごとの排出済み数と箱の中の残り数が含まれます。

すべてのボックスガチャの概要画面を作る際に使います。たとえば「初心者ボックス: 15/50排出済み」「プレミアムボックス: 3/100排出済み」のように進捗バー付きで表示できます。

このAPIはボックスモードのガチャにのみ適用されます。通常ガチャは景品が無制限に排出されるためボックスの状態はありません。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession
pageTokenstring~ 1024文字データの取得を開始する位置を指定するトークン
limitint301 ~ 1000データの取得件数

Result

説明
itemsList<EzBoxItems>ボックスから取り出したアイテムのリスト
nextPageTokenstringリストの続きを取得するためのページトークン

実装例

    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

特定のボックスガチャの状態を取得する

排出確率テーブル名を指定して、特定のボックスの現在の状態を取得します。
レスポンスにはボックス内の各景品、排出済み数、残り数が含まれます。

ボックスガチャの詳細画面を表示する際に使います。たとえば、残り数付きで全景品を一覧表示できます:
「SSR 伝説の剣: 0/1排出済み、SR 魔法の杖: 2/5排出済み、R ポーション: 10/30排出済み、…」

プレイヤーがもう1回引くかどうかを判断するために、箱の中に何が残っているかを確認できます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
prizeTableNamestring
~ 128文字排出確率テーブル名
gameSessionGameSession
GameSession

Result

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

実装例

    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 callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    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);

resetBox

ボックスガチャを初期状態にリセットする

ボックスをリセットして、すべての景品を元の数量に戻します。プレイヤーがまだ一度も引いていない状態に戻ります。
リセット後、すべての景品が再び排出可能になります。

ボックスガチャのUIで「ボックスリセット」ボタンを実装する際に使います。プレイヤーが目当ての景品を引いた後にボックスをリセットして、新しいボックスで再挑戦するような使い方ができます。
たとえば、SSRアイテムを引いた後にボックスをリセットして、新品のボックスからもう一度SSRを狙うといった流れです。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
prizeTableNamestring
~ 128文字排出確率テーブル名
gameSessionGameSession
GameSession

Result

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

実装例

    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

ガチャの現在の排出確率を取得する

指定されたガチャのすべての景品と、その現在の排出確率を取得します。
多くのゲームでプレイヤーに表示する「排出確率」「ガチャ詳細」画面を作る際に使います。

返される確率はガチャのモードによって異なります:

  • 通常ガチャ: すべてのプレイヤーに対して常に同じ確率が返されます(例: SSR: 3%、SR: 15%、R: 82%)。
  • ボックスガチャ: プレイヤーのボックスの現在の状態を反映した確率が返されます。景品が排出されて箱から取り除かれると、残りの景品の確率がそれに応じて変化します。たとえば、唯一のSSRが既に排出済みなら、SSRの確率は0%になります。

このAPIは、ガチャの排出確率表示義務への対応にも利用できます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
lotteryNamestring
~ 128文字抽選モデル名
抽選モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession

Result

説明
itemsList<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 callbackId = domain.SubscribeProbabilities(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

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

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

getLotteryModel

特定のガチャ(抽選)の詳細を取得する

抽選名を指定して、1つの抽選モデルの詳細を取得します。
ガチャの詳細画面を表示する際に使います。抽選モード(通常/ボックス)、関連する排出確率テーブル名などの設定情報を確認できます。

たとえば、プレイヤーが「引く」ボタンをタップする前に、そのガチャが通常ガチャなのかボックスガチャなのかを表示したり、ListProbabilities と組み合わせて現在の排出確率を表示したりできます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
lotteryNamestring
~ 128文字抽選モデル名
抽選モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

説明
itemEzLotteryModel抽選モデル

実装例

    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 callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    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);

listLotteryModels

ガチャ(抽選)の設定一覧を取得する

ネームスペースに設定されているすべての抽選モデルを取得します。
各モデルは1つのガチャ(抽選)を定義しており、抽選モード、参照する排出確率テーブル、景品の選出方法が含まれます。

抽選モードは2種類あります:

  • 通常抽選: 毎回固定の確率テーブルに基づいて抽選します。同じ景品が何度でも排出されます。一般的なガチャの動作です。
  • ボックス抽選: あらかじめ決められた数量の景品が仮想的な箱に入っており、抽選するたびに箱から景品を1つ取り出します。設定された数量以上に同じ景品は排出されず、箱が空になるとすべての景品を獲得したことになります。

ガチャ一覧画面を表示する際に使います。たとえば「プレミアムガチャ」「武器ガチャ」「ステップアップガチャ」などの一覧です。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

説明
itemsList<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 callbackId = domain.SubscribeLotteryModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

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

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