GS2-Experience

Growth is an essential element of game as a service. We provide experience and ranking features to implement a game cycle in which players can grow their characters and take on more challenging content with their grown characters.

Rank

GS2-Experience automatically calculates ranks from experience values. To do this, you need to define an experience value table that uses master data as rank-up thresholds. You can manage the rank-up thresholds in the experience model and hang property IDs with arbitrary values below them. For each property ID, the experience value is managed and the rank is determined based on the experience value.

Rank Cap

Ranks can be capped. If an experience value is gained while the rank cap is reached, the experience value is discarded.

The rank cap is initially set in the experience model, but can be raised for each property ID individually. This makes it possible to raise the experience cap when it is exceeded.

Reward addition table

The Experience Model allows you to configure acquireActionRates to adjust reward amounts based on rank. In addition to standard rates, you can define bigRates to handle values exceeding int64, enabling precise reward control even in games with high inflation.

Script Triggers

By configuring rankCapScript, changeExperienceScript, changeExperienceDone, changeRankScript, changeRankDone, changeRankCapScript, changeRankCapDone, and overflowExperienceScript in the namespace, you can invoke custom scripts before and after rank cap acquisition, experience point changes, rank changes, cap changes, and experience overflow. Scripts can be executed synchronously or asynchronously. Asynchronous execution supports external processing via GS2-Script or Amazon EventBridge.

The main configurable event triggers and script names are as follows:

• rankCapScript (Completion Notification: rankCapDone): Before and after rank cap acquisition
• changeExperienceScript (Completion Notification: changeExperienceDone): Before and after experience point changes
• changeRankScript (Completion Notification: changeRankDone): Before and after rank changes
• changeRankCapScript (Completion Notification: changeRankCapDone): Before and after rank cap changes
• overflowExperienceScript (Completion Notification: overflowExperienceDone): When experience points overflow

Master Data Operations

Registering master data allows you to configure data and behaviors available to microservices.

Master data types include the following:

• ExperienceModel: Rank thresholds and reward addition tables

Master data can be registered via the Management Console, reflected from GitHub, or integrated into workflows using GS2-Deploy for CI registration.

Buff-Based Adjustments

When integrated with GS2-Buff, buffs can adjust the experienceValue for actions like rankCapValue, AddExperienceByUserId, and SubExperienceByUserId. This enables flexible adjustments, such as temporarily increasing or decreasing acquisition rates or rank caps during events or campaigns.

Transaction Actions

GS2-Experience provides the following transaction actions:

• Verify Actions: Verify rank, verify rank cap
• Consume Actions: Subtract experience, subtract rank cap
• Acquire Actions: Add experience, set experience, add rank cap, set rank cap, apply reward multipliers based on rank

Transaction Actions

GS2-Experience provides the following transaction actions:

• Verify Actions: Verify rank, verify rank cap
• Consume Actions: Subtract experience, subtract rank cap
• Acquire Actions: Add experience, set experience, add rank cap, set rank cap, apply reward multipliers based on rank

By using “Add experience” as an acquire action, it is possible to perform processes such as directly increasing a character’s experience and leveling them up as a reward for purchasing a product at a shop or achieving a mission. Additionally, by setting “Add rank cap” as a reward, it is possible to automatically unlock level caps when specific conditions are met.

Example of implementation

Experience value addition

The game engine SDK does not handle experience value addition.

Please add experience as a quest completion reward via GS2-Quest or as an enhancement reward via GS2-Enhance.

Raising the Rank Cap

Raising the rank cap is not handled by the game engine SDK.

Please use GS2-Exchange to raise the rank cap as a reward for exchanging enhancement materials or duplicate copies of the same character.

Get a list of experience values

    var items = await gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).StatusesAsync(
    ).ToListAsync();

    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Statuses( // experienceName
    );
    TArray<Gs2::UE5::Experience::Model::FEzStatusPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Get an experience value

    var item = await gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    ).ModelAsync();

    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    const auto item = Domain.Model();

Obtaining a Possessive Certification Signature

When interfacing with other microservices within GS2, you may be asked for data that guarantees that the rank or experience in GS2-Experience is indeed correct.

For example, suppose that GS2-Experience manages the player’s rank, and GS2-Stamina determines the maximum stamina value according to that rank. GS2-Stamina will request that the rank be specified along with the possession certificate signature.

This eliminates the need for GS2-Stamina to communicate with GS2-Experience behind the scenes to determine if the player has really reached that rank.

    var result = await gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    ).GetStatusWithSignatureAsync(
        keyId: "grn:gs2:{region}:{yourOwnerId}:key:namespace-0001:key:key-0001"
    );

    var body = result.Body;
    var signature = result.Signature;

    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    const auto Future = Domain->GetStatusWithSignature(
        "key-0001"
    );
    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 false;
    const auto Result = Future2->GetTask().Result();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

Detailed Reference