Documentation index for AI agents

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

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

모델

EzStamina

스태미나

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

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

EzStaminaModel

스태미나 모델

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

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

※ isOverflow이(가) true 이면 필수
maxStaminaTableEzMaxStaminaTable스태미나 최대값 테이블
플레이어의 GS2-Experience 랭크에 기반하여 스태미나 최대값을 동적으로 결정하는 MaxStaminaTable에 대한 참조입니다.
설정 시, 플레이어의 최대 스태미나는 현재 랭크 인덱스로 테이블에서 참조되며, initialCapacity를 오버라이드합니다.
미설정 시, 모든 플레이어가 동일한 initialCapacity를 최대값으로 공유합니다.
recoverIntervalTableEzRecoverIntervalTable회복 간격 테이블
플레이어의 GS2-Experience 랭크에 기반하여 회복 간격을 동적으로 결정하는 RecoverIntervalTable에 대한 참조입니다.
설정 시, 플레이어의 회복 간격은 현재 랭크 인덱스로 테이블에서 참조되며, recoverIntervalMinutes를 오버라이드합니다.
미설정 시, 모든 플레이어가 동일한 recoverIntervalMinutes를 공유합니다.
recoverValueTableEzRecoverValueTable회복량 테이블
플레이어의 GS2-Experience 랭크에 기반하여 회복량을 동적으로 결정하는 RecoverValueTable에 대한 참조입니다.
설정 시, 플레이어의 회복량은 현재 랭크 인덱스로 테이블에서 참조되며, recoverValue를 오버라이드합니다.
미설정 시, 모든 플레이어가 동일한 recoverValue를 공유합니다.

EzMaxStaminaTable

스태미나 최대값 테이블

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

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

EzRecoverIntervalTable

회복 간격 테이블

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

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

EzRecoverValueTable

스태미나 회복량 테이블

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

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

메서드

getStaminaModel

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

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

Request

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

Result

타입설명
itemEzStaminaModel스타미나 모델

구현 예제

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    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;
    }
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
값 변경 이벤트 핸들링
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    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);
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)

listStaminaModels

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

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

Request

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

Result

타입설명
itemsList<EzStaminaModel>스타미나 모델의 리스트

구현 예제

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.StaminaModelsAsync(
    ).ToListAsync();
    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;
        }
    }
    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());
    }
값 변경 이벤트 핸들링
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminaModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminaModels(callbackId);
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminaModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminaModels(callbackId);
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeStaminaModels(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

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

apply

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

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

Request

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

Result

타입설명
itemEzStamina스타미나
staminaModelEzStaminaModel스타미나 모델

구현 예제

    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();
    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;
    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();
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

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

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

Request

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

Result

타입설명
itemEzStamina스타미나
staminaModelEzStaminaModel스타미나 모델

Error

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

타입베이스 클래스설명
InsufficientExceptionBadRequestException스타미나 잔량이 부족합니다.

구현 예제

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.
}
    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;
    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();
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

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

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

Request

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

Result

타입설명
itemEzStamina스타미나
staminaModelEzStaminaModel스타미나 모델

구현 예제

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    var item = await domain.ModelAsync();
    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;
    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;
    }
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
값 변경 이벤트 핸들링
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    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);
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)

listStaminas

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

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

Request

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

Result

타입설명
itemsList<EzStamina>스태미나 목록
nextPageTokenstring목록의 나머지를 취득하기 위한 페이지 토큰

구현 예제

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.StaminasAsync(
    ).ToListAsync();
    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;
        }
    }
    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());
    }
값 변경 이벤트 핸들링
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminas(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminas(callbackId);
    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStaminas(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStaminas(callbackId);
    const auto Domain = Gs2->Stamina->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeStaminas(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

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

setMaxValue

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

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

Request

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

Result

타입설명
itemEzStamina스타미나
oldEzStamina스타미나
staminaModelEzStaminaModel스타미나 모델

구현 예제

    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();
    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;
    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();
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

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

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

Request

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

Result

타입설명
itemEzStamina스타미나
oldEzStamina스타미나
staminaModelEzStaminaModel스타미나 모델

구현 예제

    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();
    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;
    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();
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

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

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

Request

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

Result

타입설명
itemEzStamina스타미나
oldEzStamina스타미나
staminaModelEzStaminaModel스타미나 모델

구현 예제

    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();
    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;
    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();
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