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

# GS2-Enchant

エンチャント・ランダムパラメーター機能



装備やキャラクターにユニークなランダムパラメーターを付与する機能を実現します。
RPG における武器の追加ステータス、ガチャで入手したカードに付与される個体値、ハクスラ系における装備の追加効果など、「同じアイテムでも個体ごとに性能が異なる」表現を実装する際に活用できます。

ランダムパラメーターには2種類用意しています。

- バランスパラメーター
- レアリティパラメーター

```mermaid
graph TD
  Item["装備・キャラクターなど<br/>(propertyId で識別)"] --> Choose{パラメーター種別}
  Choose -- 総量を分配 --> Balance["バランスパラメーター<br/>例: 攻撃力60/防御力40"]
  Choose -- 確率で複数付与 --> Rarity["レアリティパラメーター<br/>例: クリティカル率+5%、HP+100"]
  Balance --> ReDraw1["再抽選 / 値の直接設定"]
  Rarity --> ReDraw2["再抽選 / 追加 / 値の直接設定"]
```

ランダムパラメーターは「対象アイテムの識別子」となる `propertyId` をキーとして管理されます。
`propertyId` には GS2-Inventory のアイテムインスタンスIDや、GS2-Formation のフォーム識別子などを指定することで、装備個体ごとにパラメーターを紐付けることができます。

## バランスパラメーター

バランスパラメーターは用意された複数のパラメーターを定められた総量でランダムに分配します。
たとえば、攻撃力と防御力の2つのパラメーターを用意し、総量に100を設定した場合に攻撃力が60で抽選されると防御力は40になります。

| マスター項目 | 説明 |
| --- | --- |
| `name` | バランスパラメーターモデル名 |
| `totalValue` | パラメーター値の合計総量 |
| `initialValueStrategy` | 初期値の決定方法（`average`：平均値 / `random`：ランダム） |
| `parameters` | 分配対象となるパラメーターの一覧 |

### 再抽選

バランスパラメーターは再抽選が可能です。
再抽選を行う際に、一部パラメーターの値を固定することができます。
パラメーターを一部固定することで、プレイヤーがパラメーターの最適化を効率的に行う手段を提供することができます。

### 初期値

バランスパラメーターの初期値はランダム値にするか、平均値にするかを定めることが可能です。

### 値の直接設定

バランスパラメーターには、管理画面や API（トランザクションアクション）を通じて、抽選を経ずに任意の値を直接設定することも可能です。これにより、特定のイベント報酬として固定のステータスを持つ装備を配布するといった運用が可能になります。

## レアリティパラメーター

レアリティパラメーターは、バランスパラメーターのように一定のパラメーターに値を分配するのではなく、
装備やスキルに一定確率で追加パラメーターを付与するようなケースで利用できます。

マスターデータには、まずパラメーターを付与する個数の抽選確率を設定します。
次に、付与するパラメーターの種類と確率を設定します。
これで、確率に基づいて追加パラメータを付与することが可能となります。

| マスター項目 | 説明 |
| --- | --- |
| `name` | レアリティパラメーターモデル名 |
| `maximumParameterCount` | 1つの propertyId に付与できる最大パラメーター数 |
| `parameterCounts` | 付与する個数とその重み（重み付き抽選） |
| `parameters` | 個別のパラメーターと、付与確率となる重み |

各パラメーター（`RarityParameterValueModel`）には、`resourceName`/`resourceValue` を設定することができ、付与された結果として何のリソースをどれだけ参照しているかを表現できます。

### 再抽選

付与されたパラメーターは再抽選が可能で、再抽選の際には付与されたパラメーターの種類のみ変動し、数は変わりません。
バランスパラメーターと同様に、再抽選するパラメーターのうち一部のパラメーターを固定することができます。

### 追加

レアリティパラメーターは、後から追加することができます。
追加する際には、すでにあるパラメーターは変更せず、指定された個数のパラメーターを追加できます。

### 値の直接設定

レアリティパラメーターには、管理画面や API（トランザクションアクション）を通じて、付与されているパラメーターの種類やその値を直接設定することも可能です。これにより、バランスパラメーターと同様に、特定の性能が保証されたアイテムの配布などが可能になります。

## トランザクションアクション

GS2-Enchant では以下のトランザクションアクションを提供しています。これらを利用することで、クエスト報酬やショップ購入などを通じてパラメーターの操作を行えます。

### 検証アクション

| アクション | 用途 |
| --- | --- |
| `Gs2Enchant:VerifyRarityParameterStatus` | レアリティパラメーターの所持状態（保持している/していない）や個数を検証します。`verifyType` に `havent`／`have`／`count` を指定して動作を切り替えます。 |

### 入手アクション

| アクション | 用途 |
| --- | --- |
| `Gs2Enchant:ReDrawBalanceParameterStatusByUserId` | バランスパラメーターを再抽選します。固定したいパラメーター名を `fixedParameterNames` に指定できます。 |
| `Gs2Enchant:SetBalanceParameterStatusByUserId` | バランスパラメーターを抽選を経ずに直接書き換えます。 |
| `Gs2Enchant:ReDrawRarityParameterStatusByUserId` | レアリティパラメーターを再抽選します。固定したいパラメーター名を指定できます。 |
| `Gs2Enchant:AddRarityParameterStatusByUserId` | 既存のレアリティパラメーターを残したまま、指定した個数の追加抽選を行います。 |
| `Gs2Enchant:SetRarityParameterStatusByUserId` | レアリティパラメーターを抽選を経ずに直接書き換えます。 |

## マスターデータ運用
マスターデータを登録することでマイクロサービスで利用可能なデータや振る舞いを設定できます。

マスターデータの種類には以下があります。

- `BalanceParameterModel`: パラメーターの分配設定
- `RarityParameterModel`: 付与パラメーターと確率の設定

以下はマスターデータ 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 }
      ]
    }
  ]
}
```

マスターデータの登録はマネージメントコンソールから登録する他、GitHubからデータを反映したり、GS2-Deployを使ってCIから登録するようなワークフローを組むことが可能です。

## 実装例

### バランスパラメーター

#### パラメーターの初期化/取得

初めてパラメーターの情報を取得した際にパラメーターの抽選処理が作成されます。



**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();
```


#### パラメーター値の参照

`ModelAsync` で取得した `EzBalanceParameterStatus` の `ParameterValues` から、各パラメーター名と現在の値を取得できます。



**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);
    }
```


#### パラメーターの再抽選

再抽選はゲームエンジン用の SDK では処理できません。
ゲーム内からは GS2-Distributor 経由で `Gs2Enchant:ReDrawBalanceParameterStatusByUserId` などのトランザクションアクションを実行することで再抽選を行ってください。

### レアリティパラメーター

#### パラメーターの初期化/取得

初めてパラメーターの情報を取得した際にパラメーターの抽選処理が作成されます。



**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();
```


#### パラメーターの検証

レアリティパラメーターが付与されているか、もしくは特定の個数が付与されているかをサーバーに検証させることができます。
ガチャや強化処理で「特定のパラメーターを持つ装備のみを許可する」といった条件チェックに利用できます。



**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;
```


#### パラメーターの再抽選

再抽選はゲームエンジン用の SDK では処理できません。
ゲーム内からは GS2-Distributor 経由で `Gs2Enchant:ReDrawRarityParameterStatusByUserId` などのトランザクションアクションを実行することで再抽選を行ってください。

### パラメーターの追加

パラメーターの追加はゲームエンジン用の SDK では処理できません。
GS2-Distributor 経由で `Gs2Enchant:AddRarityParameterStatusByUserId` を実行することで追加してください。

## 詳細なリファレンス

[GS2-Enchant API リファレンス](../../api_reference/enchant)