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

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

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



## 모델

### EzBalanceParameterStatus

밸런스 파라미터 상태<br>

사용자가 소유한 특정 리소스에 대해 추첨된 파라미터의 실제 값을 나타냅니다. 각 상태는 밸런스 파라미터 모델과 연결되며, 추첨 처리 후 각 파라미터 슬롯에 할당된 구체적인 값을 보유합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| parameterName | string |  | ✓ |  |  ~ 128자 | 밸런스 파라미터 모델 이름<br>이 상태의 추첨 조건을 정의하는 밸런스 파라미터 모델의 이름입니다. 합계 값, 배분 방침, 사용 가능한 파라미터 슬롯을 지정하는 모델을 참조합니다. |
| propertyId | string |  | ✓ |  |  ~ 1024자 | 파라미터를 보유한 리소스의 프로퍼티 ID<br>이러한 밸런스 파라미터가 연결되어 있는 특정 게임 리소스(예: 무기 또는 장비 아이템)를 식별합니다. 일반적으로 GS2-Inventory의 아이템 등의 리소스를 프로퍼티 ID로 참조합니다. |
| parameterValues | [List&lt;EzBalanceParameterValue&gt;](#ezbalanceparametervalue) |  | ✓ |  | 1 ~ 10 items | 밸런스 파라미터 값 리스트<br>추첨 처리 후 각 파라미터 슬롯에 할당된 구체적인 값입니다. 각 엔트리는 모델에서 정의된 파라미터 슬롯에 대응하며, 할당된 실제 수치를 보유합니다. 모든 값의 합계는 모델에서 지정된 합계 값과 같아집니다. |

**관련 메서드:**
getBalanceParameterStatus - 특정 아이템의 밸런스 파라미터 값을 취득합니다
listBalanceParameterStatuses - 플레이어의 밸런스 파라미터 값 목록을 취득합니다


---

### EzRarityParameterStatus

레어리티 파라미터의 상태<br>

유저가 소유한 특정 리소스에 대해 추첨된 파라미터의 실제 값을 나타냅니다. 각 상태는 레어리티 파라미터 모델에 연결되며, 부여된 각 파라미터 슬롯에 대해 가중 추첨으로 선택된 구체적인 값을 보유합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| parameterName | string |  | ✓ |  |  ~ 128자 | 레어리티 파라미터 모델명<br>이 상태의 추첨 조건을 정의하는 레어리티 파라미터 모델의 이름입니다. 최대 파라미터 수, 부여 수 추첨 가중치, 값 추첨 풀을 지정하는 모델을 참조합니다. |
| propertyId | string |  | ✓ |  |  ~ 1024자 | 파라미터의 보유 리소스의 프로퍼티 ID<br>이 레어리티 파라미터가 연결되어 있는 특정 게임 리소스(예: 무기나 장비 아이템)를 식별합니다. 일반적으로 GS2-Inventory의 아이템 등의 리소스를 프로퍼티 ID로 참조합니다. |
| parameterValues | [List&lt;EzRarityParameterValue&gt;](#ezrarityparametervalue) |  |  |  | 0 ~ 10 items | 레어리티 파라미터의 값 목록<br>부여된 각 슬롯에 대해 가중 추첨으로 선택된 구체적인 파라미터 값입니다. 엔트리 수는 부여 수 추첨으로 결정되며, 각 엔트리의 값은 값 모델 풀에서 선택됩니다. 최대 파라미터 수보다 적은 엔트리 수가 될 수 있습니다. |

**관련 메서드:**
getRarityParameterStatus - 특정 아이템의 레어리티 파라미터 값을 취득합니다
listRarityParameterStatuses - 플레이어의 레어리티 파라미터 값 목록을 취득합니다
verifyRarityParameterStatus - 특정 아이템의 레어리티 파라미터를 검증합니다


---

### EzBalanceParameterModel

밸런스 파라미터 모델<br>

밸런스 파라미터의 추첨 조건을 정의합니다.<br>
밸런스 파라미터는 고정된 합계 값을 여러 파라미터 슬롯에 분배합니다. 예를 들어 합계 파워가 100인 무기에 대해 ATK=60, DEF=30, SPD=10과 같이 배분됩니다. 초기값 설정 방침에 따라 값의 할당 방법이 결정됩니다: `average`는 균등하게 분배하고, `lottery`는 합계 값을 무작위로 배분합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 밸런스 파라미터 모델 이름<br>밸런스 파라미터 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| totalValue | long |  | ✓ |  | 0 ~ 9223372036854775805 | 합계값<br>모든 파라미터 슬롯에 분배되는 고정된 합계값입니다. 파라미터가 추첨될 때, 사용되는 배분 방식과 관계없이 개별 값의 합계는 항상 이 합계값이 됩니다. |
| initialValueStrategy | 문자열 열거형<br>enum {<br>"average",<br>"lottery"<br>}<br> |  |  | "average" |  | 초기값 설정 방침<br>최초 할당 시 합계값을 파라미터 슬롯에 어떻게 분배할지를 결정합니다. `average`는 합계값을 모든 파라미터에 균등하게 분배하고, `lottery`는 합계값을 무작위로 분배하여 다양한 파라미터 조합을 만듭니다.average: 평균값 / lottery: 추첨 /  |
| parameters | [List&lt;EzBalanceParameterValueModel&gt;](#ezbalanceparametervaluemodel) |  | ✓ |  | 1 ~ 10 items | 밸런스 파라미터 값 모델 목록<br>이 밸런스 파라미터에서 사용 가능한 파라미터 슬롯을 정의합니다. 각 엔트리는 이름이 지정된 파라미터 슬롯(예: ATK, DEF, SPD)을 선택적 메타데이터와 함께 지정합니다. 합계값은 이 슬롯들에 분배됩니다. |

**관련 메서드:**
getBalanceParameterModel - 이름을 지정하여 밸런스 파라미터 정의를 조회
listBalanceParameterModels - 밸런스 파라미터 모델 목록을 조회


---

### EzBalanceParameterValueModel

밸런스 파라미터 값 모델<br>

밸런스 파라미터 내에서 사용 가능한 단일 파라미터 슬롯을 정의합니다. 각 엔트리는 추첨 처리 중 합계값의 일부를 받는 이름이 지정된 슬롯(예: ATK, DEF, SPD)을 지정합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 64자 | 이름<br>이 파라미터 슬롯의 식별자(예: ATK, DEF, SPD)입니다. 밸런스 파라미터 모델 내에서 고유해야 합니다. 추첨된 파라미터 값을 저장·취득할 때 키로 사용됩니다. |
| metadata | string |  |  |  |  ~ 512자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |


**관련 모델:**
EzBalanceParameterModel - 밸런스 파라미터 모델



---

### EzRarityParameterModel

레어리티 파라미터 모델<br>

레어리티 파라미터의 추첨 조건을 정의합니다. 레어리티 파라미터는 가중 추첨 시스템을 사용하여 부여되는 파라미터의 수와 할당되는 구체적인 값을 모두 결정합니다. 먼저, 부여 수 모델 목록에서 가중 추첨을 통해 채울 파라미터 슬롯 수가 결정됩니다. 그런 다음, 각 슬롯의 값이 파라미터 값 모델 목록에서 가중 추첨으로 선택되어, 제어된 확률 분포에 따른 무작위 장비 속성을 제공합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 레어리티 파라미터 모델명<br>레어리티 파라미터 모델 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| maximumParameterCount | int |  | ✓ |  | 1 ~ 10 | 부여할 파라미터의 최대 수<br>리소스에 부여할 수 있는 파라미터 슬롯 수의 상한입니다. 실제로 부여되는 수는 부여 수 모델 목록에서의 가중 추첨으로 결정되지만, 이 값을 초과하지 않습니다. |
| parameterCounts | [List&lt;EzRarityParameterCountModel&gt;](#ezrarityparametercountmodel) |  | ✓ |  | 1 ~ 10 items | 레어리티 파라미터의 부여 수 모델 목록<br>부여되는 파라미터 슬롯 수를 결정하기 위한 가중 추첨 엔트리를 정의합니다. 각 엔트리는 부여 수와 추첨 가중치를 지정합니다. 가중치가 클수록 해당 부여 수가 선택될 확률이 높아집니다. |
| parameters | [List&lt;EzRarityParameterValueModel&gt;](#ezrarityparametervaluemodel) |  | ✓ |  | 1 ~ 1000 items | 레어리티 파라미터 값 모델 목록<br>추첨 가능한 파라미터 값의 풀을 정의합니다. 각 엔트리는 파라미터 이름, 리소스 상세 정보, 추첨 가중치를 지정합니다. 파라미터 슬롯을 채울 때, 이 풀에서 중복 없이 가중 추첨으로 값이 선택됩니다. |

**관련 메서드:**
getRarityParameterModel - 이름을 지정하여 레어리티 파라미터 정의를 취득합니다
listRarityParameterModels - 레어리티 파라미터 모델 목록을 조회


---

### EzRarityParameterCountModel

레어리티 파라미터의 부여 수 모델<br>

리소스에 부여되는 파라미터 슬롯 수를 결정하기 위한 가중 추첨의 단일 엔트리를 정의합니다. 각 엔트리는 파라미터 수와 추첨 가중치를 짝지어, 파라미터 수량의 확률 분포를 세밀하게 제어할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| count | int |  | ✓ |  | 0 ~ 10 | 부여 수<br>이 엔트리가 추첨되었을 때 부여되는 파라미터 슬롯 수입니다. 예를 들어 부여 수가 3인 경우, 리소스는 값 모델 풀에서 선택된 3개의 파라미터 값을 받게 됩니다. |
| weight | int |  | ✓ |  | 1 ~ 2147483646 | 추첨 가중치<br>파라미터 부여 수를 결정하는 가중치 추첨에서 사용되는 상대적인 가중치입니다. 값이 클수록 이 부여 수가 선택될 확률이 높아집니다. 실제 확률은 이 가중치를 부여 수 모델 리스트 내 모든 가중치의 합으로 나눈 값입니다. |


**관련 모델:**
EzRarityParameterModel - 레어리티 파라미터 모델



---

### EzRarityParameterValueModel

레어리티 파라미터 값 모델<br>

레어리티 파라미터 값의 가중 추첨 풀 내 단일 엔트리를 정의합니다. 각 엔트리는 파라미터 이름, 게임에서 정의한 리소스 상세 정보, 그리고 풀 내 다른 엔트리에 대한 선택 확률을 결정하는 추첨 가중치를 지정합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 64자 | 이름<br>이 추첨 엔트리의 식별자입니다. 레어리티 파라미터 모델의 값 풀 내에서 고유해야 합니다. 추첨되었을 때, 이 이름이 결과 레어리티 파라미터 값에 저장됩니다. |
| metadata | string |  |  |  |  ~ 512자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| resourceName | string |  | ✓ |  |  ~ 64자 | 게임에서 사용하는 파라미터 리소스 종류를 나타내는 이름(GS2의 동작에는 사용되지 않음)<br>이 파라미터 값에 연결된 게임에서 정의한 리소스 종류 이름(예: "fire_attack", "ice_resist")입니다. GS2는 자체 동작에 이 값을 사용하지 않으며, 추첨 결과에 그대로 전달되어 게임 로직에서 사용됩니다. |
| resourceValue | long |  | ✓ |  | 0 ~ 9223372036854775805 | 게임에서 사용하는 파라미터 리소스 값(GS2의 동작에는 사용되지 않음)<br>이 파라미터의 게임에서 정의한 수치(예: 공격력+50인 경우 50)입니다. GS2는 자체 동작에 이 값을 사용하지 않으며, 추첨 결과에 그대로 전달되어 게임 로직에서 사용됩니다. |
| weight | int |  | ✓ |  | 1 ~ 2147483646 | 추첨 가중치<br>파라미터 값을 선택하는 가중 추첨에서 사용되는 상대적 가중치입니다. 값이 클수록 이 엔트리가 선택될 확률이 높아집니다. 실제 확률은 이 가중치를 풀 내 모든 가중치의 합으로 나눈 값이 됩니다. |


**관련 모델:**
EzRarityParameterModel - 레어리티 파라미터 모델



---

### EzBalanceParameterValue

밸런스 파라미터 값<br>

밸런스 파라미터 상태 내의 단일 파라미터 슬롯에 할당된 실제 값을 나타냅니다. 추첨 처리 후의 슬롯 이름과 그 구체적인 수치를 보유합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 64자 | 이름<br>파라미터 슬롯의 이름(예: ATK, DEF, SPD)입니다. 밸런스 파라미터 값 모델에서 정의된 파라미터 슬롯에 대응합니다. |
| value | long |  | ✓ |  | 0 ~ 9223372036854775805 | 값<br>이 파라미터 슬롯에 할당된 수치입니다. 밸런스 파라미터가 처음 추첨될 때, 초기값 설정 방침(평균값 또는 추첨)에 따라 결정됩니다. 모든 슬롯 값의 합계는 모델에서 정의된 합계 값과 같아집니다. |


**관련 모델:**
EzBalanceParameterStatus - 밸런스 파라미터 상태



---

### EzRarityParameterValue

레어리티 파라미터 값<br>

레어리티 파라미터 상태 내의 단일 파라미터 슬롯에 할당된 실제 값을 나타냅니다. 슬롯 이름과, 값 모델 풀에서 가중 추첨으로 선택된 리소스 상세 정보(이름과 값)를 보유합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 64자 | 이름<br>값 모델 풀에서 선택된 파라미터 값의 이름입니다. 추첨된 레어리티 파라미터 값 모델 엔트리에서 정의된 이름에 대응합니다. |
| resourceName | string |  | ✓ |  |  ~ 64자 | 리소스의 이름<br>이 파라미터 값에 연결된 게임에서 정의한 리소스 종류 이름(예: "fire_attack", "ice_resist")입니다. 게임 로직에서 사용하기 위해 추첨된 레어리티 파라미터 값 모델 엔트리에서 복사됩니다. |
| resourceValue | long |  | ✓ |  | 0 ~ 9223372036854775805 | 리소스의 값<br>이 파라미터에 연결된 리소스의 수치입니다. 추첨된 레어리티 파라미터 값 모델 엔트리에서 복사됩니다. 게임 로직에서 파라미터의 효과(예: 공격력+50)를 적용하는 데 사용됩니다. |


**관련 모델:**
EzRarityParameterStatus - 레어리티 파라미터의 상태



---

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


---

## 메서드

### getBalanceParameterModel

이름을 지정하여 밸런스 파라미터 정의를 조회<br>

이름을 지정하여, 밸런스 파라미터 모델을 1건 조회합니다.<br>
조회할 수 있는 정보에는 분배할 합계값, 파라미터 슬롯의 목록(예: ATK, DEF, SPD), 초기값의 결정 방법이 포함됩니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzBalanceParameterModel](#ezbalanceparametermodel) | 밸런스 파라미터 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).BalanceParameterModel(
        parameterName: "rarity-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).BalanceParameterModel(
        parameterName: "rarity-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

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

```

**Godot**
```gdscript

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

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

```

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

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

```

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

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

```

**Godot**
```gdscript

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

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

---

### listBalanceParameterModels

밸런스 파라미터 모델 목록을 조회<br>

이 네임스페이스에 등록된 모든 밸런스 파라미터 모델을 조회합니다.<br>
밸런스 파라미터는 고정된 합계값을 여러 스탯에 분배합니다. 예를 들어 ATK·DEF·SPD 에 합계 100포인트를 나누어, 합계가 항상 100이 되도록 합니다.<br>
사용 가능한 파라미터 타입을 표시하거나, 무기·장비 상세 화면에서 파라미터 모델의 설정을 확인할 때 사용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzBalanceParameterModel&gt;](#ezbalanceparametermodel) | 밸런스 파라미터 모델 목록|

#### 구현 예제




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

```

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

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### getBalanceParameterStatus

특정 아이템의 밸런스 파라미터 값을 취득합니다<br>

플레이어가 소지한 특정 아이템(프로퍼티)에 할당된 현재 밸런스 파라미터 값을 취득합니다.<br>
값은 아이템 생성 시(또는 마지막 재추첨 시)에 무작위로 결정되며, 모든 값의 합계는 항상 모델의 합계값과 같습니다.<br>
아이템 상세 화면에서 개별 스탯 내역(예: ATK: 40, DEF: 35, SPD: 25)을 표시할 때 사용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| parameterName | string |  | ✓|  |  ~ 128자 | 밸런스 파라미터 모델 이름<br>이 상태의 추첨 조건을 정의하는 밸런스 파라미터 모델의 이름입니다. 합계 값, 배분 방침, 사용 가능한 파라미터 슬롯을 지정하는 모델을 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024자 | 파라미터를 보유한 리소스의 프로퍼티 ID<br>이러한 밸런스 파라미터가 연결되어 있는 특정 게임 리소스(예: 무기 또는 장비 아이템)를 식별합니다. 일반적으로 GS2-Inventory의 아이템 등의 리소스를 프로퍼티 ID로 참조합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzBalanceParameterStatus](#ezbalanceparameterstatus) | 밸런스 파라미터 상태|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BalanceParameterStatus(
        parameterName: "balance-0001",
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();

```

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

```

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

```

**Godot**
```gdscript

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

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

```

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

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

```

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

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

```

**Godot**
```gdscript

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

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

---

### listBalanceParameterStatuses

플레이어의 밸런스 파라미터 값 목록을 취득합니다<br>

플레이어의 아이템에 할당된 현재 밸런스 파라미터 값을 취득합니다.<br>
파라미터 이름으로 필터링하여 특정 파라미터 타입의 값만 취득할 수도 있습니다.<br>
예를 들어, 플레이어가 소지한 각 무기의 ATK/DEF/SPD 배분을 확인할 수 있습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| parameterName | string |  | |  |  ~ 128자 | 밸런스 파라미터 모델 이름<br>이 상태의 추첨 조건을 정의하는 밸런스 파라미터 모델의 이름입니다. 합계 값, 배분 방침, 사용 가능한 파라미터 슬롯을 지정하는 모델을 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| pageToken | string |  | |  |  ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int |  | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzBalanceParameterStatus&gt;](#ezbalanceparameterstatus) | 밸런스 파라미터 상태 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|

#### 구현 예제




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

```

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

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### getRarityParameterModel

이름을 지정하여 레어리티 파라미터 정의를 취득합니다<br>

이름을 지정하여 레어리티 파라미터 모델을 1건 취득합니다.<br>
취득할 수 있는 정보에는 파라미터 슬롯의 최대 수, 슬롯 수의 결정 방법, 레어리티의 가중치(추첨 확률)가 부여된 후보값 목록이 포함됩니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzRarityParameterModel](#ezrarityparametermodel) | 레어리티 파라미터 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).RarityParameterModel(
        parameterName: "rarity-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).RarityParameterModel(
        parameterName: "rarity-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

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

```

**Godot**
```gdscript

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

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

```

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

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

```

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

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

```

**Godot**
```gdscript

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

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

---

### listRarityParameterModels

레어리티 파라미터 모델 목록을 조회<br>

이 네임스페이스에 등록된 모든 레어리티 파라미터 모델을 조회합니다.<br>
레어리티 파라미터는 레어리티 가중 확률에 기반하여 파라미터 슬롯에 무작위로 값을 할당합니다. 예를 들어 무기에 커먼·레어·레전더리 스킬 슬롯이 붙는 방식입니다.<br>
사용 가능한 파라미터 타입을 표시하거나, 장비 화면에서 레어리티 설정을 확인할 때 사용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzRarityParameterModel&gt;](#ezrarityparametermodel) | 레어리티 파라미터 모델의 리스트|

#### 구현 예제




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

```

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

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### getRarityParameterStatus

특정 아이템의 레어리티 파라미터 값을 취득합니다<br>

플레이어가 소지한 특정 아이템(프로퍼티)에 할당된 현재 레어리티 파라미터 값을 취득합니다.<br>
값은 아이템 생성 시(또는 마지막 재추첨 시)에 모델에서 정의된 레어리티 가중치를 기반으로 무작위로 추첨된 것입니다.<br>
무기나 장비의 상세 화면에서 부여된 스킬이나 어빌리티를 표시할 때 사용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| parameterName | string |  | ✓|  |  ~ 128자 | 레어리티 파라미터 모델명<br>이 상태의 추첨 조건을 정의하는 레어리티 파라미터 모델의 이름입니다. 최대 파라미터 수, 부여 수 추첨 가중치, 값 추첨 풀을 지정하는 모델을 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024자 | 파라미터의 보유 리소스의 프로퍼티 ID<br>이 레어리티 파라미터가 연결되어 있는 특정 게임 리소스(예: 무기나 장비 아이템)를 식별합니다. 일반적으로 GS2-Inventory의 아이템 등의 리소스를 프로퍼티 ID로 참조합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzRarityParameterStatus](#ezrarityparameterstatus) | 레어리티 파라미터 상태|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RarityParameterStatus(
        parameterName: "rarity-0001",
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();

```

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

```

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

```

**Godot**
```gdscript

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

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

```

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

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

```

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

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

```

**Godot**
```gdscript

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

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

---

### listRarityParameterStatuses

플레이어의 레어리티 파라미터 값 목록을 취득합니다<br>

플레이어의 아이템에 할당된 현재 레어리티 파라미터 값을 취득합니다.<br>
파라미터 이름으로 필터링하여 특정 파라미터 타입의 값만 취득할 수도 있습니다.<br>
예를 들어, 플레이어의 각 무기에 어떤 스킬 슬롯(커먼·레어·레전더리)이 붙어 있는지 확인할 수 있습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| parameterName | string |  | |  |  ~ 128자 | 레어리티 파라미터 모델명<br>이 상태의 추첨 조건을 정의하는 레어리티 파라미터 모델의 이름입니다. 최대 파라미터 수, 부여 수 추첨 가중치, 값 추첨 풀을 지정하는 모델을 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| pageToken | string |  | |  |  ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int |  | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzRarityParameterStatus&gt;](#ezrarityparameterstatus) | 레어리티 파라미터 모델의 리스트|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|

#### 구현 예제




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

```

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

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### verifyRarityParameterStatus

특정 아이템의 레어리티 파라미터를 검증합니다<br>

특정 아이템의 레어리티 파라미터가 지정한 조건을 충족하는지 확인합니다.<br>
3가지 체크 타입을 사용할 수 있습니다:<br>
- `have`: 아이템이 특정 파라미터 값을 가지고 있음(예: "화염 참격" 스킬을 보유)<br>
- `havent`: 아이템이 특정 파라미터 값을 가지고 있지 않음<br>
- `count`: 아이템의 파라미터 슬롯이 지정한 수만큼 채워져 있음<br>

전제 조건으로 사용합니다. 예를 들어, 강화하기 전에 무기가 특정 스킬을 가지고 있을 것을 요구하는 경우 등에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| parameterName | string |  | ✓|  |  ~ 128자 | 레어리티 파라미터 모델명<br>이 상태의 추첨 조건을 정의하는 레어리티 파라미터 모델의 이름입니다. 최대 파라미터 수, 부여 수 추첨 가중치, 값 추첨 풀을 지정하는 모델을 참조합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024자 | 파라미터의 보유 리소스의 프로퍼티 ID<br>이 레어리티 파라미터가 연결되어 있는 특정 게임 리소스(예: 무기나 장비 아이템)를 식별합니다. 일반적으로 GS2-Inventory의 아이템 등의 리소스를 프로퍼티 ID로 참조합니다. |
| verifyType | 문자열 열거형<br>enum {<br>"havent",<br>"have",<br>"count"<br>}<br> |  | ✓|  |  | 검증 종류havent: 지정한 파라미터를 보유하고 있지 않을 것 / have: 지정한 파라미터를 보유하고 있을 것 / count: 보유하고 있는 파라미터의 수가 지정한 수와 같을 것 /  |
| parameterValueName | string | {verifyType} in ["havent", "have"] | ✓※|  |  ~ 64자 | 이름<br>이 추첨 엔트리의 식별자입니다. 레어리티 파라미터 모델의 값 풀 내에서 고유해야 합니다. 추첨되었을 때, 이 이름이 결과 레어리티 파라미터 값에 저장됩니다.<br>※ verifyType이(가) "havent","have"이면 필수 |
| parameterCount | int | {verifyType} == "count" | ✓※|  | 0 ~ 10 | 검증할 파라미터의 수 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzRarityParameterStatus](#ezrarityparameterstatus) | 레어리티 파라미터 상태|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RarityParameterStatus(
        parameterName: "rarity-0001",
        propertyId: "property-0001"
    );
    var result = await domain.VerifyRarityParameterStatusAsync(
        verifyType: "have",
        parameterValueName: "parameter-0001",
        parameterCount: 0
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RarityParameterStatus(
        parameterName: "rarity-0001",
        propertyId: "property-0001"
    );
    var future = domain.VerifyRarityParameterStatusFuture(
        verifyType: "have",
        parameterValueName: "parameter-0001",
        parameterCount: 0
    );
    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->Enchant->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RarityParameterStatus(
        "rarity-0001", // parameterName
        "property-0001" // propertyId
    );
    const auto Future = Domain->VerifyRarityParameterStatus(
        "have", // verifyType
        "parameter-0001", // parameterValueName
        0 // parameterCount
    );
    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.enchant.namespace_(
        "namespace-0001"
    ).me(game_session).rarity_parameter_status(
        "rarity-0001",
        "property-0001"
    )

var async_result = await domain.verify_rarity_parameter_status(
    "have", # verify_type
    "parameter-0001", # parameter_value_name
    null # parameter_count
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---