GS2-Experience

Experience points and rank features

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.

Example of implementation

Experience value addition

The game engine SDK does not handle experience accumulation.

Please add experience as a reward for completing GS2 quests or as a reward for upgrading GS2-Enhance.

Raising the Rank Cap

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

Please use GS2-Exchange to raise the rank cap as a reward for enhancement materials or exchange for 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 a 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();

Detailed Reference