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

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

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




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2024-04-25",
  "guildModels": [
    {
      "name": "[string]길드 모델 이름",
      "metadata": "[string?]메타데이터",
      "defaultMaximumMemberCount": "[int]기본 최대 멤버 수",
      "maximumMemberCount": "[int]최대 멤버 수 상한",
      "inactivityPeriodDays": "[int]무활동 기간(일수)",
      "roles": [
        {
          "name": "[string]롤 모델 이름",
          "metadata": "[string?]메타데이터",
          "policyDocument": "[string]정책 문서"
        }
      ],
      "guildMasterRole": "[string]길드 마스터 롤 이름",
      "guildMemberDefaultRole": "[string]기본 멤버 롤 이름",
      "rejoinCoolTimeMinutes": "[int]재가입 쿨타임(분)",
      "maxConcurrentJoinGuilds": "[int?]동시 가입 가능 길드 최대 수",
      "maxConcurrentGuildMasterCount": "[int?]동시 존재 가능 길드 마스터 최대 수"
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2024-04-25 | | 마스터 데이터 포맷 버전 |
| guildModels | [List&lt;GuildModel&gt;](#guildmodel) |  |  |  |  ~ 100 items | 길드 모델<br>길드 모델이란 길드에 가입 가능한 최대 인원수 설정 및 길드 내 직책별 권한 설정을 가지는 엔티티입니다. |

## 모델

### GuildModel

길드 모델<br>

길드 모델이란 길드에 가입 가능한 최대 인원수 설정 및 길드 내 직책별 권한 설정을 가지는 엔티티입니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| guildModelId | string |  | ※ |  |  ~ 1024자 | 길드 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 길드 모델 이름<br>길드 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| defaultMaximumMemberCount | int |  | ✓ |  | 1 ~ 2147483646 | 기본 최대 멤버 수<br>새 길드가 생성될 때 허용되는 초기 최대 멤버 수입니다. 이 값은 신규 길드의 currentMaximumMemberCount 초기값으로 사용됩니다. 길드 조작이나 입수 액션을 통해 나중에 maximumMemberCount 상한까지 늘릴 수 있습니다. |
| maximumMemberCount | int |  | ✓ |  | 1 ~ 2147483646 | 최대 멤버 수 상한<br>길드가 가질 수 있는 멤버 수의 절대적인 상한입니다. 길드의 currentMaximumMemberCount는 이 값을 초과할 수 없습니다. 길드가 의도된 규모를 넘어 성장하는 것을 방지하는 하드 캡으로 작동합니다. |
| inactivityPeriodDays | int |  |  | 7 | 1 ~ 365 | 무활동 기간(일수)<br>길드 마스터의 무활동이 이 일수를 초과한 경우, 남은 길드 멤버 중에서 새로운 길드 마스터가 자동으로 선출됩니다. 길드 마스터가 플레이를 중단했을 때 길드가 관리 불능 상태가 되는 것을 방지합니다. |
| roles | [List&lt;RoleModel&gt;](#rolemodel) |  | ✓ |  | 1 ~ 10 items | 롤 모델 리스트<br>이 타입의 길드 내에서 이용 가능한 롤 정의 리스트입니다. guildMasterRole 및 guildMemberDefaultRole에서 참조되는 롤을 최소한 포함해야 합니다. 각 롤은 정책 문서를 통해 고유한 권한 집합을 정의합니다. 최대 10개의 롤을 정의할 수 있습니다. |
| guildMasterRole | string |  | ✓ |  |  ~ 128자 | 길드 마스터 롤 이름<br>길드 마스터에게 할당되는 롤의 이름입니다. roles 리스트에 정의된 롤을 참조해야 합니다. 길드 마스터는 일반적으로 참가 신청 승인, 멤버 추방, 롤 변경, 길드 설정 갱신 등 길드를 관리하는 모든 권한을 가집니다. |
| guildMemberDefaultRole | string |  | ✓ |  |  ~ 128자 | 기본 멤버 롤 이름<br>새로운 길드 멤버가 가입할 때 자동으로 할당되는 롤의 이름입니다. roles 리스트에 정의된 롤을 참조해야 합니다. 이는 길드 마스터에 의한 롤 변경 이전, 일반 멤버의 기본 권한 집합입니다. |
| rejoinCoolTimeMinutes | int |  |  | 0 | 0 ~ 2147483646 | 재가입 쿨타임(분)<br>사용자가 길드를 탈퇴한 후 다시 길드에 가입할 수 있게 되기까지의 쿨다운 기간(분)입니다. 0으로 설정하면 즉시 재가입이 가능합니다. 사용자가 길드에 반복적으로 가입·탈퇴하는 악용 패턴을 방지합니다. |
| maxConcurrentJoinGuilds | int |  |  |  | 1 ~ 10 | 동시 가입 가능 길드 최대 수<br>사용자가 이 타입의 길드에 동시에 멤버로 가입할 수 있는 최대 수입니다. 플레이어가 여러 길드에 동시에 소속될 수 있는 디자인(예: 전투 길드와 소셜 길드)을 가능하게 합니다. 값은 1에서 10 사이입니다. |
| maxConcurrentGuildMasterCount | int |  |  |  | 1 ~ 100 | 동시 존재 가능 길드 마스터 최대 수<br>하나의 길드에 동시에 존재할 수 있는 길드 마스터의 최대 인원수입니다. 여러 플레이어가 길드 마스터의 책임과 권한을 공유하는 공동 리더십 디자인을 가능하게 합니다. 값은 1에서 100 사이입니다. |

---

### RoleModel

롤 모델<br>

롤 모델은 길드 내에서의 역할을 정의하고, 각 역할별로 실행할 수 있는 처리에 관한 권한을 설정합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 롤 모델 이름<br>롤 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| policyDocument | string |  | ✓ |  |  ~ 10240자 | 정책 문서<br>이 역할의 권한을 정의하는 JSON 형식의 정책 문서입니다. 이 역할에 할당된 멤버에 대해 어떤 길드 조작(참가 요청 승인/거부, 멤버 추방, 길드 정보 업데이트, 멤버 역할 변경 등)이 허용되거나 거부되는지를 지정합니다. |

---