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

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

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




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2019-09-09",
  "moldModels": [
    {
      "name": "[string]폼 저장 영역 모델의 이름",
      "metadata": "[string?]메타데이터",
      "initialMaxCapacity": "[int]폼을 저장할 수 있는 초기 캐파시티",
      "maxCapacity": "[int]폼을 저장할 수 있는 최대 캐파시티",
      "formModel": {
        "name": "[string]폼 모델명",
        "metadata": "[string?]메타데이터",
        "slots": [
          {
            "name": "[string]슬롯 모델명",
            "propertyRegex": "[string]프로퍼티로 설정 가능한 값의 정규 표현식",
            "metadata": "[string?]메타데이터"
          }
        ]
      }
    }
  ],
  "propertyFormModels": [
    {
      "name": "[string]프로퍼티 폼 모델 이름",
      "metadata": "[string?]메타데이터",
      "slots": [
        {
          "name": "[string]슬롯 모델명",
          "propertyRegex": "[string]프로퍼티로 설정 가능한 값의 정규 표현식",
          "metadata": "[string?]메타데이터"
        }
      ]
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2019-09-09 | | 마스터 데이터 포맷 버전 |
| moldModels | [List&lt;MoldModel&gt;](#moldmodel) |  |  |  |  ~ 100 items | 폼 저장 영역 모델<br>폼 저장 영역 모델은 파티 편성이라면 「불 속성 파티」「물 속성 파티」와 같은 형태로 저장하는 것을 상정하고 있습니다.<br>저장할 수 있는 영역의 수는 제한할 수 있으며, 개별적으로 확장할 수도 있습니다. |
| propertyFormModels | [List&lt;PropertyFormModel&gt;](#propertyformmodel) |  |  |  |  ~ 100 items | 프로퍼티 폼 모델<br>프로퍼티 폼 모델은 편성 상태를 나타내는 엔티티입니다.<br>Mold / Form과의 차이점은, 슬롯 수를 정의하고 각 슬롯에 편성을 기록하는 것이 Mold / Form이며,<br>보유하고 있는 장비에 스킬을 설정하는 것처럼 수를 사전에 정하기 어려운 편성을 표현할 때 사용하는 것이 프로퍼티 폼 모델입니다. |

## 모델

### FormModel

폼 모델<br>

폼 모델은 편성 상태를 나타내는 엔티티입니다.<br>
편성 가능한 영역으로 `슬롯`을 정의할 수 있습니다.<br>

무기·방어구라면 「오른손」「왼손」「몸통」「팔」과 같은 부위를 슬롯으로 하고,<br>
파티라면 「전위」「중위」「후위」와 같은 포지션을 슬롯으로 표현할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| formModelId | string |  | ※ |  |  ~ 1024자 | 폼 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 폼 모델명<br>폼 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| slots | [List&lt;SlotModel&gt;](#slotmodel) |  | ✓ |  | 1 ~ 10 items | 슬롯 모델 리스트<br>이 폼을 구성하는 슬롯 정의의 순서가 있는 리스트입니다. 각 슬롯은 할당 가능한 포지션을 나타내며, 슬롯명은 폼 내에서 고유해야 합니다. 장비에서는 "weapon", "armor", "accessory"와 같은 슬롯, 파티에서는 "position_1", "position_2"와 같은 슬롯을 생각할 수 있습니다. |

---

### SlotModel

슬롯 모델<br>

폼 모델 내의 하나의 슬롯을 정의합니다. 슬롯은 게임 리소스(아이템, 캐릭터, 장비 등)를 배치할 수 있는 할당 가능한 포지션을 나타냅니다. 프로퍼티 정규 표현식에 의해 슬롯에 설정 가능한 값이 검증됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 슬롯 모델명<br>폼 모델 내에서 이 슬롯을 고유하게 식별하는 이름입니다. 장비 폼에서는 "right_hand", "body"와 같은 이름이, 파티 폼에서는 "vanguard", "rear_guard"와 같은 이름이 일반적으로 사용됩니다. |
| propertyRegex | string |  |  | ".*" |  ~ 512자 | 프로퍼티로 설정 가능한 값의 정규 표현식<br>이 슬롯에 할당 가능한 프로퍼티 ID 값을 검증하는 정규 표현식 패턴입니다. 예를 들어 특정 GS2-Inventory 아이템 GRN이나 GS2-Dictionary 엔트리 GRN으로 제한할 수 있습니다. 기본값은 ".*"이며 임의의 값을 허용합니다. |
| metadata | string |  |  |  |  ~ 512자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |

---

### MoldModel

폼 저장 영역 모델<br>

폼 저장 영역 모델은 파티 편성이라면 「불 속성 파티」「물 속성 파티」와 같은 형태로 저장하는 것을 상정하고 있습니다.<br>
저장할 수 있는 영역의 수는 제한할 수 있으며, 개별적으로 확장할 수도 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| moldModelId | string |  | ※ |  |  ~ 1024자 | 폼 저장 영역 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 폼 저장 영역 모델의 이름<br>폼 저장 영역 모델 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| initialMaxCapacity | int |  | ✓ |  | 1 ~ 2147483646 | 폼을 저장할 수 있는 초기 캐파시티<br>이 저장 영역에서 각 플레이어가 이용할 수 있는 기본 폼 저장 슬롯 수입니다. 예를 들어 3으로 설정하면 플레이어는 초기 상태에서 최대 3개의 서로 다른 편성(예: 「불 속성 파티」「물 속성 파티」「바람 속성 파티」)을 저장할 수 있습니다. 플레이어별로 maxCapacity까지 확장할 수 있습니다. |
| maxCapacity | int |  | ✓ |  | 1 ~ 2147483646 | 폼을 저장할 수 있는 최대 캐파시티<br>이 저장 영역에서 플레이어별 폼 저장 슬롯 수의 절대적인 상한입니다. 캐파시티 확장 조작을 수행하더라도 캐파시티는 이 값을 초과할 수 없습니다. initialMaxCapacity 이상의 값이어야 합니다. |
| formModel | [FormModel](#formmodel) |  | ✓ |  |  | 폼 모델 |

---

### PropertyFormModel

프로퍼티 폼 모델<br>

프로퍼티 폼 모델은 편성 상태를 나타내는 엔티티입니다.<br>
Mold / Form과의 차이점은, 슬롯 수를 정의하고 각 슬롯에 편성을 기록하는 것이 Mold / Form이며,<br>
보유하고 있는 장비에 스킬을 설정하는 것처럼 수를 사전에 정하기 어려운 편성을 표현할 때 사용하는 것이 프로퍼티 폼 모델입니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| propertyFormModelId | string |  | ※ |  |  ~ 1024자 | 프로퍼티 폼 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 프로퍼티 폼 모델 이름<br>프로퍼티 폼 모델 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| slots | [List&lt;SlotModel&gt;](#slotmodel) |  | ✓ |  | 1 ~ 10 items | 슬롯 모델 목록<br>이 프로퍼티 폼의 슬롯 정의를 순서대로 나열한 목록입니다. 캐파시티에 의해 폼 수가 제한되는 Mold/Form과 달리, 프로퍼티 폼은 프로퍼티 ID로 식별되며 보유하는 리소스마다 존재할 수 있습니다. 슬롯 이름은 폼 내에서 고유해야 합니다. |

---