GS2-Experience Transaction Actions

Specification of verify/consume/acquire transaction actions
Tags:

Verify Action

Gs2Experience:VerifyRankByUserId

Verify rank by specifying a user ID

Verifies that the specified user’s current rank satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met.

Supports quantity specification: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
verifyType string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
✓
 Type of verification
DefinitionDescription
“less”Rank is less than the specified value
“lessEqual”Rank is less than or equal to the specified value
“greater”Rank is greater than the specified value
“greaterEqual”Rank is greater than or equal to the specified value
“equal”Rank is equal to the specified value
“notEqual”Rank is not equal to the specified value
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
rankValue long 0 0 ~ 9223372036854775805 Current Rank
The rank (level) derived from the cumulative experience value using the rank threshold table. Starts at 0 and increases as experience thresholds are crossed. Cannot exceed the current rank cap value.
multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:VerifyRankByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "verifyType": "[string]Type of verification",
        "propertyId": "[string]Property ID",
        "rankValue": "[long]Current Rank",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:VerifyRankByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  verifyType: "[string]Type of verification"
  propertyId: "[string]Property ID"
  rankValue: "[long]Current Rank"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").verify.verify_rank_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    verifyType="[string]Type of verification",
    propertyId="[string]Property ID",
    rankValue="[long]Current Rank",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Experience:VerifyRankCapByUserId

Verify rank cap by specifying a user ID

Verifies that the specified user’s current rank cap (including buff effects) satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met.

Supports quantity specification: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
verifyType string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
✓
 Type of verification
DefinitionDescription
“less”Rank cap is less than the specified value
“lessEqual”Rank cap is less than or equal to the specified value
“greater”Rank cap is greater than the specified value
“greaterEqual”Rank cap is greater than or equal to the specified value
“equal”Rank cap is equal to the specified value
“notEqual”Rank cap is not equal to the specified value
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
rankCapValue long
✓
 0 ~ 9223372036854775805 Current Rank Cap
The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking.
multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:VerifyRankCapByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "verifyType": "[string]Type of verification",
        "propertyId": "[string]Property ID",
        "rankCapValue": "[long]Current Rank Cap",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:VerifyRankCapByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  verifyType: "[string]Type of verification"
  propertyId: "[string]Property ID"
  rankCapValue: "[long]Current Rank Cap"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").verify.verify_rank_cap_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    verifyType="[string]Type of verification",
    propertyId="[string]Property ID",
    rankCapValue="[long]Current Rank Cap",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Consume Action

Gs2Experience:SubExperienceByUserId

Subtract experience by specifying a user ID

Subtracts experience points from the specified user’s status. Experience will not go below 0. Rank is automatically recalculated based on the rank-up threshold values.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
experienceValue long 0 0 ~ 9223372036854775805 Lost Experience
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:SubExperienceByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "propertyId": "[string]Property ID",
        "experienceValue": "[long]Lost Experience",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:SubExperienceByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  propertyId: "[string]Property ID"
  experienceValue: "[long]Lost Experience"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").consume.sub_experience_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    propertyId="[string]Property ID",
    experienceValue="[long]Lost Experience",
    timeOffsetToken="[string]Time offset token",
})

Gs2Experience:SubRankCapByUserId

Subtract rank cap by specifying a user ID

Decreases the rank cap of the specified user’s status. The rank cap will not go below 0.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
rankCapValue long
✓
 0 ~ 9223372036854775805 Current Rank Cap
The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking.
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:SubRankCapByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "propertyId": "[string]Property ID",
        "rankCapValue": "[long]Current Rank Cap",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:SubRankCapByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  propertyId: "[string]Property ID"
  rankCapValue: "[long]Current Rank Cap"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").consume.sub_rank_cap_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    propertyId="[string]Property ID",
    rankCapValue="[long]Current Rank Cap",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2Experience:AddExperienceByUserId

Add experience by specifying a user ID

Adds experience points to the specified user’s status. Rank is automatically recalculated based on the rank-up threshold values. When truncateExperienceWhenRankUp is true, excess experience beyond the rank-up threshold is discarded on rank up; when false (default), it carries over to the next rank.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
experienceValue long 0 0 ~ 9223372036854775805 Gained Experience
truncateExperienceWhenRankUp bool? false Whether to truncate the remaining experience when ranking up
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:AddExperienceByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "propertyId": "[string]Property ID",
        "experienceValue": "[long]Gained Experience",
        "truncateExperienceWhenRankUp": "[bool]Whether to truncate the remaining experience when ranking up",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:AddExperienceByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  propertyId: "[string]Property ID"
  experienceValue: "[long]Gained Experience"
  truncateExperienceWhenRankUp: "[bool]Whether to truncate the remaining experience when ranking up"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").acquire.add_experience_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    propertyId="[string]Property ID",
    experienceValue="[long]Gained Experience",
    truncateExperienceWhenRankUp="[bool]Whether to truncate the remaining experience when ranking up",
    timeOffsetToken="[string]Time offset token",
})

Gs2Experience:SetExperienceByUserId

Set experience by specifying a user ID

Directly sets the experience value for the specified user’s status to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated status. Rank is automatically recalculated based on the rank-up threshold values.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
experienceValue long 0 0 ~ 9223372036854775805 Cumulative experience gained
The total experience value accumulated by this status. The current rank is derived from this value using the rank threshold table. Experience cannot be gained beyond the threshold corresponding to the current rank cap.
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:SetExperienceByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "propertyId": "[string]Property ID",
        "experienceValue": "[long]Cumulative experience gained",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:SetExperienceByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  propertyId: "[string]Property ID"
  experienceValue: "[long]Cumulative experience gained"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").acquire.set_experience_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    propertyId="[string]Property ID",
    experienceValue="[long]Cumulative experience gained",
    timeOffsetToken="[string]Time offset token",
})

Gs2Experience:AddRankCapByUserId

Add rank cap by specifying a user ID

Increases the rank cap of the specified user’s status. The rank cap cannot exceed the maxRankCap defined in the Experience Model. The rank cap determines the maximum rank a user can achieve for the specified property.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
rankCapValue long
✓
 0 ~ 9223372036854775805 Current Rank Cap
The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking.
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:AddRankCapByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "propertyId": "[string]Property ID",
        "rankCapValue": "[long]Current Rank Cap",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:AddRankCapByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  propertyId: "[string]Property ID"
  rankCapValue: "[long]Current Rank Cap"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").acquire.add_rank_cap_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    propertyId="[string]Property ID",
    rankCapValue="[long]Current Rank Cap",
    timeOffsetToken="[string]Time offset token",
})

Gs2Experience:SetRankCapByUserId

Set rank cap by specifying a user ID

Directly sets the rank cap value for the specified user’s status to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated status. The rank cap is capped at the maxRankCap defined in the Experience Model.

Supports quantity specification: NO

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
rankCapValue long
✓
 0 ~ 9223372036854775805 Current Rank Cap
The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking.
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:SetRankCapByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "propertyId": "[string]Property ID",
        "rankCapValue": "[long]Current Rank Cap",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:SetRankCapByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  propertyId: "[string]Property ID"
  rankCapValue: "[long]Current Rank Cap"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").acquire.set_rank_cap_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    propertyId="[string]Property ID",
    rankCapValue="[long]Current Rank Cap",
    timeOffsetToken="[string]Time offset token",
})

Gs2Experience:MultiplyAcquireActionsByUserId

Multiply resources according to the rank of the property subject to the experience value by specifying user ID

Looks up the acquire action rate for the specified rateName based on the property’s current rank value, multiplies the specified acquire actions by that rate (combined with baseRate), and starts a transaction to execute the resulting actions. This is used for rank-based reward scaling, where higher ranks earn proportionally more resources.

Supports quantity specification: YES

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
experienceName string
✓
 ~ 128 chars Experience Model name
The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied.
propertyId string
✓
 ~ 1024 chars Property ID
A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience.
rateName string
✓
 ~ 128 chars Reward addition table name
A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action.
acquireActions List<AcquireAction> [] 0 ~ 100 items List of Acquire Actions
baseRate float 1 0 ~ 1000000 Base rate
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Experience:MultiplyAcquireActionsByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "experienceName": "[string]Experience Model name",
        "propertyId": "[string]Property ID",
        "rateName": "[string]Reward addition table name",
        "acquireActions": [
            {
                "action": "[string]Type of Acquire Action",
                "request": "[string]JSON string of the request used when executing the action"
            }
        ],
        "baseRate": "[float]Base rate",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Experience:MultiplyAcquireActionsByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  experienceName: "[string]Experience Model name"
  propertyId: "[string]Property ID"
  rateName: "[string]Reward addition table name"
  acquireActions: 
    - action: "[string]Type of Acquire Action"
      request: "[string]JSON string of the request used when executing the action"
  baseRate: "[float]Base rate"
  timeOffsetToken: "[string]Time offset token"
transaction.service("experience").acquire.multiply_acquire_actions_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    experienceName="[string]Experience Model name",
    propertyId="[string]Property ID",
    rateName="[string]Reward addition table name",
    acquireActions={
        {
            action="[string]Type of Acquire Action",
            request="[string]JSON string of the request used when executing the action"
        }
    },
    baseRate="[float]Base rate",
    timeOffsetToken="[string]Time offset token",
})