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

# GS2-Enhance トランザクションアクション

検証/消費/入手の各トランザクションアクションの仕様




## アクションの組み合わせと同時実行

すべてのサービスに共通する前提は [トランザクションアクションの組み合わせ]() にまとめています。先にそちらを読んでください。この節の残りは GS2-Enhance 固有の内容です。

GS2-Enhance のトランザクションアクションは、進行を介するものと介さないものの 2 つに分かれます。進行はネームスペースとユーザーの組で決まり、1 ユーザーにつき 1 つだけ存在します。

操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界
--- | --- | --- | ---
進行の作成<br>`CreateProgressByUserId` | 1 件に統合される | 失敗する | ネームスペース・ユーザー
進行の破棄<br>`DeleteProgressByUserId` | 1 件に統合される | 失敗する | ネームスペース・ユーザー
直接強化・解放<br>`DirectEnhanceByUserId` `UnleashByUserId` | 強化レート・対象・素材がすべて同じなら 1 件に統合される。1 つでも違えばそれぞれ実行される | 進行を触らない | ネームスペース・ユーザー・強化レート・対象アイテム・素材

作成と破棄は行が違い、境界が同じです。1 つのトランザクションに入れることはできません。

進行の作成は、すでに別の進行があると失敗します。これによって同時に進められる強化が 1 つに保たれています。この判定はトランザクション開始時点の状態に対して行われるため、衝突の問題を別にしても、進行を破棄してから新しい進行を作ることはできません。

`DirectEnhanceByUserId` と `UnleashByUserId` は進行をまったく触りません。何を消費して何を入手するかを算出し、それらを自身のトランザクションとして発行します。素材が違う 2 つは別の対象なのでどちらも実行されますが、消費するものと入手するものは同じトランザクションに集まります。

強化の素材は GS2-Inventory から消費され、結果も GS2-Inventory で入手されるのが一般的です。外側のトランザクションが同じアイテムを触る場合は、GS2-Inventory のページもあわせて確認してください。

### 入れ子になったトランザクションに注意

内側から作成された進行と、外側から破棄された進行が衝突して、トランザクションが失敗します。

### 制限を回避したい場合

進行の作成、直接強化、解放は入手アクション、進行の破棄は消費アクションです。作成どうしの衝突は `acquireActionUseJobQueue` を有効にすれば解消できます。作成と破棄の同居は `enableAtomicCommit` を無効にすれば解消し、このとき消費アクションが入手アクションより先に実行されるため、破棄してから新しい進行を作るという流れも成立するようになります。

### 同時実行とリトライ

同じユーザーの進行を複数のリクエストが同時に作成・破棄した場合、後から確定した側がコンフリクト (409) になります。リトライすると最新の状態で判定し直されるので、進行が期待した状態であれば成功し、すでに別の強化が始まっていればエラーが返ります。

直接強化と解放は進行を触らないため、どの程度コンフリクトするかは、素材と結果が属するサービス次第です。

---



## Consume Action

消費アクション

### Gs2Enhance:DeleteProgressByUserId

ユーザーIDを指定して実行中の強化の進行情報を削除<br>

指定されたユーザーの現在進行中の強化の進行情報レコードを削除します。<br>
進行中の2フェーズ強化がキャンセルされ、事前計算された経験値とボーナスレートは破棄されます。<br>
Start フェーズで既に消費された素材は自動的には返還されません。

**数量指定可能なアクション：いいえ**

**反転可能なアクション：いいえ**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Enhance:DeleteProgressByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Enhance:DeleteProgressByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("enhance").consume.delete_progress_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Acquire Action

入手アクション

### Gs2Enhance:DirectEnhanceByUserId

ユーザーIDを指定して強化を実行<br>

強化レートモデルに基づいて、指定された素材を消費して対象アイテムセットに経験値を付与します。<br>
獲得経験値はレートモデルで定義された経験値階層に従って素材から計算され、ボーナスレートは設定されたボーナスレート確率テーブルから抽選されます。<br>
結果には獲得した経験値量と適用されたボーナスレートが含まれます。<br>
素材の消費と経験値の取得を実行するためのトランザクションが発行されます。

**数量指定可能なアクション：いいえ**

**反転可能なアクション：いいえ**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rateName | string |  | ✓|  |  ~ 128文字 | 強化レートモデル名<br>強化レートモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| targetItemSetId | string |  | ✓|  |  ~ 1024文字 | 強化対象のアイテムセットのGRN |
| materials | List&lt;Material&gt; |  | ✓|  | 1 ~ 10 items | 強化素材リスト |
| config | List&lt;Config&gt; |  | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Enhance:DirectEnhanceByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "rateName": "[string]強化レートモデル名",
        "userId": "[string]ユーザーID",
        "targetItemSetId": "[string]強化対象のアイテムセットのGRN",
        "materials": [
            {
                "materialItemSetId": "[string]強化の素材となるアイテムセットの GRN",
                "count": "[int]消費数量"
            }
        ],
        "config": [
            {
                "key": "[string]名前",
                "value": "[string]値"
            }
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Enhance:DirectEnhanceByUserId
request:
  namespaceName: "[string]ネームスペース名"
  rateName: "[string]強化レートモデル名"
  userId: "[string]ユーザーID"
  targetItemSetId: "[string]強化対象のアイテムセットのGRN"
  materials: 
    - materialItemSetId: "[string]強化の素材となるアイテムセットの GRN"
      count: "[int]消費数量"
  config: 
    - key: "[string]名前"
      value: "[string]値"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("enhance").acquire.direct_enhance_by_user_id({
    namespaceName="[string]ネームスペース名",
    rateName="[string]強化レートモデル名",
    userId="[string]ユーザーID",
    targetItemSetId="[string]強化対象のアイテムセットのGRN",
    materials={
        {
            materialItemSetId="[string]強化の素材となるアイテムセットの GRN",
            count="[int]消費数量"
        }
    },
    config={
        {
            key="[string]名前",
            value="[string]値"
        }
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

### Gs2Enhance:UnleashByUserId

ユーザーIDを指定して限界突破を実行<br>

GS2-Grade で管理するグレードを引き上げる強化処理で利用します。<br>
なかでも、同種アイテムを素材として消費することでレベルキャップを引き上げるタイプの限界突破に利用します。<br>

指定された素材を消費する代わりに限界突破対象のリソースのグレードを1引き上げることができます。<br>
素材となるリソースが経験値などのリソースを持っていたとしても、そのリソースは引き継がれません。<br>
引き継ぎが必要な場合は、事前に別のリソースに引き継ぐためのリソースに変換しておく必要があります。

**数量指定可能なアクション：いいえ**

**反転可能なアクション：いいえ**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rateName | string |  | ✓|  |  ~ 128文字 | 強化レートモデル名<br>強化レートモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| targetItemSetId | string |  | ✓|  |  ~ 1024文字 | 限界突破対象のアイテムセットのGRN |
| materials | List&lt;string&gt; |  | ✓|  | 1 ~ 1000 items | 限界突破素材リスト |
| config | List&lt;Config&gt; |  | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Enhance:UnleashByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "rateName": "[string]強化レートモデル名",
        "userId": "[string]ユーザーID",
        "targetItemSetId": "[string]限界突破対象のアイテムセットのGRN",
        "materials": [
            "[string]素材"
        ],
        "config": [
            {
                "key": "[string]名前",
                "value": "[string]値"
            }
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Enhance:UnleashByUserId
request:
  namespaceName: "[string]ネームスペース名"
  rateName: "[string]強化レートモデル名"
  userId: "[string]ユーザーID"
  targetItemSetId: "[string]限界突破対象のアイテムセットのGRN"
  materials: 
    - "[string]素材"
  config: 
    - key: "[string]名前"
      value: "[string]値"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("enhance").acquire.unleash_by_user_id({
    namespaceName="[string]ネームスペース名",
    rateName="[string]強化レートモデル名",
    userId="[string]ユーザーID",
    targetItemSetId="[string]限界突破対象のアイテムセットのGRN",
    materials={
        "[string]素材"
    },
    config={
        {
            key="[string]名前",
            value="[string]値"
        }
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

### Gs2Enhance:CreateProgressByUserId

ユーザーIDを指定して強化を開始<br>

2フェーズ強化フローのための進行情報レコードを作成します。<br>
対象アイテムセットと素材をレートモデルに対して検証し、素材から獲得経験値を計算し、確率テーブルからボーナスレートを抽選します。<br>
計算された経験値とボーナスレートは進行情報レコードに保存され、End API で強化完了時に使用されます。<br>
force が true の場合、ユーザーの既存の進行情報は破棄され置き換えられます。

**数量指定可能なアクション：いいえ**

**反転可能なアクション：はい**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| rateName | string |  | ✓|  |  ~ 128文字 | 強化レートモデル名<br>この強化操作のパラメータを定義する強化レートモデルの名前です。対象インベントリ、素材インベントリ、経験値階層、ボーナスレートを指定するモデルを参照します。 |
| targetItemSetId | string |  | ✓|  |  ~ 1024文字 | 強化対象のアイテムセットのGRN |
| materials | List&lt;Material&gt; |  | |  | 0 ~ 10 items | 強化素材リスト |
| force | bool |  | | false |  | すでに開始している強化がある場合にそれを破棄して開始するか |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Enhance:CreateProgressByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "rateName": "[string]強化レートモデル名",
        "targetItemSetId": "[string]強化対象のアイテムセットのGRN",
        "materials": [
            {
                "materialItemSetId": "[string]強化の素材となるアイテムセットの GRN",
                "count": "[int]消費数量"
            }
        ],
        "force": "[bool]すでに開始している強化がある場合にそれを破棄して開始するか",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Enhance:CreateProgressByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  rateName: "[string]強化レートモデル名"
  targetItemSetId: "[string]強化対象のアイテムセットのGRN"
  materials: 
    - materialItemSetId: "[string]強化の素材となるアイテムセットの GRN"
      count: "[int]消費数量"
  force: "[bool]すでに開始している強化がある場合にそれを破棄して開始するか"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("enhance").acquire.create_progress_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    rateName="[string]強化レートモデル名",
    targetItemSetId="[string]強化対象のアイテムセットのGRN",
    materials={
        {
            materialItemSetId="[string]強化の素材となるアイテムセットの GRN",
            count="[int]消費数量"
        }
    },
    force="[bool]すでに開始している強化がある場合にそれを破棄して開始するか",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---