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

The transaction actions of GS2-Idle address one status, identified by the combination of namespace, user, and category. A status holds the maximum idle time and the progress of the idling, and each action writes only the value it changes.

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

Taking a reward twice in one transaction is refused on purpose. A reward is worked out from the state at the start of the transaction, so the second one would hand out the same accumulated idle time again. Where you genuinely need two, split the transaction; the second one will then start from a state where almost no idle time has accumulated.

Changing the maximum idle time and taking a reward change different values, so they may be placed together.

Take care with nested transactions

Changes to the maximum idle time are safe across a nested transaction: they are applied together as one update whichever route they arrive by.

Taking a reward is not. A receive arriving from the inside while another receive is specified on the outside makes the transaction fail.

If you want to avoid these restrictions

Taking a reward, and adding to or setting the maximum idle time, are acquire actions; subtracting from the maximum idle time is a consume action. Turning acquireActionUseJobQueue on clears a collision between two receives, but all it does is run them one at a time, so the second one is computed from a state where almost no idle time has accumulated.

Concurrency and retries

Changes to the maximum idle time do not conflict however many concurrent requests overlap, as long as the result stays within range.

Taking a reward is written with a check on the state it was computed from, so a receive that overlaps another update to the same status returns a conflict (409). Nothing is wrong with the request, so retrying will succeed.

Consume Action

Gs2Idle:DecreaseMaximumIdleMinutesByUserId

Decrease the maximum idle time by User ID

Subtracts the specified number of minutes from the user’s maximum idle time for the given category. The maximum idle time cannot go below zero. If no status exists yet, it is automatically created before applying the decrease.

Quantity specification supported: YES

Reversible action: YES

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "categoryName": "[string]Category Model Name",
        "decreaseMinutes": "[int]Minutes to decrease the maximum idle time",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Idle:DecreaseMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  categoryName: "[string]Category Model Name"
  decreaseMinutes: "[int]Minutes to decrease the maximum idle time"
  timeOffsetToken: "[string]Time offset token"

transaction.service("idle").consume.decrease_maximum_idle_minutes_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    categoryName="[string]Category Model Name",
    decreaseMinutes="[int]Minutes to decrease the maximum idle time",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2Idle:IncreaseMaximumIdleMinutesByUserId

Increase the maximum idle time by User ID

Adds the specified number of minutes to the user’s maximum idle time for the given category. The maximum idle time determines the cap on how long idle rewards can accumulate. If no status exists yet, it is automatically created before applying the increase.

Quantity specification supported: YES

Reversible action: YES

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "categoryName": "[string]Category Model Name",
        "increaseMinutes": "[int]Minutes to increase the maximum idle time",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Idle:IncreaseMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  categoryName: "[string]Category Model Name"
  increaseMinutes: "[int]Minutes to increase the maximum idle time"
  timeOffsetToken: "[string]Time offset token"

transaction.service("idle").acquire.increase_maximum_idle_minutes_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    categoryName="[string]Category Model Name",
    increaseMinutes="[int]Minutes to increase the maximum idle time",
    timeOffsetToken="[string]Time offset token",
})

Gs2Idle:SetMaximumIdleMinutesByUserId

Set the maximum idle time by User ID

Sets the user’s maximum idle time for the given category to the specified absolute value. Unlike increase/decrease operations, this directly replaces the current maximum idle time. Returns both the updated status and the status before the update, allowing the caller to see what changed. If no status exists yet, it is automatically created before applying the value.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Idle:SetMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "categoryName": "[string]Category Model Name",
        "maximumIdleMinutes": "[int]Maximum idle time to set (Minutes)",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Idle:SetMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  categoryName: "[string]Category Model Name"
  maximumIdleMinutes: "[int]Maximum idle time to set (Minutes)"
  timeOffsetToken: "[string]Time offset token"

transaction.service("idle").acquire.set_maximum_idle_minutes_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    categoryName="[string]Category Model Name",
    maximumIdleMinutes="[int]Maximum idle time to set (Minutes)",
    timeOffsetToken="[string]Time offset token",
})

Gs2Idle:ReceiveByUserId

Receive rewards by User ID

Receives idle rewards for the specified user and category based on the accumulated idle time. The reward amount is calculated from the elapsed idle time divided by rewardIntervalMinutes, capped by maximumIdleMinutes. If a receiveScript is configured, it is executed before granting rewards and can modify or reject the receive operation. An overrideAcquireActionsScriptId can also modify the acquire actions (e.g., applying rate modifiers). After receiving, the idle timer is reset to the current time. Returns a transaction containing the acquire actions for the calculated rewards.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Idle:ReceiveByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "categoryName": "[string]Category Model Name",
        "config": [
            {
                "key": "[string]Name",
                "value": "[string]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Idle:ReceiveByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  categoryName: "[string]Category Model Name"
  config: 
    - key: "[string]Name"
      value: "[string]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("idle").acquire.receive_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    categoryName="[string]Category Model Name",
    config={
        {
            key="[string]Name",
            value="[string]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})