GS2-Guild Transaction Actions

Combining actions, and concurrency

The background common to every service is collected in Combining Transaction Actions. Read that first; the rest of this section is what GS2-Guild adds to it.

The transaction actions of GS2-Guild address one guild, identified by the combination of namespace, guild model, and guild name. Note that the target is a guild rather than a user: a transaction issued for one user ends up updating something many users share. A guild is rewritten as a whole on every update.

The three update rows share one boundary, so adding, subtracting, and setting cannot be mixed against one guild.

The maximum member count has to stay within the range the guild model allows, and it is judged against the total after combining, so an addition that fits on its own can still be rejected when combined with another one.

Verify actions look at the guild as of the start of the transaction. You cannot verify a member count that is reached by the same transaction, nor a membership that the same transaction establishes.

Take care with nested transactions

Even two increases of the same guild, which would have been combined if written side by side, make the transaction fail when one of them arrives from the inside.

A guild is shared by many users, but this is not about two of its members acting at the same time: it happens when one transaction touches the same guild twice, through a reward or a draw. Take the contents of those into account as well, and design so that only one place in a transaction updates one guild.

If you want to avoid these restrictions

Adding to and setting the maximum member count are acquire actions; subtracting is a consume action. Turning acquireActionUseJobQueue on clears collisions between acquire actions, but a collision with a subtraction needs enableAtomicCommit turned off.

Concurrency and retries

A guild is rewritten as a whole with a revision check, so even two additions collide; there is no relaxation here like the one experience has in GS2-Experience, where a change within a band does not collide. A guild is also shared by its members, so updates to it collide far more readily than updates to something owned by one user. Joining and leaving, changing the guild, and updating member metadata all touch the same guild, and any of them overlapping with a change to the maximum member count may return a conflict (409). Nothing is wrong with the request, so retrying will succeed.

Where you raise the maximum member count during a busy period of members coming and going, plan on retrying.

Verify Action

Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName

Verify the maximum number of guild members by specifying a Guild name

Verifies the specified guild’s currentMaximumMemberCount against the specified value using the chosen comparison operator (server-side operation). Supported operators: less, lessEqual, greater, greaterEqual, equal, notEqual.

Quantity specification supported: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]Namespace name",
        "guildModelName": "[string]Guild Model name",
        "guildName": "[string]Guild name",
        "verifyType": "[string]Type of verification",
        "value": "[int]Maximum number of guild members",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity"
    }
}

action: Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]Namespace name"
  guildModelName: "[string]Guild Model name"
  guildName: "[string]Guild name"
  verifyType: "[string]Type of verification"
  value: "[int]Maximum number of guild members"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"

transaction.service("guild").verify.verify_current_maximum_member_count_by_guild_name({
    namespaceName="[string]Namespace name",
    guildModelName="[string]Guild Model name",
    guildName="[string]Guild name",
    verifyType="[string]Type of verification",
    value="[int]Maximum number of guild members",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
})

Gs2Guild:VerifyIncludeMemberByUserId

Verify if guild members include user ID by User ID

Verifies whether the specified user is or is not a member of the guild (server-side operation). Supports two verification types: ‘include’ and ’notInclude’.

Quantity specification supported: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Guild:VerifyIncludeMemberByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "guildModelName": "[string]Guild Model name",
        "guildName": "[string]Guild Name",
        "userId": "[string]User ID",
        "verifyType": "[string]Type of verification",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Guild:VerifyIncludeMemberByUserId
request:
  namespaceName: "[string]Namespace name"
  guildModelName: "[string]Guild Model name"
  guildName: "[string]Guild Name"
  userId: "[string]User ID"
  verifyType: "[string]Type of verification"
  timeOffsetToken: "[string]Time offset token"

transaction.service("guild").verify.verify_include_member_by_user_id({
    namespaceName="[string]Namespace name",
    guildModelName="[string]Guild Model name",
    guildName="[string]Guild Name",
    userId="[string]User ID",
    verifyType="[string]Type of verification",
    timeOffsetToken="[string]Time offset token",
})

Consume Action

Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName

Decrease the maximum number of members by specifying a Guild name

Decreases the specified guild’s currentMaximumMemberCount by the specified value (server-side operation). The resulting value cannot go below zero.

Quantity specification supported: YES

Reversible action: YES

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]Namespace name",
        "guildModelName": "[string]Guild Model name",
        "guildName": "[string]Guild name",
        "value": "[int]Increase the maximum number of members"
    }
}

action: Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]Namespace name"
  guildModelName: "[string]Guild Model name"
  guildName: "[string]Guild name"
  value: "[int]Increase the maximum number of members"

transaction.service("guild").consume.decrease_maximum_current_maximum_member_count_by_guild_name({
    namespaceName="[string]Namespace name",
    guildModelName="[string]Guild Model name",
    guildName="[string]Guild name",
    value="[int]Increase the maximum number of members",
})

Acquire Action

Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName

Add the maximum number of members by specifying a Guild name

Increases the guild’s currentMaximumMemberCount by the specified value. The resulting value must not exceed the maximumMemberCount defined in the guild model.

Quantity specification supported: YES

Reversible action: YES

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]Namespace name",
        "guildModelName": "[string]Guild Model name",
        "guildName": "[string]Guild name",
        "value": "[int]Increase the maximum number of members"
    }
}

action: Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]Namespace name"
  guildModelName: "[string]Guild Model name"
  guildName: "[string]Guild name"
  value: "[int]Increase the maximum number of members"

transaction.service("guild").acquire.increase_maximum_current_maximum_member_count_by_guild_name({
    namespaceName="[string]Namespace name",
    guildModelName="[string]Guild Model name",
    guildName="[string]Guild name",
    value="[int]Increase the maximum number of members",
})

Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName

Set the maximum number of guild members by specifying a Guild name

Sets the guild’s currentMaximumMemberCount to the specified absolute value. Unlike increase/decrease operations, this directly sets the value rather than applying a delta. Returns both the updated guild and the guild state before the update, allowing the caller to track the change.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
    "request": {
        "namespaceName": "[string]Namespace name",
        "guildName": "[string]Guild name",
        "guildModelName": "[string]Guild Model name",
        "value": "[int]Set the maximum number of members"
    }
}

action: Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName
request:
  namespaceName: "[string]Namespace name"
  guildName: "[string]Guild name"
  guildModelName: "[string]Guild Model name"
  value: "[int]Set the maximum number of members"

transaction.service("guild").acquire.set_maximum_current_maximum_member_count_by_guild_name({
    namespaceName="[string]Namespace name",
    guildName="[string]Guild name",
    guildModelName="[string]Guild Model name",
    value="[int]Set the maximum number of members",
})