GS2-Lottery

Lottery processing function

This is a mechanism for implementing gachas. GS2-Lottery supports both regular and boxed gachas.

Normal Gacha

Normal gachas are pure lotteries with a specified probability.

Prize Table

The prize table defines the emission probabilities of the prizes that will appear when the gacha is executed. It is defined as master data.

Weights

To set the probability in the prize table, set the weight for each prize. Specifically, the following table will be created.

Weight
Prize A1
Prize B2
Prize C4

Interpreting this as a probability by percentage, it can be interpreted as follows

weightprobability
Prize A114.285%
Prize B228.571%
Prize C457.143%

When you have to set probabilities on a percentage basis, you have to think about adding everything up to get to 100%, but When you set probabilities on a weight basis, there is no such burden.

Nesting of prize tables

The prize table can be nested up to 5 layers.

Specific uses include

  • 3% for the emission probability of SSR characters
  • 7% for the emission probability of SR characters
  • 90% for the emission probability of R characters

This is useful when you want to set the characters to be emitted based on the basic guideline of In this case, we would define 4 prize tables, with 2 tiers.

Prize table for rarity lottery

weightprize typelottery table name
SSR3Nested prize tablePrize table for SSR character lottery
SR7Nested prize tablePrize table for SR character lottery
R90Nested prize tablePrize table for R character lottery

Prize table for SSR character lottery

weightprize typelottery table name
SSR-00011Acquisition processRecord SSR-0001 in GS2-Dictionary
SSR-00021Acquisition processRecord SSR-0002 in GS2-Dictionary
SSR-00031Acquisition processRecord SSR-0003 in GS2-Dictionary

Prize table for SR character lottery

weightprize typelottery table name
SR-00011Acquisition processRecord SR-0001 in GS2-Dictionary
SR-00021Acquisition processRecord SR-0002 in GS2-Dictionary
SR-00031Acquisition processRecord SR-0003 in GS2-Dictionary

Prize table for R character lottery

weightprize typelottery table name
R-00011Acquisition processRecord R-0001 in GS2-Dictionary
R-00021Acquisition processRecord R-0002 in GS2-Dictionary
R-00031Acquisition processRecord R-0003 in GS2-Dictionary

BOX gacha

BOX gacha places the specified number of prizes defined in the master data in the BOX. When the lottery is carried out, the content of the prizes is determined by taking the prizes from the BOX.

In other words, if a BOX is prepared containing one prize out of 100 prizes, the winning prize will be drawn 100 times for sure.

Putting prizes into the BOX

The prize table is also used to set the prizes in the BOX. In the normal lottery mode the weight of the prize is set, but in the weight parameter the number of prizes to be thrown into the BOX is set.

Weight
Prize A1
Prize B2
Prize C4

In this case, the BOX initially contains 7 prizes, Prize A x 1, Prize B x 2 and Prize C x 4.

Lottery model

The Lottery Model specifies which of the prize tables can be used in the Lottery API. It is defined as master data.

In the above example, we want the prize table for the SSR character lottery to be used to process the lottery out of the blue when the Lottery API is called.

The following master data should be defined in the lottery model

lottery model nameprize table name
gachaPrize table for rarity lottery

When calling the lottery process, specify “gacha” in the lottery model name.

Example of implementation

Executing the lottery

Executing the lottery cannot be handled by the SDK for the game engine.

Please implement it in such a way that the lottery is executed as a reward for purchasing GS2-Showcase products.

Obtaining the probability of emission

    var items = await gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).ProbabilitiesAsync(
        lotteryName: "lottery-0001"
    ).ToListAsync();
    const auto It = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Probabilities(
        "lottery-0001" // lotteryName
    );
    TArray<Gs2::UE5::Lottery::Model::FEzProbabilityPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Get contents of BOX

    var result = await gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).GetBoxAsync(
        prizeTableName: "prizeTable-0001"
    );
    var item = await result.ModelAsync();
    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->BoxItems(
        "prizeTable-0001" // prizeTableName
    );
    const auto item = Domain.Model();

Reset BOX

    var result = await gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).ResetBoxAsync(
        prizeTableName: "prizeTable-0001"
    );
    const auto Future = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->BoxItems(
        "prizeTable-0001" // prizeTableName
    )->ResetBox(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;

Other features

Limit on quantity of prizes ejected

When operating in normal mode, you can set a maximum amount limit for each prize to be paid. Using this function will cause discrepancies between the probability that the Probabilities function responds to and the actual probability. This feature should not be used if you are using Probabilities to display the probability of dispensing.

The intended use is for a lottery process to distribute physical prizes. This function is useful in cases where there is a token with a 1% probability of being drawn, but only 100 tokens are prepared. The maximum number of tickets to be ejected is set to 100, and the failover prizes are set to outliers and different winning prizes.

By setting it this way, if 100 gift certificates have already been ejected and one gift certificate is won The prize set as the failover prize is ejected instead of the gift certificate. If a quantity limit is set for the failover prize, the same limit will apply.

Detailed Reference