API Reference of GS2-Stamina SDK for Game Engine

Model

EzStaminaModel

Stamina Model

Parameters such as the maximum value of stamina, recovery interval, and amount of recovery can be defined. You can also control the maximum value and the amount of recovery in conjunction with GS2-Experience.

	Type	Require	Default	Limitation	Description
name	string	✓		~ 128 chars	Stamina Model Name
metadata	string			~ 128 chars	metadata
recoverIntervalMinutes	int	✓		~ 2147483646	Speed at which stamina is regained (minutes)
recoverValue	int	✓	1	~ 2147483646	Amount of recovery after a period of time
initialCapacity	int	✓		~ 2147483646	Initial maximum value of stamina
isOverflow	bool	✓			Recover beyond the maximum
maxCapacity	int	{isOverflow}		~ 2147483646	Maximum value in overflow situation
maxStaminaTable	EzMaxStaminaTable				Maximum Stamina Table used when working with GS2-Experience
recoverIntervalTable	EzRecoverIntervalTable				Recovery interval table used when working with GS2-Experience
recoverValueTable	EzRecoverValueTable				Recovery amount table used when working with GS2-Experience

EzMaxStaminaTable

Maximum Stamina Table

This entity defines the maximum value of stamina for each rank of GS2-Experience.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Maximum Stamina Value Table Name
metadata	string		~ 128 chars	metadata
experienceModelId	string	✓	~ 1024 chars	Experience Model GRN
values	List<int>	✓	1 ~ 1024 items	List of Maximum Staminas

EzRecoverIntervalTable

Stamina Recovery Interval Table

This entity defines the stamina recovery interval for each rank of GS2-Experience.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Stamina recovery interval table name
metadata	string		~ 128 chars	metadata
experienceModelId	string	✓	~ 1024 chars	Experience Model GRN
values	List<int>	✓	1 ~ 1024 items	Stamina recovery interval table for each rank

EzRecoverValueTable

Stamina Recovery Value Table

This entity defines the amount of stamina recovery for each rank of GS2-Experience.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Stamina recovery value table name
metadata	string		~ 128 chars	metadata
experienceModelId	string	✓	~ 1024 chars	Experience Model GRN
values	List<int>	✓	1 ~ 1024 items	Stamina recovery value table for each rank

EzStamina

Stamina

Stamina is a point that is recovered over time in real time. Generally, this stamina is used to limit the number of times a player can play a game per day and to allow the game provider to control the speed of game progression by allowing players to consume stamina to play the game.

	Type	Require	Limitation	Description
staminaName	string	✓	~ 128 chars	Stamina Model Name
value	int	✓	~ 2147483646	Stamina value
overflowValue	int	✓	~ 2147483646	Stamina value stored in excess of the maximum stamina value
maxValue	int	✓	1 ~ 2147483646	Maximum Stamina
recoverIntervalMinutes	int		1 ~ 2147483646	Stamina recovery interval (minutes)
recoverValue	int		1 ~ 2147483646	Stamina recovery value
nextRecoverAt	long			Next time stamina is restored (Unix time unit:milliseconds)

Methods

getStaminaModel

Get Stamina Model

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
staminaName	string	✓		~ 128 chars	Stamina Model Name

Result

	Type	Description
item	EzStaminaModel	Stamina Model

Implementation Example

    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;
    }

Value change event handling

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).StaminaModel(
        staminaName: "stamina-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Stamina::Model::FStaminaModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listStaminaModels

Get list of stamina models

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name

Result

	Type	Description
items	List<EzStaminaModel>	List of Stamina Models

Implementation Example

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

Value change event handling

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeStaminaModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeStaminaModels(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeStaminaModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeStaminaModels(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

consume

Consumes stamina

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
staminaName	string	✓	~ 128 chars	Stamina Model Name
accessToken	string	✓	~ 128 chars	User Id
consumeValue	int	✓	1 ~ 2147483646	Amount of stamina consumed

Result

	Type	Description
item	EzStamina	Stamina
staminaModel	EzStaminaModel	Stamina Model

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type	Base Type	Description
InsufficientException	BadRequestException	Insufficient remaining stamina.

Implementation Example

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.Insufficient 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;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

getStamina

Get current stamina

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
staminaName	string	✓	~ 128 chars	Stamina Model Name
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
item	EzStamina	Stamina
staminaModel	EzStaminaModel	Stamina Model

Implementation Example

    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;
    }

Value change event handling

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Stamina(
        staminaName: "stamina-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Stamina::Model::FStamina> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listStaminas

Get current stamina

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzStamina>	List of Staminas
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

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

Value change event handling

    var domain = gs2.Stamina.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeStaminas(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeStaminas(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeStaminas(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeStaminas(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

setMaxValue

Update maximum using GS2-Experience status

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
staminaName	string	✓		~ 128 chars	Stamina Model Name
accessToken	string	✓		~ 128 chars	User Id
keyId	string	✓	“grn:gs2:{region}:{ownerId}:key:default:key:default”	~ 1024 chars	encryption key GRN
signedStatusBody	string	✓		~ 1048576 chars	GS2-Experience status body to be signed
signedStatusSignature	string	✓		~ 128 chars	GS2-Experience Status Signature

Result

	Type	Description
item	EzStamina	Stamina
old	EzStamina	Stamina
staminaModel	EzStaminaModel	Stamina Model

Implementation Example

    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;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

setRecoverInterval

Update recover interval using GS2-Experience status

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
staminaName	string	✓		~ 128 chars	Stamina Model Name
accessToken	string	✓		~ 128 chars	User Id
keyId	string	✓	“grn:gs2:{region}:{ownerId}:key:default:key:default”	~ 1024 chars	encryption key GRN
signedStatusBody	string	✓		~ 1048576 chars	GS2-Experience status body to be signed
signedStatusSignature	string	✓		~ 128 chars	GS2-Experience Status Signature

Result

	Type	Description
item	EzStamina	Stamina
old	EzStamina	Stamina
staminaModel	EzStaminaModel	Stamina Model

Implementation Example

    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;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

setRecoverValue

Update recover value using GS2-Experience status

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
staminaName	string	✓		~ 128 chars	Stamina Model Name
accessToken	string	✓		~ 128 chars	User Id
keyId	string	✓	“grn:gs2:{region}:{ownerId}:key:default:key:default”	~ 1024 chars	encryption key GRN
signedStatusBody	string	✓		~ 1048576 chars	GS2-Experience status body to be signed
signedStatusSignature	string	✓		~ 128 chars	GS2-Experience Status Signature

Result

	Type	Description
item	EzStamina	Stamina
old	EzStamina	Stamina
staminaModel	EzStaminaModel	Stamina Model

Implementation Example

    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;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();