GS2-Lottery SDK for Game Engine API Reference
Models
EzProbability
Draw Probability
Represents the calculated draw probability for a specific prize. The rate is computed from the prize’s weight relative to the total weight of all prizes in the Prize Table. For box gacha, the probability changes dynamically as prizes are drawn from the box.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| prize | EzDrawnPrize | ✓ |
Prize The prize that this probability corresponds to, including its ID and acquire actions. |
|||
| rate | float | ✓ |
0 ~ 1.0 | Draw Probability (0.0-1.0) The probability of drawing this prize, expressed as a value between 0.0 and 1.0. Calculated as this prize’s weight divided by the total weight of all prizes in the table. |
EzDrawnPrize
Drawn Prize
Represents a prize that has been drawn from the lottery. Contains the prize ID and the acquire actions that were executed to grant the prize to the user.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| prizeId | string | ✓ |
~ 36 chars | Prize ID The ID of the drawn prize, corresponding to a prize entry in the Prize Table. |
||
| acquireActions | List<EzAcquireAction> | 0 ~ 100 items | List of Acquire Actions The list of acquire actions executed to grant this prize to the user. |
EzBoxItems
Box Items
Records the state of a box gacha for a specific user and Prize Table. Contains the list of all prizes in the box along with their remaining and initial quantities, allowing the user to see which prizes have been drawn and which remain.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| boxId | string | * |
~ 1024 chars | Box
GRN
* Set automatically by the server |
||
| prizeTableName | string | ✓ |
~ 128 chars | Prize Table name The name of the Prize Table associated with this box. Identifies which box gacha this record belongs to. |
||
| items | List<EzBoxItem> | [] | 0 ~ 1000 items | Items The list of all prizes in the box with their remaining and initial quantities. Each item shows how many of that prize were originally in the box and how many remain, allowing tracking of the box gacha’s draw progress. |
EzLotteryModel
Lottery Model
Lottery Model is an entity that defines the draw method and how to reference the draw table.
Two draw methods are available: Normal Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw.
The lottery process uses a Prize Table. GS2-Script can be used to dynamically select the Prize Table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different Prize Table only once in a 10-round gacha.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ |
~ 128 chars | Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). |
||||||||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
|||||||||
| mode | string (enum) enum { “normal”, “box” } |
✓ |
Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn).
|
|||||||||
| prizeTableName | string | {method} == “prize_table” | ✓* |
~ 128 chars | Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” |
EzAcquireAction
Acquire Action
EzBoxItem
Box Item
Represents a single prize type within a box gacha, showing its initial quantity in the box, remaining quantity, and the acquire actions that will be executed when drawn.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| prizeId | string | ✓ |
~ 128 chars | Prize ID The ID of the prize in the Prize Table that this box item corresponds to. |
||
| acquireActions | List<EzAcquireAction> | [] | 0 ~ 100 items | List of Acquire Actions The list of acquire actions to execute when this prize is drawn from the box. |
||
| remaining | int | ✓ |
0 ~ 2147483646 | Remaining Quantity The number of this prize still remaining in the box. Decreases by one each time this prize is drawn. |
||
| initial | int | ✓ |
0 ~ 2147483646 | Initial Quantity The number of this prize that was originally placed in the box. Used together with remaining to calculate how many have been drawn. |
EzConfig
Configuration
Configuration values applied to transaction variables
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ |
~ 64 chars | Name | ||
| value | string | ~ 51200 chars | Value |
EzVerifyActionResult
Verify Action execution result
EzConsumeActionResult
Consume Action execution result
EzAcquireActionResult
Acquire Action execution result
EzTransactionResult
Transaction execution result
Result of a transaction executed using the server-side automatic execution feature
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ |
36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of Consume Action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List of Acquire Action execution results |
Methods
describeBoxes
Get the status of all box gachas the player has drawn from
Retrieves the box state for every box-mode gacha in the namespace. Each entry shows how many of each prize have already been drawn and how many remain in the box.
Use this to build an overview screen of all box gachas — for example, showing “Starter Box: 15/50 drawn” and “Premium Box: 3/100 drawn” with progress bars.
This API only applies to box-mode gachas. Normal gachas don’t have box state since prizes can be drawn repeatedly without limit.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| gameSession | GameSession | ✓ |
GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzBoxItems> | List of box states |
| 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
Get the status of a specific box gacha
Retrieves the current state of a specific box by Prize Table name. The response shows each prize in the box, how many have been drawn, and how many remain.
Use this to display the box gacha detail screen — for example, listing all available prizes with their remaining counts: “SSR Legendary Sword: 0/1 drawn, SR Magic Staff: 2/5 drawn, R Potion: 10/30 drawn, …”
This lets the player see what’s left in the box before deciding to draw again.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| prizeTableName | string | ✓ |
~ 128 chars | Prize Table name | ||
| gameSession | GameSession | ✓ |
GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzBoxItems | Box state including prizes and their remaining quantities |
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"
);
// 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); 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
resetBox
Reset a box gacha back to its initial state
Resets the box so that all prizes are returned to it, as if the player had never drawn from it. After resetting, every prize becomes available again at its original quantity.
This is useful for implementing features like “Reset Box” buttons in box gacha UIs, where the player can choose to start over — typically after obtaining the main prize they wanted. For example, the player draws the SSR item from the box, then resets the box to try for another SSR in a fresh box.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| prizeTableName | string | ✓ |
~ 128 chars | Prize Table name | ||
| gameSession | GameSession | ✓ |
GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzBoxItems | Box state including prizes and their initial quantities |
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 the current draw probability for a gacha
Retrieves the list of all prizes and their current draw probabilities for the specified gacha. Use this to display the “Draw Probability” or “Gacha Details” screen that many games show to players.
The probabilities returned depend on the gacha mode:
- Normal gacha: The probabilities are always the same for all players (e.g., SSR: 3%, SR: 15%, R: 82%).
- Box gacha: The probabilities reflect the current state of the player’s box. As prizes are drawn and removed, the remaining prizes’ probabilities change accordingly. For example, if the only SSR has already been drawn, the SSR probability becomes 0%.
This API is typically used to comply with gacha probability disclosure requirements.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| lotteryName | string | ✓ |
~ 128 chars | Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). |
||
| gameSession | GameSession | ✓ |
GameSession |
Result
| Type | Description | |
|---|---|---|
| items | List<EzProbability> | List of draw probabilities |
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"
);
// Start event handling
var callbackId = domain.SubscribeProbabilities(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeProbabilities(callbackId); 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getLotteryModel
Get the details of a specific gacha/lottery
Retrieves a single lottery model by name. Use this to display the gacha detail screen — showing the draw mode (normal or box), the associated Prize Table name, and other configuration.
For example, before the player taps “Draw”, you can use this API to show whether the gacha is a standard gacha or a box gacha, and combine it with ListProbabilities to display the current draw probabilities.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| lotteryName | string | ✓ |
~ 128 chars | Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). |
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"
);
// 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); 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listLotteryModels
Get a list of all gacha/lottery configurations
Retrieves all lottery models configured in the namespace. Each model defines a gacha (lottery) — its draw mode, the Prize Table it references, and how prizes are selected.
There are two draw modes:
- Normal: Each draw uses a fixed probability table. The same prize can be drawn any number of times. This is the standard gacha behavior.
- Box: Prizes are placed in a virtual box with fixed quantities. Each draw removes a prize from the box, so the same prize cannot be drawn more than its set quantity. When the box is empty, all prizes have been obtained.
Use this to display a gacha list screen — for example, “Premium Gacha”, “Weapon Gacha”, “Step-Up Gacha”, etc.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
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"
);
// Start event handling
var callbackId = domain.SubscribeLotteryModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeLotteryModels(callbackId); 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.