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

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

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



## 모델

### EzStatus

스테이터스<br>

스테이터스란 프로퍼티 ID마다 존재하는 엔티티로,<br>
현재 그레이드의 값을 보유합니다.<br>

프로퍼티 ID란 스테이터스 고유의 ID로, 개발자가 임의의 값을 설정할 수 있습니다.<br>
연동되는 GS2-Experience의 프로퍼티 ID와 완전히 일치하는 값을 사용할 것을 강력히 권장합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| gradeName | string |  | ✓ |  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| propertyId | string |  | ✓ |  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| gradeValue | long |  |  | 1 | 1 ~ 9223372036854775805 | 현재 그레이드<br>이 스테이터스의 현재 그레이드 값입니다. 연동되는 GS2-Experience 모델의 랭크 캡을 결정하기 위해 그레이드 모델의 그레이드 엔트리 배열의 인덱스로 사용됩니다. 이 값이 변경되면 관련된 경험치 스테이터스의 랭크 캡이 해당 그레이드 엔트리에서 정의된 값으로 자동 갱신됩니다. |

**관련 메서드:**
applyRankCap - 현재 한계돌파 그레이드에 맞춰 최대 레벨을 동기화하기
getStatus - 특정 아이템이나 캐릭터의 한계돌파·각성 상태 가져오기
listStatuses - 플레이어의 한계돌파·각성 상태 목록 가져오기


---

### EzGradeModel

그레이드 모델<br>

그레이드 모델이란 캐릭터나 장비의 랭크를 나타내는 엔티티로, 그레이드에 따라 GS2-Experience의 랭크 캡을 설정할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 그레이드 모델 이름<br>그레이드 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| experienceModelId | string |  | ✓ |  |  ~ 1024자 | GS2-Experience 경험치 모델 GRN<br>이 그레이드 모델과 연동시킬 GS2-Experience의 경험치 모델의 GRN입니다. 그레이드 값이 변경되면, 그레이드 엔트리의 매핑에 기반하여 연동된 경험치 모델의 랭크 캡이 자동으로 업데이트됩니다. 이를 통해 높은 그레이드가 더 높은 랭크 캡을 해제하는 그레이드 기반 성장을 구현할 수 있습니다. |
| gradeEntries | [List&lt;EzGradeEntryModel&gt;](#ezgradeentrymodel) |  | ✓ |  | 1 ~ 100 items | 그레이드 엔트리 모델 리스트<br>각 그레이드 값을 연동된 GS2-Experience 모델의 랭크 캡에 매핑하는 그레이드 엔트리의 순서가 있는 리스트입니다. 배열의 인덱스가 그레이드 값에 대응하므로, 첫 번째 항목(인덱스 0)이 그레이드 0의 랭크 캡을, 두 번째 항목이 그레이드 1의 랭크 캡을 정의합니다. |
| acquireActionRates | [List&lt;EzAcquireActionRate&gt;](#ezacquireactionrate) |  |  |  | 0 ~ 100 items | 보상 가산 테이블 리스트<br>그레이드를 기반으로 보상량을 스케일링하기 위한 이름이 지정된 배율 테이블의 컬렉션입니다. 여러 테이블을 정의하여 서로 다른 종류의 보상(예: 경험치, 통화, 아이템)에 다른 스케일링 규칙을 적용할 수 있습니다. |

**관련 메서드:**
getGradeModel - 이름을 지정하여 한계돌파·각성 모델 가져오기
listGradeModels - 한계돌파·각성 모델 목록 가져오기


---

### EzGradeEntryModel

그레이드 엔트리 모델<br>

그레이드 값과 연동되는 GS2-Experience 모델의 랭크 캡 매핑을 정의합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| rankCapValue | long |  | ✓ |  | 0 ~ 9223372036854775805 | 랭크 캡 값<br>이 그레이드가 적용되었을 때 연동된 GS2-Experience 모델에 설정할 랭크 캡 값입니다. 플레이어의 그레이드가 이 항목에 대응하는 값으로 변경되면, 관련된 경험치 스테이터스의 랭크 캡이 이 값으로 자동 업데이트되어 도달 가능한 최대 랭크가 제어됩니다. |


**관련 모델:**
EzGradeModel - 그레이드 모델



---

### EzAcquireAction

입수 액션

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


---

### EzAcquireActionRate

보상 가산 테이블<br>

현재 그레이드 값을 기준으로 보상량을 조정하는 이름이 지정된 배율 테이블을 정의합니다. 각 그레이드 값은 트랜잭션의 입수 액션에 적용되는 배율에 매핑되며, 그레이드가 높은 캐릭터나 장비일수록 더 많은 보상을 받을 수 있습니다. 표준적인 배정밀도 부동소수점수 모드와, 매우 큰 값에 대응하는 빅 넘버 모드를 모두 지원합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 보상 가산 테이블 이름<br>그레이드 모델 내에서 이 배율 테이블을 고유하게 식별하는 이름입니다. 트랜잭션의 특정 입수 액션에 그레이드 기반 보상 스케일링을 적용할 때 참조됩니다. |
| mode | 문자열 열거형<br>enum {<br>"double",<br>"big"<br>}<br> |  |  | "double" |  | 보상 가산 테이블 종류<br>배율 값의 수치 정밀도 모드를 선택합니다. "double" 모드는 대부분의 경우에 적합한 표준 부동소수점수를 사용합니다. "big" 모드는 최대 1024자리까지의 문자열 표현 숫자를 사용하여, 매우 큰 값 계산이 필요한 게임에 대응합니다.double: 2^48 미만의 부동소수점 수 / big: 문자열 표기로 1024자리 미만의 부동소수점 수 /  |
| rates | List&lt;double&gt; | {mode} == "double" | ✓※ |  | 1 ~ 1000 items | 그레이드별 배율 리스트 (double 모드)<br>그레이드 값으로 인덱싱된 보상 배율의 배열로, 배정밀도 부동소수점수를 사용합니다. 인덱스 0의 항목이 그레이드 0의 배율, 인덱스 1이 그레이드 1의 배율이 됩니다. mode가 "double"로 설정된 경우에 사용됩니다.<br><br>※ mode이(가) "double" 이면 필수 |
| bigRates | List&lt;string&gt; | {mode} == "big" | ✓※ |  | 1 ~ 1000 items | 그레이드별 배율 리스트 (big 모드)<br>그레이드 값으로 인덱싱된 보상 배율의 배열로, 확장된 정밀도를 위해 문자열 표현 숫자를 사용합니다. 인덱스 0의 항목이 그레이드 0의 배율, 인덱스 1이 그레이드 1의 배율이 됩니다. 매우 큰 수치 계산이 필요한 게임을 위해 mode가 "big"으로 설정된 경우에 사용됩니다.<br><br>※ mode이(가) "big" 이면 필수 |


**관련 모델:**
EzGradeModel - 그레이드 모델



---

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


---

## 메서드

### getGradeModel

이름을 지정하여 한계돌파·각성 모델 가져오기<br>

이름을 지정하여 그레이드 모델을 1건 가져옵니다.<br>
가져올 수 있는 정보에는 그레이드 엔트리(각 그레이드에서 최대 레벨이 어떻게 변하는지의 정의), 기본 초기 그레이드, 보상 배율 레이트가 포함됩니다.<br>
특정 한계돌파 시스템의 상세 정보를 표시할 때 사용합니다. 예를 들어 「철의 검: 그레이드 2 → 최대 Lv 70, 그레이드 3 → 최대 Lv 80」이나 「현재 보상 보너스: x1.5」와 같은 표시에 유용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzGradeModel](#ezgrademodel) | 그레이드 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).GradeModel(
        gradeName: "grade-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).GradeModel(
        gradeName: "grade-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

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

```

**Godot**
```gdscript

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

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

```

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

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

```

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

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

```

**Godot**
```gdscript

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

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

---

### listGradeModels

한계돌파·각성 모델 목록 가져오기<br>

이 네임스페이스에 등록된 모든 그레이드 모델을 가져옵니다.<br>
그레이드 모델은 「한계돌파」나 「각성」의 구조를 정의합니다. 플레이어가 그레이드를 올림으로써 아이템이나 캐릭터의 최대 레벨(랭크 캡)이 얼마나 올라가는지를 제어합니다.<br>
예를 들어, 그레이드 0의 무기는 최대 레벨이 50이지만, 한계돌파하여 그레이드 1이 되면 최대 레벨이 60으로, 그레이드 2에서 70으로… 이렇게 올라갑니다.<br>
보상 배율 레이트도 정의할 수 있어, 그레이드 레벨에 따라 보상량을 늘릴 수 있습니다(예: 그레이드 3의 캐릭터는 골드 획득량 1.5배).<br>
한계돌파·각성 UI를 구축하는 데 사용합니다. 예를 들어 「그레이드 2/5 — 최대 Lv: 70 — 다음: 동일 캐릭터 3체 필요」와 같은 표시에 유용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzGradeModel&gt;](#ezgrademodel) | 그레이드 모델 목록|

#### 구현 예제




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

```

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

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### applyRankCap

현재 한계돌파 그레이드에 맞춰 최대 레벨을 동기화하기<br>

GS2-Experience의 최대 레벨(랭크 캡)을 현재 그레이드(한계돌파 레벨)에 맞춰 업데이트합니다.<br>
예를 들어, 캐릭터가 그레이드 2(최대 Lv 70)에서 그레이드 3(최대 Lv 80)으로 한계돌파된 경우, 이를 호출하면 Experience 시스템에 새로운 최대 레벨이 80이라는 것이 반영됩니다.<br>
그레이드가 외부에서 변경되어 Experience의 최대 레벨과 동기화할 필요가 있을 때 유용합니다.<br>
일반적으로 그레이드 변경 시 최대 레벨은 자동으로 업데이트되지만, 데이터가 어긋난 경우 수동으로 호출할 수도 있습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStatus](#ezstatus) | 상태|
| experienceNamespaceName | string | GS2-Experience 네임스페이스 이름|
| experienceStatus | [EzStatus](../../experience/game_engine/#ezstatus) | 랭크 캡 갱신 후의 GS2-Experience 상태|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var result = await domain.ApplyRankCapAsync(
    );
    var item = await result.ModelAsync();
    var experienceNamespaceName = result.ExperienceNamespaceName;

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var future = domain.ApplyRankCapFuture(
    );
    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;
    var experienceNamespaceName = future.Result.ExperienceNamespaceName;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "grade-0001", // gradeName
        "property-0001" // propertyId
    );
    const auto Future = Domain->ApplyRankCap(
    );
    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();
    const auto ExperienceNamespaceName = Result->ExperienceNamespaceName;

```

**Godot**
```gdscript

var domain = ez.grade.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "grade-0001",
        "property-0001"
    )

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

var result = async_result.result

```


---

### getStatus

특정 아이템이나 캐릭터의 한계돌파·각성 상태 가져오기<br>

플레이어가 보유한 특정 프로퍼티의 현재 그레이드(한계돌파 레벨)를 가져옵니다.<br>
프로퍼티는 그레이드 모델 이름(어떤 한계돌파 시스템을 사용할지)과 프로퍼티 ID(어떤 아이템이나 캐릭터인지)로 식별합니다.<br>
한계돌파 상세 화면을 표시할 때 사용합니다. 예를 들어 "철의 검 — 그레이드: ★3 — 최대 Lv: 80 — 다음 한계돌파에는 2개 더 필요"와 같은 표시에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |

#### Result

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

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

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

```

**Godot**
```gdscript

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

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

```

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

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

```

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

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

```

**Godot**
```gdscript

var domain = ez.grade.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "grade-0001",
        "property-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>
각 상태에는 현재 그레이드 값과 그것이 어느 프로퍼티(아이템이나 캐릭터)에 속하는지가 포함됩니다.<br>
한계돌파를 완료한 아이템의 목록을 표시하는 데 사용합니다. 예를 들어 "철의 검 ★3, 불의 지팡이 ★1, 용의 갑옷 ★5"와 같은 표시에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gradeName | string |  | |  |  ~ 128자 | 그레이드 모델명 |
| 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.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.StatusesAsync(
        gradeName: "grade-0001"
    ).ToListAsync();

```

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

```


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




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

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

```

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

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

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Grade->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의 실행에 의해 변화한 것만이 대상이 됩니다.

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

---