> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Enchant

Enchantment(random parameter) feature



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

```mermaid
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.

| Master item | Description |
| --- | --- |
| `name` | Balance parameter model name |
| `totalValue` | Total amount distributed across parameter values |
| `initialValueStrategy` | How the initial value is determined (`average`: average value / `random`: random) |
| `parameters` | List of parameters that are the distribution targets |

### 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.

| Master item | Description |
| --- | --- |
| `name` | Rarity parameter model name |
| `maximumParameterCount` | Maximum number of parameters that can be granted to a single propertyId |
| `parameterCounts` | The number granted and its weight (weighted draw) |
| `parameters` | Individual parameters and the weight that becomes the probability of being granted |

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

| Action | Use |
| --- | --- |
| `Gs2Enchant:VerifyRarityParameterStatus` | Verifies the possession state of a rarity parameter (held / not held) or count. Switch the behavior by specifying `havent`, `have`, or `count` for `verifyType`. |

### Acquire actions

| Action | Use |
| --- | --- |
| `Gs2Enchant:ReDrawBalanceParameterStatusByUserId` | Re-draws a balance parameter. The names of parameters to be fixed can be specified in `fixedParameterNames`. |
| `Gs2Enchant:SetBalanceParameterStatusByUserId` | Directly overwrites a balance parameter without a draw. |
| `Gs2Enchant:ReDrawRarityParameterStatusByUserId` | Re-draws a rarity parameter. The names of parameters to be fixed can be specified. |
| `Gs2Enchant:AddRarityParameterStatusByUserId` | Performs an additional draw of the specified count while keeping existing rarity parameters. |
| `Gs2Enchant:SetRarityParameterStatusByUserId` | Directly overwrites rarity parameters without a draw. |

## 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:

```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.



**Unity**
```csharp

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

    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.



**Unity**
```csharp

    foreach (var parameterValue in item.ParameterValues) {
        Debug.Log($"{parameterValue.Name} = {parameterValue.Value}");
    }
```
**Unreal Engine**
```cpp

    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.



**Unity**
```csharp

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

    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.



**Unity**
```csharp

    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
    );
```
**Unreal Engine**
```cpp

    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

[GS2-Enchant API Reference](../../api_reference/enchant)