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

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

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




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2019-02-05",
  "inventoryModels": [
    {
      "name": "[string]인벤토리 모델 이름",
      "metadata": "[string?]메타데이터",
      "initialCapacity": "[int]초기 크기",
      "maxCapacity": "[int]최대 크기",
      "protectReferencedItem": "[bool?]참조된 아이템 보호",
      "itemModels": [
        {
          "name": "[string]아이템 모델 이름",
          "metadata": "[string?]메타데이터",
          "stackingLimit": "[long]스택 가능한 최대 수량",
          "allowMultipleStacks": "[bool]복수 스택 허용",
          "sortValue": "[int]표시 순서"
        }
      ]
    }
  ],
  "simpleInventoryModels": [
    {
      "name": "[string]심플 인벤토리 모델 이름",
      "metadata": "[string?]메타데이터",
      "simpleItemModels": [
        {
          "name": "[string]심플 아이템 모델 이름",
          "metadata": "[string?]메타데이터"
        }
      ]
    }
  ],
  "bigInventoryModels": [
    {
      "name": "[string]거대 인벤토리 모델 이름",
      "metadata": "[string?]메타데이터",
      "bigItemModels": [
        {
          "name": "[string]거대 아이템 모델 이름",
          "metadata": "[string?]메타데이터"
        }
      ]
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2019-02-05 | | 마스터 데이터 포맷 버전 |
| inventoryModels | [List&lt;InventoryModel&gt;](#inventorymodel) |  |  |  |  ~ 50 items | 인벤토리 모델<br>인벤토리는 게임 플레이어가 소유한 아이템을 담는 가방과 같은 것입니다.<br>인벤토리에는 용량을 설정할 수 있으며, 용량을 초과하여 소유할 수 없습니다. |
| simpleInventoryModels | [List&lt;SimpleInventoryModel&gt;](#simpleinventorymodel) |  |  |  |  ~ 50 items | 심플 인벤토리 모델<br>일반적인 InventoryModel에서는 인벤토리 안에 저장할 수 있는 아이템의 용량 제한을 설정할 수 있었습니다.<br>하지만 심플 인벤토리에는 그러한 기능이 없으며, 단순히 아이템의 소지 수량을 보유할 뿐입니다.<br><br>다만 심플 인벤토리에서는 여러 아이템의 증감 처리를 한 번의 처리로 실행할 수 있는 API를 사용할 수 있습니다. |
| bigInventoryModels | [List&lt;BigInventoryModel&gt;](#biginventorymodel) |  |  |  |  ~ 50 items | 거대 인벤토리 모델<br>일반적인 InventoryModel이나 SimpleInventoryModel에서는 인벤토리에 저장할 수 있는 아이템의 수가 int64 범위로 제한되었습니다.<br>인플레이션 계열 게임에서는 더 넓은 범위의 값이 필요한 경우가 있습니다.<br><br>거대 인벤토리 모델에서는 인벤토리에 저장할 수 있는 아이템의 수가 최대 1024자리의 정수값을 가질 수 있습니다. |

## 모델

### InventoryModel

인벤토리 모델<br>

인벤토리는 게임 플레이어가 소유한 아이템을 담는 가방과 같은 것입니다.<br>
인벤토리에는 용량을 설정할 수 있으며, 용량을 초과하여 소유할 수 없습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| inventoryModelId | string |  | ※ |  |  ~ 1024자 | 인벤토리 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 인벤토리 모델 이름<br>인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| initialCapacity | int |  | ✓ |  | 0 ~ 2147483646 | 초기 크기<br>인벤토리가 처음 생성될 때 사용자에게 제공되는 인벤토리 칸의 수입니다. 각 칸에는 하나의 아이템 스택을 저장할 수 있습니다. 사용자는 게임 플레이 액션을 통해 maxCapacity까지 용량을 확장할 수 있습니다. |
| maxCapacity | int |  | ✓ |  | 0 ~ 2147483646 | 최대 크기<br>사용자가 확장할 수 있는 인벤토리 칸의 상한값입니다. 이 값을 초과하여 용량을 늘릴 수 없습니다. 모든 칸이 사용 중이고 아이템을 더 이상 스택할 수 없는 경우, 오버플로우 스크립트가 초과분을 처리하지 않는 한 입수는 실패합니다. |
| protectReferencedItem | bool? |  |  | false |  | 참조된 아이템 보호<br>활성화하면 (referenceOf 메커니즘을 통해) 참조가 등록된 아이템 세트는 소비하거나 삭제할 수 없게 됩니다. 다른 시스템에서 사용 중인 아이템(예: 장착 중인 장비, 편성에 연결된 아이템)이 실수로 삭제되는 것을 방지합니다. |
| itemModels | [List&lt;ItemModel&gt;](#itemmodel) |  |  | [] | 1 ~ 1000 items | 아이템 모델 목록<br>이 인벤토리에 저장할 수 있는 아이템의 종류입니다. 각 아이템 모델은 한 종류의 아이템에 대한 스택 및 입수 동작을 정의합니다. 인벤토리 모델당 최대 1000개의 아이템 모델까지 설정할 수 있습니다. |

---

### ItemModel

아이템 모델<br>

아이템은 포션 ×99 처럼, 하나의 인벤토리 칸에 여러 개를 모아서 소지할 수 있습니다.<br>
이렇게 한 칸에 여러 개를 모으는 것을 "스택"이라고 하며, 아이템마다 스택 가능한 상한 수를 설정할 수 있습니다.<br>

스택 상한에 도달했을 때의 동작도 아이템마다 설정할 수 있습니다.<br>
구체적으로는 다음 중 하나를 선택할 수 있습니다:<br>

- 새로운 인벤토리 칸을 추가하여 추가로 소지할 수 있도록 한다<br>
- 상한에 도달했으므로 더 이상 입수할 수 없도록 한다

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| itemModelId | string |  | ※ |  |  ~ 1024자 | 아이템 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 아이템 모델 이름<br>아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>GS2-Enhance에는 GS2-Inventory와 연동하여 강화를 수행하는 메커니즘이 있으며, ItemModel의 메타데이터에 JSON 형식으로 강화 소재로 사용했을 때의 경험치량을 설정합니다.<br>자세한 내용은 [마이크로서비스 소개 / GS2-Enhance](/microservices/enhance/#강화-레이트) 항목에서 설명합니다. |
| stackingLimit | long |  | ✓ |  | 1 ~ 9223372036854775805 | 스택 가능한 최대 수량<br>하나의 인벤토리 칸(스택)에 보관할 수 있는 이 아이템의 최대 수입니다. 이 상한에 도달하면 allowMultipleStacks 설정에 따라 새로운 칸이 할당되거나 추가 입수가 차단됩니다. |
| allowMultipleStacks | bool |  | ✓ |  |  | 복수 스택 허용<br>활성화하면 스택 상한에 도달했을 때 새로운 인벤토리 칸이 자동으로 할당되어 이 아이템의 추가 수량을 저장합니다(추가 용량을 소비합니다). 비활성화하면 기존 칸에서 스택 상한에 도달한 시점에 입수가 차단됩니다. |
| sortValue | int |  | ✓ |  | 0 ~ 2147483646 | 표시 순서<br>인벤토리 내 아이템을 표시용으로 정렬하기 위한 수치입니다. 값이 작을수록 먼저 표시됩니다. 이 값은 ItemSet 레코드에도 복사되어 소지 아이템의 일관된 정렬을 가능하게 합니다. |

---

### SimpleInventoryModel

심플 인벤토리 모델<br>

일반적인 InventoryModel에서는 인벤토리 안에 저장할 수 있는 아이템의 용량 제한을 설정할 수 있었습니다.<br>
하지만 심플 인벤토리에는 그러한 기능이 없으며, 단순히 아이템의 소지 수량을 보유할 뿐입니다.<br>

다만 심플 인벤토리에서는 여러 아이템의 증감 처리를 한 번의 처리로 실행할 수 있는 API를 사용할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| inventoryModelId | string |  | ※ |  |  ~ 1024자 | 심플 인벤토리 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 심플 인벤토리 모델 이름<br>심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| simpleItemModels | [List&lt;SimpleItemModel&gt;](#simpleitemmodel) |  |  | [] | 1 ~ 1000 items | 심플 아이템 모델 목록<br>이 심플 인벤토리에 저장할 수 있는 아이템의 종류입니다. 일반적인 인벤토리와 달리 심플 아이템에는 스택 상한이나 용량 제약이 없습니다. 심플 인벤토리 모델당 최대 1000개의 아이템 모델을 사용할 수 있습니다. |

---

### SimpleItemModel

심플 아이템 모델<br>

ItemModel에서는 스택할 수 있는 수량의 최댓값을 설정할 수 있어, 일정 수를 초과하는 경우 여러 스택으로 나누는 구현이 가능했습니다.<br>
심플 아이템에는 그러한 기능이 없으며, 단순히 아이템의 소지 수량만을 보관합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| itemModelId | string |  | ※ |  |  ~ 1024자 | 심플 아이템 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 심플 아이템 모델 이름<br>심플 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |

---

### BigInventoryModel

거대 인벤토리 모델<br>

일반적인 InventoryModel이나 SimpleInventoryModel에서는 인벤토리에 저장할 수 있는 아이템의 수가 int64 범위로 제한되었습니다.<br>
인플레이션 계열 게임에서는 더 넓은 범위의 값이 필요한 경우가 있습니다.<br>

거대 인벤토리 모델에서는 인벤토리에 저장할 수 있는 아이템의 수가 최대 1024자리의 정수값을 가질 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| inventoryModelId | string |  | ※ |  |  ~ 1024자 | 거대 인벤토리 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 거대 인벤토리 모델 이름<br>거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| bigItemModels | [List&lt;BigItemModel&gt;](#bigitemmodel) |  |  | [] | 1 ~ 1000 items | 거대 아이템 모델 목록<br>이 거대 인벤토리에 저장할 수 있는 아이템의 종류입니다. 각 거대 아이템 모델은 최대 1024자리의 정수 문자열로 표현되는 수량을 보유할 수 있습니다. 거대 인벤토리 모델당 최대 1000개의 아이템 모델까지 설정할 수 있습니다. |

---

### BigItemModel

거대 아이템 모델<br>

거대 아이템 모델은 거대 인벤토리 모델에 저장되는 거대 아이템을 정의하는 모델입니다.<br>
거대 아이템은 소지 수량을 int64 범위를 초과하여 보유할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| itemModelId | string |  | ※ |  |  ~ 1024자 | 거대 아이템 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 거대 아이템 모델 이름<br>거대 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |

---