API Reference of GS2-Lottery SDK for Game Engine

Model

EzLotteryModel

Lottery Model

The Lottery Model is the entity that defines the emission method and emission rate in Lottery. There are two types of emission methods: the normal lottery method draws lots with a fixed probability each time, and the rate of emission is determined by the number of lots drawn. The box lottery is a lottery method in which a predefined number of prizes are placed in a box and the prizes are removed from the box each time the lottery is drawn.

The lottery process uses an ejection probability table. GS2-Script can be used to replace a part of the ejection probability table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different lottery probability table only once in a 10-round gacha.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Lottery Model Name
metadata	string		~ 128 chars	metadata
mode	enum { “normal”, “box” }	✓	~ 128 chars	Drawing mode
prizeTableName	string	{method} == “prize_table”	~ 128 chars	Name of prize table

Enumeration type definition to specify as mode

Enumerator String Definition	Description
normal	Normal
box	Box

EzProbability

Probability

	Type	Require	Default	Limitation	Description
prize	EzDrawnPrize	✓			Type of prize
rate	float	✓		~ 1.0	Emission probability (0.0-1.0)

EzAcquireAction

Acquire Action

	Type	Require	Default	Limitation	Description
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 chars	Types of actions to be performed in the acquire action
request	string	✓		~ 1048576 chars	JSON of request

EzDrawnPrize

Types of prizes

	Type	Require	Default	Limitation	Description
prizeId	string	✓		~ 36 chars	Prize ID
acquireActions	List<EzAcquireAction>			~ 100 items	List of Acquire Actions

EzBoxItem

Item taken out of the lottery box

	Type	Require	Limitation	Description
prizeId	string	✓	~ 128 chars	Prize Id
acquireActions	List<EzAcquireAction>		~ 100 items	List of Acquire Action
remaining	int	✓	~ 2147483646	Remaining quantity
initial	int	✓	~ 2147483646	Initial quantity

EzBoxItems

Items taken out of the lottery box

	Type	Require	Limitation	Description
boxId	string	✓	~ 1024 chars	Box GRN
prizeTableName	string	✓	~ 128 chars	Prize Table Name
items	List<EzBoxItem>		~ 1000 items	List of Items taken out of the box

EzConfig

Configration

Set values to be applied to transaction variables

	Type	Require	Default	Limitation	Description
key	string	✓		~ 64 chars	Name
value	string			~ 51200 chars	Value

EzVerifyActionResult

Verify action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the verify task
verifyRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
verifyResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzConsumeActionResult

Consume action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the consume action
consumeRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
consumeResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzAcquireActionResult

Acquire action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the acquire action
acquireRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
acquireResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzTransactionResult

Transaction execution results

Transaction execution results executed using server-side transaction auto-execution functionality

	Type	Require	Limitation	Description
transactionId	string	✓	36 ~ 36 chars	Transaction ID
verifyResults	List<EzVerifyActionResult>		~ 10 items	List of verify action execution results
consumeResults	List<EzConsumeActionResult>		~ 10 items	List of consume action execution results
acquireResults	List<EzAcquireActionResult>		~ 100 items	List of acquire action execution results

Methods

describeBoxes

Retrieve list of information on ejected items in the box

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzBoxItems>	List of boxes
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

    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

Retrieve information on ejected items in a box

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
prizeTableName	string	✓	~ 128 chars	Name of prize table
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
item	EzBoxItems	List of items taken out of the box

Implementation Example

    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;
    }

Value change event handling

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Lottery::Model::FBoxItems> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

resetBox

Reset Box

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
prizeTableName	string	✓	~ 128 chars	Name of prize table
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
item	EzBoxItems	List of items taken out of the box

Implementation Example

    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

Get emission probability

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
lotteryName	string	✓	~ 128 chars	Lottery Model Name
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
items	List<EzProbability>	List of Emission rate

Implementation Example

    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());
    }

Value change event handling

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Lottery(
        lotteryName: "lottery-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeProbabilities(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeProbabilities(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeProbabilities(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

getLotteryModel

Get lottery model by specifying lottery name

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
lotteryName	string	✓		~ 128 chars	Lottery Model Name

Result

	Type	Description
item	EzLotteryModel	Lottery Model

Implementation Example

    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;
    }

Value change event handling

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Lottery::Model::FLotteryModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listLotteryModels

Get list of lottery models

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name

Result

	Type	Description
items	List<EzLotteryModel>	List of Lottery Model

Implementation Example

    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());
    }

Value change event handling

    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeLotteryModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeLotteryModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeLotteryModels(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.