Documentation index for AI agents

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종류가 마련되어 있으며, 일반 추첨은 매번 일정한 확률로 추첨하는 방식이고, 박스 추첨은 상자 안에 미리 정해진 수량의 경품이 들어 있어 추첨할 때마다 상자에서 경품을 꺼내는 추첨 방식입니다.

추첨 처리를 수행할 때 배출 확률 테이블을 사용하는데,
GS2-Script를 사용하면 여러 번 추첨을 실행할 때 배출 확률 테이블 일부만 다른 테이블로 교체할 수 있습니다.
이 구조를 이용하면 10연 가챠에서 1회만 다른 추첨 확률 테이블을 적용하는 것이 가능해집니다.

타입활성화 조건필수기본값값 제한설명
namestring
~ 128자추첨 모델 이름
추첨 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
metadatastring~ 2048자메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에 영향을 미치지 않으므로, 게임 내에서 사용할 정보를 저장하는 용도로 사용할 수 있습니다.
mode문자열 열거형
enum {
  “normal”,
  “box”
}
추첨 모드
경품의 추첨 방식을 선택합니다. “normal"은 매번 일정한 확률로 추첨을 진행합니다(경품은 반복해서 배출됩니다). “box"는 가상의 상자에 미리 정해진 수량의 경품을 넣어두고, 추첨할 때마다 상자에서 경품을 꺼냅니다(모든 경품이 최종적으로 배출되는 것이 보장됩니다).
정의설명
normal일반 추첨
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 배출 완료, …"

플레이어가 다시 뽑을지 여부를 판단할 수 있도록, 상자 안에 무엇이 남아 있는지 확인할 수 있습니다.

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 = ez.lottery.namespace_(
        "namespace-0001"
    ).me(game_session).box_items(
        "prizeTable-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result
값 변경 이벤트 핸들링
    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);
var domain = ez.lottery.namespace_(
        "namespace-0001"
    ).me(game_session).box_items(
        "prizeTable-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

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

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
var domain = ez.lottery.namespace_(
        "namespace-0001"
    ).me(game_session).box_items(
        "prizeTable-0001"
    )

var async_result = await domain.reset_box(
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.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

특정 가챠(추첨)의 상세 정보를 취득한다

추첨 이름을 지정하여 하나의 추첨 모델의 상세 정보를 취득합니다.
가챠 상세 화면을 표시할 때 사용합니다. 추첨 모드(일반/박스), 관련된 배출 확률 테이블 이름 등의 설정 정보를 확인할 수 있습니다.

예를 들어 플레이어가 “뽑기” 버튼을 탭하기 전에, 해당 가챠가 일반 가챠인지 박스 가챠인지를 표시하거나, 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 = ez.lottery.namespace_(
        "namespace-0001"
    ).lottery_model(
        "lotteryModel-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result
값 변경 이벤트 핸들링
    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);
var domain = ez.lottery.namespace_(
        "namespace-0001"
    ).lottery_model(
        "lotteryModel-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

listLotteryModels

가챠(추첨)의 설정 목록을 취득한다

네임스페이스에 설정된 모든 추첨 모델을 취득합니다.
각 모델은 하나의 가챠(추첨)를 정의하며, 추첨 모드, 참조하는 배출 확률 테이블, 경품 선정 방법이 포함됩니다.

추첨 모드에는 2가지가 있습니다:

  • 일반 추첨: 매번 고정된 확률 테이블을 기준으로 추첨합니다. 같은 경품이 몇 번이라도 배출됩니다. 일반적인 가챠의 동작입니다.
  • 박스 추첨: 미리 정해진 수량의 경품이 가상의 상자에 들어 있으며, 추첨할 때마다 상자에서 경품을 하나씩 꺼냅니다. 설정된 수량 이상으로는 같은 경품이 배출되지 않으며, 상자가 비면 모든 경품을 획득한 것이 됩니다.

가챠 목록 화면을 표시할 때 사용합니다. 예를 들어 “프리미엄 가챠”, “무기 가챠”, “스텝업 가챠” 등의 목록입니다.

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