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

# GS2-Enhance 마스터 데이터 레퍼런스

마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2020-08-22",
  "rateModels": [
    {
      "name": "[string]강화 레이트 모델 이름",
      "description": "[string?]설명문",
      "metadata": "[string?]메타데이터",
      "targetInventoryModelId": "[string]강화 대상으로 사용할 수 있는 GS2-Inventory 인벤토리 모델의 GRN",
      "acquireExperienceSuffix": "[string]GS2-Experience에서 획득한 경험치를 저장하는 프로퍼티 ID에 부여하는 서픽스",
      "materialInventoryModelId": "[string]강화 소재로 사용할 수 있는 GS2-Inventory 인벤토리 모델 GRN",
      "acquireExperienceHierarchy": [
        "[string]ItemModel의 메타데이터에 저장할, 획득 경험치를 정의하는 JSON 데이터의 계층 구조 정의"
      ],
      "experienceModelId": "[string]강화 결과로 얻는 GS2-Experience 경험치 모델 GRN",
      "bonusRates": [
        {
          "rate": "[float]경험치 보너스 배율 (1.0 = 보너스 없음)",
          "weight": "[int]추첨 가중치"
        }
      ]
    }
  ],
  "unleashRateModels": [
    {
      "name": "[string]한계돌파 레이트 모델명",
      "description": "[string?]설명문",
      "metadata": "[string?]메타데이터",
      "targetInventoryModelId": "[string]한계돌파 대상에 사용할 수 있는 GS2-Inventory 인벤토리 모델 GRN",
      "gradeModelId": "[string]그레이드 모델 GRN",
      "gradeEntries": [
        {
          "gradeValue": "[long]대상 그레이드",
          "needCount": "[int]동일 종류의 아이템을 몇 개 소비할지"
        }
      ]
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2020-08-22 | | 마스터 데이터 포맷 버전 |
| rateModels | [List&lt;RateModel&gt;](#ratemodel) |  |  |  |  ~ 10000 items | 강화 레이트 모델<br>강화 레이트는 강화에 사용하는 소재와 강화 대상을 정의한 데이터입니다.<br><br>소재 데이터와 강화 대상 데이터는 모두 GS2-Inventory에서 관리되고 있어야 합니다.<br>강화로 얻는 경험치는 GS2-Inventory의 메타데이터에 JSON 형식으로 기록됩니다.<br>여기서는 메타데이터의 어느 계층에 경험치 값이 저장되어 있는지를 기재해야 합니다.<br><br>강화 시 일정 확률로 `대성공`과 같은 형태로 입수할 수 있는 경험치량에 보정값을 적용할 수 있습니다.<br>그 추첨 확률도 이 엔티티에서 정의합니다. |
| unleashRateModels | [List&lt;UnleashRateModel&gt;](#unleashratemodel) |  |  |  |  ~ 10000 items | 한계돌파 레이트 모델<br>아이템의 한계돌파(해방) 조건을 정의합니다. GS2-Inventory에서 관리되는 아이템과 GS2-Grade의 그레이드 모델을 연결하여 그레이드 진행을 가능하게 합니다. 각 그레이드 레벨에서 소비하는 동일 종류 아이템의 수를 개별적으로 설정할 수 있어, 각 한계돌파 단계의 비용을 세밀하게 제어할 수 있습니다. |

## 모델

### RateModel

강화 레이트 모델<br>

강화 레이트는 강화에 사용하는 소재와 강화 대상을 정의한 데이터입니다.<br>

소재 데이터와 강화 대상 데이터는 모두 GS2-Inventory에서 관리되고 있어야 합니다.<br>
강화로 얻는 경험치는 GS2-Inventory의 메타데이터에 JSON 형식으로 기록됩니다.<br>
여기서는 메타데이터의 어느 계층에 경험치 값이 저장되어 있는지를 기재해야 합니다.<br>

강화 시 일정 확률로 `대성공`과 같은 형태로 입수할 수 있는 경험치량에 보정값을 적용할 수 있습니다.<br>
그 추첨 확률도 이 엔티티에서 정의합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rateModelId | string |  | ※ |  |  ~ 1024자 | 강화 레이트 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 강화 레이트 모델 이름<br>강화 레이트 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. |
| description | string |  |  |  |  ~ 1024자 | 설명문 |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| targetInventoryModelId | string |  | ✓ |  |  ~ 1024자 | 강화 대상으로 사용할 수 있는 GS2-Inventory 인벤토리 모델의 GRN<br>강화 대상이 되는 아이템을 보유하는 GS2-Inventory의 인벤토리 모델을 지정합니다. 강화되는 아이템은 이 인벤토리 모델에 속해 있어야 합니다. |
| acquireExperienceSuffix | string |  | ✓ |  |  ~ 1024자 | GS2-Experience에서 획득한 경험치를 저장하는 프로퍼티 ID에 부여하는 서픽스<br>아이템의 프로퍼티 ID 끝에 추가되어, 경험치가 저장되는 GS2-Experience의 프로퍼티 ID를 구성하는 문자열입니다. 같은 아이템에 여러 경험치 종류를 부여할 수 있습니다(예: 캐릭터 레벨의 "level", 호감도의 "like"). |
| materialInventoryModelId | string |  | ✓ |  |  ~ 1024자 | 강화 소재로 사용할 수 있는 GS2-Inventory 인벤토리 모델 GRN<br>강화 소재로 사용할 수 있는 아이템을 보유하는 GS2-Inventory의 인벤토리 모델을 지정합니다. 각 소재가 제공하는 경험치는 acquireExperienceHierarchy로 지정된 JSON 계층을 사용하여 아이템 모델의 메타데이터에 정의됩니다. |
| acquireExperienceHierarchy | List&lt;string&gt; |  |  |  | 0 ~ 10 items | ItemModel의 메타데이터에 저장할, 획득 경험치를 정의하는 JSON 데이터의 계층 구조 정의<br>GS2-Enhance에는 GS2-Inventory와 연동하여 강화를 수행하는 기능이 있으며, ItemModel의 메타데이터에 JSON 형식으로 강화 소재로 사용했을 때의 경험치량을 설정합니다.<br>예를 들어, { "aaa": { "bbb": { "experienceValue": 100 } } }와 같은 구조의 데이터 정의로 메타데이터에 설정하고 싶은 경우에는 [ "aaa", "bbb", "experienceValue" ]와 같이 지정합니다.<br>자세한 내용은 [마이크로서비스 소개 / GS2-Enhance](/microservices/enhance/#강화-레이트) 항목에서 설명합니다. |
| experienceModelId | string |  | ✓ |  |  ~ 1024자 | 강화 결과로 얻는 GS2-Experience 경험치 모델 GRN<br>강화로 얻은 경험치가 기록되는 GS2-Experience의 경험치 모델을 지정합니다. 경험치는 대상 아이템의 프로퍼티 ID와 acquireExperienceSuffix를 조합하여 식별되는 프로퍼티에 가산됩니다. |
| bonusRates | [List&lt;BonusRate&gt;](#bonusrate) |  |  |  | 0 ~ 1000 items | 경험치 획득량 보너스<br>강화 시 보너스 경험치 배율의 가중치 추첨을 정의합니다. 각 항목은 배율(예: 1.5로 150%)과 추첨 가중치를 지정합니다. 강화 실행 시 가중치 추첨으로 하나의 항목이 선택되어, 획득 경험치에 "대성공" 보너스가 적용되는지 여부가 결정됩니다. |

---

### BonusRate

경험치 획득량 보너스<br>

강화 시 경험치 보너스 배율을 결정하는 가중치 추첨의 단일 항목을 정의합니다. 서로 다른 배율과 가중치를 가진 여러 항목을 설정함으로써, 제어된 확률에 따른 "대성공"이나 "초성공" 같은 시스템을 구현할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rate | float |  |  | 1.0 | 0 ~ 10000 | 경험치 보너스 배율 (1.0 = 보너스 없음)<br>이 항목이 추첨되었을 때 기본 경험치에 적용되는 배율입니다. 1.0은 보너스 없는 일반 강화, 1.5는 경험치 150%(대성공), 2.0은 경험치 200%(초성공) 등을 의미합니다. |
| weight | int |  |  | 1 | 0 ~ 2147483645 | 추첨 가중치<br>보너스 레이트를 선택하는 가중치 추첨에서 사용되는 상대적인 가중치입니다. 값이 클수록 이 보너스 레이트가 선택될 확률이 높아집니다. 실제 확률은 이 가중치를 보너스 레이트 목록 내 모든 가중치의 합계로 나눈 값이 됩니다. |

---

### UnleashRateModel

한계돌파 레이트 모델<br>

아이템의 한계돌파(해방) 조건을 정의합니다. GS2-Inventory에서 관리되는 아이템과 GS2-Grade의 그레이드 모델을 연결하여 그레이드 진행을 가능하게 합니다. 각 그레이드 레벨에서 소비하는 동일 종류 아이템의 수를 개별적으로 설정할 수 있어, 각 한계돌파 단계의 비용을 세밀하게 제어할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| unleashRateModelId | string |  | ※ |  |  ~ 1024자 | 한계돌파 레이트 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 한계돌파 레이트 모델명<br>한계돌파 레이트 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| description | string |  |  |  |  ~ 1024자 | 설명문 |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| targetInventoryModelId | string |  | ✓ |  |  ~ 1024자 | 한계돌파 대상에 사용할 수 있는 GS2-Inventory 인벤토리 모델 GRN<br>한계돌파 대상이 되는 아이템을 보유하는 GS2-Inventory의 인벤토리 모델을 지정합니다. 한계돌파하는 아이템과 소재로 소비되는 동일 종류 아이템 모두 이 인벤토리 모델에 속해 있어야 합니다. |
| gradeModelId | string |  | ✓ |  |  ~ 1024자 | 그레이드 모델 GRN<br>대상 아이템의 한계돌파 레벨을 추적하는 GS2-Grade의 그레이드 모델을 지정합니다. 한계돌파가 성공하면, 이 그레이드 모델 내에서 아이템의 그레이드가 가산됩니다. |
| gradeEntries | [List&lt;UnleashRateEntryModel&gt;](#unleashrateentrymodel) |  | ✓ |  | 1 ~ 1000 items | 그레이드 엔트리 목록<br>한계돌파의 각 그레이드 레벨에 대한 소재 비용을 정의합니다. 각 엔트리는 그레이드 값과, 해당 그레이드에 도달하기 위해 소비해야 하는 동일 종류 아이템 수를 매핑합니다. 예를 들어, 그레이드 1은 복제품 1개, 그레이드 2는 복제품 3개와 같이 설정할 수 있습니다. |

---

### UnleashRateEntryModel

한계돌파 레이트 엔트리 모델<br>

한계돌파 진행에서 단일 그레이드 레벨의 소재 비용을 정의합니다. 각 엔트리는 대상이 되는 그레이드 값과, 해당 그레이드를 달성하기 위해 소비해야 하는 동일 종류 아이템의 수를 지정합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| gradeValue | long |  | ✓ |  | 1 ~ 1000 | 대상 그레이드<br>이 엔트리가 비용을 정의하는 그레이드 값입니다. 이 그레이드 레벨로의 한계돌파를 실행할 때, needCount로 지정된 수의 아이템이 소비됩니다. |
| needCount | int |  | ✓ |  | 1 ~ 1000 | 동일 종류의 아이템을 몇 개 소비할지<br>대상 그레이드로의 한계돌파를 실행하기 위해 소비해야 하는 동일 종류 아이템의 수입니다. 이 아이템들은 한계돌파되는 아이템과 동일한 아이템 모델의 것입니다. |

---