> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Lottery SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-Lottery SDK의 모델 사양과 API 레퍼런스



## 모델

### EzProbability

배출 확률<br>

특정 경품의 산출된 배출 확률을 나타냅니다. 확률은 배출 확률 테이블 내 전체 경품 가중치의 합에 대한 이 경품의 가중치로 계산됩니다. 박스 가챠의 경우, 경품이 박스에서 배출됨에 따라 확률이 동적으로 변화합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| prize | [EzDrawnPrize](#ezdrawnprize) |  | ✓ |  |  | 경품<br>이 확률이 대응하는 경품으로, ID와 입수 액션을 포함합니다. |
| rate | float |  | ✓ |  | 0 ~ 1.0 | 배출 확률 (0.0~1.0)<br>이 경품이 배출될 확률로, 0.0에서 1.0 사이의 값으로 표현됩니다. 이 경품의 가중치를 테이블 내 전체 경품 가중치의 합으로 나누어 산출됩니다. |

**관련 메서드:**
listProbabilities - 가챠의 현재 배출 확률을 취득한다


---

### EzDrawnPrize

배출된 경품<br>

추첨으로 배출된 경품을 나타냅니다. 경품 ID와 사용자에게 경품을 지급하기 위해 실행된 입수 액션을 포함합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| prizeId | string |  | ✓ |  |  ~ 36자 | 경품 ID<br>배출된 경품의 ID로, 배출 확률 테이블 내 경품 항목에 대응합니다. |
| acquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  |  | 0 ~ 100 items | 입수 액션 리스트<br>이 경품을 사용자에게 지급하기 위해 실행된 입수 액션의 리스트입니다. |


**관련 모델:**
EzProbability - 배출 확률



---

### EzBoxItems

박스 아이템 리스트<br>

특정 사용자와 배출 확률 테이블에 대한 박스 가챠의 상태를 기록합니다. 박스 내 모든 경품과 그 잔여 수량·초기 수량의 리스트를 포함하여, 어떤 경품이 배출되었고 어떤 경품이 남아있는지 사용자가 확인할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| boxId | string |  | ※ |  |  ~ 1024자 | 박스 GRN<br>※ 서버가 자동으로 설정 |
| prizeTableName | string |  | ✓ |  |  ~ 128자 | 배출 확률 테이블 이름<br>이 박스와 연결된 배출 확률 테이블의 이름입니다. 이 레코드가 어느 박스 가챠에 속하는지를 식별합니다. |
| items | [List&lt;EzBoxItem&gt;](#ezboxitem) |  |  | [] | 0 ~ 1000 items | 아이템 리스트<br>박스 내 모든 경품과 그 잔여 수량·초기 수량의 리스트입니다. 각 아이템은 해당 경품이 처음 박스에 몇 개 있었는지, 몇 개 남아있는지를 나타내며, 박스 가챠의 추첨 진행 상황을 추적할 수 있게 합니다. |

**관련 메서드:**
describeBoxes - 플레이어가 뽑은 모든 박스 가챠의 상태를 취득한다
getBox - 특정 박스 가챠의 상태를 취득한다
resetBox - 박스 가챠를 초기 상태로 리셋한다


---

### EzLotteryModel

추첨 모델<br>

추첨 모델은 배출 방식과 배출 테이블의 참조 방법을 정의하는 엔티티입니다.<br>

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

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

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

**관련 메서드:**
getLotteryModel - 특정 가챠(추첨)의 상세 정보를 취득한다
listLotteryModels - 가챠(추첨)의 설정 목록을 취득한다


---

### EzAcquireAction

입수 액션

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 입수 액션에서 실행할 액션의 종류 |
| request | string |  | ✓ |  |  ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |


**관련 모델:**
EzDrawnPrize - 배출된 경품
EzBoxItem - 박스 아이템



---

### EzBoxItem

박스 아이템<br>

박스 가챠 내 단일 경품 유형을 나타내며, 박스 내 초기 수량, 잔여 수량, 그리고 배출 시 실행되는 입수 액션을 나타냅니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| prizeId | string |  | ✓ |  |  ~ 128자 | 경품 ID<br>이 박스 아이템이 대응하는 배출 확률 테이블 내 경품 ID입니다. |
| acquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  | [] | 0 ~ 100 items | 입수 액션 리스트<br>이 경품이 박스에서 배출되었을 때 실행할 입수 액션의 리스트입니다. |
| remaining | int |  | ✓ |  | 0 ~ 2147483646 | 잔여 수량<br>박스 내에 남아있는 이 경품의 수입니다. 이 경품이 배출될 때마다 1개씩 감소합니다. |
| initial | int |  | ✓ |  | 0 ~ 2147483646 | 초기 수량<br>처음 박스에 담긴 이 경품의 수입니다. 잔여 수량과 함께 얼마나 배출되었는지를 계산하는 데 사용됩니다. |


**관련 모델:**
EzBoxItems - 박스 아이템 리스트



---

### EzConfig

컨피그 설정<br>

트랜잭션의 변수에 적용하는 설정 값

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64자 | 이름 |
| value | string |  |  |  |  ~ 51200자 | 값 |


---

### EzVerifyActionResult

검증 액션 실행 결과

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 검증 액션에서 실행할 액션의 종류 |
| verifyRequest | string |  | ✓ |  |  ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
| statusCode | int |  |  |  | 0 ~ 999 | 상태 코드 |
| verifyResult | string |  |  |  |  ~ 1048576자 | 결과 내용 |


**관련 모델:**
EzTransactionResult - 트랜잭션 실행 결과



---

### EzConsumeActionResult

소비 액션 실행 결과

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 소비 액션에서 실행할 액션의 종류 |
| consumeRequest | string |  | ✓ |  |  ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
| statusCode | int |  |  |  | 0 ~ 999 | 상태 코드 |
| consumeResult | string |  |  |  |  ~ 1048576자 | 결과 내용 |


**관련 모델:**
EzTransactionResult - 트랜잭션 실행 결과



---

### EzAcquireActionResult

획득 액션 실행 결과

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 입수 액션에서 실행할 액션의 종류 |
| acquireRequest | string |  | ✓ |  |  ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
| statusCode | int |  |  |  | 0 ~ 999 | 상태 코드 |
| acquireResult | string |  |  |  |  ~ 1048576자 | 결과 내용 |


**관련 모델:**
EzTransactionResult - 트랜잭션 실행 결과



---

### EzTransactionResult

트랜잭션 실행 결과<br>

서버 사이드에서 트랜잭션 자동 실행 기능을 이용하여 실행된 트랜잭션의 실행 결과

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string |  | ✓ |  | 36 ~ 36자 | 트랜잭션 ID |
| verifyResults | [List&lt;EzVerifyActionResult&gt;](#ezverifyactionresult) |  |  |  | 0 ~ 10 items | 검증 액션의 실행 결과 목록 |
| consumeResults | [List&lt;EzConsumeActionResult&gt;](#ezconsumeactionresult) |  |  | [] | 0 ~ 10 items | 소비 액션의 실행 결과 목록 |
| acquireResults | [List&lt;EzAcquireActionResult&gt;](#ezacquireactionresult) |  |  | [] | 0 ~ 100 items | 획득 액션 실행 결과 리스트 |


---

## 메서드

### describeBoxes

플레이어가 뽑은 모든 박스 가챠의 상태를 취득한다<br>

네임스페이스 내 모든 박스 모드 가챠에 대해 박스 상태를 취득합니다.<br>
각 항목에는 경품별 배출 완료 수와 상자 안에 남은 수가 포함됩니다.<br>

모든 박스 가챠의 개요 화면을 만들 때 사용합니다. 예를 들어 "초심자 박스: 15/50 배출 완료", "프리미엄 박스: 3/100 배출 완료"처럼 진행률 바와 함께 표시할 수 있습니다.<br>

이 API는 박스 모드 가챠에만 적용됩니다. 일반 가챠는 경품이 무제한으로 배출되므로 박스 상태가 없습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| pageToken | string |  | |  |  ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int |  | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzBoxItems&gt;](#ezboxitems) | 박스 상태 리스트|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.BoxesAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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

특정 박스 가챠의 상태를 취득한다<br>

배출 확률 테이블 이름을 지정하여 특정 박스의 현재 상태를 취득합니다.<br>
응답에는 박스 안의 각 경품, 배출 완료 수, 남은 수가 포함됩니다.<br>

박스 가챠 상세 화면을 표시할 때 사용합니다. 예를 들어 남은 수와 함께 모든 경품을 목록으로 표시할 수 있습니다:<br>
"SSR 전설의 검: 0/1 배출 완료, SR 마법 지팡이: 2/5 배출 완료, R 물약: 10/30 배출 완료, ..."<br>

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

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| prizeTableName | string |  | ✓|  |  ~ 128자 | 배출 확률 테이블 이름 |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzBoxItems](#ezboxitems) | 박스 내 경품과 잔여 수량 정보|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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;
    }

```

**Godot**
```gdscript

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

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BoxItems(
        prizeTableName: "prizeTable-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    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);

```

**Godot**
```gdscript

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)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### resetBox

박스 가챠를 초기 상태로 리셋한다<br>

박스를 리셋하여 모든 경품을 원래 수량으로 되돌립니다. 플레이어가 아직 한 번도 뽑지 않은 상태로 돌아갑니다.<br>
리셋 후 모든 경품이 다시 배출 가능해집니다.<br>

박스 가챠 UI에서 "박스 리셋" 버튼을 구현할 때 사용합니다. 플레이어가 원하는 경품을 뽑은 후 박스를 리셋하여 새 박스에서 다시 도전하는 것과 같은 사용 방법이 가능합니다.<br>
예를 들어 SSR 아이템을 뽑은 후 박스를 리셋하여 새 박스에서 다시 SSR을 노리는 흐름입니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| prizeTableName | string |  | ✓|  |  ~ 128자 | 배출 확률 테이블 이름 |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzBoxItems](#ezboxitems) | 박스 내 경품과 초기 수량 정보|

#### 구현 예제




**Unity (UniTask)**
```csharp
    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();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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();

```

**Godot**
```gdscript

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

가챠의 현재 배출 확률을 취득한다<br>

지정된 가챠의 모든 경품과 그 현재 배출 확률 목록을 취득합니다.<br>
많은 게임에서 플레이어에게 표시하는 "배출 확률" 또는 "가챠 상세" 화면을 만들 때 사용합니다.<br>

반환되는 확률은 가챠 모드에 따라 다릅니다:<br>
- 일반 가챠: 모든 플레이어에게 항상 동일한 확률이 반환됩니다(예: SSR: 3%, SR: 15%, R: 82%).<br>
- 박스 가챠: 플레이어의 박스의 현재 상태를 반영한 확률이 반환됩니다. 경품이 배출되어 상자에서 제거되면 남은 경품들의 확률이 그에 따라 변합니다. 예를 들어 유일한 SSR이 이미 배출되었다면 SSR의 확률은 0%가 됩니다.<br>

이 API는 가챠의 배출 확률 표시 의무 대응에도 이용할 수 있습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| lotteryName | string |  | ✓|  |  ~ 128자 | 추첨 모델 이름<br>추첨 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzProbability&gt;](#ezprobability) | 배출 확률 목록|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Lottery(
        lotteryName: "lottery-0001"
    );
    var items = await domain.ProbabilitiesAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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());
    }

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Lottery(
        lotteryName: "lottery-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeProbabilities(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeProbabilities(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Lottery(
        lotteryName: "lottery-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeProbabilities(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeProbabilities(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Lottery(
        "lottery-0001" // lotteryName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeProbabilities(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeProbabilities(CallbackId);

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### getLotteryModel

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

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

예를 들어 플레이어가 "뽑기" 버튼을 탭하기 전에, 해당 가챠가 일반 가챠인지 박스 가챠인지를 표시하거나, ListProbabilities와 조합하여 현재 배출 확률을 표시할 수 있습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| lotteryName | string |  | ✓|  |  ~ 128자 | 추첨 모델 이름<br>추첨 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzLotteryModel](#ezlotterymodel) | 추첨 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    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;
    }

```

**Godot**
```gdscript

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

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    ).LotteryModel(
        lotteryName: "lotteryModel-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    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);

```

**Godot**
```gdscript

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)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### listLotteryModels

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

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

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

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

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzLotteryModel&gt;](#ezlotterymodel) | 추첨 모델 목록|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.LotteryModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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());
    }

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeLotteryModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeLotteryModels(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lottery.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeLotteryModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeLotteryModels(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Lottery->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeLotteryModels(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeLotteryModels(CallbackId);

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---