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

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

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




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

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

GS2-Guild のトランザクションアクションは、ネームスペース・ギルドモデル・ギルド名の組で決まる 1 つのギルドを対象にします。対象がユーザーではなくギルドである点に注意してください。あるユーザーに対して発行したトランザクションが、多数のユーザーで共有しているものを更新することになります。ギルドは更新のたびに全体が書き換わります。

操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 | 直列実行モード有効時
--- | --- | --- | --- | ---
最大メンバー数の加算<br>`IncreaseMaximumCurrentMaximumMemberCountByGuildName` | 統合され、値が合算される | 失敗する | ネームスペース・ギルドモデル・ギルド名 | 成立する。入れ子越しでも合算される
最大メンバー数の減算<br>`DecreaseMaximumCurrentMaximumMemberCountByGuildName` | 統合され、値が合算される | 失敗する | ネームスペース・ギルドモデル・ギルド名 | 成立する。入れ子越しでも合算される
最大メンバー数の設定<br>`SetMaximumCurrentMaximumMemberCountByGuildName` | 同値なら統合。値が違えば発行時にエラー | 失敗する | ネームスペース・ギルドモデル・ギルド名 | 入れ子越しでも成立する。同値なら通り、値が違えば後から実行された方の値になる
最大メンバー数の検証<br>`VerifyCurrentMaximumMemberCountByGuildName` | まったく同じ検証は 1 件にまとめられる | 読み取りだけなので衝突しない | ギルド・検証タイプ・人数 | 変わらない。読み取りだけなのでもともと衝突しない
メンバーであることの検証<br>`VerifyIncludeMemberByUserId` | まったく同じ検証は 1 件にまとめられる | 読み取りだけなので衝突しない | ギルド・検証タイプ・対象ユーザー | 変わらない。読み取りだけなのでもともと衝突しない

更新する 3 つの行は境界が同じです。1 つのギルドに対して加算・減算・設定を混ぜることはできません。**直列実行モード（`enableSequentialExecution` または `TransactionSettingV2`）を有効にすると、アクションが 1 件ずつ実行され、それぞれが直前のアクションの書き込みを見られるようになるため、この制約はなくなります。1 つのギルドに対して加算・減算・設定を 1 つのトランザクションに混ぜられるようになり、加算と減算は実際に実行された順で合算され、設定が混在する場合は後から実行された方の値になります。**

最大メンバー数はギルドモデルで許された範囲に収まる必要があり、統合後の合計に対して判定されるので、単独なら収まる加算でも他の加算と合わさると弾かれることがあります。

**最大メンバー数の検証は `multiplyValueSpecifyingQuantity` を明示的に `true` にしたときだけ、しきい値が合算され数量に応じて倍になります。** 未指定は、まったく同じ検証が 1 件にまとめられるだけです。明示的に `true` にした場合は検証タイプを問わず合算されます。しきい値を「1 個あたりの量」として宣言したことになるためです。`less` `lessEqual` では数量が増えるほど条件が緩むので、指定するときは意図を確認してください。

検証アクションはトランザクション開始時点のギルドを見ます。同じトランザクションで到達するメンバー数や、同じトランザクションで成立する加入を検証することはできません。

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

並べて書けば 1 件に統合されたはずの同じギルドへの加算どうしでも、片方が内側から届く場合はトランザクションが失敗します。直列実行モードを有効にすると、この失敗は起こらなくなります。内側のトランザクションは外側と同じ直列実行の区間で実行されるようになるため、2 つの加算は衝突する代わりに同じ行として統合されます。

ギルドは多数のユーザーで共有されますが、これは「同じギルドに所属する 2 人が同時に何かをした」ときではなく、「1 つのトランザクションが報酬や抽選を通じて同じギルドに二度触れた」ときに起こります。報酬や抽選の中身まで含めて、1 つのトランザクションの中で 1 つのギルドを更新する箇所が 1 つだけになるように設計してください。

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

最大メンバー数の加算と設定は入手アクション、減算は消費アクションです。入手アクションどうしの衝突は `acquireActionUseJobQueue` を有効にすれば解消できますが、減算との同居は `enableAtomicCommit` を無効にしないと解消しません。

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

ギルドはリビジョンの照合を伴って全体が書き換わるため、加算どうしであっても、GS2-Experience の経験値のように「一定範囲なら衝突しない」という緩和はありません。しかもギルドはメンバーで共有されるものなので、1 人のユーザーが所有するものに比べて更新が重なりやすくなります。加入・脱退、ギルドの変更、メンバーのメタデータ更新はいずれも同じギルドを触るため、これらと最大メンバー数の変更が重なるとコンフリクト (409) が返ることがあります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。

メンバーの出入りが激しい時間帯に最大メンバー数を引き上げるトランザクションを実行する場合は、リトライを前提にしてください。

---


## Verify Action

検証アクション

### Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName

ギルド名を指定して最大参加可能人数を検証<br>

選択された比較演算子を使用して、指定されたギルドの currentMaximumMemberCount を指定された値と比較検証します（サーバーサイド操作）。<br>
サポートされる演算子：less、lessEqual、greater、greaterEqual、equal、notEqual。

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string |  | ✓|  |  ~ 128文字 | ギルドモデル名<br>ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string |  | ✓|  |  ~ 128文字 | ギルド名 |
| verifyType | 文字列列挙型<br>enum {<br>"less",<br>"lessEqual",<br>"greater",<br>"greaterEqual",<br>"equal",<br>"notEqual"<br>}<br> |  | ✓|  |  | 検証の種類less: 最大参加可能人数が指定値未満であること / lessEqual: 最大参加可能人数が指定値以下であること / greater: 最大参加可能人数が指定値超過であること / greaterEqual: 最大参加可能人数が指定値以上であること / equal: 最大参加可能人数が指定値と一致すること / notEqual: 最大参加可能人数が指定値と一致しないこと /  |
| value | int |  | |  | 1 ~ 2147483646 | 最大参加可能人数 |
| multiplyValueSpecifyingQuantity | bool |  | | false |  | 数量指定した際に、検証に使用する値も乗算するか |




**JSON**
```json
{
    "action": "Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "guildModelName": "[string]ギルドモデル名",
        "guildName": "[string]ギルド名",
        "verifyType": "[string]検証の種類",
        "value": "[int]最大参加可能人数",
        "multiplyValueSpecifyingQuantity": "[bool]数量指定した際に、検証に使用する値も乗算するか"
    }
}
```

**YAML**
```yaml

action: Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]ネームスペース名"
  guildModelName: "[string]ギルドモデル名"
  guildName: "[string]ギルド名"
  verifyType: "[string]検証の種類"
  value: "[int]最大参加可能人数"
  multiplyValueSpecifyingQuantity: "[bool]数量指定した際に、検証に使用する値も乗算するか"
```

**GS2-Script**
```lua

transaction.service("guild").verify.verify_current_maximum_member_count_by_guild_name({
    namespaceName="[string]ネームスペース名",
    guildModelName="[string]ギルドモデル名",
    guildName="[string]ギルド名",
    verifyType="[string]検証の種類",
    value="[int]最大参加可能人数",
    multiplyValueSpecifyingQuantity="[bool]数量指定した際に、検証に使用する値も乗算するか",
})
```


---

### Gs2Guild:VerifyIncludeMemberByUserId

ユーザーIDを指定してギルドメンバーにユーザーIDが含まれているかを検証<br>

指定されたユーザーがギルドのメンバーであるかどうかを検証します（サーバーサイド操作）。<br>
2つの検証タイプをサポートします：`include` と `notInclude`。

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string |  | ✓|  |  ~ 128文字 | ギルドモデル名<br>ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string |  | ✓| UUID |  ~ 36文字 | ギルド名<br>ギルドの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| verifyType | 文字列列挙型<br>enum {<br>"include",<br>"notInclude"<br>}<br> |  | ✓|  |  | 検証の種類include: ギルドメンバーに指定したユーザーが含まれていること / notInclude: ギルドメンバーに指定したユーザーが含まれないこと /  |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Guild:VerifyIncludeMemberByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "guildModelName": "[string]ギルドモデル名",
        "guildName": "[string]ギルド名",
        "userId": "[string]ユーザーID",
        "verifyType": "[string]検証の種類",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Guild:VerifyIncludeMemberByUserId
request:
  namespaceName: "[string]ネームスペース名"
  guildModelName: "[string]ギルドモデル名"
  guildName: "[string]ギルド名"
  userId: "[string]ユーザーID"
  verifyType: "[string]検証の種類"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("guild").verify.verify_include_member_by_user_id({
    namespaceName="[string]ネームスペース名",
    guildModelName="[string]ギルドモデル名",
    guildName="[string]ギルド名",
    userId="[string]ユーザーID",
    verifyType="[string]検証の種類",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Consume Action

消費アクション

### Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName

ギルド名を指定して最大参加可能人数を減算<br>

指定されたギルドの currentMaximumMemberCount を指定された値だけ減少させます（サーバーサイド操作）。<br>
結果の値はゼロ未満にはなりません。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string |  | ✓|  |  ~ 128文字 | ギルドモデル名<br>ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string |  | ✓|  |  ~ 128文字 | ギルド名 |
| value | int |  | |  | 1 ~ 2147483646 | 最大人数の減少量 |




**JSON**
```json
{
    "action": "Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "guildModelName": "[string]ギルドモデル名",
        "guildName": "[string]ギルド名",
        "value": "[int]最大人数の減少量"
    }
}
```

**YAML**
```yaml

action: Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]ネームスペース名"
  guildModelName: "[string]ギルドモデル名"
  guildName: "[string]ギルド名"
  value: "[int]最大人数の減少量"
```

**GS2-Script**
```lua

transaction.service("guild").consume.decrease_maximum_current_maximum_member_count_by_guild_name({
    namespaceName="[string]ネームスペース名",
    guildModelName="[string]ギルドモデル名",
    guildName="[string]ギルド名",
    value="[int]最大人数の減少量",
})
```


---

## Acquire Action

入手アクション

### Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName

ギルド名を指定して最大参加可能人数を加算<br>

ギルドの currentMaximumMemberCount を指定された値だけ増加させます。<br>
結果の値はギルドモデルで定義された maximumMemberCount を超えてはなりません。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string |  | ✓|  |  ~ 128文字 | ギルドモデル名<br>ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string |  | ✓|  |  ~ 128文字 | ギルド名 |
| value | int |  | |  | 1 ~ 2147483646 | 最大人数の増加量 |




**JSON**
```json
{
    "action": "Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "guildModelName": "[string]ギルドモデル名",
        "guildName": "[string]ギルド名",
        "value": "[int]最大人数の増加量"
    }
}
```

**YAML**
```yaml

action: Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]ネームスペース名"
  guildModelName: "[string]ギルドモデル名"
  guildName: "[string]ギルド名"
  value: "[int]最大人数の増加量"
```

**GS2-Script**
```lua

transaction.service("guild").acquire.increase_maximum_current_maximum_member_count_by_guild_name({
    namespaceName="[string]ネームスペース名",
    guildModelName="[string]ギルドモデル名",
    guildName="[string]ギルド名",
    value="[int]最大人数の増加量",
})
```


---

### Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName

ギルド名を指定して最大参加可能人数を設定<br>

ギルドの currentMaximumMemberCount を指定された絶対値に設定します。<br>
増減操作とは異なり、差分を適用するのではなく値を直接設定します。<br>
更新後のギルドと更新前のギルド状態の両方を返し、呼び出し元が変更を追跡できるようにします。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string |  | ✓|  |  ~ 128文字 | ギルド名 |
| guildModelName | string |  | ✓|  |  ~ 128文字 | ギルドモデル名<br>ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| value | int |  | |  | 1 ~ 2147483646 | 設定する最大人数 |




**JSON**
```json
{
    "action": "Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "guildName": "[string]ギルド名",
        "guildModelName": "[string]ギルドモデル名",
        "value": "[int]設定する最大人数"
    }
}
```

**YAML**
```yaml

action: Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]ネームスペース名"
  guildName: "[string]ギルド名"
  guildModelName: "[string]ギルドモデル名"
  value: "[int]設定する最大人数"
```

**GS2-Script**
```lua

transaction.service("guild").acquire.set_maximum_current_maximum_member_count_by_guild_name({
    namespaceName="[string]ネームスペース名",
    guildName="[string]ギルド名",
    guildModelName="[string]ギルドモデル名",
    value="[int]設定する最大人数",
})
```


---