API Reference of GS2-Experience SDK for Game Engine

Model

EzExperienceModel

Experience Model

An experience model is an entity that sets the threshold of experience required for rank advancement and for each default and maximum rank cap.

TypeRequireDefaultLimitationDescription
namestring~ 128 charsExperience Model Name
metadatastring~ 2048 charsmetadata
defaultExperiencelong0~ 9223372036854775805Initial Experience Value
defaultRankCaplong~ 9223372036854775805Initial value of rank cap
maxRankCaplong~ 9223372036854775805Maximum rank cap
rankThresholdEzThresholdrank-up threshold
acquireActionRatesList<EzAcquireActionRate>~ 100 itemsList of Remuneration addition table

EzThreshold

Rank Up Threshold

TypeRequireDefaultLimitationDescription
metadatastring~ 2048 charsmetadata
valuesList<long>1 ~ 1024 itemsList of Rank Up Experience Threshold

EzStatus

Status

Status is an entity that exists for each property ID. Holds the current experience and rank cap values.

Property ID is a status-specific ID and can be set to any value by the developer. In GS2, the itemset GRN of a GS2-Inventory or entry GRN of a GS2-Dictionary that has an experience value is followed by a It is recommended that the property ID be the value to which the suffix that serves as the experience value model is added.

TypeRequireDefaultLimitationDescription
experienceNamestring~ 128 charsExperience Model Name
propertyIdstring~ 1024 charsProperty ID
experienceValuelong0~ 9223372036854775805Cumulative experience gained
rankValuelong0~ 9223372036854775805Current Rank
rankCapValuelong~ 9223372036854775805Current Rank Cap
nextRankUpExperienceValuelong0~ 9223372036854775805Total amount of experience for the next rank up

EzAcquireAction

Acquire Action

TypeRequireDefaultLimitationDescription
actionenum [
"Gs2AdReward:AcquirePointByUserId",
"Gs2Dictionary:AddEntriesByUserId",
"Gs2Enchant:ReDrawBalanceParameterStatusByUserId",
"Gs2Enchant:SetBalanceParameterStatusByUserId",
"Gs2Enchant:ReDrawRarityParameterStatusByUserId",
"Gs2Enchant:AddRarityParameterStatusByUserId",
"Gs2Enchant:SetRarityParameterStatusByUserId",
"Gs2Enhance:DirectEnhanceByUserId",
"Gs2Enhance:UnleashByUserId",
"Gs2Enhance:CreateProgressByUserId",
"Gs2Exchange:ExchangeByUserId",
"Gs2Exchange:IncrementalExchangeByUserId",
"Gs2Exchange:UnlockIncrementalExchangeByUserId",
"Gs2Exchange:CreateAwaitByUserId",
"Gs2Exchange:SkipByUserId",
"Gs2Experience:AddExperienceByUserId",
"Gs2Experience:SetExperienceByUserId",
"Gs2Experience:AddRankCapByUserId",
"Gs2Experience:SetRankCapByUserId",
"Gs2Experience:MultiplyAcquireActionsByUserId",
"Gs2Formation:AddMoldCapacityByUserId",
"Gs2Formation:SetMoldCapacityByUserId",
"Gs2Formation:AcquireActionsToFormProperties",
"Gs2Formation:SetFormByUserId",
"Gs2Formation:AcquireActionsToPropertyFormProperties",
"Gs2Grade:AddGradeByUserId",
"Gs2Grade:ApplyRankCapByUserId",
"Gs2Grade:MultiplyAcquireActionsByUserId",
"Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
"Gs2Idle:SetMaximumIdleMinutesByUserId",
"Gs2Inbox:SendMessageByUserId",
"Gs2Inventory:AddCapacityByUserId",
"Gs2Inventory:SetCapacityByUserId",
"Gs2Inventory:AcquireItemSetByUserId",
"Gs2Inventory:AcquireItemSetWithGradeByUserId",
"Gs2Inventory:AddReferenceOfByUserId",
"Gs2Inventory:DeleteReferenceOfByUserId",
"Gs2Inventory:AcquireSimpleItemsByUserId",
"Gs2Inventory:SetSimpleItemsByUserId",
"Gs2Inventory:AcquireBigItemByUserId",
"Gs2Inventory:SetBigItemByUserId",
"Gs2JobQueue:PushByUserId",
"Gs2Limit:CountDownByUserId",
"Gs2Limit:DeleteCounterByUserId",
"Gs2LoginReward:DeleteReceiveStatusByUserId",
"Gs2LoginReward:UnmarkReceivedByUserId",
"Gs2Lottery:DrawByUserId",
"Gs2Lottery:ResetBoxByUserId",
"Gs2Mission:RevertReceiveByUserId",
"Gs2Mission:IncreaseCounterByUserId",
"Gs2Money:DepositByUserId",
"Gs2Money:RevertRecordReceipt",
"Gs2Quest:CreateProgressByUserId",
"Gs2Schedule:TriggerByUserId",
"Gs2SerialKey:RevertUseByUserId",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
]
~ 128 charsTypes of actions to be performed in the stamp sheet
requeststring~ 1048576 charsJSON of request

EzAcquireActionRate

Remuneration addition table master

You can adjust the amount of rewards according to the rank.

TypeRequireDefaultLimitationDescription
namestring~ 128 charsRemuneration addition table name
modeenum [
“double”,
“big”
]
“double”~ 128 charsRemuneration addition table type
ratesList<double>{mode} == “double”1 ~ 1000 itemsAmount added per rank (multiplier)
bigRatesList<string>{mode} == “big”1 ~ 1000 itemsAmount added per rank (multiplier)

Methods

getExperienceModel

Obtain experience and rank-up threshold model information

Get rank cap information and rank-up threshold information by specifying experience type name.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
experienceNamestring~ 128 charsExperience Model Name

Result

TypeDescription
itemEzExperienceModelExperience Model

Implementation Example

    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->ExperienceModel(
        "experience-0001" // experienceName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-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.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->ExperienceModel(
        "experience-0001" // experienceName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Experience::Model::FExperienceModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

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

listExperienceModels

Get list of experience and rank-up threshold model information

Obtain information on rank caps and rank advancement thresholds. Use this model data if you want to display in-game information such as the amount of experience required to gain before the next rank-up.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name

Result

TypeDescription
itemsList<EzExperienceModel>List of Experience Model

Implementation Example

    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.ExperienceModelsAsync(
    ).ToListAsync();
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.ExperienceModels(
    );
    List<EzExperienceModel> items = new List<EzExperienceModel>();
    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->Experience->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->ExperienceModels(
    );
    TArray<Gs2::UE5::Experience::Model::FEzExperienceModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeExperienceModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeExperienceModels(callbackId);
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.ExperienceModels(
    );
    List<EzExperienceModel> items = new List<EzExperienceModel>();
    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->Experience->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeExperienceModels(
        []() {
            // Called when an element of the list changes.
        }
    );

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

getStatus

Get status information by experience type and property ID

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
experienceNamestring~ 128 charsExperience Model Name
accessTokenstring~ 128 charsUser Id
propertyIdstring~ 1024 charsProperty ID

Result

TypeDescription
itemEzStatusStatus

Implementation Example

    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-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.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Experience::Model::FStatus> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

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

getStatusWithSignature

Get signature of status value

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
experienceNamestring~ 128 charsExperience Model Name
accessTokenstring~ 128 charsUser Id
propertyIdstring~ 1024 charsProperty ID
keyIdstring“grn:gs2:{region}:{ownerId}:key:default:key:default”~ 1024 charsencryption key GRN

Result

TypeDescription
itemEzStatusStatus
bodystringObject to be verified
signaturestringsignature

Implementation Example

    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var result = await domain.GetStatusWithSignatureAsync(
        keyId: "key-0001"
    );
    var item = await result.ModelAsync();
    var body = result.Body;
    var signature = result.Signature;
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var future = domain.GetStatusWithSignatureFuture(
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var body = future.Result.Body;
    var signature = future.Result.Signature;
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    const auto Future = Domain->GetStatusWithSignature(
        "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();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

listStatuses

Get list of status information

The experience type name is optional; if not specified, all status information belonging to the game player is retrieved.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
experienceNamestring~ 128 charsExperience Model Name
accessTokenstring~ 128 charsUser Id
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data acquired

Result

TypeDescription
itemsList<EzStatus>List of Status
nextPageTokenstringPage token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.StatusesAsync(
        experienceName: "character_ssr"
    ).ToListAsync();
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Statuses(
        experienceName: "character_ssr"
    );
    List<EzStatus> items = new List<EzStatus>();
    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->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Statuses(
        "character_ssr" // experienceName
    );
    TArray<Gs2::UE5::Experience::Model::FEzStatusPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeStatuses(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeStatuses(callbackId);
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Statuses(
        experienceName: "character_ssr"
    );
    List<EzStatus> items = new List<EzStatus>();
    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->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeStatuses(
        []() {
            // Called when an element of the list changes.
        }
    );

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