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

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

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



## 모델

### EzStatus

스테이터스<br>

처음으로 GetIdleStatus 를 호출했을 때 생성되며, 그 시점부터 방치 시간의 카운트가 시작됩니다.<br>
방치 시간의 카운트는 보상을 받으면 리셋됩니다.<br>

GS2-Schedule 의 이벤트가 연관되어 있는 경우, 이벤트 개최 전에는 Category 에 액세스할 수 없으며, 스테이터스를 생성할 수도 없습니다.<br>
이벤트가 연관되어 있는 경우, 스테이터스는 이벤트의 반복 횟수를 보유합니다.<br>
현재 이벤트ID와 스테이터스 생성 시의 이벤트ID가 일치하지 않는 경우, 현재 이벤트의 반복 횟수와 스테이터스가 보유한 반복 횟수가 일치하지 않는 경우, 또는 이벤트의 시작 시각보다 앞서 스테이터스가 생성된 경우, 대기 시간은 리셋됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| categoryName | string |  | ✓ |  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| randomSeed | long |  |  | 0 | 0 ~ 9223372036854775805 | 난수 시드<br>방치 보상 계산 시 결정론적 난수 생성에 사용되는 시드 값입니다. 보상 계산이 재현 가능하고 일관성이 있음을 보장하여 서버가 보상 결과를 검증할 수 있도록 합니다. 보상을 받을 때마다 갱신됩니다. |
| idleMinutes | int |  | ✓ |  | 0 ~ 2147483646 | 방치 시간(분)<br>마지막 보상 수취 또는 스테이터스 생성 이후의 누적 방치 시간(분)입니다. 이 값은 idleStartedAt 으로부터의 경과 시간으로 계산되며, maximumIdleMinutes 로 상한이 설정됩니다. 이용 가능한 보상 수는 이 값을 카테고리 모델의 rewardIntervalMinutes 로 나누어 결정됩니다. |
| maximumIdleMinutes | int |  |  | 0 | 0 ~ 2147483646 | 최대 방치 시간(분)<br>이 스테이터스가 축적할 수 있는 최대 방치 시간(분)입니다. 스테이터스 생성 시 카테고리 모델의 defaultMaximumIdleMinutes 로 초기화됩니다. 입수 액션을 통해 사용자별로 늘릴 수 있으며, 프리미엄 사용자나 이벤트 참가자가 더 많은 방치 보상을 축적할 수 있도록 합니다. |

**관련 메서드:**
getStatus - 특정 카테고리의 방치 보상 상태 조회
listStatuses - 플레이어의 방치 보상 상태 목록 조회
prediction - 지금 수령할 수 있는 방치 보상을 미리보기
receive - 누적된 방치 보상을 수령


---

### EzCategoryModel

카테고리 모델<br>

카테고리 모델이란, 방치 보상을 얻을 수 있는 대기 카테고리를 설정하는 엔티티입니다.<br>
설정에는 대기 시간별 보상이나 최대 대기 시간 등의 정보가 포함됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 카테고리 모델 이름<br>카테고리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| rewardIntervalMinutes | int |  | ✓ |  | 0 ~ 2147483646 | 보상 간격(분)<br>각 방치 보상 사이의 시간 간격(분)입니다. 예를 들어 60으로 설정하면, 사용자는 방치 시간 60분마다 보상 1유닛을 획득합니다. 보상의 총 개수는 (경과 방치 분수) / rewardIntervalMinutes로 계산되며, acquireActions 배열을 순환합니다. |
| defaultMaximumIdleMinutes | int |  | ✓ |  | 0 ~ 2147483646 | 기본 최대 방치 시간(분)<br>이 카테고리의 새로운 스테이터스에 대한 기본 최대 방치 시간(분)입니다. 이 제한을 초과하는 방치 시간은 추가 보상을 축적하지 않습니다. 이 값은 스테이터스 생성 시 각 스테이터스의 maximumIdleMinutes 에 복사되며, 입수 액션을 통해 사용자별로 확장할 수 있습니다. |
| acquireActions | [List&lt;EzAcquireActionList&gt;](#ezacquireactionlist) |  |  | [] | 1 ~ 100 items | 대기 시간마다 얻을 수 있는 입수 액션 리스트<br>대기 시간을 "X분"이라고 가정하면<br>"X / rewardIntervalMinutes"가 보상을 받을 수 있는 횟수가 되지만, 여기서 지정한 배열의 요소를 반복함으로써 대기 시간마다 다른 보상을 부여할 수 있습니다. |
| idlePeriodScheduleId | string |  |  |  |  ~ 1024자 | 방치 기간 스케줄ID<br>방치 시간이 축적되는 기간을 정의하는 GS2-Schedule 이벤트의 GRN입니다. 설정하면 이벤트가 활성 상태인 동안에만 방치 시간이 카운트됩니다. 이벤트가 반복되는 경우, 스테이터스는 반복 횟수를 추적하고 새로운 사이클이 시작될 때 방치 시간을 리셋하여 이벤트 기간마다 보상이 계산되도록 합니다. |
| receivePeriodScheduleId | string |  |  |  |  ~ 1024자 | 수취 기간 스케줄ID<br>사용자가 축적된 방치 보상을 받을 수 있는 시간대를 정의하는 GS2-Schedule 이벤트의 GRN입니다. 설정하면 이벤트가 활성 상태인 동안에만 보상 수취가 허용됩니다. 이를 통해 방치 축적 기간과는 별도의 기간 한정 보상 수취 기간을 설정할 수 있습니다. |

**관련 메서드:**
getCategoryModel - 이름을 지정하여 방치 보상 카테고리 정의 조회
listCategoryModels - 방치 보상 카테고리 정의 목록 조회


---

### EzConfig

컨피그 설정<br>

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

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


---

### EzAcquireAction

입수 액션<br>

방치 보상으로 사용되는 단일 입수 액션을 나타냅니다. 액션 타입(예: 아이템 추가, 통화 증가)과 그 요청 파라미터로 구성됩니다. 방치 보상을 수령하면 이러한 액션들이 트랜잭션으로 조합되어 실행되며, 사용자에게 보상이 지급됩니다.

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

**관련 메서드:**
prediction - 지금 수령할 수 있는 방치 보상을 미리보기
receive - 누적된 방치 보상을 수령


**관련 모델:**
EzAcquireActionList - 입수 액션 리스트



---

### EzAcquireActionList

입수 액션 리스트<br>

하나의 보상 간격에서 함께 지급되는 여러 입수 액션을 그룹화하는 래퍼입니다. 각 AcquireActionList는 카테고리 모델의 acquireActions 배열 내 하나의 보상 주기에 대응하며, 각 간격마다 서로 다른 보상 조합을 설정할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| acquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  | [] | 0 ~ 100 items | 입수 액션 리스트<br>이 보상 간격이 트리거될 때 함께 실행되는 입수 액션의 집합입니다. 여러 액션을 조합하여 하나의 방치 보상 주기에서 서로 다른 종류의 보상을 동시에 지급할 수 있습니다. 리스트당 최대 100개의 액션입니다. |


**관련 모델:**
EzCategoryModel - 카테고리 모델



---

### 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 | 획득 액션 실행 결과 리스트 |

**관련 메서드:**
receive - 누적된 방치 보상을 수령


---

## 메서드

### getCategoryModel

이름을 지정하여 방치 보상 카테고리 정의 조회<br>

이름을 지정하여 방치 보상 카테고리 모델을 1건 조회합니다.<br>
조회되는 정보에는 보상 간격(몇 분마다 보상이 누적되는지), 최대 방치 시간의 상한, 지급되는 보상 내용, 스케줄 설정이 포함됩니다.<br>
특정 방치 보상 유형의 상세 정보를 표시하는 데 사용합니다. 예를 들어 "금광 — 30분마다 골드 10개 — 최대 누적: 8시간 — 현재: 160골드 수령 가능"과 같은 표시에 유용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzCategoryModel](#ezcategorymodel) | 카테고리 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->CategoryModel(
        "category-0001" // categoryName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.idle.namespace_(
        "namespace-0001"
    ).category_model(
        "category-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.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

```

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

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

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->CategoryModel(
        "category-0001" // categoryName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Idle::Model::FCategoryModel> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

```

**Godot**
```gdscript

var domain = ez.idle.namespace_(
        "namespace-0001"
    ).category_model(
        "category-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의 실행에 의해 변화한 것만이 대상이 됩니다.

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

---

### listCategoryModels

방치 보상 카테고리 정의 목록 조회<br>

이 네임스페이스에 등록된 모든 방치 보상 카테고리를 조회합니다.<br>
카테고리 모델은 AFK(방치) 보상의 동작 방식을 정의합니다. 보상이 누적되는 간격(예: 10분마다), 최대 방치 시간(예: 최대 8시간), 플레이어가 받는 보상 내용, 수령 후 타이머를 리셋할지 여부 등입니다.<br>
또한 카테고리를 스케줄에 연결하여 방치 보상이 활성화되는 기간을 제어할 수도 있습니다(예: 평일 이벤트 중에만 유효).<br>
플레이어에게 어떤 종류의 방치 보상이 있는지 표시하는 데 사용합니다. 예를 들어 "금광(30분마다 골드 10개, 최대 8시간)", "수련장(1시간마다 XP 50, 최대 24시간)"과 같은 표시에 유용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzCategoryModel&gt;](#ezcategorymodel) | 카테고리 모델 리스트|

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.CategoryModels(
    );
    List<EzCategoryModel> items = new List<EzCategoryModel>();
    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->Idle->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->CategoryModels(
    );
    TArray<Gs2::UE5::Idle::Model::FEzCategoryModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### getStatus

특정 카테고리의 방치 보상 상태 조회<br>

특정 카테고리에서 플레이어의 방치 보상 상태를 조회합니다.<br>
상태에는 방치 타이머 시작 시각과 현재 최대 방치 시간이 포함됩니다. 상태가 아직 존재하지 않는 경우, 현재 시각을 시작 시각으로 하여 자동으로 생성됩니다.<br>
특정 방치 보상의 진행 상황을 표시하는 데 사용합니다. 예를 들어 "금광 — 방치 중 4시간 30분 / 최대 8시간 — 90골드 수령 가능"과 같은 표시에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| categoryName | string |  | ✓|  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStatus](#ezstatus) | 상태|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "category-0001" // categoryName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.idle.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "category-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.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

```

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

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

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "category-0001" // categoryName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Idle::Model::FStatus> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

```

**Godot**
```gdscript

var domain = ez.idle.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "category-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의 실행에 의해 변화한 것만이 대상이 됩니다.

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

---

### listStatuses

플레이어의 방치 보상 상태 목록 조회<br>

모든 카테고리에 걸친 플레이어의 방치 보상 상태를 모두 조회합니다.<br>
각 상태에는 플레이어가 언제부터 방치를 시작했는지(마지막으로 보상을 수령한 시각 또는 타이머 시작 시각)와 현재 최대 방치 시간이 포함됩니다.<br>
"방치 보상" 개요 화면을 구성하는 데 사용합니다. 예를 들어 "금광: 4시간 30분 누적, 수련장: 1시간 15분 누적"처럼 각 카테고리에 "수령" 버튼을 붙여 표시하는 화면에 유용합니다.

#### Request

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

#### Result

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

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Statuses(
    );
    List<EzStatus> items = new List<EzStatus>();
    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->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Statuses(
    );
    TArray<Gs2::UE5::Idle::Model::FEzStatusPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### prediction

지금 수령할 수 있는 방치 보상을 미리보기<br>

플레이어가 지금 수령할 경우 받게 될 보상을 계산하여 반환합니다. 실제로 수령하지는 않습니다.<br>
보상량은 플레이어가 방치한 시간을 보상 간격으로 나눈 값을 기준으로 하며, 최대 방치 시간으로 상한이 설정됩니다.<br>
타이머 리셋이나 보상 지급은 이루어지지 않습니다. 읽기 전용 미리보기입니다.<br>
플레이어가 "수령" 버튼을 누르기 전에 무엇을 받게 될지 표시하는 데 사용합니다. 예를 들어 "수령 예정: 골드 90개, 젬 5개"와 같은 표시에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| categoryName | string |  | ✓|  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzAcquireAction&gt;](#ezacquireaction) | 보상|
| status | [EzStatus](#ezstatus) | 상태|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    var result = await domain.PredictionAsync(
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    var future = domain.PredictionFuture(
    );
    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->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "category-0001" // categoryName
    );
    const auto Future = Domain->Prediction(
    );
    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.idle.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "category-0001"
    )

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

var result = async_result.result

```


---

### receive

누적된 방치 보상을 수령<br>

지정한 카테고리에서 플레이어의 방치 시간을 기준으로 누적된 보상을 수령합니다.<br>
보상량은 플레이어가 방치한 시간을 보상 간격으로 나눈 값에서 계산되며, 최대 방치 시간으로 상한이 설정됩니다.<br>
수령 후, 방치 타이머는 리셋되고 0부터 다시 누적이 시작됩니다.<br>
방치 보상 화면의 "보상 수령" 또는 "회수" 버튼에 사용합니다. 예를 들어 플레이어가 "회수"를 탭하면 자리를 비운 동안 누적된 "골드 90개, 젬 5개"를 수령하는 동작입니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| categoryName | string |  | ✓|  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzAcquireAction&gt;](#ezacquireaction) | 보상|
| status | [EzStatus](#ezstatus) | 갱신한 스테이터스|
| transactionId | string | 발행된 트랜잭션 ID|
| stampSheet | string | 퀘스트 시작 처리 실행에 사용하는 스탬프 시트|
| stampSheetEncryptionKeyId | string | 스탬프 시트의 서명 계산에 사용한 암호화 키 GRN|
| autoRunStampSheet | bool | 트랜잭션 자동 실행이 활성화되어 있는지 여부|
| atomicCommit | bool | 트랜잭션을 원자적으로 커밋할지 여부|
| transaction | string | 발행된 트랜잭션|
| transactionResult | [EzTransactionResult](#eztransactionresult) | 트랜잭션 실행 결과|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    var result = await domain.ReceiveAsync(
    );
    // New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
    // 에러가 발생하면 TransactionException이 발생합니다.
    // TransactionException::Retry()로 재시도할 수 있습니다.

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    var future = domain.ReceiveFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
    // 에러가 발생하면 TransactionException이 발생합니다.
    // TransactionException::Retry()로 재시도할 수 있습니다.

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "category-0001" // categoryName
    );
    const auto Future = Domain->Receive(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.idle.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "category-0001"
    )

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

var result = async_result.result

```


---