Criteria

Description

In r4nkt, you create criteria in order to judge or decide whether or not a player has earned an achievement. They are relatively simple resources that specify an action, a rule, and possibly some conditions.

Criteria are created and attached to criteria groups, which are in turn attached to achievements. Once this is done, then an achievement's criteria, which consist of at least one criterion within at least one criteria group, can be evaluated. Then, whenever a player's activities are reported to r4nkt, any related achievements' criteria groups are evaluated. If they resolve to true, then the player has earned the achievement and will be awarded a corresponding badge.

Properties

A criterion has the following properties:

Name	Type	Default
custom_id	string	-
name	string	-
description	string	empty
type	string	sum
custom_action_id	string	-
conditions	json	empty
rule	string	gte:1
streak	string	-

Click here for information about common properties.

Type

The criterion's type property is intended to determine how a player's activities are considered during evaluation. A criterion will consider a set of relevant activities and its type will determine what value to use when applying its rule property.

Currently, there are three values from which to choose:

• amount: When evaluated, if any single relevant activity's amount value allows the criterion's rule to pass, then the criterion is met.

• average: When evaluated, this type of criterion takes the average of all relevant activity amounts, which is then used by the rule.

• sum: This type of criterion, when evaluated, calculates the sum of all relevant activity amounts. This sum is then used when applying the rule.

So, let's say that your player has recorded the following activities:

[
    {"custom_action_id": "close.sale", "amount": 2},
    {"custom_action_id": "close.sale", "amount": 5},
    {"custom_action_id": "close.sale", "amount": 1},
    {"custom_action_id": "close.sale", "amount": 4}
]

If you have a criterion of type amount, then the rule will look at each of the individual amount values. If any of them allow the rule to pass, then the criterion will have been met.

Here are some possible rules and the result for this scenario:

• gt:5: false, because none of the amounts are greater than 5

• lt:3: true

• eq:12: false, because none of the amounts are equal to 12

If you have a criterion of type average, then the rule will look at an average of the various amount values, which happens to be 3 in this case. If the rule passes when using 3, then the criterion will have been met.

Here are some possible rules and the result for this scenario:

• gt:5: false, because the average is 3, which is not greater than 5

• lt:3: false, because the average is 3, which is not less than 3

• eq:12: false, because the average is 3, which is not equal to 12

If you have a criterion of type sum, then the rule will look at a sum of the various amount values, which happens to be 12 in this case. If the rule passes when using 12, then the criterion will have been met.

Here are some possible rules and the result for this scenario:

• gt:5: true

• lt:3: false, because the sum is 12, which is not less than 3

• eq:12: true

Action

A criterion's action is represented by its custom_action_id, which corresponds to the related action's custom_id property. When a criterion is evaluated, its rule is applied against all player activities for the same action to determine whether or not the criterion has been met.

Conditions

Criteria conditions are common to both criteria and criteria groups. If present, they are applied before looking to see if a criterion has been met. Conditions provide a way to filter player activities when determining whether or not a criterion has been met. Once filtered, the criterion's rule is used against whatever activities remain.

Rule

The criterion's rule property is used during evaluation. It consists of an operator and a threshold. They have the following form: operator:threshold.

When a criterion is evaluated, it determines a value. This value is determined based on the criterion's type. Once determined, it is used when the criterion's rule is applied. When applied, the rule compares the value to the specified threshold. The comparison is determined by operator.

Operator

The criterion rule's operator can have any one of the following values:

• eq: If a criterion rule's operator is set to eq, then the criterion will resolve to true if the given value is equal to threshold.

• gt: If a criterion rule's operator is set to gt, then the criterion will resolve to true if the given value is greater than threshold.

• gte: If a criterion rule's operator is set to gte, then the criterion will resolve to true if the given value is greater than or equal to threshold.

• lt: If a criterion rule's operator is set to lt, then the criterion will resolve to true if the given value is less than threshold.

• lte: If a criterion rule's operator is set to lte, then the criterion will resolve to true if the given value is less than or equal to threshold.

Be careful when using eq, since there are times where a player will record activities where the amount might increment the total count for a given action such that the threshold is passed, meaning the criterion might not be met when it's otherwise expected. More often than not, gte should be used.

Threshold

A criterion rule's threshold is a number that is compared to the value determined by its type. The comparison is made using the specified operator.

Streak

The criterion's streak property is used during evaluation. It consists of an interval and an amount. They have the following form: interval:amount.

Interval

The criterion streak's interval can have any one of the following values:

• days: The criterion will have been met if, after all of the conditions have been applied, the rule resolves to true over the course of several consecutive days, which is determined by the streak amount.

• hours: The criterion will have been met if, after all of the conditions have been applied, the rule resolves to true over the course of several consecutive hours, which is determined by the streak amount.

Amount

A criterion streak's amount is an integer indicated the minimum length of the streak.

Currently, streaks of any kind may be between 1 and 100, inclusive.

Examples

Here are some simple examples:

• days:5: The rule must resolve to true for five consecutive days.

• hours:12: The rule must resolve to true for twelve consecutive hours.