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

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

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




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2023-06-06",
  "categoryModels": [
    {
      "name": "[string]카테고리 모델 이름",
      "metadata": "[string?]메타데이터",
      "rewardIntervalMinutes": "[int]보상 간격(분)",
      "defaultMaximumIdleMinutes": "[int]기본 최대 방치 시간(분)",
      "rewardResetMode": "[문자열 열거형]보상 리셋 모드",
      "acquireActions": [
        {
          "acquireActions": [
            {
              "action": "[string]입수 액션에서 실행할 액션의 종류",
              "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
            }
          ]
        }
      ],
      "idlePeriodScheduleId": "[string?]방치 기간 스케줄ID",
      "receivePeriodScheduleId": "[string?]수취 기간 스케줄ID"
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2023-06-06 | | 마스터 데이터 포맷 버전 |
| categoryModels | [List&lt;CategoryModel&gt;](#categorymodel) |  |  |  |  ~ 100 items | 카테고리 모델<br>카테고리 모델이란, 방치 보상을 얻을 수 있는 대기 카테고리를 설정하는 엔티티입니다.<br>설정에는 대기 시간별 보상이나 최대 대기 시간 등의 정보가 포함됩니다. |

## 모델

### CategoryModel

카테고리 모델<br>

카테고리 모델이란, 방치 보상을 얻을 수 있는 대기 카테고리를 설정하는 엔티티입니다.<br>
설정에는 대기 시간별 보상이나 최대 대기 시간 등의 정보가 포함됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| categoryModelId | string |  | ※ |  |  ~ 1024자 | 카테고리 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 카테고리 모델 이름<br>카테고리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| rewardIntervalMinutes | int |  | ✓ |  | 0 ~ 2147483646 | 보상 간격(분)<br>각 방치 보상 사이의 시간 간격(분)입니다. 예를 들어 60으로 설정하면, 사용자는 방치 시간 60분마다 보상 1유닛을 획득합니다. 보상의 총 개수는 (경과 방치 분수) / rewardIntervalMinutes로 계산되며, acquireActions 배열을 순환합니다. |
| defaultMaximumIdleMinutes | int |  | ✓ |  | 0 ~ 2147483646 | 기본 최대 방치 시간(분)<br>이 카테고리의 새로운 스테이터스에 대한 기본 최대 방치 시간(분)입니다. 이 제한을 초과하는 방치 시간은 추가 보상을 축적하지 않습니다. 이 값은 스테이터스 생성 시 각 스테이터스의 maximumIdleMinutes 에 복사되며, 입수 액션을 통해 사용자별로 확장할 수 있습니다. |
| rewardResetMode | 문자열 열거형<br>enum {<br>"Reset",<br>"CarryOver"<br>}<br> |  |  | "Reset" |  | 보상 리셋 모드<br>사용자가 보상을 받은 후 방치 시간의 처리 방법을 결정합니다. "Reset"은 방치 시간을 0으로 되돌리며, 부분적인 간격 시간은 소실됩니다. "CarryOver"는 추가 보상을 얻기에 부족했던 나머지 시간을 유지하여 다음 보상 사이클에 반영됩니다.Reset: 대기 시간을 0으로 리셋 / CarryOver: 보상을 받기에 부족했던 나머지 시간을 이월 /  |
| acquireActions | [List&lt;AcquireActionList&gt;](#acquireactionlist) |  |  | [] | 1 ~ 100 items | 대기 시간마다 얻을 수 있는 입수 액션 리스트<br>대기 시간을 "X분"이라고 가정하면<br>"X / rewardIntervalMinutes"가 보상을 받을 수 있는 횟수가 되지만, 여기서 지정한 배열의 요소를 반복함으로써 대기 시간마다 다른 보상을 부여할 수 있습니다. |
| idlePeriodScheduleId | string |  |  |  |  ~ 1024자 | 방치 기간 스케줄ID<br>방치 시간이 축적되는 기간을 정의하는 GS2-Schedule 이벤트의 GRN입니다. 설정하면 이벤트가 활성 상태인 동안에만 방치 시간이 카운트됩니다. 이벤트가 반복되는 경우, 스테이터스는 반복 횟수를 추적하고 새로운 사이클이 시작될 때 방치 시간을 리셋하여 이벤트 기간마다 보상이 계산되도록 합니다. |
| receivePeriodScheduleId | string |  |  |  |  ~ 1024자 | 수취 기간 스케줄ID<br>사용자가 축적된 방치 보상을 받을 수 있는 시간대를 정의하는 GS2-Schedule 이벤트의 GRN입니다. 설정하면 이벤트가 활성 상태인 동안에만 보상 수취가 허용됩니다. 이를 통해 방치 축적 기간과는 별도의 기간 한정 보상 수취 기간을 설정할 수 있습니다. |

---

### AcquireActionList

입수 액션 리스트<br>

하나의 보상 간격에서 함께 지급되는 여러 입수 액션을 그룹화하는 래퍼입니다. 각 AcquireActionList는 카테고리 모델의 acquireActions 배열 내 하나의 보상 주기에 대응하며, 각 간격마다 서로 다른 보상 조합을 설정할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| acquireActions | [List&lt;AcquireAction&gt;](#acquireaction) |  |  | [] | 0 ~ 100 items | 입수 액션 리스트<br>이 보상 간격이 트리거될 때 함께 실행되는 입수 액션의 집합입니다. 여러 액션을 조합하여 하나의 방치 보상 주기에서 서로 다른 종류의 보상을 동시에 지급할 수 있습니다. 리스트당 최대 100개의 액션입니다. |

---

### AcquireAction

입수 액션<br>

방치 보상으로 사용되는 단일 입수 액션을 나타냅니다. 액션 타입(예: 아이템 추가, 통화 증가)과 그 요청 파라미터로 구성됩니다. 방치 보상을 수령하면 이러한 액션들이 트랜잭션으로 조합되어 실행되며, 사용자에게 보상이 지급됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 입수 액션에서 실행할 액션의 종류 |
| request | string |  | ✓ |  |  ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |

---