GS2-Grade Transaction Actions

Specification of verify/consume/acquire transaction actions

VerifyAction

Gs2Grade:VerifyGradeByUserId

Verify grade by specifying a user ID

Verifies that the specified user’s grade value satisfies a specified condition (server-side operation). Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. If the condition is not met, an error is returned with a descriptive message including the expected and actual values. When multiplyValueSpecifyingQuantity is true, the verification threshold value is multiplied by the specified quantity.

Whether the action allows 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
Set #{userId} to replace the currently logged in user ID.

gradeName

string

✓

~ 128 chars

Grade Model Name

The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables.

verifyType

String Enum
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}

✓

Type of verification

Definition	Description
“less”	Grade is less than the specified value
“lessEqual”	Grade is less than or equal to the specified value
“greater”	Grade is greater than the specified value
“greaterEqual”	Grade is greater than or equal to the specified value
“equal”	Grade is equal to the specified value
“notEqual”	Grade is not equal to the specified value

propertyId

string

✓

~ 1024 chars

Property ID

A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps.

gradeValue

long

1 ~ 9223372036854775805

Current Grade

The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry.

multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity

timeOffsetToken string ~ 1024 chars Time offset token

{
    "action": "Gs2Grade:VerifyGradeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "verifyType": "[string]Type of verification",
        "propertyId": "[string]Property ID",
        "gradeValue": "[long]Current Grade",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Grade:VerifyGradeByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  verifyType: "[string]Type of verification"
  propertyId: "[string]Property ID"
  gradeValue: "[long]Current Grade"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("grade").verify.verify_grade_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    verifyType="[string]Type of verification",
    propertyId="[string]Property ID",
    gradeValue="[long]Current Grade",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Grade:VerifyGradeUpMaterialByUserId

Verify grade up material by specifying a user ID

Verifies whether a material property ID is valid for grading up the specified property for the specified user (server-side operation). The verification builds a regex pattern from the grade entry’s PropertyIdRegex and GradeUpPropertyIdRegex, then checks if the material property ID matches. Supports two verification types: ‘match’ (material must match the pattern) and ’notMatch’ (material must not match the pattern).

Whether the action allows 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
Set #{userId} to replace the currently logged in user ID.

gradeName

string

✓

~ 128 chars

Grade Model Name

The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables.

verifyType

String Enum
enum {
“match”,
“notMatch”
}

✓

Type of verification

Definition	Description
“match”	Grade is equal to the specified value
“notMatch”	Grade is not equal to the specified value

propertyId

string

✓

~ 1024 chars

Property ID

materialPropertyId

string

✓

~ 1024 chars

Property ID

timeOffsetToken string ~ 1024 chars Time offset token

{
    "action": "Gs2Grade:VerifyGradeUpMaterialByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "verifyType": "[string]Type of verification",
        "propertyId": "[string]Property ID",
        "materialPropertyId": "[string]Property ID",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Grade:VerifyGradeUpMaterialByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  verifyType: "[string]Type of verification"
  propertyId: "[string]Property ID"
  materialPropertyId: "[string]Property ID"
  timeOffsetToken: "[string]Time offset token"

transaction.service("grade").verify.verify_grade_up_material_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    verifyType="[string]Type of verification",
    propertyId="[string]Property ID",
    materialPropertyId="[string]Property ID",
    timeOffsetToken="[string]Time offset token",
})

ConsumeAction

Gs2Grade:SubGradeByUserId

Subtract grade by specifying a user ID

Subtracts the specified grade value from the specified user’s current grade for the given grade model and property (server-side operation). After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Returns the updated grade status along with the Experience namespace name and the updated Experience status.

Whether the action allows quantity specification: YES

Whether the action is reversible: YES

	Type	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 Set `#{userId}` to replace the currently logged in user ID.
gradeName	string	✓		~ 128 chars	Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables.
propertyId	string	✓		~ 1024 chars	Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps.
gradeValue	long		0	0 ~ 9223372036854775805	Lost Grade
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Grade:SubGradeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "gradeValue": "[long]Lost Grade",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Grade:SubGradeByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  gradeValue: "[long]Lost Grade"
  timeOffsetToken: "[string]Time offset token"

transaction.service("grade").consume.sub_grade_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    gradeValue="[long]Lost Grade",
    timeOffsetToken="[string]Time offset token",
})

AcquireAction

Gs2Grade:AddGradeByUserId

Add grade by specifying a user ID

Adds the specified grade value to the user’s current grade for the given grade model and property. After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Returns the updated grade status along with the Experience namespace name and the updated Experience status.

Whether the action allows quantity specification: YES

Whether the action is reversible: YES

	Type	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 Set `#{userId}` to replace the currently logged in user ID.
gradeName	string	✓		~ 128 chars	Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables.
propertyId	string	✓		~ 1024 chars	Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps.
gradeValue	long		0	0 ~ 9223372036854775805	Gained Grade
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Grade:AddGradeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "gradeValue": "[long]Gained Grade",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Grade:AddGradeByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  gradeValue: "[long]Gained Grade"
  timeOffsetToken: "[string]Time offset token"

transaction.service("grade").acquire.add_grade_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    gradeValue="[long]Gained Grade",
    timeOffsetToken="[string]Time offset token",
})

Gs2Grade:ApplyRankCapByUserId

Apply rank cap to GS2-Experience Status by specifying a user ID

Applies the rank cap corresponding to the current grade to the linked GS2-Experience status for the specified user (server-side operation). Looks up the grade entry matching the current grade value to determine the rank cap value. This is useful when the grade has been modified externally and the Experience rank cap needs to be synchronized. Returns the updated grade status along with the Experience namespace name and the updated Experience status.

Whether the action allows quantity specification: NO

Whether the action is reversible: NO

	Type	Required	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 Set `#{userId}` to replace the currently logged in user ID.
gradeName	string	✓	~ 128 chars	Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables.
propertyId	string	✓	~ 1024 chars	Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps.
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Grade:ApplyRankCapByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Grade:ApplyRankCapByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  timeOffsetToken: "[string]Time offset token"

transaction.service("grade").acquire.apply_rank_cap_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    timeOffsetToken="[string]Time offset token",
})

Gs2Grade:MultiplyAcquireActionsByUserId

Multiply acquire actions by grade-based rate

Multiplies the quantities of the specified acquire actions by a rate multiplier determined by the user’s current grade. The rate multiplier is looked up from the grade model’s acquireActionRates using the specified rateName and the current grade value. The multiplied acquire actions are then executed as a transaction, enabling grade-based reward scaling (e.g., higher grades receive more resources).

Whether the action allows quantity specification: NO

Whether the action is reversible: NO

	Type	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 Set `#{userId}` to replace the currently logged in user ID.
gradeName	string	✓		~ 128 chars	Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables.
propertyId	string	✓		~ 1024 chars	Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps.
rateName	string	✓		~ 128 chars	Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions.
acquireActions	List<AcquireAction>		[]	0 ~ 100 items	List of Acquire Actions
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Grade:MultiplyAcquireActionsByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "rateName": "[string]Reward Addition Table Name",
        "acquireActions": [
            {
                "action": "[string]Type of action to be executed in the Acquire Action",
                "request": "[string]JSON string of the request used when executing the action"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Grade:MultiplyAcquireActionsByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  rateName: "[string]Reward Addition Table Name"
  acquireActions: 
    - action: "[string]Type of action to be executed in the Acquire Action"
      request: "[string]JSON string of the request used when executing the action"
  timeOffsetToken: "[string]Time offset token"

transaction.service("grade").acquire.multiply_acquire_actions_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    rateName="[string]Reward Addition Table Name",
    acquireActions={
        {
            action="[string]Type of action to be executed in the Acquire Action",
            request="[string]JSON string of the request used when executing the action"
        }
    },
    timeOffsetToken="[string]Time offset token",
})