GS2-Enchant 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-Enchant adds to it.

The transaction actions of GS2-Enchant address two kinds of status, both identified by the combination of namespace, user, parameter model, and property. Each is rewritten as a whole on every update.

• Balance parameter status
• Rarity parameter status

Only an addition to a rarity parameter carries a value that can be added up. A redraw and a set replace the whole status, so they cannot sit alongside another row on the same status.

A redraw redraws the whole status, so you cannot specify two or more redraws against the same status. Two redraws that are identical down to the parameters they fix are still rejected when the transaction is issued. Treat “redraw twice” as something that cannot be expressed.

A balance parameter status and a rarity parameter status are separate targets even for the same property, so updating both in one transaction is fine.

Verify actions look at the status as of the start of the transaction. You cannot verify a parameter that is reached by the same transaction.

Take care with nested transactions

Even two additions to the same rarity parameter, which would have been combined if written side by side, make the transaction fail when one of them arrives from the inside. Take the contents of any rewards or draws into account as well, and design so that only one place in a transaction updates one status.

Redraws are rejected when the transaction is issued if they are written side by side, and when the transaction runs if one of them arrives from the inside. Only the point at which the error is raised differs, so keep a redraw of one status to a single place in a transaction.

If you want to avoid these restrictions

Every action of GS2-Enchant that updates a status is an acquire action, so turning acquireActionUseJobQueue on clears all of the collisions above.

Duplicates that are rejected when the transaction is issued are the exception: redraws written side by side, and sets written side by side with different values. Both are rejected before the acquireActionUseJobQueue check, so turning it on does not help. If you want to redraw the same status twice, split the transaction itself.

Concurrency and retries

A status is rewritten as a whole with a revision check, so when several requests update the same status at the same time, the one confirmed later returns a conflict (409). Nothing is wrong with the request, so retrying will succeed.

This gets more likely the more places enchant the same property at once, so serialise updates to one status where you can.

Verify Action

Gs2Enchant:VerifyRarityParameterStatusByUserId

Verify rarity parameter by User ID

Verifies that a rarity parameter status of the specified user meets the specified condition. Three verification types are supported:

• ‘have’: Verifies that the specified parameter value exists in the status
• ‘havent’: Verifies that the specified parameter value does not exist in the status
• ‘count’: Verifies that the number of parameters matches the specified count This can be used as a precondition check before executing other actions.

Quantity specification supported: YES

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Enchant:VerifyRarityParameterStatusByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "parameterName": "[string]Rarity Parameter Model name",
        "userId": "[string]User ID",
        "propertyId": "[string]Property ID of the resource that owns the parameter",
        "verifyType": "[string]Type of verification",
        "parameterValueName": "[string]Name",
        "parameterCount": "[int]Number of parameters to verify",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Enchant:VerifyRarityParameterStatusByUserId
request:
  namespaceName: "[string]Namespace name"
  parameterName: "[string]Rarity Parameter Model name"
  userId: "[string]User ID"
  propertyId: "[string]Property ID of the resource that owns the parameter"
  verifyType: "[string]Type of verification"
  parameterValueName: "[string]Name"
  parameterCount: "[int]Number of parameters to verify"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("enchant").verify.verify_rarity_parameter_status_by_user_id({
    namespaceName="[string]Namespace name",
    parameterName="[string]Rarity Parameter Model name",
    userId="[string]User ID",
    propertyId="[string]Property ID of the resource that owns the parameter",
    verifyType="[string]Type of verification",
    parameterValueName="[string]Name",
    parameterCount="[int]Number of parameters to verify",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2Enchant:ReDrawBalanceParameterStatusByUserId

Re-draw balance parameter by User ID

Re-draws the balance parameter values for a specific property, redistributing the total value among the parameters. Specific parameters can be fixed (locked) to prevent them from being re-drawn by specifying their names in fixedParameterNames (up to 10). The total value constraint is maintained: the sum of all parameter values (including fixed ones) always equals the model’s total value. Both the updated and previous parameter states are returned.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Enchant:ReDrawBalanceParameterStatusByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "parameterName": "[string]Balance Parameter Model name",
        "propertyId": "[string]Property ID of the resource that owns the parameter",
        "fixedParameterNames": [
            "[string]Parameter name not to re-draw"
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Enchant:ReDrawBalanceParameterStatusByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  parameterName: "[string]Balance Parameter Model name"
  propertyId: "[string]Property ID of the resource that owns the parameter"
  fixedParameterNames: 
    - "[string]Parameter name not to re-draw"
  timeOffsetToken: "[string]Time offset token"

transaction.service("enchant").acquire.re_draw_balance_parameter_status_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    parameterName="[string]Balance Parameter Model name",
    propertyId="[string]Property ID of the resource that owns the parameter",
    fixedParameterNames={
        "[string]Parameter name not to re-draw"
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Enchant:SetBalanceParameterStatusByUserId

Set any value to Balance Parameter Status by User ID

Directly sets parameter values for a specific property of the specified user, bypassing the normal draw/re-draw mechanism. This is an administrative operation that allows arbitrary parameter values to be assigned. Both the updated and previous parameter states are returned.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Enchant:SetBalanceParameterStatusByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "parameterName": "[string]Balance Parameter Model name",
        "propertyId": "[string]Property ID of the resource that owns the parameter",
        "parameterValues": [
            {
                "name": "[string]Name",
                "value": "[long]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Enchant:SetBalanceParameterStatusByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  parameterName: "[string]Balance Parameter Model name"
  propertyId: "[string]Property ID of the resource that owns the parameter"
  parameterValues: 
    - name: "[string]Name"
      value: "[long]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("enchant").acquire.set_balance_parameter_status_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    parameterName="[string]Balance Parameter Model name",
    propertyId="[string]Property ID of the resource that owns the parameter",
    parameterValues={
        {
            name="[string]Name",
            value="[long]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Enchant:ReDrawRarityParameterStatusByUserId

Re-draw Rarity Parameter Status by User ID

Re-draws the rarity parameter values for a specific property, randomly assigning new values based on the rarity weights. Specific parameters can be fixed (locked) to prevent them from being re-drawn by specifying their names in fixedParameterNames (up to 10). Fixed parameters retain their current values while unfixed parameters are re-drawn. Both the updated and previous parameter states are returned.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Enchant:ReDrawRarityParameterStatusByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "parameterName": "[string]Rarity Parameter Model name",
        "propertyId": "[string]Property ID of the resource that owns the parameter",
        "fixedParameterNames": [
            "[string]Parameter name not to re-draw"
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Enchant:ReDrawRarityParameterStatusByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  parameterName: "[string]Rarity Parameter Model name"
  propertyId: "[string]Property ID of the resource that owns the parameter"
  fixedParameterNames: 
    - "[string]Parameter name not to re-draw"
  timeOffsetToken: "[string]Time offset token"

transaction.service("enchant").acquire.re_draw_rarity_parameter_status_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    parameterName="[string]Rarity Parameter Model name",
    propertyId="[string]Property ID of the resource that owns the parameter",
    fixedParameterNames={
        "[string]Parameter name not to re-draw"
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Enchant:AddRarityParameterStatusByUserId

Add Rarity Parameter Status by User ID

Adds new parameter slots to an existing rarity parameter status by randomly drawing values based on the rarity weights. The count specifies how many parameter slots to add (1 to 10), up to the model’s maximum parameter count. Both the updated and previous parameter states are returned.

Quantity specification supported: YES

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Enchant:AddRarityParameterStatusByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "parameterName": "[string]Rarity Parameter Model name",
        "propertyId": "[string]Property ID of the resource that owns the parameter",
        "count": "[int]Number of parameters to add",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Enchant:AddRarityParameterStatusByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  parameterName: "[string]Rarity Parameter Model name"
  propertyId: "[string]Property ID of the resource that owns the parameter"
  count: "[int]Number of parameters to add"
  timeOffsetToken: "[string]Time offset token"

transaction.service("enchant").acquire.add_rarity_parameter_status_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    parameterName="[string]Rarity Parameter Model name",
    propertyId="[string]Property ID of the resource that owns the parameter",
    count="[int]Number of parameters to add",
    timeOffsetToken="[string]Time offset token",
})

Gs2Enchant:SetRarityParameterStatusByUserId

Set any value to rarity parameter by User ID

Directly sets parameter values for a specific property of the specified user, bypassing the normal draw/re-draw mechanism. This is an administrative operation that allows arbitrary parameter values to be assigned regardless of rarity weights. Both the updated and previous parameter states are returned.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Enchant:SetRarityParameterStatusByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "parameterName": "[string]Rarity Parameter Model name",
        "propertyId": "[string]Property ID of the resource that owns the parameter",
        "parameterValues": [
            {
                "name": "[string]Name",
                "resourceName": "[string]Resource Name",
                "resourceValue": "[long]Resource Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Enchant:SetRarityParameterStatusByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  parameterName: "[string]Rarity Parameter Model name"
  propertyId: "[string]Property ID of the resource that owns the parameter"
  parameterValues: 
    - name: "[string]Name"
      resourceName: "[string]Resource Name"
      resourceValue: "[long]Resource Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("enchant").acquire.set_rarity_parameter_status_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    parameterName="[string]Rarity Parameter Model name",
    propertyId="[string]Property ID of the resource that owns the parameter",
    parameterValues={
        {
            name="[string]Name",
            resourceName="[string]Resource Name",
            resourceValue="[long]Resource Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})