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

# GS2-Idle 트랜잭션 액션

검증/소비/입수 각 트랜잭션 액션의 사양





## Consume Action

소비 액션

### Gs2Idle:DecreaseMaximumIdleMinutesByUserId

사용자 ID를 지정하여 최대 대기 시간을 감산<br>

지정된 카테고리에서 사용자의 최대 대기 시간에서 지정된 분(分) 수를 감산합니다.<br>
최대 대기 시간은 0 미만으로 내려갈 수 없습니다.<br>
스테이터스가 아직 존재하지 않는 경우, 감산을 적용하기 전에 자동으로 생성됩니다.

**수량 지정 가능한 액션: 예**

**반전 가능한 액션: 예**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| categoryName | string |  | ✓|  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| decreaseMinutes | int |  | |  | 1 ~ 2147483646 | 최대 대기 시간 감소량(분) |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "categoryName": "[string]카테고리 모델 이름",
        "decreaseMinutes": "[int]최대 대기 시간 감소량(분)",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:DecreaseMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  categoryName: "[string]카테고리 모델 이름"
  decreaseMinutes: "[int]최대 대기 시간 감소량(분)"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("idle").consume.decrease_maximum_idle_minutes_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    categoryName="[string]카테고리 모델 이름",
    decreaseMinutes="[int]최대 대기 시간 감소량(분)",
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

## Acquire Action

입수 액션

### Gs2Idle:IncreaseMaximumIdleMinutesByUserId

사용자 ID를 지정하여 최대 대기 시간을 가산<br>

지정된 카테고리에서 사용자의 최대 대기 시간에 지정된 분(分) 수를 가산합니다.<br>
최대 대기 시간은 방치 보상이 누적될 수 있는 시간의 상한을 결정합니다.<br>
스테이터스가 아직 존재하지 않는 경우, 가산을 적용하기 전에 자동으로 생성됩니다.

**수량 지정 가능한 액션: 예**

**반전 가능한 액션: 예**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| categoryName | string |  | ✓|  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| increaseMinutes | int |  | |  | 1 ~ 2147483646 | 최대 대기 시간 증가량(분) |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "categoryName": "[string]카테고리 모델 이름",
        "increaseMinutes": "[int]최대 대기 시간 증가량(분)",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:IncreaseMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  categoryName: "[string]카테고리 모델 이름"
  increaseMinutes: "[int]최대 대기 시간 증가량(분)"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("idle").acquire.increase_maximum_idle_minutes_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    categoryName="[string]카테고리 모델 이름",
    increaseMinutes="[int]최대 대기 시간 증가량(분)",
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

### Gs2Idle:SetMaximumIdleMinutesByUserId

사용자 ID를 지정하여 최대 대기 시간을 설정<br>

지정된 카테고리에서 사용자의 최대 대기 시간을 지정된 절대값으로 설정합니다.<br>
가산/감산 조작과 달리, 현재 최대 대기 시간을 직접 대체합니다.<br>
갱신 후 스테이터스와 갱신 전 스테이터스를 모두 반환하므로, 호출한 측에서 변경 내용을 확인할 수 있습니다.<br>
스테이터스가 아직 존재하지 않는 경우, 값을 적용하기 전에 자동으로 생성됩니다.

**수량 지정 가능한 액션: 아니오**

**반전 가능한 액션: 아니오**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| categoryName | string |  | ✓|  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| maximumIdleMinutes | int |  | |  | 1 ~ 2147483646 | 설정할 최대 대기 시간 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Idle:SetMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "categoryName": "[string]카테고리 모델 이름",
        "maximumIdleMinutes": "[int]설정할 최대 대기 시간",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:SetMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  categoryName: "[string]카테고리 모델 이름"
  maximumIdleMinutes: "[int]설정할 최대 대기 시간"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("idle").acquire.set_maximum_idle_minutes_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    categoryName="[string]카테고리 모델 이름",
    maximumIdleMinutes="[int]설정할 최대 대기 시간",
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

### Gs2Idle:ReceiveByUserId

사용자 ID를 지정하여 보상 수령<br>

지정된 사용자와 카테고리의 누적된 대기 시간을 기준으로 방치 보상을 수령합니다.<br>
보상량은 경과한 대기 시간을 rewardIntervalMinutes로 나눈 값으로 계산되며, maximumIdleMinutes로 상한이 설정됩니다.<br>
receiveScript가 설정되어 있는 경우, 보상 지급 전에 실행되어 수령 조작을 변경하거나 거부할 수 있습니다.<br>
overrideAcquireActionsScriptId를 통해 입수 액션(배율 보정 적용 등)을 변경하는 것도 가능합니다.<br>
수령 후, 대기 타이머는 현재 시각으로 리셋됩니다.<br>
계산된 보상의 입수 액션을 포함하는 트랜잭션을 반환합니다.

**수량 지정 가능한 액션: 아니오**

**반전 가능한 액션: 아니오**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| categoryName | string |  | ✓|  |  ~ 128자 | 카테고리 모델 이름<br>이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. |
| config | List&lt;Config&gt; |  | | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Idle:ReceiveByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "categoryName": "[string]카테고리 모델 이름",
        "config": [
            {
                "key": "[string]이름",
                "value": "[string]값"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:ReceiveByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  categoryName: "[string]카테고리 모델 이름"
  config: 
    - key: "[string]이름"
      value: "[string]값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("idle").acquire.receive_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    categoryName="[string]카테고리 모델 이름",
    config={
        {
            key="[string]이름",
            value="[string]값"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---