GS2-Enchant

This service provides a feature for adding unique random parameters to equipment and characters. It can be used to implement expressions such as additional stats on weapons in an RPG, individual values granted to cards obtained from gacha, or additional effects on equipment in hack-and-slash games — i.e., representations where “even the same item has different performance for each individual instance”.

Two types of random parameters are available:

• Balance parameter
• Rarity parameter

graph TD
  Item["Equipment, character, etc.<br/>(identified by propertyId)"] --> Choose{Parameter type}
  Choose -- Distribute a total amount --> Balance["Balance Parameter<br/>e.g. ATK 60 / DEF 40"]
  Choose -- Grant multiple by probability --> Rarity["Rarity Parameter<br/>e.g. Critical Rate +5%, HP +100"]
  Balance --> ReDraw1["Re-draw / Set value directly"]
  Rarity --> ReDraw2["Re-draw / Add / Set value directly"]

Random parameters are managed using propertyId, the “identifier of the target item”, as a key. By specifying values such as a GS2-Inventory item instance ID or a GS2-Formation form identifier as propertyId, parameters can be associated with each individual piece of equipment.

Balance parameter

A balance parameter randomly distributes multiple prepared parameters within a fixed total amount. For example, if two parameters — attack and defense — are prepared and the total is set to 100, and attack is drawn at 60, then defense becomes 40.

Re-drawing

Balance parameters can be re-drawn. Some parameter values can be fixed when re-drawing. By fixing some parameters, you can provide players with a means of efficiently optimizing their parameters.

Initial values

You can decide whether the initial values of balance parameters are random or use the average value.

Setting values directly

Balance parameters can also be set directly to arbitrary values without a draw, via the management console or API (transaction action). This makes it possible to distribute equipment with fixed stats as a specific event reward.

Rarity parameter

Unlike balance parameters, which distribute values across a fixed set of parameters, rarity parameters can be used in cases where additional parameters are granted to equipment or skills with a certain probability.

In the master data, you first set the draw probability for the number of parameters to be granted. Then, set the type and probability of each parameter to be granted. This allows additional parameters to be granted based on probability.

Each parameter (RarityParameterValueModel) can be configured with resourceName/resourceValue to express which resource the granted result references and by how much.

Re-drawing

Granted parameters can be re-drawn; when re-drawn, only the types of granted parameters change, not the number. As with balance parameters, some of the parameters being re-drawn can be fixed.

Adding

Rarity parameters can be added later. When adding, existing parameters remain unchanged, and the specified number of additional parameters can be added.

Setting values directly

Rarity parameters can also have the types of granted parameters and their values set directly, via the management console or API (transaction action). As with balance parameters, this enables distribution of items with guaranteed specific performance.

Transaction Actions

GS2-Enchant provides the following transaction actions. These can be used to manipulate parameters through quest rewards, shop purchases, and so on.

Verify actions

Acquire actions

Master data operations

Registering master data allows you to configure data and behaviors available to the microservice.

Master data types include:

• BalanceParameterModel: Parameter distribution settings
• RarityParameterModel: Granted parameters and probability settings

Below is an example of master data JSON:

{
  "version": "2023-04-27",
  "balanceParameterModels": [
    {
      "name": "balance-0001",
      "metadata": "weapon",
      "totalValue": 100,
      "initialValueStrategy": "average",
      "parameters": [
        { "name": "attack", "metadata": "ATK" },
        { "name": "defense", "metadata": "DEF" }
      ]
    }
  ],
  "rarityParameterModels": [
    {
      "name": "rarity-0001",
      "metadata": "weapon",
      "maximumParameterCount": 4,
      "parameterCounts": [
        { "count": 1, "weight": 70 },
        { "count": 2, "weight": 25 },
        { "count": 3, "weight": 5 }
      ],
      "parameters": [
        { "name": "critical", "weight": 50, "resourceName": "critical", "resourceValue": 5 },
        { "name": "hp", "weight": 50, "resourceName": "hp", "resourceValue": 100 }
      ]
    }
  ]
}

Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs.

Example implementation

Balance Parameter

Parameter initialization / retrieval

When parameter information is retrieved for the first time, the parameter drawing process is created.

    var item = await gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BalanceParameterStatus(
        parameterName: "balance-0001",
        propertyId: "property-0001"
    ).ModelAsync();

    const auto item = Gs2->Enchant->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->BalanceParameterStatus(
        "balance-0001", // parameterName
        "property-0001" // propertyId
    ).Model();

Referencing parameter values

From ParameterValues of the EzBalanceParameterStatus obtained with ModelAsync, you can retrieve each parameter name and its current value.

    foreach (var parameterValue in item.ParameterValues) {
        Debug.Log($"{parameterValue.Name} = {parameterValue.Value}");
    }

    for (auto ParameterValue : *item->ParameterValues) {
        UE_LOG(LogTemp, Log, TEXT("%s = %lld"), *ParameterValue->Name, ParameterValue->Value);
    }

Parameter re-drawing

Re-drawing cannot be handled by the SDK for game engines. From within the game, perform re-drawing by executing a transaction action such as Gs2Enchant:ReDrawBalanceParameterStatusByUserId via GS2-Distributor.

Rarity Parameter

Parameter initialization / retrieval

When parameter information is retrieved for the first time, the parameter drawing process is created.

    var item = await gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RarityParameterStatus(
        parameterName: "rarity-0001",
        propertyId: "property-0001"
    ).ModelAsync();

    const auto item = Gs2->Enchant->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->RarityParameterStatus(
        "rarity-0001", // parameterName
        "property-0001" // propertyId
    ).Model();

Parameter verification

You can have the server verify whether a rarity parameter has been granted, or whether a specific number has been granted. This is useful for condition checks such as “only allow equipment with a specific parameter” during gacha or enhancement processes.

    var domain = await gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RarityParameterStatus(
        parameterName: "rarity-0001",
        propertyId: "property-0001"
    ).VerifyRarityParameterStatusAsync(
        verifyType: "have",
        parameterValueName: "critical",
        parameterCount: 1
    );

    const auto Future = Gs2->Enchant->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->RarityParameterStatus(
        "rarity-0001", // parameterName
        "property-0001" // propertyId
    )->VerifyRarityParameterStatus(
        "have", // verifyType
        "critical", // parameterValueName
        1 // parameterCount
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;

Parameter re-drawing

Re-drawing cannot be handled by the SDK for game engines. From within the game, perform re-drawing by executing a transaction action such as Gs2Enchant:ReDrawRarityParameterStatusByUserId via GS2-Distributor.

Adding parameters

Adding parameters cannot be handled by the SDK for game engines. Add them by executing Gs2Enchant:AddRarityParameterStatusByUserId via GS2-Distributor.

Detailed Reference