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

# GS2-Stamina SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-Stamina SDK의 모델 사양과 API 레퍼런스



## 모델

### EzStamina

스태미나<br>

스태미나란 현실 시간의 경과에 따라 회복되는 포인트입니다.<br>
일반적으로 이 스태미나를 소비해야 게임을 플레이할 수 있도록 함으로써, 플레이어의 하루 플레이 횟수를 제한하고 게임의 진행 속도를 게임 제공사가 제어할 목적으로 사용됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| staminaName | string |  | ✓ |  |  ~ 128자 | 스태미나 모델 이름<br>이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다.<br>사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다. |
| value | int |  | ✓ |  | 0 ~ 2147483646 | 스태미나 값<br>오버플로우분을 제외한, 이 사용자의 현재 스태미나 양입니다.<br>회복 간격과 회복량에 기반하여 시간 경과에 따라 자동으로 증가하며, maxValue까지 회복됩니다.<br>lastRecoveredAt로부터의 경과 시간을 사용하여 recoverSteps = elapsedMinutes / recoverIntervalMinutes 식으로 계산됩니다. |
| overflowValue | int |  | ✓ |  | 0 ~ 2147483646 | 오버플로우 값<br>통상의 최대값(maxValue)을 초과하여 저장되어 있는 스태미나량입니다.<br>StaminaModel의 isOverflow가 활성화된 경우에만 사용됩니다. 실효 스태미나의 합계는 value + overflowValue이며, maxCapacity가 상한입니다.<br>스태미나 소비 시 오버플로우분이 먼저 소비됩니다. |
| maxValue | int |  | ✓ |  | 1 ~ 2147483646 | 스태미나 최대값<br>StaminaModel로부터 결정되며, 옵션으로 플레이어의 GS2-Experience 랭크에 따라 MaxStaminaTable로 오버라이드되는 사용자별 스태미나 최대값입니다.<br>오버플로우가 비활성화된 경우 initialCapacity가 하한이 됩니다. 오버플로우가 활성화된 경우 maxCapacity가 상한이 됩니다.<br>자연 회복은 이 값에서 멈춥니다. |
| recoverIntervalMinutes | int |  |  |  | 1 ~ 2147483646 | 스태미나 회복 간격(분)<br>StaminaModel로부터 결정되며, 옵션으로 플레이어의 GS2-Experience 랭크에 따라 RecoverIntervalTable로 오버라이드되는 사용자별 회복 간격(분)입니다.<br>테이블이 설정되어 있지 않은 경우, 모델의 기본값인 recoverIntervalMinutes로 대체됩니다. |
| recoverValue | int |  |  |  | 1 ~ 2147483646 | 스태미나 회복량<br>StaminaModel로부터 결정되며, 옵션으로 플레이어의 GS2-Experience 랭크에 따라 RecoverValueTable로 오버라이드되는 사용자별 틱당 회복량입니다.<br>테이블이 설정되어 있지 않은 경우, 모델의 기본값인 recoverValue로 대체됩니다. |
| nextRecoverAt | long |  |  |  |  | 다음 회복 시각<br>다음 스태미나 회복 틱이 발생하는 Unix 타임스탬프(밀리초)입니다.<br>lastRecoveredAt + recoverIntervalMinutes * 60 * 1000으로 계산됩니다. 스태미나가 이미 maxValue인 경우, 이 필드는 설정되지 않을 수 있습니다. |

**관련 메서드:**
apply - 스태미나의 시간 경과에 따른 자연 회복을 적용한다
consume - 스태미나를 사용(소비)한다
getStamina - 특정 종류의 플레이어의 현재 스태미나를 취득한다
listStaminas - 플레이어의 스태미나 값 목록을 취득한다
setMaxValue - 플레이어 레벨에 따라 스태미나 상한을 업데이트한다
setRecoverInterval - 플레이어 레벨에 따라 스태미나 회복 간격을 업데이트한다
setRecoverValue - 플레이어 레벨에 따라 스태미나 회복량을 업데이트한다


---

### EzStaminaModel

스태미나 모델<br>

스태미나의 최대값, 회복 간격, 회복량과 같은 파라미터를 정의할 수 있습니다.<br>
GS2-Experience와 연동하여 최대값이나 회복량을 제어할 수도 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 스태미나 모델 이름<br>스태미나 모델 고유의 이름. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 128자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| recoverIntervalMinutes | int |  | ✓ |  | 0 ~ 2147483646 | 회복 간격(분)<br>스태미나 회복 틱의 간격(분 단위)입니다.<br>이 간격이 경과할 때마다 플레이어의 스태미나가 회복량만큼 증가합니다.<br>RecoverIntervalTable을 사용하여 GS2-Experience의 랭크별로 사용자 단위로 오버라이드할 수 있습니다.<br>0으로 설정하면 시간 기반 자동 회복이 비활성화됩니다. |
| recoverValue | int |  |  | 1 | 0 ~ 2147483646 | 회복량<br>회복 틱마다 회복되는 스태미나의 양입니다.<br>회복 간격이 경과할 때마다 최대값에 도달할 때까지 이 값만큼 스태미나가 증가합니다.<br>RecoverValueTable을 사용하여 GS2-Experience의 랭크별로 사용자 단위로 오버라이드할 수 있습니다.<br>기본값은 1입니다. |
| initialCapacity | int |  | ✓ |  | 0 ~ 2147483646 | 최대값의 초기값<br>모든 플레이어에 대한 기본 스태미나 최대값입니다.<br>오버플로우가 비활성화된 경우, 사용자별 최대값의 하한으로 작용합니다.<br>MaxStaminaTable을 사용하여 GS2-Experience의 랭크별로 사용자 단위로 오버라이드할 수 있습니다. |
| isOverflow | bool |  | ✓ |  |  | 오버플로우 가능 여부<br>아이템 사용 등의 수단으로 스태미나가 초기 최대값을 초과할 수 있는지 여부입니다.<br>활성화된 경우, 스태미나는 initialCapacity를 초과하여 maxCapacity까지 설정할 수 있습니다. 자연 회복은 일반적인 최대값에서 정지합니다.<br>비활성화된 경우, 사용자별 최대값은 initialCapacity 이상으로 제한됩니다. |
| maxCapacity | int | {isOverflow} == true | ✓※ |  | 0 ~ 2147483646 | 오버플로우 시 최대값<br>오버플로우 활성화 시 스태미나의 절대 상한값입니다.<br>오버플로우 상태에서도 스태미나는 이 값을 초과할 수 없습니다. isOverflow가 true인 경우에만 표시됩니다.<br>예를 들어 initialCapacity가 100, maxCapacity가 200인 경우, 아이템으로 스태미나를 200까지 늘릴 수 있지만 자연 회복은 100에서 정지합니다.<br><br>※ isOverflow이(가) true 이면 필수 |
| maxStaminaTable | [EzMaxStaminaTable](#ezmaxstaminatable) |  |  |  |  | 스태미나 최대값 테이블<br>플레이어의 GS2-Experience 랭크에 기반하여 스태미나 최대값을 동적으로 결정하는 MaxStaminaTable에 대한 참조입니다.<br>설정 시, 플레이어의 최대 스태미나는 현재 랭크 인덱스로 테이블에서 참조되며, initialCapacity를 오버라이드합니다.<br>미설정 시, 모든 플레이어가 동일한 initialCapacity를 최대값으로 공유합니다. |
| recoverIntervalTable | [EzRecoverIntervalTable](#ezrecoverintervaltable) |  |  |  |  | 회복 간격 테이블<br>플레이어의 GS2-Experience 랭크에 기반하여 회복 간격을 동적으로 결정하는 RecoverIntervalTable에 대한 참조입니다.<br>설정 시, 플레이어의 회복 간격은 현재 랭크 인덱스로 테이블에서 참조되며, recoverIntervalMinutes를 오버라이드합니다.<br>미설정 시, 모든 플레이어가 동일한 recoverIntervalMinutes를 공유합니다. |
| recoverValueTable | [EzRecoverValueTable](#ezrecovervaluetable) |  |  |  |  | 회복량 테이블<br>플레이어의 GS2-Experience 랭크에 기반하여 회복량을 동적으로 결정하는 RecoverValueTable에 대한 참조입니다.<br>설정 시, 플레이어의 회복량은 현재 랭크 인덱스로 테이블에서 참조되며, recoverValue를 오버라이드합니다.<br>미설정 시, 모든 플레이어가 동일한 recoverValue를 공유합니다. |

**관련 메서드:**
getStaminaModel - 특정 스태미나 종류의 정의를 취득한다
listStaminaModels - 스태미나 종류 정의 목록을 취득한다
apply - 스태미나의 시간 경과에 따른 자연 회복을 적용한다
consume - 스태미나를 사용(소비)한다
getStamina - 특정 종류의 플레이어의 현재 스태미나를 취득한다
setMaxValue - 플레이어 레벨에 따라 스태미나 상한을 업데이트한다
setRecoverInterval - 플레이어 레벨에 따라 스태미나 회복 간격을 업데이트한다
setRecoverValue - 플레이어 레벨에 따라 스태미나 회복량을 업데이트한다


---

### EzMaxStaminaTable

스태미나 최대값 테이블<br>

스태미나 최대값 테이블은 GS2-Experience의 랭크별로 스태미나의 최대값을 정의하는 엔티티입니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 스태미나 최대값 테이블 이름<br>스태미나 최대값 테이블 고유의 이름. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 128자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| experienceModelId | string |  | ✓ |  |  ~ 1024자 | 경험치 모델 ID<br>플레이어의 현재 랭크를 참조하기 위해 사용하는 GS2-Experience의 ExperienceModel의 GRN.<br>랭크 인덱스가 values 목록의 배열 인덱스로 사용되어, 사용자별 스태미나 최대값이 결정됩니다. |
| values | List&lt;int&gt; |  | ✓ |  | 1 ~ 1024 items | 랭크별 스태미나 최대값<br>플레이어의 GS2-Experience 랭크 인덱스로 색인되는 스태미나 최대값의 배열.<br>인덱스 i의 값이 랭크 i의 플레이어의 최대 스태미나로 사용됩니다. 배열 길이는 참조하는 ExperienceModel에서 정의된 랭크 수와 일치해야 합니다. |


**관련 모델:**
EzStaminaModel - 스태미나 모델



---

### EzRecoverIntervalTable

회복 간격 테이블<br>

회복 간격 테이블은 GS2-Experience의 랭크별로 스태미나의 회복 간격을 정의하는 엔티티입니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 회복 간격 테이블 이름<br>회복 간격 테이블 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 128자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| experienceModelId | string |  | ✓ |  |  ~ 1024자 | 경험치 모델 ID<br>플레이어의 현재 랭크를 참조하기 위해 사용하는 GS2-Experience의 ExperienceModel의 GRN.<br>랭크 인덱스가 values 목록의 배열 인덱스로 사용되어, 사용자별 회복 간격이 결정됩니다. |
| values | List&lt;int&gt; |  | ✓ |  | 1 ~ 1024 items | 랭크별 회복 간격<br>플레이어의 GS2-Experience 랭크 인덱스로 색인되는 회복 간격 값(분 단위)의 배열.<br>인덱스 i의 값이 랭크 i의 플레이어의 회복 간격으로 사용되며, 모델의 기본값 recoverIntervalMinutes를 오버라이드합니다. |


**관련 모델:**
EzStaminaModel - 스태미나 모델



---

### EzRecoverValueTable

스태미나 회복량 테이블<br>

스태미나 회복량 테이블은 GS2-Experience의 랭크별로 스태미나의 회복량을 정의하는 엔티티입니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 스태미나 회복량 테이블 이름<br>스태미나 회복량 테이블 고유의 이름. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 128자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| experienceModelId | string |  | ✓ |  |  ~ 1024자 | 경험치 모델 ID<br>플레이어의 현재 랭크를 참조하기 위해 사용하는 GS2-Experience의 ExperienceModel의 GRN.<br>랭크 인덱스가 values 목록의 배열 인덱스로 사용되어, 사용자별 회복량이 결정됩니다. |
| values | List&lt;int&gt; |  | ✓ |  | 1 ~ 1024 items | 랭크별 회복량<br>플레이어의 GS2-Experience 랭크 인덱스로 색인되는 회복량 값의 배열입니다.<br>인덱스 i의 값은 랭크 i의 플레이어에 대한 틱당 회복량으로 사용되며, 모델의 기본 recoverValue를 오버라이드합니다. |


**관련 모델:**
EzStaminaModel - 스태미나 모델



---

## 메서드

### getStaminaModel

특정 스태미나 종류의 정의를 취득한다<br>

특정 스태미나 종류의 정의를 취득합니다.<br>
응답에는 회복 간격(얼마나 자주 회복되는가), 회복량(1회당 얼마나 회복되는가), 최대 용량, 오버플로 설정이 포함됩니다.<br>
특정 스태미나 종류의 규칙을 표시하는 데 사용합니다. 예를 들어, 스태미나 상세 화면에서 "액션 스태미나: 5분마다 1회복, 최대 100"과 같이 표시하는 데 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| staminaName | string |  | ✓|  |  ~ 128자 | 스태미나 모델 이름<br>스태미나 모델 고유의 이름. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStaminaModel](#ezstaminamodel) | 스타미나 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->StaminaModel(
        "stamina-0001" // staminaName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).stamina_model(
        "stamina-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->StaminaModel(
        "stamina-0001" // staminaName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Stamina::Model::FStaminaModel> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).stamina_model(
        "stamina-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### listStaminaModels

스태미나 종류 정의 목록을 취득한다<br>

게임에 설정된 모든 스태미나 모델 정의를 취득합니다.<br>
스태미나 모델은 스태미나 종류별 규칙을 정의합니다. 시간 경과에 따른 회복 속도, 1회당 회복량, 최대 용량, 최대값을 초과하는 오버플로 가능 여부 등이 포함됩니다.<br>
예를 들어 "액션 스태미나"(5분마다 1회복, 최대 100)와 "아레나 티켓"(2시간마다 1회복, 최대 5)처럼 별도의 스태미나 모델을 준비할 수 있습니다.<br>
일부 스태미나 모델은 플레이어 레벨(GS2-Experience 경유)과 연동시킬 수도 있어, 레벨이 높은 플레이어일수록 스태미나 상한이 늘어나거나 회복이 빨라지도록 할 수 있습니다.<br>
도움말 화면이나 설정 화면에서 이용 가능한 스태미나의 종류와 규칙을 표시하는 데 사용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzStaminaModel&gt;](#ezstaminamodel) | 스타미나 모델의 리스트|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.StaminaModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.StaminaModels(
    );
    List<EzStaminaModel> items = new List<EzStaminaModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->StaminaModels(
    );
    TArray<Gs2::UE5::Stamina::Model::FEzStaminaModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminaModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminaModels(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminaModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminaModels(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeStaminaModels(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeStaminaModels(CallbackId);

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### apply

스태미나의 시간 경과에 따른 자연 회복을 적용한다<br>

마지막 업데이트로부터의 경과 시간을 기반으로 스태미나가 얼마나 회복되었는지 계산하여 현재 값에 반영합니다.<br>
스태미나는 시간 경과에 따라 자동으로 회복됩니다. 예를 들어, 회복 간격이 5분, 회복량이 1인 경우, 플레이어는 5분마다 스태미나가 1씩 최대값까지 회복됩니다.<br>
일반적으로 스태미나 값을 읽을 때 서버가 자동으로 회복을 계산합니다. 이 API를 명시적으로 호출하는 것은 최신 회복 값을 서버에 확실히 기록하고 싶은 경우입니다. 예를 들어, GS2 트랜잭션으로 관리되지 않는 액션 전에 스태미나가 충분한지 확인하는 경우에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| staminaName | string |  | ✓|  |  ~ 128자 | 스태미나 모델 이름<br>이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다.<br>사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStamina](#ezstamina) | 스타미나|
| staminaModel | [EzStaminaModel](#ezstaminamodel) | 스타미나 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var result = await domain.ApplyAsync(
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var future = domain.ApplyFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Stamina(
        "stamina-0001" // staminaName
    );
    const auto Future = Domain->Apply(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).me(game_session).stamina(
        "stamina-0001"
    )

var async_result = await domain.apply(
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### consume

스태미나를 사용(소비)한다<br>

플레이어의 현재 스태미나에서 지정한 양을 차감합니다.<br>
스태미나가 부족한 경우 오류가 발생하며, 소비는 이루어지지 않습니다. 스태미나가 0 미만이 되는 일은 없습니다.<br>
예를 들어, 퀘스트에 20 스태미나가 필요한데 플레이어가 15밖에 가지고 있지 않은 경우, 소비는 실패하며 "스태미나가 부족합니다"라는 메시지를 표시할 수 있습니다.<br>
주의: 대부분의 경우, 스태미나 소비는 GS2-Quest나 GS2-Showcase가 퀘스트 시작이나 구매 시 자동으로 처리합니다. 이 API를 직접 호출할 필요가 있는 것은 이러한 흐름 외에서 스태미나를 소비하고 싶은 경우뿐입니다. 예를 들어, 독자적인 미니 게임이나 트레이닝 기능에서 스태미나를 소비하는 경우에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| staminaName | string |  | ✓|  |  ~ 128자 | 스태미나 모델 이름<br>이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다.<br>사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| consumeValue | int |  | ✓|  | 1 ~ 2147483646 | 소비할 스타미나 양 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStamina](#ezstamina) | 스타미나|
| staminaModel | [EzStaminaModel](#ezstaminamodel) | 스타미나 모델|

#### Error

이 API에는 특별한 예외가 정의되어 있습니다.<br>
GS2-SDK for Game Engine에서는 게임 내에서 핸들링이 필요할 것으로 예상되는 에러를, 일반적인 예외에서 파생된 특수화된 예외로 제공하여 다루기 쉽게 하고 있습니다.<br>
일반적인 에러의 종류와 핸들링 방법은 [여기]() 문서를 참고해 주세요.

| 타입 | 베이스 클래스 | 설명 |
| --- | --- | --- |
| InsufficientException | BadRequestException | 스타미나 잔량이 부족합니다. |

#### 구현 예제




**Unity (UniTask)**
```csharp

try {
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var result = await domain.ConsumeAsync(
        consumeValue: 50
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Stamina.Exception.InsufficientException e) {
    // Insufficient remaining stamina.
}

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var future = domain.ConsumeFuture(
        consumeValue: 50
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Stamina.Exception.InsufficientException)
        {
            // Insufficient remaining stamina.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Stamina(
        "stamina-0001" // staminaName
    );
    const auto Future = Domain->Consume(
        50 // consumeValue
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Stamina::Error::FInsufficientError::Class))
        {
            // Insufficient remaining stamina.
        }
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).me(game_session).stamina(
        "stamina-0001"
    )

var async_result = await domain.consume(
    50 # consume_value
)
if async_result.error != null:
    if async_result.error is Gs2StaminaInsufficientException:
        # 스타미나 잔량이 부족합니다.
        pass
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### getStamina

특정 종류의 플레이어의 현재 스태미나를 취득한다<br>

특정 스태미나 종류에 대해 플레이어의 현재 스태미나 값을 모델 정의와 함께 취득합니다.<br>
응답에는 현재 값, 최대 용량, 회복 간격, 회복량, 오버플로 양이 포함됩니다.<br>
특정 스태미나 게이지를 표시하는 데 사용합니다. 예를 들어, 퀘스트 시작 화면에서 "액션 스태미나: 45/100"을 진행 바와 함께 표시하고, "전체 회복까지 4시간 35분"이라고 표시하는 데 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| staminaName | string |  | ✓|  |  ~ 128자 | 스태미나 모델 이름<br>이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다.<br>사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStamina](#ezstamina) | 스타미나|
| staminaModel | [EzStaminaModel](#ezstaminamodel) | 스타미나 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Stamina(
        "stamina-0001" // staminaName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).me(game_session).stamina(
        "stamina-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Stamina(
        "stamina-0001" // staminaName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Stamina::Model::FStamina> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).me(game_session).stamina(
        "stamina-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### listStaminas

플레이어의 스태미나 값 목록을 취득한다<br>

플레이어의 모든 스태미나 종류에 대한 현재 스태미나 값을 취득합니다.<br>
각 항목에는 스태미나 종류별 현재 값, 최대 용량, 회복 상태가 포함됩니다.<br>
스태미나 개요를 표시하는 데 사용합니다. 예를 들어, 홈 화면이나 상태 바에서 "액션 스태미나: 85/100(전체 회복까지 1시간 15분)", "아레나 티켓: 3/5(다음 회복까지 1시간 30분)"과 같이 표시하는 데 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| pageToken | string |  | |  |  ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int |  | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzStamina&gt;](#ezstamina) | 스태미나 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.StaminasAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Staminas(
    );
    List<EzStamina> items = new List<EzStamina>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Staminas(
    );
    TArray<Gs2::UE5::Stamina::Model::FEzStaminaPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminas(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminas(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminas(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminas(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeStaminas(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeStaminas(CallbackId);

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### setMaxValue

플레이어 레벨에 따라 스태미나 상한을 업데이트한다<br>

GS2-Experience의 플레이어 현재 레벨(랭크)을 기반으로 스태미나 최대 용량을 업데이트합니다.<br>
스태미나 모델에는 "스태미나 최대값 테이블"을 설정할 수 있으며, 플레이어 레벨과 스태미나 상한을 대응시킵니다. 예를 들어, 레벨 1=상한 50, 레벨 10=상한 80, 레벨 50=상한 150과 같이 설정할 수 있습니다.<br>
이 API를 호출하면 서명된 GS2-Experience 상태에서 플레이어의 현재 레벨을 읽어들여, 테이블에서 대응하는 스태미나 상한을 참조하여 업데이트합니다.<br>
플레이어가 레벨업한 후 스태미나 상한을 업데이트하는 데 사용합니다. 예를 들어, 레벨업 시 이 API를 호출하여 스태미나 상한을 80에서 85로 늘리는 등의 처리에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| staminaName | string |  | ✓|  |  ~ 128자 | 스태미나 모델 이름<br>이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다.<br>사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| keyId | string |  | | "grn:gs2:{region}:{ownerId}:key:default:key:default" |  ~ 1024자 | 암호화 키 GRN |
| signedStatusBody | string |  | ✓|  |  ~ 524288자 | 서명 대상인 GS2-Experience 스테이터스의 바디 |
| signedStatusSignature | string |  | ✓|  |  ~ 128자 | GS2-Experience 스테이터스의 서명 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStamina](#ezstamina) | 스타미나|
| old | [EzStamina](#ezstamina) | 스타미나|
| staminaModel | [EzStaminaModel](#ezstaminamodel) | 스타미나 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var result = await domain.SetMaxValueAsync(
        signedStatusBody: "statusBody...",
        signedStatusSignature: "statusSignature...",
        keyId: "key-0001"
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var future = domain.SetMaxValueFuture(
        signedStatusBody: "statusBody...",
        signedStatusSignature: "statusSignature...",
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Stamina(
        "stamina-0001" // staminaName
    );
    const auto Future = Domain->SetMaxValue(
        "statusBody...", // signedStatusBody
        "statusSignature...", // signedStatusSignature
        "key-0001" // keyId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).me(game_session).stamina(
        "stamina-0001"
    )

var async_result = await domain.set_max_value(
    "statusBody...", # signed_status_body
    "statusSignature...", # signed_status_signature
    "key-0001" # key_id
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### setRecoverInterval

플레이어 레벨에 따라 스태미나 회복 간격을 업데이트한다<br>

GS2-Experience의 플레이어 현재 레벨(랭크)을 기반으로 플레이어의 스태미나가 회복되는 빈도를 업데이트합니다.<br>
스태미나 모델에는 "회복 간격 테이블"을 설정할 수 있으며, 플레이어 레벨과 회복 간격(분)을 대응시킵니다. 예를 들어, 레벨 1=6분마다 회복, 레벨 20=5분마다, 레벨 50=3분마다와 같이 설정할 수 있습니다.<br>
플레이어가 레벨업한 후 스태미나 회복 빈도를 높이는 데 사용합니다. 예를 들어, 플레이어가 레벨 20에 도달하면 회복 간격이 6분에서 5분으로 단축되어, 스태미나가 더 자주 회복하게 됩니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| staminaName | string |  | ✓|  |  ~ 128자 | 스태미나 모델 이름<br>이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다.<br>사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| keyId | string |  | | "grn:gs2:{region}:{ownerId}:key:default:key:default" |  ~ 1024자 | 암호화 키 GRN |
| signedStatusBody | string |  | ✓|  |  ~ 524288자 | 서명 대상인 GS2-Experience 스테이터스의 바디 |
| signedStatusSignature | string |  | ✓|  |  ~ 128자 | GS2-Experience 스테이터스의 서명 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStamina](#ezstamina) | 스타미나|
| old | [EzStamina](#ezstamina) | 스타미나|
| staminaModel | [EzStaminaModel](#ezstaminamodel) | 스타미나 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var result = await domain.SetRecoverIntervalAsync(
        signedStatusBody: "statusBody...",
        signedStatusSignature: "statusSignature...",
        keyId: "key-0001"
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var future = domain.SetRecoverIntervalFuture(
        signedStatusBody: "statusBody...",
        signedStatusSignature: "statusSignature...",
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Stamina(
        "stamina-0001" // staminaName
    );
    const auto Future = Domain->SetRecoverInterval(
        "statusBody...", // signedStatusBody
        "statusSignature...", // signedStatusSignature
        "key-0001" // keyId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).me(game_session).stamina(
        "stamina-0001"
    )

var async_result = await domain.set_recover_interval(
    "statusBody...", # signed_status_body
    "statusSignature...", # signed_status_signature
    "key-0001" # key_id
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### setRecoverValue

플레이어 레벨에 따라 스태미나 회복량을 업데이트한다<br>

GS2-Experience의 플레이어 현재 레벨(랭크)을 기반으로 1회당 스태미나 회복량을 업데이트합니다.<br>
스태미나 모델에는 "회복량 테이블"을 설정할 수 있으며, 플레이어 레벨과 회복량을 대응시킵니다. 예를 들어, 레벨 1=1회복/간격, 레벨 20=2회복, 레벨 50=3회복과 같이 설정할 수 있습니다.<br>
플레이어가 레벨업한 후 스태미나 회복을 더 빠르게 하는 데 사용합니다. 예를 들어, 플레이어가 레벨 20에 도달하면 회복량이 1회복/간격에서 2회복/간격으로 늘어나, 스태미나가 2배 빠르게 회복하게 됩니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| staminaName | string |  | ✓|  |  ~ 128자 | 스태미나 모델 이름<br>이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다.<br>사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| keyId | string |  | | "grn:gs2:{region}:{ownerId}:key:default:key:default" |  ~ 1024자 | 암호화 키 GRN |
| signedStatusBody | string |  | ✓|  |  ~ 524288자 | 서명 대상인 GS2-Experience 스테이터스의 바디 |
| signedStatusSignature | string |  | ✓|  |  ~ 128자 | GS2-Experience 스테이터스의 서명 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzStamina](#ezstamina) | 스타미나|
| old | [EzStamina](#ezstamina) | 스타미나|
| staminaModel | [EzStaminaModel](#ezstaminamodel) | 스타미나 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var result = await domain.SetRecoverValueAsync(
        signedStatusBody: "statusBody...",
        signedStatusSignature: "statusSignature...",
        keyId: "key-0001"
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var future = domain.SetRecoverValueFuture(
        signedStatusBody: "statusBody...",
        signedStatusSignature: "statusSignature...",
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Stamina(
        "stamina-0001" // staminaName
    );
    const auto Future = Domain->SetRecoverValue(
        "statusBody...", // signedStatusBody
        "statusSignature...", // signedStatusSignature
        "key-0001" // keyId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```

**Godot**
```gdscript

var domain = ez.stamina.namespace_(
        "namespace-0001"
    ).me(game_session).stamina(
        "stamina-0001"
    )

var async_result = await domain.set_recover_value(
    "statusBody...", # signed_status_body
    "statusSignature...", # signed_status_signature
    "key-0001" # key_id
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---