# 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 |    -    |

{% hint style="info" %}
Click [here](https://docs.r4nkt.com/overview#common-properties) for information about common properties.
{% endhint %}

### 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:

```javascript
[
    {"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](https://docs.r4nkt.com/concepts/criteria-conditions) are common to both criteria and [criteria groups](https://docs.r4nkt.com/concepts/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](#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`.

{% hint style="warning" %}
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.
{% endhint %}

#### 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.

{% hint style="warning" %}
Currently, streaks of any kind may be between 1 and 100, inclusive.
{% endhint %}

#### 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.